langsmith 0.10.3 → 0.10.5

package/dist/sandbox/service_url.cjs

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceLoginUrl = exports.ServiceUrl = exports.SERVICE_TOKEN_HEADER = void 0;
+/** Header the sandbox router reads the minted service token from. */
+exports.SERVICE_TOKEN_HEADER = "X-Langsmith-Sandbox-Service-Token";
+/** Refresh this many seconds before the token actually expires. */
+const REFRESH_MARGIN_SECONDS = 60;
+/**
+ * Service URL carrying a short-lived token, refreshed as it nears expiry.
+ *
+ * Accessors are async because a refresh is a network call.
+ */
+class ServiceUrl {
+    constructor(data, refresher) {
+        Object.defineProperty(this, "_browserUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_serviceUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_token", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_expiresAt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_refresher", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this._browserUrl = data.browser_url ?? "";
+        this._serviceUrl = data.service_url ?? "";
+        this._token = data.token ?? "";
+        this._expiresAt = data.expires_at ?? "";
+        this._refresher = refresher;
+    }
+    _shouldRefresh() {
+        if (!this._refresher || !this._expiresAt)
+            return false;
+        const expires = Date.parse(this._expiresAt);
+        if (Number.isNaN(expires))
+            return false;
+        return (expires - Date.now()) / 1000 <= REFRESH_MARGIN_SECONDS;
+    }
+    async _maybeRefresh() {
+        if (!this._refresher || !this._shouldRefresh())
+            return;
+        const fresh = await this._refresher();
+        this._browserUrl = fresh._browserUrl;
+        this._serviceUrl = fresh._serviceUrl;
+        this._token = fresh._token;
+        this._expiresAt = fresh._expiresAt;
+    }
+    /** The signed token, refreshed if near expiry. */
+    async token() {
+        await this._maybeRefresh();
+        return this._token;
+    }
+    /** The service base URL, refreshed if near expiry. */
+    async serviceUrl() {
+        await this._maybeRefresh();
+        return this._serviceUrl;
+    }
+    /** The browser URL that authenticates then redirects, refreshed if near expiry. */
+    async browserUrl() {
+        await this._maybeRefresh();
+        return this._browserUrl;
+    }
+    /** ISO 8601 expiry of the current token, refreshed if near expiry. */
+    async expiresAt() {
+        await this._maybeRefresh();
+        return this._expiresAt;
+    }
+    /** Fetch a path on the service with the token header injected. */
+    async fetch(path = "/", init = {}) {
+        const base = (await this.serviceUrl()).replace(/\/+$/, "");
+        const url = `${base}/${path.replace(/^\/+/, "")}`;
+        const headers = new Headers(init.headers);
+        headers.set(exports.SERVICE_TOKEN_HEADER, await this.token());
+        return fetch(url, { ...init, headers });
+    }
+}
+exports.ServiceUrl = ServiceUrl;
+/**
+ * Service URL gated by LangSmith login rather than a token.
+ *
+ * The grant is durable: no token, no expiry, and only usable from a browser
+ * signed in to LangSmith — which is why there is no fetch helper here, a
+ * programmatic request cannot satisfy the login.
+ */
+class ServiceLoginUrl {
+    constructor(data) {
+        /** The URL to open in a browser. */
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Who may open it: "restricted" or "workspace". */
+        Object.defineProperty(this, "access", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.url = data.browser_url || data.service_url || "";
+        this.access = data.access ?? "";
+    }
+}
+exports.ServiceLoginUrl = ServiceLoginUrl;

package/dist/sandbox/service_url.d.ts

@@ -0,0 +1,50 @@
+/** How a service URL is gated. Omit for a minted token. */
+export type ServiceAccess = "restricted" | "workspace";
+/** Header the sandbox router reads the minted service token from. */
+export declare const SERVICE_TOKEN_HEADER = "X-Langsmith-Sandbox-Service-Token";
+export interface ServiceUrlData {
+    browser_url?: string;
+    service_url?: string;
+    token?: string;
+    expires_at?: string;
+    access?: string;
+}
+/**
+ * Service URL carrying a short-lived token, refreshed as it nears expiry.
+ *
+ * Accessors are async because a refresh is a network call.
+ */
+export declare class ServiceUrl {
+    private _browserUrl;
+    private _serviceUrl;
+    private _token;
+    private _expiresAt;
+    private readonly _refresher?;
+    constructor(data: ServiceUrlData, refresher?: () => Promise<ServiceUrl>);
+    private _shouldRefresh;
+    private _maybeRefresh;
+    /** The signed token, refreshed if near expiry. */
+    token(): Promise<string>;
+    /** The service base URL, refreshed if near expiry. */
+    serviceUrl(): Promise<string>;
+    /** The browser URL that authenticates then redirects, refreshed if near expiry. */
+    browserUrl(): Promise<string>;
+    /** ISO 8601 expiry of the current token, refreshed if near expiry. */
+    expiresAt(): Promise<string>;
+    /** Fetch a path on the service with the token header injected. */
+    fetch(path?: string, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Service URL gated by LangSmith login rather than a token.
+ *
+ * The grant is durable: no token, no expiry, and only usable from a browser
+ * signed in to LangSmith — which is why there is no fetch helper here, a
+ * programmatic request cannot satisfy the login.
+ */
+export declare class ServiceLoginUrl {
+    /** The URL to open in a browser. */
+    readonly url: string;
+    /** Who may open it: "restricted" or "workspace". */
+    readonly access: string;
+    constructor(data: ServiceUrlData);
+}

package/dist/sandbox/service_url.js

@@ -0,0 +1,120 @@
+/** Header the sandbox router reads the minted service token from. */
+export const SERVICE_TOKEN_HEADER = "X-Langsmith-Sandbox-Service-Token";
+/** Refresh this many seconds before the token actually expires. */
+const REFRESH_MARGIN_SECONDS = 60;
+/**
+ * Service URL carrying a short-lived token, refreshed as it nears expiry.
+ *
+ * Accessors are async because a refresh is a network call.
+ */
+export class ServiceUrl {
+    constructor(data, refresher) {
+        Object.defineProperty(this, "_browserUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_serviceUrl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_token", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_expiresAt", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_refresher", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this._browserUrl = data.browser_url ?? "";
+        this._serviceUrl = data.service_url ?? "";
+        this._token = data.token ?? "";
+        this._expiresAt = data.expires_at ?? "";
+        this._refresher = refresher;
+    }
+    _shouldRefresh() {
+        if (!this._refresher || !this._expiresAt)
+            return false;
+        const expires = Date.parse(this._expiresAt);
+        if (Number.isNaN(expires))
+            return false;
+        return (expires - Date.now()) / 1000 <= REFRESH_MARGIN_SECONDS;
+    }
+    async _maybeRefresh() {
+        if (!this._refresher || !this._shouldRefresh())
+            return;
+        const fresh = await this._refresher();
+        this._browserUrl = fresh._browserUrl;
+        this._serviceUrl = fresh._serviceUrl;
+        this._token = fresh._token;
+        this._expiresAt = fresh._expiresAt;
+    }
+    /** The signed token, refreshed if near expiry. */
+    async token() {
+        await this._maybeRefresh();
+        return this._token;
+    }
+    /** The service base URL, refreshed if near expiry. */
+    async serviceUrl() {
+        await this._maybeRefresh();
+        return this._serviceUrl;
+    }
+    /** The browser URL that authenticates then redirects, refreshed if near expiry. */
+    async browserUrl() {
+        await this._maybeRefresh();
+        return this._browserUrl;
+    }
+    /** ISO 8601 expiry of the current token, refreshed if near expiry. */
+    async expiresAt() {
+        await this._maybeRefresh();
+        return this._expiresAt;
+    }
+    /** Fetch a path on the service with the token header injected. */
+    async fetch(path = "/", init = {}) {
+        const base = (await this.serviceUrl()).replace(/\/+$/, "");
+        const url = `${base}/${path.replace(/^\/+/, "")}`;
+        const headers = new Headers(init.headers);
+        headers.set(SERVICE_TOKEN_HEADER, await this.token());
+        return fetch(url, { ...init, headers });
+    }
+}
+/**
+ * Service URL gated by LangSmith login rather than a token.
+ *
+ * The grant is durable: no token, no expiry, and only usable from a browser
+ * signed in to LangSmith — which is why there is no fetch helper here, a
+ * programmatic request cannot satisfy the login.
+ */
+export class ServiceLoginUrl {
+    constructor(data) {
+        /** The URL to open in a browser. */
+        Object.defineProperty(this, "url", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Who may open it: "restricted" or "workspace". */
+        Object.defineProperty(this, "access", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.url = data.browser_url || data.service_url || "";
+        this.access = data.access ?? "";
+    }
+}

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.