langsmith 0.8.10 → 0.8.12

package/dist/sandbox/client.js

@@ -400,6 +400,10 @@ export class SandboxClient {
      * Callers can add specific status checks (e.g. 404) before calling this.
      * @internal
      */
+    _boxUrl(name, ...segments) {
+        const suffix = segments.length ? `/${segments.join("/")}` : "";
+        return `${this._baseUrl}/boxes/${encodeURIComponent(name)}${suffix}`;
+    }
     async _postJson(url, body, options) {
         const response = await this._fetch(url, {
             method: "POST",
@@ -484,7 +488,7 @@ export class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async getSandbox(name, options) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
@@ -524,7 +528,7 @@ export class SandboxClient {
             deleteAfterStopSeconds === undefined) {
             return this.getSandbox(name);
         }
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const payload = {};
         if (newName !== undefined) {
             payload.name = newName;
@@ -561,7 +565,7 @@ export class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async deleteSandbox(name) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}`;
+        const url = this._boxUrl(name);
         const response = await this._fetch(url, { method: "DELETE" });
         if (!response.ok) {
             if (response.status === 404) {
@@ -581,7 +585,7 @@ export class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     async getSandboxStatus(name, options) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/status`;
+        const url = this._boxUrl(name, "status");
         const response = await this._fetch(url, { signal: options?.signal });
         if (!response.ok) {
             if (response.status === 404) {
@@ -644,17 +648,61 @@ export class SandboxClient {
      */
     async startSandbox(name, options = {}) {
         const { timeout = 120, signal } = options;
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/start`;
+        const url = this._boxUrl(name, "start");
         await this._postJson(url, {}, { signal });
         return this.waitForSandbox(name, { timeout, signal });
     }
+    /**
+     * Create a link that downloads one file from a sandbox.
+     *
+     * The link carries its own token, so anyone holding the URL can fetch that
+     * one file without a LangSmith credential. It is pinned to the sandbox and
+     * the exact path and cannot be repointed at another file. Fetching wakes a
+     * stopped sandbox.
+     *
+     * Do not modify the file after minting a link for it. The link is pinned to
+     * a path, not to a snapshot of the contents, so a later write to that path
+     * may or may not be reflected in what the link serves. Write a new file and
+     * mint a new link when the contents change.
+     *
+     * @param name - Sandbox name.
+     * @param path - File path inside the sandbox.
+     * @param options - Expiry and response header overrides.
+     * @returns The link and its expiry, if any.
+     *
+     * @example
+     * ```typescript
+     * const link = await client.generateDownloadURL("my-vm", "/tmp/report.pdf");
+     * console.log(link.download_url);
+     * ```
+     */
+    async generateDownloadURL(name, path, options = {}) {
+        const { expiresInSeconds, contentType, contentDisposition, signal } = options;
+        if (expiresInSeconds !== undefined && expiresInSeconds < 1) {
+            throw new LangSmithValidationError(`expiresInSeconds must be greater than 0 (got ${expiresInSeconds}); ` +
+                `omit it for a link that never expires`);
+        }
+        const url = this._boxUrl(name, "download-url");
+        const payload = { path };
+        if (expiresInSeconds !== undefined) {
+            payload.expires_in_seconds = expiresInSeconds;
+        }
+        if (contentType !== undefined) {
+            payload.content_type = contentType;
+        }
+        if (contentDisposition !== undefined) {
+            payload.content_disposition = contentDisposition;
+        }
+        const response = await this._postJson(url, payload, { signal });
+        return (await response.json());
+    }
     /**
      * Stop a running sandbox (preserves sandbox files for later restart).
      *
      * @param name - Sandbox name.
      */
     async stopSandbox(name) {
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/stop`;
+        const url = this._boxUrl(name, "stop");
         await this._postJson(url, {});
     }
     // =========================================================================
@@ -695,13 +743,19 @@ export class SandboxClient {
      *
      * @param name - Snapshot name.
      * @param dockerfile - Local Dockerfile path, relative to context by default.
-     * @param fsCapacityBytes - Filesystem capacity in bytes.
-     * @param options - Build context, args, target, build log callback, builder
-     *   vCPUs/memory, timeout.
+     * @param fsCapacityBytesOrOptions - Optional filesystem capacity in bytes, or
+     *   build options. When omitted, the server applies its default capacity.
+     * @param options - Build options when capacity is passed separately.
      * @returns Snapshot in "ready" status.
      */
-    async createSnapshotFromDockerfile(name, dockerfile, fsCapacityBytes, options = {}) {
-        const { context = ".", buildArgs, target, onBuildLog, vCpus, memBytes, timeout = 60, } = options;
+    async createSnapshotFromDockerfile(name, dockerfile, fsCapacityBytesOrOptions, options = {}) {
+        const fsCapacityBytes = typeof fsCapacityBytesOrOptions === "number"
+            ? fsCapacityBytesOrOptions
+            : undefined;
+        const resolvedOptions = typeof fsCapacityBytesOrOptions === "number"
+            ? options
+            : (fsCapacityBytesOrOptions ?? options);
+        const { context = ".", buildArgs, target, onBuildLog, vCpus, memBytes, timeout = 60, } = resolvedOptions;
         const { contextPath, dockerfileRel } = await resolveDockerfileContext(dockerfile, context);
         const builderName = `snapshot-builder-${uuidv4().replace(/-/g, "").slice(0, 12)}`;
         // Stage the build on the capacity-backed root filesystem, not /tmp.
@@ -769,7 +823,7 @@ export class SandboxClient {
      */
     async captureSnapshot(sandboxName, name, options = {}) {
         const { dockerImage, fsCapacityBytes, timeout = 60, signal } = options;
-        const url = `${this._baseUrl}/boxes/${encodeURIComponent(sandboxName)}/snapshot`;
+        const url = this._boxUrl(sandboxName, "snapshot");
         const payload = { name };
         if (dockerImage !== undefined) {
             payload.docker_image = dockerImage;

package/dist/sandbox/errors.cjs

@@ -7,7 +7,7 @@
  * properties for specific handling when needed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectTimeoutError = exports.LangSmithStreamEndedBeforeStartedError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = void 0;
+exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectTimeoutError = exports.LangSmithStreamEndedBeforeStartedError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxRetryableConnectionError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = void 0;
 /**
  * Base exception for sandbox client errors.
  */
@@ -53,6 +53,19 @@ class LangSmithSandboxConnectionError extends LangSmithSandboxError {
     }
 }
 exports.LangSmithSandboxConnectionError = LangSmithSandboxConnectionError;
+/**
+ * Raised when a transient connection failure occurs before a command starts.
+ *
+ * `run()` retries this error with the same command ID so the server can
+ * deduplicate an attempt whose outcome is unknown.
+ */
+class LangSmithSandboxRetryableConnectionError extends LangSmithSandboxConnectionError {
+    constructor(message) {
+        super(message);
+        this.name = "LangSmithSandboxRetryableConnectionError";
+    }
+}
+exports.LangSmithSandboxRetryableConnectionError = LangSmithSandboxRetryableConnectionError;
 // =============================================================================
 // Resource Errors (type-based, with resourceType property)
 // =============================================================================
@@ -375,12 +388,10 @@ exports.LangSmithStreamEndedBeforeStartedError = LangSmithStreamEndedBeforeStart
 /**
  * Thrown when the socket fails or times out before the WebSocket handshake.
  *
- * Distinct from its parent because it is safely retryable: the execute frame
- * was never sent, so re-issuing the same command_id cannot double-run a
- * command. run() retries this with backoff; a plain connection error (a
- * rejected handshake) is permanent and propagates immediately.
+ * The execute frame was never sent, so re-issuing the same command ID cannot
+ * double-run a command.
  */
-class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxRetryableConnectionError {
     constructor(message) {
         super(message);
         this.name = "LangSmithSandboxConnectTimeoutError";

package/dist/sandbox/errors.d.ts

@@ -31,6 +31,15 @@ export declare class LangSmithSandboxAuthenticationError extends LangSmithSandbo
 export declare class LangSmithSandboxConnectionError extends LangSmithSandboxError {
     constructor(message: string);
 }
+/**
+ * Raised when a transient connection failure occurs before a command starts.
+ *
+ * `run()` retries this error with the same command ID so the server can
+ * deduplicate an attempt whose outcome is unknown.
+ */
+export declare class LangSmithSandboxRetryableConnectionError extends LangSmithSandboxConnectionError {
+    constructor(message: string);
+}
 /**
  * Raised when a resource is not found.
  */
@@ -168,12 +177,10 @@ export declare class LangSmithStreamEndedBeforeStartedError extends LangSmithSan
 /**
  * Thrown when the socket fails or times out before the WebSocket handshake.
  *
- * Distinct from its parent because it is safely retryable: the execute frame
- * was never sent, so re-issuing the same command_id cannot double-run a
- * command. run() retries this with backoff; a plain connection error (a
- * rejected handshake) is permanent and propagates immediately.
+ * The execute frame was never sent, so re-issuing the same command ID cannot
+ * double-run a command.
  */
-export declare class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+export declare class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxRetryableConnectionError {
     constructor(message: string);
 }
 /**

package/dist/sandbox/errors.js

@@ -46,6 +46,18 @@ export class LangSmithSandboxConnectionError extends LangSmithSandboxError {
         this.name = "LangSmithSandboxConnectionError";
     }
 }
+/**
+ * Raised when a transient connection failure occurs before a command starts.
+ *
+ * `run()` retries this error with the same command ID so the server can
+ * deduplicate an attempt whose outcome is unknown.
+ */
+export class LangSmithSandboxRetryableConnectionError extends LangSmithSandboxConnectionError {
+    constructor(message) {
+        super(message);
+        this.name = "LangSmithSandboxRetryableConnectionError";
+    }
+}
 // =============================================================================
 // Resource Errors (type-based, with resourceType property)
 // =============================================================================
@@ -354,12 +366,10 @@ export class LangSmithStreamEndedBeforeStartedError extends LangSmithSandboxOper
 /**
  * Thrown when the socket fails or times out before the WebSocket handshake.
  *
- * Distinct from its parent because it is safely retryable: the execute frame
- * was never sent, so re-issuing the same command_id cannot double-run a
- * command. run() retries this with backoff; a plain connection error (a
- * rejected handshake) is permanent and propagates immediately.
+ * The execute frame was never sent, so re-issuing the same command ID cannot
+ * double-run a command.
  */
-export class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+export class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxRetryableConnectionError {
     constructor(message) {
         super(message);
         this.name = "LangSmithSandboxConnectTimeoutError";

package/dist/sandbox/index.cjs

@@ -29,7 +29,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectTimeoutError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = exports.s3Mount = exports.mountConfig = exports.gitMount = exports.gcsMount = exports.workspaceSecret = exports.proxyConfig = exports.opaqueSecret = exports.gcpAuth = exports.awsAuth = exports.CommandHandle = exports.Sandbox = exports.SandboxClient = void 0;
+exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithCommandTimeoutError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithSandboxCreationError = exports.LangSmithResourceCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxServerReloadError = exports.LangSmithSandboxConnectTimeoutError = exports.LangSmithSandboxRetryableConnectionError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = exports.s3Mount = exports.mountConfig = exports.gitMount = exports.gcsMount = exports.contextHubMount = exports.workspaceSecret = exports.proxyConfig = exports.opaqueSecret = exports.gcpAuth = exports.awsAuth = exports.CommandHandle = exports.Sandbox = exports.SandboxClient = void 0;
 // Main classes
 var client_js_1 = require("./client.cjs");
 Object.defineProperty(exports, "SandboxClient", { enumerable: true, get: function () { return client_js_1.SandboxClient; } });
@@ -44,6 +44,7 @@ Object.defineProperty(exports, "opaqueSecret", { enumerable: true, get: function
 Object.defineProperty(exports, "proxyConfig", { enumerable: true, get: function () { return proxy_config_js_1.proxyConfig; } });
 Object.defineProperty(exports, "workspaceSecret", { enumerable: true, get: function () { return proxy_config_js_1.workspaceSecret; } });
 var mounts_js_1 = require("./mounts.cjs");
+Object.defineProperty(exports, "contextHubMount", { enumerable: true, get: function () { return mounts_js_1.contextHubMount; } });
 Object.defineProperty(exports, "gcsMount", { enumerable: true, get: function () { return mounts_js_1.gcsMount; } });
 Object.defineProperty(exports, "gitMount", { enumerable: true, get: function () { return mounts_js_1.gitMount; } });
 Object.defineProperty(exports, "mountConfig", { enumerable: true, get: function () { return mounts_js_1.mountConfig; } });
@@ -55,6 +56,7 @@ Object.defineProperty(exports, "LangSmithSandboxError", { enumerable: true, get:
 Object.defineProperty(exports, "LangSmithSandboxAPIError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxAPIError; } });
 Object.defineProperty(exports, "LangSmithSandboxAuthenticationError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxAuthenticationError; } });
 Object.defineProperty(exports, "LangSmithSandboxConnectionError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxConnectionError; } });
+Object.defineProperty(exports, "LangSmithSandboxRetryableConnectionError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxRetryableConnectionError; } });
 Object.defineProperty(exports, "LangSmithSandboxConnectTimeoutError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxConnectTimeoutError; } });
 Object.defineProperty(exports, "LangSmithSandboxServerReloadError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxServerReloadError; } });
 // Resource errors (type-based with resourceType attribute)

package/dist/sandbox/index.d.ts

@@ -31,6 +31,6 @@ export { SandboxClient } from "./client.js";
 export { Sandbox } from "./sandbox.js";
 export { CommandHandle } from "./command_handle.js";
 export { awsAuth, gcpAuth, opaqueSecret, proxyConfig, workspaceSecret, } from "./proxy_config.js";
-export { gcsMount, gitMount, mountConfig, s3Mount } from "./mounts.js";
-export type { ExecutionResult, OutputChunk, WsMessage, WsRunOptions, ResourceStatus, Snapshot, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, SandboxAccessControl, SandboxAwsAuthRule, SandboxAwsMountAuthConfig, SandboxGcpAuthRule, SandboxGcpMountAuthConfig, SandboxMountAuth, SandboxMountAuthConfig, SandboxMountConfig, SandboxProxyConfig, SandboxProxyRule, SandboxProxySecret, SandboxMount, MountCacheConfig, GCSMountConfig, GCSMountSpec, GitMountConfig, GitMountRefSpec, GitMountSpec, S3MountConfig, S3MountSpec, CreateSnapshotOptions, CreateDockerfileSnapshotOptions, CaptureSnapshotOptions, ListSnapshotsOptions, WaitForSnapshotOptions, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, } from "./types.js";
-export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithCommandTimeoutError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";
+export { contextHubMount, gcsMount, gitMount, mountConfig, s3Mount, } from "./mounts.js";
+export type { ExecutionResult, OutputChunk, WsMessage, WsRunOptions, ResourceStatus, Snapshot, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, SandboxAccessControl, SandboxAwsAuthRule, SandboxAwsMountAuthConfig, SandboxGcpAuthRule, SandboxGcpMountAuthConfig, SandboxMountAuth, SandboxMountAuthConfig, SandboxMountConfig, SandboxProxyConfig, SandboxProxyRule, SandboxProxySecret, SandboxMount, MountCacheConfig, ContextHubMountConfig, ContextHubMountSpec, GCSMountConfig, GCSMountSpec, GitMountConfig, GitMountRefSpec, GitMountSpec, S3MountConfig, S3MountSpec, CreateSnapshotOptions, CreateDockerfileSnapshotOptions, CaptureSnapshotOptions, DownloadContentDisposition, DownloadURL, GenerateDownloadURLOptions, ListSnapshotsOptions, WaitForSnapshotOptions, StartSandboxOptions, UpdateSandboxOptions, WaitForSandboxOptions, } from "./types.js";
+export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxRetryableConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithCommandTimeoutError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";

package/dist/sandbox/index.js

@@ -32,11 +32,11 @@ export { SandboxClient } from "./client.js";
 export { Sandbox } from "./sandbox.js";
 export { CommandHandle } from "./command_handle.js";
 export { awsAuth, gcpAuth, opaqueSecret, proxyConfig, workspaceSecret, } from "./proxy_config.js";
-export { gcsMount, gitMount, mountConfig, s3Mount } from "./mounts.js";
+export { contextHubMount, gcsMount, gitMount, mountConfig, s3Mount, } from "./mounts.js";
 // Errors
 export { 
 // Base and connection errors
-LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, 
+LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxRetryableConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, 
 // Resource errors (type-based with resourceType attribute)
 LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, 
 // Validation and quota errors

package/dist/sandbox/mounts.cjs

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.s3Mount = s3Mount;
 exports.gitMount = gitMount;
 exports.gcsMount = gcsMount;
+exports.contextHubMount = contextHubMount;
 exports.mountConfig = mountConfig;
 exports.validateMountConfigProxyConfig = validateMountConfigProxyConfig;
 function requireNonEmptyString(value, field) {
@@ -132,6 +133,25 @@ function gcsMount({ id, mountPath, bucket, prefix, readOnly, cache, }) {
     }
     return mount;
 }
+/**
+ * Build a read-only Context Hub mount. The sync is one-way: files written
+ * under the mount path inside the sandbox are never pushed back to the repo,
+ * and the next sync overwrites them.
+ */
+function contextHubMount({ id, mountPath, repo, initialPullOnly, }) {
+    const mount = {
+        id: requireNonEmptyString(id, "id"),
+        type: "contexthub",
+        mount_path: requireNonEmptyString(mountPath, "mountPath"),
+        contexthub: {
+            repo: requireNonEmptyString(repo, "repo"),
+        },
+    };
+    if (initialPullOnly !== undefined) {
+        mount.contexthub.initial_pull_only = initialPullOnly;
+    }
+    return mount;
+}
 function normalizeMounts(mounts) {
     if (!Array.isArray(mounts) || mounts.length === 0) {
         throw new Error("mounts must be a non-empty array of mount objects");
@@ -140,8 +160,11 @@ function normalizeMounts(mounts) {
         if (mount === null || typeof mount !== "object" || Array.isArray(mount)) {
             throw new Error("mounts must be a non-empty array of mount objects");
         }
-        if (mount.type !== "s3" && mount.type !== "gcs" && mount.type !== "git") {
-            throw new Error("mountConfig only supports s3, gcs, and git mounts");
+        if (mount.type !== "s3" &&
+            mount.type !== "gcs" &&
+            mount.type !== "git" &&
+            mount.type !== "contexthub") {
+            throw new Error("mountConfig only supports s3, gcs, git, and contexthub mounts");
         }
         rejectProviderCredentialsInMount(mount);
         return mount;

package/dist/sandbox/mounts.d.ts

@@ -1,4 +1,4 @@
-import type { GCSMountSpec, GitMountRefSpec, GitMountSpec, MountCacheConfig, S3MountSpec, SandboxMount, SandboxMountAuth, SandboxMountConfig, SandboxProxyConfig } from "./types.js";
+import type { ContextHubMountSpec, GCSMountSpec, GitMountRefSpec, GitMountSpec, MountCacheConfig, S3MountSpec, SandboxMount, SandboxMountAuth, SandboxMountConfig, SandboxProxyConfig } from "./types.js";
 export declare function s3Mount({ id, mountPath, bucket, region, prefix, endpointUrl, pathStyle, readOnly, cache, }: {
     id: string;
     mountPath: string;
@@ -25,6 +25,17 @@ export declare function gcsMount({ id, mountPath, bucket, prefix, readOnly, cach
     readOnly?: boolean;
     cache?: MountCacheConfig;
 }): GCSMountSpec;
+/**
+ * Build a read-only Context Hub mount. The sync is one-way: files written
+ * under the mount path inside the sandbox are never pushed back to the repo,
+ * and the next sync overwrites them.
+ */
+export declare function contextHubMount({ id, mountPath, repo, initialPullOnly, }: {
+    id: string;
+    mountPath: string;
+    repo: string;
+    initialPullOnly?: boolean;
+}): ContextHubMountSpec;
 export declare function mountConfig({ auth, mounts, }: {
     auth?: SandboxMountAuth[];
     mounts: SandboxMount[];

package/dist/sandbox/mounts.js

@@ -125,6 +125,25 @@ export function gcsMount({ id, mountPath, bucket, prefix, readOnly, cache, }) {
     }
     return mount;
 }
+/**
+ * Build a read-only Context Hub mount. The sync is one-way: files written
+ * under the mount path inside the sandbox are never pushed back to the repo,
+ * and the next sync overwrites them.
+ */
+export function contextHubMount({ id, mountPath, repo, initialPullOnly, }) {
+    const mount = {
+        id: requireNonEmptyString(id, "id"),
+        type: "contexthub",
+        mount_path: requireNonEmptyString(mountPath, "mountPath"),
+        contexthub: {
+            repo: requireNonEmptyString(repo, "repo"),
+        },
+    };
+    if (initialPullOnly !== undefined) {
+        mount.contexthub.initial_pull_only = initialPullOnly;
+    }
+    return mount;
+}
 function normalizeMounts(mounts) {
     if (!Array.isArray(mounts) || mounts.length === 0) {
         throw new Error("mounts must be a non-empty array of mount objects");
@@ -133,8 +152,11 @@ function normalizeMounts(mounts) {
         if (mount === null || typeof mount !== "object" || Array.isArray(mount)) {
             throw new Error("mounts must be a non-empty array of mount objects");
         }
-        if (mount.type !== "s3" && mount.type !== "gcs" && mount.type !== "git") {
-            throw new Error("mountConfig only supports s3, gcs, and git mounts");
+        if (mount.type !== "s3" &&
+            mount.type !== "gcs" &&
+            mount.type !== "git" &&
+            mount.type !== "contexthub") {
+            throw new Error("mountConfig only supports s3, gcs, git, and contexthub mounts");
         }
         rejectProviderCredentialsInMount(mount);
         return mount;

package/dist/sandbox/proxy_config.cjs

@@ -17,6 +17,22 @@ function requireNonEmptyStringArray(values, field) {
     }
     return values.map((value) => requireNonEmptyString(value, field));
 }
+function requireEnvVars(envVars) {
+    if (envVars === null ||
+        typeof envVars !== "object" ||
+        Array.isArray(envVars)) {
+        throw new Error("envVars must be a non-empty object of names to values");
+    }
+    const entries = Object.entries(envVars);
+    if (entries.length === 0) {
+        throw new Error("envVars must be a non-empty object of names to values");
+    }
+    return Object.fromEntries(entries.map(([name, value]) => {
+        // Validated on the trimmed form, stored verbatim: whitespace can be significant.
+        requireNonEmptyString(value, `envVars[${name}]`);
+        return [requireNonEmptyString(name, "envVars name"), value];
+    }));
+}
 function requireProxyRules(rules) {
     if (rules === undefined) {
         return [];
@@ -79,8 +95,8 @@ function proxyConfig({ rules, noProxy, accessControl, } = {}) {
     return config;
 }
 /** Build a sandbox proxy rule that signs AWS HTTPS requests with SigV4. */
-function awsAuth({ accessKeyId, secretAccessKey, name = "aws", enabled = true, }) {
-    return {
+function awsAuth({ accessKeyId, secretAccessKey, name = "aws", enabled = true, envVars, }) {
+    const rule = {
         name: requireNonEmptyString(name, "name"),
         type: "aws",
         enabled,
@@ -89,19 +105,27 @@ function awsAuth({ accessKeyId, secretAccessKey, name = "aws", enabled = true, }
             secret_access_key: secretAccessKey,
         },
     };
+    if (envVars !== undefined) {
+        rule.env_vars = requireEnvVars(envVars);
+    }
+    return rule;
 }
 /** Build a sandbox proxy rule that injects GCP OAuth bearer auth. */
-function gcpAuth({ serviceAccountJson, scopes, name = "gcp", enabled = true, }) {
+function gcpAuth({ serviceAccountJson, scopes, name = "gcp", enabled = true, envVars, }) {
     const gcp = {
         service_account_json: serviceAccountJson,
     };
     if (scopes !== undefined) {
         gcp.scopes = requireNonEmptyStringArray(scopes, "scopes");
     }
-    return {
+    const rule = {
         name: requireNonEmptyString(name, "name"),
         type: "gcp",
         enabled,
         gcp,
     };
+    if (envVars !== undefined) {
+        rule.env_vars = requireEnvVars(envVars);
+    }
+    return rule;
 }

package/dist/sandbox/proxy_config.d.ts

@@ -10,16 +10,18 @@ export declare function proxyConfig({ rules, noProxy, accessControl, }?: {
     accessControl?: SandboxAccessControl;
 }): SandboxProxyConfig;
 /** Build a sandbox proxy rule that signs AWS HTTPS requests with SigV4. */
-export declare function awsAuth({ accessKeyId, secretAccessKey, name, enabled, }: {
+export declare function awsAuth({ accessKeyId, secretAccessKey, name, enabled, envVars, }: {
     accessKeyId: SandboxProxySecret;
     secretAccessKey: SandboxProxySecret;
     name?: string;
     enabled?: boolean;
+    envVars?: Record<string, string>;
 }): SandboxAwsAuthRule;
 /** Build a sandbox proxy rule that injects GCP OAuth bearer auth. */
-export declare function gcpAuth({ serviceAccountJson, scopes, name, enabled, }: {
+export declare function gcpAuth({ serviceAccountJson, scopes, name, enabled, envVars, }: {
     serviceAccountJson: SandboxProxySecret;
     scopes?: string[];
     name?: string;
     enabled?: boolean;
+    envVars?: Record<string, string>;
 }): SandboxGcpAuthRule;

package/dist/sandbox/proxy_config.js

@@ -10,6 +10,22 @@ function requireNonEmptyStringArray(values, field) {
     }
     return values.map((value) => requireNonEmptyString(value, field));
 }
+function requireEnvVars(envVars) {
+    if (envVars === null ||
+        typeof envVars !== "object" ||
+        Array.isArray(envVars)) {
+        throw new Error("envVars must be a non-empty object of names to values");
+    }
+    const entries = Object.entries(envVars);
+    if (entries.length === 0) {
+        throw new Error("envVars must be a non-empty object of names to values");
+    }
+    return Object.fromEntries(entries.map(([name, value]) => {
+        // Validated on the trimmed form, stored verbatim: whitespace can be significant.
+        requireNonEmptyString(value, `envVars[${name}]`);
+        return [requireNonEmptyString(name, "envVars name"), value];
+    }));
+}
 function requireProxyRules(rules) {
     if (rules === undefined) {
         return [];
@@ -72,8 +88,8 @@ export function proxyConfig({ rules, noProxy, accessControl, } = {}) {
     return config;
 }
 /** Build a sandbox proxy rule that signs AWS HTTPS requests with SigV4. */
-export function awsAuth({ accessKeyId, secretAccessKey, name = "aws", enabled = true, }) {
-    return {
+export function awsAuth({ accessKeyId, secretAccessKey, name = "aws", enabled = true, envVars, }) {
+    const rule = {
         name: requireNonEmptyString(name, "name"),
         type: "aws",
         enabled,
@@ -82,19 +98,27 @@ export function awsAuth({ accessKeyId, secretAccessKey, name = "aws", enabled =
             secret_access_key: secretAccessKey,
         },
     };
+    if (envVars !== undefined) {
+        rule.env_vars = requireEnvVars(envVars);
+    }
+    return rule;
 }
 /** Build a sandbox proxy rule that injects GCP OAuth bearer auth. */
-export function gcpAuth({ serviceAccountJson, scopes, name = "gcp", enabled = true, }) {
+export function gcpAuth({ serviceAccountJson, scopes, name = "gcp", enabled = true, envVars, }) {
     const gcp = {
         service_account_json: serviceAccountJson,
     };
     if (scopes !== undefined) {
         gcp.scopes = requireNonEmptyStringArray(scopes, "scopes");
     }
-    return {
+    const rule = {
         name: requireNonEmptyString(name, "name"),
         type: "gcp",
         enabled,
         gcp,
     };
+    if (envVars !== undefined) {
+        rule.env_vars = requireEnvVars(envVars);
+    }
+    return rule;
 }

package/dist/sandbox/sandbox.cjs

@@ -264,7 +264,7 @@ class Sandbox {
                 // Idempotent re-issue (same command_id): neither an early close nor a
                 // failed connect can have started a second command.
                 if (!(e instanceof errors_js_1.LangSmithStreamEndedBeforeStartedError) &&
-                    !(e instanceof errors_js_1.LangSmithSandboxConnectTimeoutError)) {
+                    !(e instanceof errors_js_1.LangSmithSandboxRetryableConnectionError)) {
                     throw e;
                 }
                 attempt++;
@@ -410,6 +410,32 @@ class Sandbox {
         const buffer = await response.arrayBuffer();
         return new Uint8Array(buffer);
     }
+    /**
+     * Create a link that downloads one file from this sandbox.
+     *
+     * The link carries its own token, so anyone holding the URL can fetch that
+     * one file without a LangSmith credential. Fetching wakes a stopped sandbox.
+     *
+     * Do not modify the file after minting a link for it. The link is pinned to
+     * a path, not to a snapshot of the contents, so a later write to that path
+     * may or may not be reflected in what the link serves. Write a new file and
+     * mint a new link when the contents change.
+     *
+     * @param path - File path inside the sandbox.
+     * @param options - Expiry and response header overrides.
+     * @returns The link and its expiry, if any.
+     *
+     * @example
+     * ```typescript
+     * const link = await sandbox.generateDownloadURL("/tmp/report.pdf", {
+     *   expiresInSeconds: 3600,
+     * });
+     * console.log(link.download_url);
+     * ```
+     */
+    async generateDownloadURL(path, options = {}) {
+        return this._client.generateDownloadURL(this.name, path, options);
+    }
     /**
      * Delete this sandbox.
      *