langsmith 0.10.3 → 0.10.5

package/dist/sandbox/client.cjs

@@ -4,6 +4,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SandboxClient = void 0;
+const access_delegation_js_1 = require("./access_delegation.cjs");
+const service_url_js_1 = require("./service_url.cjs");
 const env_js_1 = require("../utils/env.cjs");
 const fetch_js_1 = require("../singletons/fetch.cjs");
 const async_caller_js_1 = require("../utils/async_caller.cjs");
@@ -407,6 +409,53 @@ class SandboxClient {
         const suffix = segments.length ? `/${segments.join("/")}` : "";
         return `${this._baseUrl}/boxes/${encodeURIComponent(name)}${suffix}`;
     }
+    /**
+     * Generate an authenticated URL for an HTTP service running in a sandbox.
+     *
+     * Without `access`, mints a short-lived token and returns a {@link ServiceUrl}
+     * that refreshes it as it nears expiry. With `access` set to `"restricted"`
+     * or `"workspace"` the URL is gated by LangSmith login instead and a
+     * {@link ServiceLoginUrl} is returned: no token, no expiry, browser only.
+     *
+     * A login grant is durable, so token mode is refused with 409 while one is
+     * in place, and `expiresInSeconds` does not apply to the login modes.
+     */
+    async serviceUrl(name, options) {
+        const { port, expiresInSeconds, access, signal } = options;
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new errors_js_1.LangSmithValidationError(`port must be between 1 and 65535 (got ${port})`, "port");
+        }
+        if (access !== undefined &&
+            access !== "restricted" &&
+            access !== "workspace") {
+            throw new errors_js_1.LangSmithValidationError(`access must be "restricted" or "workspace" (got ${String(access)})`, "access");
+        }
+        const loginMode = access !== undefined;
+        if (expiresInSeconds !== undefined && loginMode) {
+            throw new errors_js_1.LangSmithValidationError(`expiresInSeconds does not apply to access "${access}": a LangSmith ` +
+                "login URL carries no token and does not expire", "expiresInSeconds");
+        }
+        const url = this._boxUrl(name, "service-url");
+        const payload = { port };
+        if (!loginMode && expiresInSeconds !== undefined) {
+            payload.expires_in_seconds = expiresInSeconds;
+        }
+        if (access !== undefined) {
+            payload.access = access;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const data = await response.json();
+        if (loginMode) {
+            return new service_url_js_1.ServiceLoginUrl(data);
+        }
+        // Refresh with the token parameters only. Carrying options.signal over
+        // would tie every later refresh to the first request's lifetime, so a
+        // caller-supplied timeout signal would leave the URL unable to refresh.
+        return new service_url_js_1.ServiceUrl(data, () => this.serviceUrl(name, {
+            port,
+            expiresInSeconds,
+        }));
+    }
     async _postJson(url, body, options) {
         const response = await this._fetch(url, {
             method: "POST",
@@ -424,7 +473,7 @@ class SandboxClient {
         const resolvedOptions = typeof snapshotIdOrOptions === "object" && snapshotIdOrOptions !== null
             ? snapshotIdOrOptions
             : options;
-        const { snapshotName, name, timeout = 30, waitForReady = true, idleTtlSeconds, deleteAfterStopSeconds, vCpus, memBytes, fsCapacityBytes, mountConfig, proxyConfig, } = resolvedOptions;
+        const { snapshotName, name, timeout = 30, waitForReady = true, idleTtlSeconds, deleteAfterStopSeconds, vCpus, memBytes, fsCapacityBytes, mountConfig, proxyConfig, runConfig, accessDelegation, } = resolvedOptions;
         if (snapshotId && snapshotName) {
             throw new errors_js_1.LangSmithValidationError("At most one of snapshotId or options.snapshotName may be set", "snapshotId");
         }
@@ -468,6 +517,12 @@ class SandboxClient {
         if (proxyConfig !== undefined) {
             payload.proxy_config = proxyConfig;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
+        if (accessDelegation !== undefined) {
+            payload.access_delegation = (0, access_delegation_js_1.validateAccessDelegation)(accessDelegation);
+        }
         const httpTimeout = waitForReady ? (timeout + 30) * 1000 : 30 * 1000;
         const response = await this._fetch(url, {
             method: "POST",
@@ -523,13 +578,14 @@ class SandboxClient {
         const options = typeof newNameOrOptions === "string"
             ? { newName: newNameOrOptions }
             : newNameOrOptions;
-        const { newName, idleTtlSeconds, deleteAfterStopSeconds, proxyConfig } = options;
+        const { newName, idleTtlSeconds, deleteAfterStopSeconds, proxyConfig, runConfig, } = options;
         (0, helpers_js_1.validateTtl)(idleTtlSeconds, "idleTtlSeconds");
         (0, helpers_js_1.validateTtl)(deleteAfterStopSeconds, "deleteAfterStopSeconds");
         if (newName === undefined &&
             idleTtlSeconds === undefined &&
             deleteAfterStopSeconds === undefined &&
-            proxyConfig === undefined) {
+            proxyConfig === undefined &&
+            runConfig === undefined) {
             return this.getSandbox(name);
         }
         const url = this._boxUrl(name);
@@ -546,6 +602,9 @@ class SandboxClient {
         if (proxyConfig !== undefined) {
             payload.proxy_config = proxyConfig;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._fetch(url, {
             method: "PATCH",
             headers: { "Content-Type": "application/json" },
@@ -730,7 +789,7 @@ class SandboxClient {
      * @returns Snapshot in "ready" status.
      */
     async createSnapshot(name, dockerImage, fsCapacityBytes, options = {}) {
-        const { registryId, timeout = 60, signal } = options;
+        const { registryId, runConfig, timeout = 60, signal } = options;
         const url = `${this._baseUrl}/snapshots`;
         const payload = {
             name,
@@ -740,6 +799,9 @@ class SandboxClient {
         if (registryId !== undefined) {
             payload.registry_id = registryId;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._postJson(url, payload, { signal });
         const snapshot = (await response.json());
         return this.waitForSnapshot(snapshot.id, { timeout, signal });
@@ -832,7 +894,7 @@ class SandboxClient {
      * @returns Snapshot in "ready" status.
      */
     async captureSnapshot(sandboxName, name, options = {}) {
-        const { dockerImage, fsCapacityBytes, timeout = 60, signal } = options;
+        const { dockerImage, fsCapacityBytes, runConfig, timeout = 60, signal, } = options;
         const url = this._boxUrl(sandboxName, "snapshot");
         const payload = { name };
         if (dockerImage !== undefined) {
@@ -841,6 +903,9 @@ class SandboxClient {
         if (fsCapacityBytes !== undefined) {
             payload.fs_capacity_bytes = fsCapacityBytes;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._postJson(url, payload, { signal });
         const snapshot = (await response.json());
         return this.waitForSnapshot(snapshot.id, { timeout, signal });

package/dist/sandbox/client.d.ts

@@ -1,6 +1,7 @@
 /**
  * Main SandboxClient class for interacting with the sandbox server API.
  */
+import { ServiceLoginUrl, ServiceUrl, type ServiceAccess } from "./service_url.js";
 import { Registries } from "../_openapi_client/resources/sandboxes/registries.js";
 import type { CaptureSnapshotOptions, CreateDockerfileSnapshotOptions, CreateSandboxOptions, CreateSnapshotOptions, DownloadURL, GenerateDownloadURLOptions, ListSnapshotsOptions, ResourceStatus, SandboxClientConfig, Snapshot, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, WaitForSnapshotOptions } from "./types.js";
 import { Sandbox } from "./sandbox.js";
@@ -64,6 +65,23 @@ export declare class SandboxClient {
      * ```
      */
     get registries(): Registries;
+    /**
+     * Generate an authenticated URL for an HTTP service running in a sandbox.
+     *
+     * Without `access`, mints a short-lived token and returns a {@link ServiceUrl}
+     * that refreshes it as it nears expiry. With `access` set to `"restricted"`
+     * or `"workspace"` the URL is gated by LangSmith login instead and a
+     * {@link ServiceLoginUrl} is returned: no token, no expiry, browser only.
+     *
+     * A login grant is durable, so token mode is refused with 409 while one is
+     * in place, and `expiresInSeconds` does not apply to the login modes.
+     */
+    serviceUrl(name: string, options: {
+        port: number;
+        expiresInSeconds?: number;
+        access?: ServiceAccess;
+        signal?: AbortSignal;
+    }): Promise<ServiceUrl | ServiceLoginUrl>;
     private _postJson;
     /**
      * Create a new Sandbox.

package/dist/sandbox/client.js

@@ -1,6 +1,8 @@
 /**
  * Main SandboxClient class for interacting with the sandbox server API.
  */
+import { validateAccessDelegation } from "./access_delegation.js";
+import { ServiceLoginUrl, ServiceUrl, } from "./service_url.js";
 import { getLangSmithEnvironmentVariable } from "../utils/env.js";
 import { _getFetchImplementation } from "../singletons/fetch.js";
 import { AsyncCaller } from "../utils/async_caller.js";
@@ -404,6 +406,53 @@ export class SandboxClient {
         const suffix = segments.length ? `/${segments.join("/")}` : "";
         return `${this._baseUrl}/boxes/${encodeURIComponent(name)}${suffix}`;
     }
+    /**
+     * Generate an authenticated URL for an HTTP service running in a sandbox.
+     *
+     * Without `access`, mints a short-lived token and returns a {@link ServiceUrl}
+     * that refreshes it as it nears expiry. With `access` set to `"restricted"`
+     * or `"workspace"` the URL is gated by LangSmith login instead and a
+     * {@link ServiceLoginUrl} is returned: no token, no expiry, browser only.
+     *
+     * A login grant is durable, so token mode is refused with 409 while one is
+     * in place, and `expiresInSeconds` does not apply to the login modes.
+     */
+    async serviceUrl(name, options) {
+        const { port, expiresInSeconds, access, signal } = options;
+        if (!Number.isInteger(port) || port < 1 || port > 65535) {
+            throw new LangSmithValidationError(`port must be between 1 and 65535 (got ${port})`, "port");
+        }
+        if (access !== undefined &&
+            access !== "restricted" &&
+            access !== "workspace") {
+            throw new LangSmithValidationError(`access must be "restricted" or "workspace" (got ${String(access)})`, "access");
+        }
+        const loginMode = access !== undefined;
+        if (expiresInSeconds !== undefined && loginMode) {
+            throw new LangSmithValidationError(`expiresInSeconds does not apply to access "${access}": a LangSmith ` +
+                "login URL carries no token and does not expire", "expiresInSeconds");
+        }
+        const url = this._boxUrl(name, "service-url");
+        const payload = { port };
+        if (!loginMode && expiresInSeconds !== undefined) {
+            payload.expires_in_seconds = expiresInSeconds;
+        }
+        if (access !== undefined) {
+            payload.access = access;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        const data = await response.json();
+        if (loginMode) {
+            return new ServiceLoginUrl(data);
+        }
+        // Refresh with the token parameters only. Carrying options.signal over
+        // would tie every later refresh to the first request's lifetime, so a
+        // caller-supplied timeout signal would leave the URL unable to refresh.
+        return new ServiceUrl(data, () => this.serviceUrl(name, {
+            port,
+            expiresInSeconds,
+        }));
+    }
     async _postJson(url, body, options) {
         const response = await this._fetch(url, {
             method: "POST",
@@ -421,7 +470,7 @@ export class SandboxClient {
         const resolvedOptions = typeof snapshotIdOrOptions === "object" && snapshotIdOrOptions !== null
             ? snapshotIdOrOptions
             : options;
-        const { snapshotName, name, timeout = 30, waitForReady = true, idleTtlSeconds, deleteAfterStopSeconds, vCpus, memBytes, fsCapacityBytes, mountConfig, proxyConfig, } = resolvedOptions;
+        const { snapshotName, name, timeout = 30, waitForReady = true, idleTtlSeconds, deleteAfterStopSeconds, vCpus, memBytes, fsCapacityBytes, mountConfig, proxyConfig, runConfig, accessDelegation, } = resolvedOptions;
         if (snapshotId && snapshotName) {
             throw new LangSmithValidationError("At most one of snapshotId or options.snapshotName may be set", "snapshotId");
         }
@@ -465,6 +514,12 @@ export class SandboxClient {
         if (proxyConfig !== undefined) {
             payload.proxy_config = proxyConfig;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
+        if (accessDelegation !== undefined) {
+            payload.access_delegation = validateAccessDelegation(accessDelegation);
+        }
         const httpTimeout = waitForReady ? (timeout + 30) * 1000 : 30 * 1000;
         const response = await this._fetch(url, {
             method: "POST",
@@ -520,13 +575,14 @@ export class SandboxClient {
         const options = typeof newNameOrOptions === "string"
             ? { newName: newNameOrOptions }
             : newNameOrOptions;
-        const { newName, idleTtlSeconds, deleteAfterStopSeconds, proxyConfig } = options;
+        const { newName, idleTtlSeconds, deleteAfterStopSeconds, proxyConfig, runConfig, } = options;
         validateTtl(idleTtlSeconds, "idleTtlSeconds");
         validateTtl(deleteAfterStopSeconds, "deleteAfterStopSeconds");
         if (newName === undefined &&
             idleTtlSeconds === undefined &&
             deleteAfterStopSeconds === undefined &&
-            proxyConfig === undefined) {
+            proxyConfig === undefined &&
+            runConfig === undefined) {
             return this.getSandbox(name);
         }
         const url = this._boxUrl(name);
@@ -543,6 +599,9 @@ export class SandboxClient {
         if (proxyConfig !== undefined) {
             payload.proxy_config = proxyConfig;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._fetch(url, {
             method: "PATCH",
             headers: { "Content-Type": "application/json" },
@@ -727,7 +786,7 @@ export class SandboxClient {
      * @returns Snapshot in "ready" status.
      */
     async createSnapshot(name, dockerImage, fsCapacityBytes, options = {}) {
-        const { registryId, timeout = 60, signal } = options;
+        const { registryId, runConfig, timeout = 60, signal } = options;
         const url = `${this._baseUrl}/snapshots`;
         const payload = {
             name,
@@ -737,6 +796,9 @@ export class SandboxClient {
         if (registryId !== undefined) {
             payload.registry_id = registryId;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._postJson(url, payload, { signal });
         const snapshot = (await response.json());
         return this.waitForSnapshot(snapshot.id, { timeout, signal });
@@ -829,7 +891,7 @@ export class SandboxClient {
      * @returns Snapshot in "ready" status.
      */
     async captureSnapshot(sandboxName, name, options = {}) {
-        const { dockerImage, fsCapacityBytes, timeout = 60, signal } = options;
+        const { dockerImage, fsCapacityBytes, runConfig, timeout = 60, signal, } = options;
         const url = this._boxUrl(sandboxName, "snapshot");
         const payload = { name };
         if (dockerImage !== undefined) {
@@ -838,6 +900,9 @@ export class SandboxClient {
         if (fsCapacityBytes !== undefined) {
             payload.fs_capacity_bytes = fsCapacityBytes;
         }
+        if (runConfig !== undefined) {
+            payload.run_config = runConfig;
+        }
         const response = await this._postJson(url, payload, { signal });
         const snapshot = (await response.json());
         return this.waitForSnapshot(snapshot.id, { timeout, signal });

package/dist/sandbox/command_handle.cjs

@@ -141,6 +141,18 @@ class CommandHandle {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_stdinClosed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_pty", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this._stream = messageStream;
         this._control = control;
         this._sandbox = sandbox;
@@ -148,6 +160,8 @@ class CommandHandle {
         this._lastStderrOffset = options?.stderrOffset ?? 0;
         this._onStdout = options?.onStdout;
         this._onStderr = options?.onStderr;
+        this._stdinClosed = options?.stdinClosed ?? false;
+        this._pty = options?.pty ?? false;
         // New executions (no commandId): _ensureStarted reads "started".
         // Reconnections (commandId set): skip since reconnect streams
         // don't send a "started" message.
@@ -319,10 +333,28 @@ class CommandHandle {
      * Write data to the command's stdin.
      */
     sendInput(data) {
+        if (this._stdinClosed) {
+            throw new errors_js_1.LangSmithSandboxOperationError("stdin is closed for this command. Non-PTY commands close stdin by " +
+                "default so a command that reads it sees EOF instead of hanging; " +
+                "pass closeInput: false to run() to stream input into it.", "sendInput");
+        }
         if (this._control) {
             this._control.sendInput(data);
         }
     }
+    /**
+     * Half-close stdin so the command reads EOF.
+     *
+     * Idempotent, and a no-op under a PTY, where input and output share one
+     * terminal file descriptor and there is no write end to close -- send an
+     * EOT byte (0x04) with {@link sendInput} instead.
+     */
+    closeInput() {
+        if (this._pty || this._stdinClosed)
+            return;
+        this._stdinClosed = true;
+        this._control?.sendCloseStdin();
+    }
     /** Last known stdout byte offset (for manual reconnection). */
     get lastStdoutOffset() {
         return this._lastStdoutOffset;
@@ -344,6 +376,8 @@ class CommandHandle {
         return this._sandbox.reconnect(this._commandId, {
             stdoutOffset: this._lastStdoutOffset,
             stderrOffset: this._lastStderrOffset,
+            stdinClosed: this._stdinClosed,
+            pty: this._pty,
         });
     }
 }

package/dist/sandbox/command_handle.d.ts

@@ -48,6 +48,8 @@ export declare class CommandHandle {
     private _reconnectAttempts;
     private _onStdout?;
     private _onStderr?;
+    private _stdinClosed;
+    private _pty;
     /**
      * Read the 'started' message to populate commandId and pid.
      *
@@ -87,6 +89,14 @@ export declare class CommandHandle {
      * Write data to the command's stdin.
      */
     sendInput(data: string): void;
+    /**
+     * Half-close stdin so the command reads EOF.
+     *
+     * Idempotent, and a no-op under a PTY, where input and output share one
+     * terminal file descriptor and there is no write end to close -- send an
+     * EOT byte (0x04) with {@link sendInput} instead.
+     */
+    closeInput(): void;
     /** Last known stdout byte offset (for manual reconnection). */
     get lastStdoutOffset(): number;
     /** Last known stderr byte offset (for manual reconnection). */

package/dist/sandbox/command_handle.js

@@ -138,6 +138,18 @@ export class CommandHandle {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_stdinClosed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "_pty", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this._stream = messageStream;
         this._control = control;
         this._sandbox = sandbox;
@@ -145,6 +157,8 @@ export class CommandHandle {
         this._lastStderrOffset = options?.stderrOffset ?? 0;
         this._onStdout = options?.onStdout;
         this._onStderr = options?.onStderr;
+        this._stdinClosed = options?.stdinClosed ?? false;
+        this._pty = options?.pty ?? false;
         // New executions (no commandId): _ensureStarted reads "started".
         // Reconnections (commandId set): skip since reconnect streams
         // don't send a "started" message.
@@ -316,10 +330,28 @@ export class CommandHandle {
      * Write data to the command's stdin.
      */
     sendInput(data) {
+        if (this._stdinClosed) {
+            throw new LangSmithSandboxOperationError("stdin is closed for this command. Non-PTY commands close stdin by " +
+                "default so a command that reads it sees EOF instead of hanging; " +
+                "pass closeInput: false to run() to stream input into it.", "sendInput");
+        }
         if (this._control) {
             this._control.sendInput(data);
         }
     }
+    /**
+     * Half-close stdin so the command reads EOF.
+     *
+     * Idempotent, and a no-op under a PTY, where input and output share one
+     * terminal file descriptor and there is no write end to close -- send an
+     * EOT byte (0x04) with {@link sendInput} instead.
+     */
+    closeInput() {
+        if (this._pty || this._stdinClosed)
+            return;
+        this._stdinClosed = true;
+        this._control?.sendCloseStdin();
+    }
     /** Last known stdout byte offset (for manual reconnection). */
     get lastStdoutOffset() {
         return this._lastStdoutOffset;
@@ -341,6 +373,8 @@ export class CommandHandle {
         return this._sandbox.reconnect(this._commandId, {
             stdoutOffset: this._lastStdoutOffset,
             stderrOffset: this._lastStderrOffset,
+            stdinClosed: this._stdinClosed,
+            pty: this._pty,
         });
     }
 }

package/dist/sandbox/helpers.cjs

@@ -14,6 +14,12 @@ exports.handleSandboxCreationError = handleSandboxCreationError;
 exports.throwIfNotReady = throwIfNotReady;
 exports.handleClientHttpError = handleClientHttpError;
 exports.handleSandboxHttpError = handleSandboxHttpError;
+exports.assertRunConfigNotCombined = assertRunConfigNotCombined;
+exports.resolveCloseInput = resolveCloseInput;
+exports.buildRangeHeader = buildRangeHeader;
+exports.fileStatFromResponse = fileStatFromResponse;
+exports.fileChunkFromResponse = fileChunkFromResponse;
+exports.handleFileHttpError = handleFileHttpError;
 const errors_js_1 = require("./errors.cjs");
 // =============================================================================
 // Input validation
@@ -268,3 +274,126 @@ async function handleSandboxHttpError(response) {
     }
     throw new errors_js_1.LangSmithSandboxError(message);
 }
+// =============================================================================
+// Run configuration
+// =============================================================================
+/**
+ * Reject a per-command `runConfig` alongside the deprecated `env`/`cwd`.
+ *
+ * The server answers 400 for a request carrying both spellings rather than
+ * letting one silently win, so refuse it here where the message can name the
+ * replacement.
+ */
+function assertRunConfigNotCombined(options) {
+    if (options.runConfig !== undefined &&
+        (options.env !== undefined || options.cwd !== undefined)) {
+        throw new errors_js_1.LangSmithValidationError("Cannot combine runConfig with the deprecated env/cwd options. " +
+            "Use runConfig.env_vars and runConfig.work_dir instead.");
+    }
+}
+/**
+ * Whether to half-close stdin at spawn.
+ *
+ * Defaults on for a non-PTY command: a command that reads stdin otherwise
+ * blocks on a pipe nobody writes to until the timeout kills it. A PTY has no
+ * separate write end to close, so the server ignores the flag there.
+ */
+function resolveCloseInput(closeInput, pty) {
+    if (pty)
+        return false;
+    return closeInput ?? true;
+}
+// =============================================================================
+// Ranged downloads
+// =============================================================================
+/** Render a byte range as an RFC 9110 `Range` header value. */
+function buildRangeHeader(options) {
+    const { start, end, suffixBytes } = options;
+    if (suffixBytes !== undefined) {
+        if (start !== undefined || end !== undefined) {
+            throw new errors_js_1.LangSmithValidationError("Cannot combine suffixBytes with start/end.");
+        }
+        if (suffixBytes <= 0) {
+            throw new errors_js_1.LangSmithValidationError("suffixBytes must be positive.");
+        }
+        return `bytes=-${suffixBytes}`;
+    }
+    if (start === undefined) {
+        throw new errors_js_1.LangSmithValidationError("Provide start (with optional end), or suffixBytes.");
+    }
+    if (start < 0) {
+        throw new errors_js_1.LangSmithValidationError("start must not be negative.");
+    }
+    if (end === undefined) {
+        return `bytes=${start}-`;
+    }
+    if (end < start) {
+        throw new errors_js_1.LangSmithValidationError("end must not precede start.");
+    }
+    return `bytes=${start}-${end}`;
+}
+/** Read the first byte offset and total size out of `Content-Range`. */
+function parseContentRange(value) {
+    if (!value || !value.startsWith("bytes "))
+        return { start: 0 };
+    const spec = value.slice("bytes ".length).trim();
+    const [rangePart, totalPart] = spec.split("/");
+    const first = rangePart.split("-")[0].trim();
+    const start = /^\d+$/.test(first) ? Number(first) : 0;
+    const total = /^\d+$/.test((totalPart ?? "").trim())
+        ? Number(totalPart)
+        : undefined;
+    return { start, total };
+}
+/** Build a FileStat from a HEAD response's headers. */
+function fileStatFromResponse(response) {
+    const length = response.headers.get("content-length");
+    return {
+        size_bytes: length && /^\d+$/.test(length) ? Number(length) : 0,
+        etag: response.headers.get("etag") ?? undefined,
+        last_modified: response.headers.get("last-modified") ?? undefined,
+        content_type: response.headers.get("content-type") ?? undefined,
+    };
+}
+/** Build a FileChunk from a ranged download response. */
+async function fileChunkFromResponse(response) {
+    const etag = response.headers.get("etag") ?? undefined;
+    const lastModified = response.headers.get("last-modified") ?? undefined;
+    if (response.status === 304) {
+        return {
+            content: new Uint8Array(0),
+            etag,
+            start: 0,
+            partial: false,
+            unchanged: true,
+            last_modified: lastModified,
+        };
+    }
+    const content = new Uint8Array(await response.arrayBuffer());
+    const partial = response.status === 206;
+    // A stale If-Range answers 200 with the whole file; the caller has to
+    // restart rather than append, so report it from byte zero.
+    const { start, total } = partial
+        ? parseContentRange(response.headers.get("content-range"))
+        : { start: 0, total: content.length };
+    return {
+        content,
+        etag,
+        total_bytes: total,
+        start,
+        partial,
+        unchanged: false,
+        last_modified: lastModified,
+    };
+}
+/** Map a file-operation HTTP error, including the non-JSON 416. */
+async function handleFileHttpError(response, path, sandboxName) {
+    if (response.status === 404) {
+        throw new errors_js_1.LangSmithResourceNotFoundError(`File '${path}' not found in sandbox '${sandboxName}'`, "file");
+    }
+    if (response.status === 416) {
+        throw new errors_js_1.LangSmithSandboxOperationError(`Requested range for '${path}' starts past the end of the file ` +
+            `(${response.headers.get("content-range") ?? "unknown size"}).`, "read");
+    }
+    return handleSandboxHttpError(response);
+}

package/dist/sandbox/helpers.d.ts

@@ -4,6 +4,7 @@
  * These functions are used to parse error responses and raise appropriate
  * exceptions. They contain no I/O operations.
  */
+import type { FileChunk, FileStat, ReadRangeOptions, RunConfig } from "./types.js";
 /**
  * Validate TTL values for sandbox create/update (minute resolution).
  *
@@ -76,4 +77,32 @@ export declare function handleClientHttpError(response: Response): Promise<never
  * - 403 -> LangSmithSandboxOperationError (permission denied)
  */
 export declare function handleSandboxHttpError(response: Response): Promise<never>;
+/**
+ * Reject a per-command `runConfig` alongside the deprecated `env`/`cwd`.
+ *
+ * The server answers 400 for a request carrying both spellings rather than
+ * letting one silently win, so refuse it here where the message can name the
+ * replacement.
+ */
+export declare function assertRunConfigNotCombined(options: {
+    runConfig?: RunConfig;
+    env?: Record<string, string>;
+    cwd?: string;
+}): void;
+/**
+ * Whether to half-close stdin at spawn.
+ *
+ * Defaults on for a non-PTY command: a command that reads stdin otherwise
+ * blocks on a pipe nobody writes to until the timeout kills it. A PTY has no
+ * separate write end to close, so the server ignores the flag there.
+ */
+export declare function resolveCloseInput(closeInput: boolean | undefined, pty: boolean): boolean;
+/** Render a byte range as an RFC 9110 `Range` header value. */
+export declare function buildRangeHeader(options: ReadRangeOptions): string;
+/** Build a FileStat from a HEAD response's headers. */
+export declare function fileStatFromResponse(response: Response): FileStat;
+/** Build a FileChunk from a ranged download response. */
+export declare function fileChunkFromResponse(response: Response): Promise<FileChunk>;
+/** Map a file-operation HTTP error, including the non-JSON 416. */
+export declare function handleFileHttpError(response: Response, path: string, sandboxName: string): Promise<never>;
 export {};