langsmith 0.10.4 → 0.10.5

package/dist/sandbox/mounts.cjs

@@ -6,6 +6,7 @@ exports.gcsMount = gcsMount;
 exports.contextHubMount = contextHubMount;
 exports.mountConfig = mountConfig;
 exports.validateMountConfigProxyConfig = validateMountConfigProxyConfig;
+const proxy_config_js_1 = require("./proxy_config.cjs");
 function requireNonEmptyString(value, field) {
     if (typeof value !== "string" || value.trim() === "") {
         throw new Error(`${field} must be a non-empty string`);
@@ -217,6 +218,11 @@ function normalizeMountAuth(auth) {
             if (aws === undefined) {
                 throw new Error("aws mount auth must include an aws block");
             }
+            const roleArn = (0, proxy_config_js_1.getAwsRoleArn)(aws);
+            if (roleArn !== undefined) {
+                byProvider.aws = { role_arn: roleArn };
+                continue;
+            }
             byProvider.aws = {
                 access_key_id: copyMountSecret(aws.access_key_id, "accessKeyId"),
                 secret_access_key: copyMountSecret(aws.secret_access_key, "secretAccessKey"),
@@ -234,11 +240,21 @@ function normalizeMountAuth(auth) {
     }
     return byProvider;
 }
-function mountConfig({ auth = [], mounts, }) {
+/**
+ * Build mount-scoped auth, or use an enabled AWS rule from proxyConfig for S3.
+ * Pass the same proxyConfig to sandbox creation; its general IAM permissions
+ * remain unchanged. GCS mounts still require explicit GCP auth in this config.
+ */
+function mountConfig({ auth = [], mounts, proxyConfig, }) {
     const normalizedMounts = normalizeMounts(mounts);
     const authByProvider = normalizeMountAuth(auth);
     const mountProviders = new Set(normalizedMounts.map((mount) => mount.type));
-    if (mountProviders.has("s3") && authByProvider.aws === undefined) {
+    const proxyProviders = new Set((proxyConfig?.rules ?? [])
+        .filter((rule) => rule?.enabled === true)
+        .map((rule) => rule.type));
+    if (mountProviders.has("s3") &&
+        authByProvider.aws === undefined &&
+        !proxyProviders.has("aws")) {
         throw new Error("s3 mounts require aws auth in mountConfig");
     }
     if (mountProviders.has("gcs") && authByProvider.gcp === undefined) {
@@ -250,10 +266,12 @@ function mountConfig({ auth = [], mounts, }) {
     if (authByProvider.gcp !== undefined && !mountProviders.has("gcs")) {
         throw new Error("gcp auth requires at least one gcs mount in mountConfig");
     }
-    return {
+    const config = {
         auth: authByProvider,
         mounts: normalizedMounts,
     };
+    validateMountConfigProxyConfig(config, proxyConfig);
+    return config;
 }
 function validateMountConfigProxyConfig(mountConfig, proxyConfig) {
     if (proxyConfig === undefined) {

package/dist/sandbox/mounts.d.ts

@@ -36,8 +36,14 @@ export declare function contextHubMount({ id, mountPath, repo, initialPullOnly,
     repo: string;
     initialPullOnly?: boolean;
 }): ContextHubMountSpec;
-export declare function mountConfig({ auth, mounts, }: {
+/**
+ * Build mount-scoped auth, or use an enabled AWS rule from proxyConfig for S3.
+ * Pass the same proxyConfig to sandbox creation; its general IAM permissions
+ * remain unchanged. GCS mounts still require explicit GCP auth in this config.
+ */
+export declare function mountConfig({ auth, mounts, proxyConfig, }: {
     auth?: SandboxMountAuth[];
     mounts: SandboxMount[];
+    proxyConfig?: SandboxProxyConfig;
 }): SandboxMountConfig;
 export declare function validateMountConfigProxyConfig(mountConfig: SandboxMountConfig, proxyConfig: SandboxProxyConfig | undefined): void;

package/dist/sandbox/mounts.js

@@ -1,3 +1,4 @@
+import { getAwsRoleArn } from "./proxy_config.js";
 function requireNonEmptyString(value, field) {
     if (typeof value !== "string" || value.trim() === "") {
         throw new Error(`${field} must be a non-empty string`);
@@ -209,6 +210,11 @@ function normalizeMountAuth(auth) {
             if (aws === undefined) {
                 throw new Error("aws mount auth must include an aws block");
             }
+            const roleArn = getAwsRoleArn(aws);
+            if (roleArn !== undefined) {
+                byProvider.aws = { role_arn: roleArn };
+                continue;
+            }
             byProvider.aws = {
                 access_key_id: copyMountSecret(aws.access_key_id, "accessKeyId"),
                 secret_access_key: copyMountSecret(aws.secret_access_key, "secretAccessKey"),
@@ -226,11 +232,21 @@ function normalizeMountAuth(auth) {
     }
     return byProvider;
 }
-export function mountConfig({ auth = [], mounts, }) {
+/**
+ * Build mount-scoped auth, or use an enabled AWS rule from proxyConfig for S3.
+ * Pass the same proxyConfig to sandbox creation; its general IAM permissions
+ * remain unchanged. GCS mounts still require explicit GCP auth in this config.
+ */
+export function mountConfig({ auth = [], mounts, proxyConfig, }) {
     const normalizedMounts = normalizeMounts(mounts);
     const authByProvider = normalizeMountAuth(auth);
     const mountProviders = new Set(normalizedMounts.map((mount) => mount.type));
-    if (mountProviders.has("s3") && authByProvider.aws === undefined) {
+    const proxyProviders = new Set((proxyConfig?.rules ?? [])
+        .filter((rule) => rule?.enabled === true)
+        .map((rule) => rule.type));
+    if (mountProviders.has("s3") &&
+        authByProvider.aws === undefined &&
+        !proxyProviders.has("aws")) {
         throw new Error("s3 mounts require aws auth in mountConfig");
     }
     if (mountProviders.has("gcs") && authByProvider.gcp === undefined) {
@@ -242,10 +258,12 @@ export function mountConfig({ auth = [], mounts, }) {
     if (authByProvider.gcp !== undefined && !mountProviders.has("gcs")) {
         throw new Error("gcp auth requires at least one gcs mount in mountConfig");
     }
-    return {
+    const config = {
         auth: authByProvider,
         mounts: normalizedMounts,
     };
+    validateMountConfigProxyConfig(config, proxyConfig);
+    return config;
 }
 export function validateMountConfigProxyConfig(mountConfig, proxyConfig) {
     if (proxyConfig === undefined) {

package/dist/sandbox/proxy_config.cjs

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAwsRoleArn = getAwsRoleArn;
 exports.workspaceSecret = workspaceSecret;
 exports.opaqueSecret = opaqueSecret;
 exports.proxyConfig = proxyConfig;
@@ -49,6 +50,10 @@ function requireProxyRules(rules) {
     });
 }
 function validateProxyProviderRule(rule) {
+    if (rule.type === "aws") {
+        getAwsRoleArn(rule.aws);
+        return;
+    }
     if (rule.type !== "gcp") {
         return;
     }
@@ -58,6 +63,21 @@ function validateProxyProviderRule(rule) {
     }
     requireNonEmptyStringArray(gcp.scopes, "scopes");
 }
+/** Validate role-only descriptors without tightening legacy static inputs. */
+function getAwsRoleArn(aws) {
+    if (aws === null || typeof aws !== "object" || Array.isArray(aws)) {
+        return undefined;
+    }
+    const config = aws;
+    if (!("role_arn" in config) || config.role_arn === "") {
+        return undefined;
+    }
+    const roleArn = requireNonEmptyString(config.role_arn, "roleArn");
+    if (Object.keys(config).some((key) => key !== "role_arn")) {
+        throw new Error("AWS role auth must contain only role_arn");
+    }
+    return roleArn;
+}
 /** Reference a LangSmith workspace secret in a sandbox proxy configuration. */
 function workspaceSecret(name) {
     const normalized = requireNonEmptyString(name, "name");
@@ -82,28 +102,39 @@ function opaqueSecret(value) {
     };
 }
 /** Build a sandbox proxy config from one or more proxy rules. */
-function proxyConfig({ rules, noProxy, accessControl, } = {}) {
+function proxyConfig({ rules, accessControl, } = {}) {
     const config = {
         rules: requireProxyRules(rules),
     };
-    if (noProxy !== undefined) {
-        config.no_proxy = requireNonEmptyStringArray(noProxy, "noProxy");
-    }
     if (accessControl !== undefined) {
         config.access_control = { ...accessControl };
     }
     return config;
 }
-/** Build a sandbox proxy rule that signs AWS HTTPS requests with SigV4. */
-function awsAuth({ accessKeyId, secretAccessKey, name = "aws", enabled = true, envVars, }) {
+function awsAuth({ accessKeyId, secretAccessKey, roleArn, name = "aws", enabled = true, envVars, }) {
+    const candidate = {};
+    if (roleArn !== undefined)
+        candidate.role_arn = roleArn;
+    if (accessKeyId !== undefined)
+        candidate.access_key_id = accessKeyId;
+    if (secretAccessKey !== undefined)
+        candidate.secret_access_key = secretAccessKey;
+    const normalizedRole = getAwsRoleArn(candidate);
+    let aws;
+    if (normalizedRole !== undefined) {
+        aws = { role_arn: normalizedRole };
+    }
+    else {
+        if (accessKeyId === undefined || secretAccessKey === undefined) {
+            throw new Error("AWS auth requires roleArn or both static credentials");
+        }
+        aws = { access_key_id: accessKeyId, secret_access_key: secretAccessKey };
+    }
     const rule = {
         name: requireNonEmptyString(name, "name"),
         type: "aws",
         enabled,
-        aws: {
-            access_key_id: accessKeyId,
-            secret_access_key: secretAccessKey,
-        },
+        aws,
     };
     if (envVars !== undefined) {
         rule.env_vars = requireEnvVars(envVars);

package/dist/sandbox/proxy_config.d.ts

@@ -1,22 +1,48 @@
 import type { SandboxAccessControl, SandboxAwsAuthRule, SandboxGcpAuthRule, SandboxProxyConfig, SandboxProxyRule, SandboxProxySecret } from "./types.js";
+/** Validate role-only descriptors without tightening legacy static inputs. */
+export declare function getAwsRoleArn(aws: unknown): string | undefined;
 /** Reference a LangSmith workspace secret in a sandbox proxy configuration. */
 export declare function workspaceSecret(name: string): SandboxProxySecret;
 /** Provide a write-only secret value for a sandbox proxy configuration. */
 export declare function opaqueSecret(value: string): SandboxProxySecret;
 /** Build a sandbox proxy config from one or more proxy rules. */
-export declare function proxyConfig({ rules, noProxy, accessControl, }?: {
+export declare function proxyConfig({ rules, accessControl, }?: {
     rules?: SandboxProxyRule[];
+    /** @deprecated Ignored. The sandbox runtime has no proxy bypass list. */
     noProxy?: string[];
     accessControl?: SandboxAccessControl;
 }): SandboxProxyConfig;
-/** Build a sandbox proxy rule that signs AWS HTTPS requests with SigV4. */
-export declare function awsAuth({ accessKeyId, secretAccessKey, name, enabled, envVars, }: {
-    accessKeyId: SandboxProxySecret;
-    secretAccessKey: SandboxProxySecret;
+interface AwsAuthCommonOptions {
     name?: string;
     enabled?: boolean;
     envVars?: Record<string, string>;
-}): SandboxAwsAuthRule;
+}
+type AwsStaticAuthConfig = Extract<SandboxAwsAuthRule["aws"], {
+    access_key_id: SandboxProxySecret;
+}>;
+type AwsRoleAuthConfig = Extract<SandboxAwsAuthRule["aws"], {
+    role_arn: string;
+}>;
+type AwsStaticAuthOptions = AwsAuthCommonOptions & {
+    accessKeyId: SandboxProxySecret;
+    secretAccessKey: SandboxProxySecret;
+    roleArn?: "";
+};
+type AwsRoleAuthOptions = AwsAuthCommonOptions & {
+    roleArn: string;
+    accessKeyId?: never;
+    secretAccessKey?: never;
+};
+/**
+ * Sign supported AWS HTTPS requests using static keys or an IAM role.
+ * Role auth requires backend support and is configured at sandbox creation.
+ * LangSmith supplies the workspace External ID and renews credentials.
+ * A role in proxyConfig uses its effective IAM permissions; the same helper
+ * in mountConfig.auth uses the backend's mount-scoped S3 permissions.
+ */
+export declare function awsAuth(options: AwsStaticAuthOptions): SandboxAwsAuthRule<AwsStaticAuthConfig>;
+export declare function awsAuth(options: AwsRoleAuthOptions): SandboxAwsAuthRule<AwsRoleAuthConfig>;
+export declare function awsAuth(options: AwsStaticAuthOptions | AwsRoleAuthOptions): SandboxAwsAuthRule;
 /** Build a sandbox proxy rule that injects GCP OAuth bearer auth. */
 export declare function gcpAuth({ serviceAccountJson, scopes, name, enabled, envVars, }: {
     serviceAccountJson: SandboxProxySecret;
@@ -25,3 +51,4 @@ export declare function gcpAuth({ serviceAccountJson, scopes, name, enabled, env
     enabled?: boolean;
     envVars?: Record<string, string>;
 }): SandboxGcpAuthRule;
+export {};

package/dist/sandbox/proxy_config.js

@@ -42,6 +42,10 @@ function requireProxyRules(rules) {
     });
 }
 function validateProxyProviderRule(rule) {
+    if (rule.type === "aws") {
+        getAwsRoleArn(rule.aws);
+        return;
+    }
     if (rule.type !== "gcp") {
         return;
     }
@@ -51,6 +55,21 @@ function validateProxyProviderRule(rule) {
     }
     requireNonEmptyStringArray(gcp.scopes, "scopes");
 }
+/** Validate role-only descriptors without tightening legacy static inputs. */
+export function getAwsRoleArn(aws) {
+    if (aws === null || typeof aws !== "object" || Array.isArray(aws)) {
+        return undefined;
+    }
+    const config = aws;
+    if (!("role_arn" in config) || config.role_arn === "") {
+        return undefined;
+    }
+    const roleArn = requireNonEmptyString(config.role_arn, "roleArn");
+    if (Object.keys(config).some((key) => key !== "role_arn")) {
+        throw new Error("AWS role auth must contain only role_arn");
+    }
+    return roleArn;
+}
 /** Reference a LangSmith workspace secret in a sandbox proxy configuration. */
 export function workspaceSecret(name) {
     const normalized = requireNonEmptyString(name, "name");
@@ -75,28 +94,39 @@ export function opaqueSecret(value) {
     };
 }
 /** Build a sandbox proxy config from one or more proxy rules. */
-export function proxyConfig({ rules, noProxy, accessControl, } = {}) {
+export function proxyConfig({ rules, accessControl, } = {}) {
     const config = {
         rules: requireProxyRules(rules),
     };
-    if (noProxy !== undefined) {
-        config.no_proxy = requireNonEmptyStringArray(noProxy, "noProxy");
-    }
     if (accessControl !== undefined) {
         config.access_control = { ...accessControl };
     }
     return config;
 }
-/** Build a sandbox proxy rule that signs AWS HTTPS requests with SigV4. */
-export function awsAuth({ accessKeyId, secretAccessKey, name = "aws", enabled = true, envVars, }) {
+export function awsAuth({ accessKeyId, secretAccessKey, roleArn, name = "aws", enabled = true, envVars, }) {
+    const candidate = {};
+    if (roleArn !== undefined)
+        candidate.role_arn = roleArn;
+    if (accessKeyId !== undefined)
+        candidate.access_key_id = accessKeyId;
+    if (secretAccessKey !== undefined)
+        candidate.secret_access_key = secretAccessKey;
+    const normalizedRole = getAwsRoleArn(candidate);
+    let aws;
+    if (normalizedRole !== undefined) {
+        aws = { role_arn: normalizedRole };
+    }
+    else {
+        if (accessKeyId === undefined || secretAccessKey === undefined) {
+            throw new Error("AWS auth requires roleArn or both static credentials");
+        }
+        aws = { access_key_id: accessKeyId, secret_access_key: secretAccessKey };
+    }
     const rule = {
         name: requireNonEmptyString(name, "name"),
         type: "aws",
         enabled,
-        aws: {
-            access_key_id: accessKeyId,
-            secret_access_key: secretAccessKey,
-        },
+        aws,
     };
     if (envVars !== undefined) {
         rule.env_vars = requireEnvVars(envVars);

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.
      *