langsmith 0.10.4 → 0.10.5

package/dist/sandbox/types.d.ts

@@ -3,6 +3,7 @@
  *
  * Field names use snake_case to match API response format.
  */
+import type { AccessDelegation } from "./access_delegation.js";
 /**
  * Result of executing a command in a sandbox.
  */
@@ -20,6 +21,164 @@ export interface ResourceStatus {
     /** Human-readable details when failed. */
     status_message?: string;
 }
+/**
+ * The user, working directory and environment commands run with.
+ *
+ * Mirrors `docker run -u / -w / -e`: `user` and `work_dir` replace the layer
+ * below, `env_vars` merge into it key by key. It applies at three points, each
+ * layered over the one before -- the snapshot, the sandbox, and a single
+ * command.
+ */
+export interface RunConfig {
+    /**
+     * Account to run as: `name`, `uid`, `name:group` or `uid:gid`. Defaults to
+     * the Docker image's `USER`.
+     */
+    user?: string;
+    /**
+     * Absolute working directory. Defaults to the image's `WORKDIR`. A relative
+     * path is rejected by the server.
+     */
+    work_dir?: string;
+    /** Environment variables, merged over the layer below. */
+    env_vars?: Record<string, string>;
+}
+/**
+ * One filesystem entry returned by `sandbox.glob()`.
+ */
+export interface FileInfo {
+    /** Absolute path of the entry. */
+    path: string;
+    /** True for a directory. */
+    is_dir: boolean;
+    /** Size in bytes. */
+    size_bytes: number;
+    /** RFC 3339 modification timestamp. */
+    modified_at?: string;
+}
+/**
+ * Entries matching a glob pattern.
+ */
+export interface GlobResult {
+    matches: FileInfo[];
+    /**
+     * True when the server hit its result cap or deadline, so the search is a
+     * partial answer worth refining.
+     */
+    truncated: boolean;
+}
+/**
+ * One matching line found by `sandbox.grep()`.
+ */
+export interface GrepMatch {
+    /** Absolute path of the file the match was found in. */
+    path: string;
+    /** 1-based line number. */
+    line: number;
+    /** The matching line's text. */
+    text: string;
+}
+/**
+ * Lines matching a literal search.
+ */
+export interface GrepResult {
+    matches: GrepMatch[];
+    /** True when the server hit its result cap or deadline. */
+    truncated: boolean;
+}
+/**
+ * Options for the read-only filesystem search operations.
+ */
+export interface GlobOptions {
+    /** Maximum matches to return. */
+    limit?: number;
+    /** Request timeout in seconds. */
+    timeout?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Options for `sandbox.grep()`.
+ */
+export interface GrepOptions extends GlobOptions {
+    /**
+     * Restrict which files are searched. A bare `*.py` matches by basename at
+     * any depth; a pattern containing `/` or `**` matches the path relative to
+     * the search root.
+     */
+    glob?: string;
+}
+/**
+ * What a `HEAD` on a sandbox file reports, without transferring it.
+ */
+export interface FileStat {
+    /** The file's size. */
+    size_bytes: number;
+    /**
+     * Strong validator for the current contents. Opaque -- compare it, never
+     * parse it. Pass it back as `ifRange` to resume a download safely, or as
+     * `ifNoneMatch` to poll for a change.
+     */
+    etag?: string;
+    /** HTTP-date of the last modification, second-resolution. */
+    last_modified?: string;
+    /** The server's content type for the file. */
+    content_type?: string;
+}
+/**
+ * Bytes returned by a ranged read, and where they sit in the file.
+ */
+export interface FileChunk {
+    /** The bytes returned. Empty when `unchanged` is true. */
+    content: Uint8Array;
+    /**
+     * Validator for the version these bytes came from. Pass it as `ifRange` on
+     * the next chunk so a rewrite restarts the read instead of splicing two
+     * versions together.
+     */
+    etag?: string;
+    /** The file's full size, or undefined when the server did not report it. */
+    total_bytes?: number;
+    /** Offset of the first byte returned. */
+    start: number;
+    /**
+     * True when the server answered 206 with only part of the file. A false
+     * here after a ranged request means the file changed and the server sent it
+     * whole -- restart from zero.
+     */
+    partial: boolean;
+    /**
+     * True when the caller passed `ifNoneMatch` and the file still matches it.
+     * No bytes are returned.
+     */
+    unchanged: boolean;
+    /** HTTP-date of the last modification. */
+    last_modified?: string;
+}
+/**
+ * Options for a ranged read. Provide `start` (with optional `end`), or
+ * `suffixBytes`.
+ */
+export interface ReadRangeOptions {
+    /** First byte to return. With `end`, an inclusive range. */
+    start?: number;
+    /** Last byte to return, inclusive. Clamped to EOF rather than rejected. */
+    end?: number;
+    /** Return the last N bytes. Mutually exclusive with `start`/`end`. */
+    suffixBytes?: number;
+    /**
+     * An `ETag` from an earlier chunk. The range is honored only while the file
+     * still matches it.
+     */
+    ifRange?: string;
+    /**
+     * An `ETag` the caller already holds. An unchanged file answers with
+     * `unchanged: true` and no bytes.
+     */
+    ifNoneMatch?: string;
+    /** Request timeout in seconds. */
+    timeout?: number;
+    headers?: Record<string, string>;
+}
 /**
  * Represents a sandbox snapshot.
  *
@@ -41,6 +200,13 @@ export interface Snapshot {
     registry_id?: string;
     created_at?: string;
     updated_at?: string;
+    /**
+     * User, working directory and environment sandboxes built from this
+     * snapshot boot with, resolved from the Docker image at build time. Absent
+     * on snapshots built before the server recorded it, which boot as root with
+     * no image environment.
+     */
+    run_config?: RunConfig;
 }
 /**
  * Data representing a sandbox instance from the API.
@@ -79,6 +245,16 @@ export interface SandboxData {
     mem_bytes?: number;
     /** Root filesystem capacity in bytes. */
     fs_capacity_bytes?: number;
+    /**
+     * User, working directory and environment the sandbox's commands run with.
+     * Absent on sandboxes created before the server recorded it.
+     */
+    run_config?: RunConfig;
+    /**
+     * LangSmith access granted to code inside the sandbox. Absent when it has
+     * none.
+     */
+    access_delegation?: AccessDelegation;
 }
 /**
  * Configuration options for the SandboxClient.
@@ -170,6 +346,10 @@ export interface WsRunOptions {
     ttlSeconds?: number;
     /** Whether to allocate a PTY. */
     pty?: boolean;
+    /** Per-command user, working directory and environment. */
+    runConfig?: RunConfig;
+    /** Half-close the spawned process's stdin so it reads EOF. */
+    closeStdin?: boolean;
     /**
      * Additional headers attached to the WebSocket upgrade request. Merged on
      * top of any default headers the SandboxClient was constructed with.
@@ -186,12 +366,30 @@ export interface RunOptions {
     timeout?: number;
     /**
      * Environment variables to set for the command.
+     *
+     * @deprecated Use `runConfig.env_vars`. The two cannot be combined.
      */
     env?: Record<string, string>;
     /**
      * Working directory for command execution.
+     *
+     * @deprecated Use `runConfig.work_dir`. The two cannot be combined.
      */
     cwd?: string;
+    /**
+     * User, working directory and environment for this one command, layered
+     * over the sandbox's own.
+     */
+    runConfig?: RunConfig;
+    /**
+     * Half-close the command's stdin so a command that reads it sees EOF
+     * rather than blocking until the timeout. Defaults to true for a non-PTY
+     * command, which means `sendInput()` on the returned handle throws unless
+     * this is set to false. Ignored under `pty: true`, where input and output
+     * share one terminal file descriptor -- send an EOT byte (0x04) as input
+     * instead.
+     */
+    closeInput?: boolean;
     /**
      * Shell to use for command execution. Defaults to "/bin/bash".
      */
@@ -262,8 +460,20 @@ export interface SandboxProxySecret {
     /** Workspace secret reference or opaque secret value. */
     value: string;
 }
+/** Static credentials used by the sandbox proxy signer. */
+interface AwsStaticAuthConfig {
+    access_key_id: SandboxProxySecret;
+    secret_access_key: SandboxProxySecret;
+    role_arn?: "";
+}
+/** IAM role assumed and renewed by LangSmith, outside the sandbox. */
+interface AwsRoleAuthConfig {
+    role_arn: string;
+    access_key_id?: never;
+    secret_access_key?: never;
+}
 /** AWS auth rule for sandbox proxy SigV4 signing. */
-export interface SandboxAwsAuthRule {
+export interface SandboxAwsAuthRule<Auth extends AwsStaticAuthConfig | AwsRoleAuthConfig = AwsStaticAuthConfig | AwsRoleAuthConfig> {
     /** Rule name. */
     name: string;
     /** AWS auth rules are matched by the sandbox proxy's AWS endpoint matcher. */
@@ -277,11 +487,8 @@ export interface SandboxAwsAuthRule {
      * the wire.
      */
     env_vars?: Record<string, string>;
-    /** AWS credentials used by the proxy signer. */
-    aws: {
-        access_key_id: SandboxProxySecret;
-        secret_access_key: SandboxProxySecret;
-    };
+    /** Exclusive static credentials or IAM-role descriptor. */
+    aws: Auth;
 }
 /** GCP auth rule for sandbox proxy OAuth bearer injection. */
 export interface SandboxGcpAuthRule {
@@ -314,7 +521,7 @@ export type SandboxProxyRule = SandboxAwsAuthRule | SandboxGcpAuthRule | Record<
 export interface SandboxProxyConfig {
     /** Header-injection rules keyed by host pattern. */
     rules?: SandboxProxyRule[];
-    /** Hosts that bypass the proxy entirely. */
+    /** @deprecated Ignored by the server. The sandbox runtime has no proxy bypass list. */
     no_proxy?: string[];
     /** Allow/deny list enforced at the proxy sidecar. */
     access_control?: SandboxAccessControl;
@@ -427,6 +634,7 @@ export type SandboxMount = S3MountSpec | GCSMountSpec | GitMountSpec | ContextHu
 export interface SandboxAwsMountAuthConfig {
     access_key_id: SandboxProxySecret;
     secret_access_key: SandboxProxySecret;
+    role_arn?: "";
 }
 /** GCP credentials used by the backend to authenticate GCS mounts. */
 export interface SandboxGcpMountAuthConfig {
@@ -434,7 +642,8 @@ export interface SandboxGcpMountAuthConfig {
 }
 /** Provider auth blocks for sandbox mounts. */
 export interface SandboxMountAuthConfig {
-    aws?: SandboxAwsMountAuthConfig;
+    /** IAM roles here are restricted to this sandbox's S3 mount scopes. */
+    aws?: SandboxAwsMountAuthConfig | AwsRoleAuthConfig;
     gcp?: SandboxGcpMountAuthConfig;
 }
 /** Provider auth helper output accepted by mountConfig. */
@@ -507,6 +716,21 @@ export interface CreateSandboxOptions {
      * auth.
      */
     proxyConfig?: SandboxProxyConfig;
+    /**
+     * User, working directory and environment the sandbox boots with,
+     * overriding the snapshot's: `user` and `work_dir` replace, `env_vars`
+     * merge. The sandbox's own env vars remain a layer above this one.
+     */
+    runConfig?: RunConfig;
+    /**
+     * Grant letting code inside the sandbox call the LangSmith API as you, with
+     * no API key of its own. `{ mode: "INHERIT" }` grants everything you can do;
+     * `{ mode: "EXPLICIT", permissions: [...] }` grants only the permissions
+     * listed, each of which you must already hold. The grant belongs to the
+     * sandbox, so anyone who can exec into it can make calls under it. Omit for
+     * no access.
+     */
+    accessDelegation?: AccessDelegation;
 }
 /**
  * Options for creating a snapshot from a Docker image.
@@ -514,6 +738,13 @@ export interface CreateSandboxOptions {
 export interface CreateSnapshotOptions {
     /** Private registry ID. */
     registryId?: string;
+    /**
+     * Override the Docker image's `USER`, `WORKDIR` and `ENV` for sandboxes
+     * built from this snapshot: `user` and `work_dir` replace the image's,
+     * `env_vars` merge over it key by key. Omitting it adopts the image's own
+     * configuration. Pass `{ user: "0" }` to keep running as root.
+     */
+    runConfig?: RunConfig;
     /** Timeout in seconds when waiting for ready. Default: 60. */
     timeout?: number;
     /** AbortSignal for cancellation. */
@@ -554,6 +785,11 @@ export interface CaptureSnapshotOptions {
     dockerImage?: string;
     /** Filesystem capacity in bytes for Docker image export. */
     fsCapacityBytes?: number;
+    /**
+     * Override applied over the configuration the captured sandbox was running
+     * with: `user` and `work_dir` replace, `env_vars` merge.
+     */
+    runConfig?: RunConfig;
     /** Timeout in seconds when waiting for ready. Default: 60. */
     timeout?: number;
     /** AbortSignal for cancellation. */
@@ -669,6 +905,13 @@ export interface UpdateSandboxOptions {
      * `ready`; start a stopped one first.
      */
     proxyConfig?: SandboxProxyConfig;
+    /**
+     * Merge into the sandbox's stored run configuration: `user` and `work_dir`
+     * replace, `env_vars` merge. Takes effect for subsequent commands; commands
+     * already running are unaffected, and a stopped sandbox picks it up on its
+     * next start. Omitting it leaves the stored value untouched.
+     */
+    runConfig?: RunConfig;
 }
 /**
  * Options for waiting for a sandbox to become ready.

package/dist/sandbox/ws_execute.cjs

@@ -136,10 +136,20 @@ class WSStreamControl {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_closeStdinPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
     }
     /** Bind to the active WebSocket. Called inside the generator. */
     _bind(ws) {
         this._ws = ws;
+        if (this._closeStdinPending) {
+            this._closeStdinPending = false;
+            this.sendCloseStdin();
+        }
     }
     /** Mark as closed. Called when the generator exits. */
     _unbind() {
@@ -163,6 +173,22 @@ class WSStreamControl {
             this._ws.send(JSON.stringify({ type: "input", data }));
         }
     }
+    /**
+     * Half-close the command's stdin so it reads EOF.
+     *
+     * A reconnected stream binds its socket only once iteration starts, so a
+     * close arriving before that is queued and sent on bind — dropping it would
+     * leave the command waiting for an EOF that never comes.
+     */
+    sendCloseStdin() {
+        if (this._closed)
+            return;
+        if (this._ws && this._ws.readyState === 1) {
+            this._ws.send(JSON.stringify({ type: "close_stdin" }));
+            return;
+        }
+        this._closeStdinPending = true;
+    }
 }
 exports.WSStreamControl = WSStreamControl;
 // =============================================================================
@@ -330,7 +356,7 @@ async function* readWsMessages(ws) {
  * data arrives in addition to yielding the messages.
  */
 async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
-    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, openTimeout = exports.WS_OPEN_TIMEOUT, } = options;
+    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, runConfig, closeStdin, headers: extraHeaders, openTimeout = exports.WS_OPEN_TIMEOUT, } = options;
     const wsUrl = buildWsUrl(dataplaneUrl);
     const headers = buildAuthHeaders(apiKey, extraHeaders);
     const control = new WSStreamControl();
@@ -353,6 +379,10 @@ async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
                 payload.env = env;
             if (cwd)
                 payload.cwd = cwd;
+            if (runConfig)
+                payload.run_config = runConfig;
+            if (closeStdin)
+                payload.close_stdin = true;
             if (commandId)
                 payload.command_id = commandId;
             if (pty)

package/dist/sandbox/ws_execute.d.ts

@@ -35,6 +35,7 @@ export declare class WSStreamControl {
     private _ws;
     private _closed;
     private _killed;
+    private _closeStdinPending;
     /** Bind to the active WebSocket. Called inside the generator. */
     _bind(ws: WsWebSocket): void;
     /** Mark as closed. Called when the generator exits. */
@@ -45,6 +46,14 @@ export declare class WSStreamControl {
     sendKill(): void;
     /** Send stdin data to the running command. */
     sendInput(data: string): void;
+    /**
+     * Half-close the command's stdin so it reads EOF.
+     *
+     * A reconnected stream binds its socket only once iteration starts, so a
+     * close arriving before that is queued and sent on bind — dropping it would
+     * leave the command waiting for an EOF that never comes.
+     */
+    sendCloseStdin(): void;
 }
 /**
  * Raise the appropriate exception from a server error message.

package/dist/sandbox/ws_execute.js

@@ -124,10 +124,20 @@ export class WSStreamControl {
             writable: true,
             value: false
         });
+        Object.defineProperty(this, "_closeStdinPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
     }
     /** Bind to the active WebSocket. Called inside the generator. */
     _bind(ws) {
         this._ws = ws;
+        if (this._closeStdinPending) {
+            this._closeStdinPending = false;
+            this.sendCloseStdin();
+        }
     }
     /** Mark as closed. Called when the generator exits. */
     _unbind() {
@@ -151,6 +161,22 @@ export class WSStreamControl {
             this._ws.send(JSON.stringify({ type: "input", data }));
         }
     }
+    /**
+     * Half-close the command's stdin so it reads EOF.
+     *
+     * A reconnected stream binds its socket only once iteration starts, so a
+     * close arriving before that is queued and sent on bind — dropping it would
+     * leave the command waiting for an EOF that never comes.
+     */
+    sendCloseStdin() {
+        if (this._closed)
+            return;
+        if (this._ws && this._ws.readyState === 1) {
+            this._ws.send(JSON.stringify({ type: "close_stdin" }));
+            return;
+        }
+        this._closeStdinPending = true;
+    }
 }
 // =============================================================================
 // Error Handling
@@ -317,7 +343,7 @@ async function* readWsMessages(ws) {
  * data arrives in addition to yielding the messages.
  */
 export async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
-    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, openTimeout = WS_OPEN_TIMEOUT, } = options;
+    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, runConfig, closeStdin, headers: extraHeaders, openTimeout = WS_OPEN_TIMEOUT, } = options;
     const wsUrl = buildWsUrl(dataplaneUrl);
     const headers = buildAuthHeaders(apiKey, extraHeaders);
     const control = new WSStreamControl();
@@ -340,6 +366,10 @@ export async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
                 payload.env = env;
             if (cwd)
                 payload.cwd = cwd;
+            if (runConfig)
+                payload.run_config = runConfig;
+            if (closeStdin)
+                payload.close_stdin = true;
             if (commandId)
                 payload.command_id = commandId;
             if (pty)

package/dist/utils/error.cjs

@@ -140,32 +140,27 @@ async function raiseForStatus(response, context, consumeOnSuccess) {
         }
         return;
     }
+    try {
+        errorBody = await response.text();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }
+    catch (_e) {
+        errorBody = "";
+    }
     if (response.status === 403) {
+        let errorData;
         try {
-            const errorData = await response.json();
-            const errorCode = errorData?.error;
-            if (errorCode === "org_scoped_key_requires_workspace") {
-                errorBody =
-                    "This API key is org-scoped and requires workspace specification. " +
-                        "Please provide 'workspaceId' parameter, " +
-                        "or set LANGSMITH_WORKSPACE_ID environment variable.";
-            }
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        }
-        catch (_e) {
-            const errorWithStatus = new Error(`${response.status} ${response.statusText}`);
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            errorWithStatus.status = response?.status;
-            throw errorWithStatus;
+            errorData = JSON.parse(errorBody);
         }
-    }
-    if (errorBody === undefined) {
-        try {
-            errorBody = await response.text();
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        catch {
+            // Non-JSON body (e.g. a proxy in front of a self-hosted instance):
+            // fall through and surface the raw body like every other status.
         }
-        catch (_e) {
-            errorBody = "";
+        if (errorData?.error === "org_scoped_key_requires_workspace") {
+            errorBody =
+                "This API key is org-scoped and requires workspace specification. " +
+                    "Please provide 'workspaceId' parameter, " +
+                    "or set LANGSMITH_WORKSPACE_ID environment variable.";
         }
     }
     const fullMessage = `Failed to ${context}. Received status [${response.status}]: ${response.statusText}. Message: ${errorBody}`;

package/dist/utils/error.js

@@ -129,32 +129,27 @@ export async function raiseForStatus(response, context, consumeOnSuccess) {
         }
         return;
     }
+    try {
+        errorBody = await response.text();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    }
+    catch (_e) {
+        errorBody = "";
+    }
     if (response.status === 403) {
+        let errorData;
         try {
-            const errorData = await response.json();
-            const errorCode = errorData?.error;
-            if (errorCode === "org_scoped_key_requires_workspace") {
-                errorBody =
-                    "This API key is org-scoped and requires workspace specification. " +
-                        "Please provide 'workspaceId' parameter, " +
-                        "or set LANGSMITH_WORKSPACE_ID environment variable.";
-            }
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        }
-        catch (_e) {
-            const errorWithStatus = new Error(`${response.status} ${response.statusText}`);
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            errorWithStatus.status = response?.status;
-            throw errorWithStatus;
+            errorData = JSON.parse(errorBody);
         }
-    }
-    if (errorBody === undefined) {
-        try {
-            errorBody = await response.text();
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        catch {
+            // Non-JSON body (e.g. a proxy in front of a self-hosted instance):
+            // fall through and surface the raw body like every other status.
         }
-        catch (_e) {
-            errorBody = "";
+        if (errorData?.error === "org_scoped_key_requires_workspace") {
+            errorBody =
+                "This API key is org-scoped and requires workspace specification. " +
+                    "Please provide 'workspaceId' parameter, " +
+                    "or set LANGSMITH_WORKSPACE_ID environment variable.";
         }
     }
     const fullMessage = `Failed to ${context}. Received status [${response.status}]: ${response.statusText}. Message: ${errorBody}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "packageManager": "pnpm@10.33.0",
   "files": [