langsmith 0.8.6 → 0.8.8

package/dist/sandbox/errors.js

@@ -351,6 +351,20 @@ export class LangSmithStreamEndedBeforeStartedError extends LangSmithSandboxOper
         this.name = "LangSmithStreamEndedBeforeStartedError";
     }
 }
+/**
+ * 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.
+ */
+export class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+    constructor(message) {
+        super(message);
+        this.name = "LangSmithSandboxConnectTimeoutError";
+    }
+}
 /**
  * Raised when the sandbox server is reloading (close code 1001).
  *

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.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.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;
 // Main classes
 var client_js_1 = require("./client.cjs");
 Object.defineProperty(exports, "SandboxClient", { enumerable: true, get: function () { return client_js_1.SandboxClient; } });
@@ -55,6 +55,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, "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)
 Object.defineProperty(exports, "LangSmithResourceNotFoundError", { enumerable: true, get: function () { return errors_js_1.LangSmithResourceNotFoundError; } });

package/dist/sandbox/index.d.ts

@@ -33,4 +33,4 @@ 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, LangSmithSandboxServerReloadError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithCommandTimeoutError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";
+export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithCommandTimeoutError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";

package/dist/sandbox/index.js

@@ -36,7 +36,7 @@ export { gcsMount, gitMount, mountConfig, s3Mount } from "./mounts.js";
 // Errors
 export { 
 // Base and connection errors
-LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxServerReloadError, 
+LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxServerReloadError, 
 // Resource errors (type-based with resourceType attribute)
 LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, 
 // Validation and quota errors

package/dist/sandbox/sandbox.cjs

@@ -199,8 +199,9 @@ class Sandbox {
             // wait=true with callbacks: drain stream and return result
             return handle.result;
         }
-        // wait=true, no callbacks: try WS, fall back to HTTP
-        try {
+        // wait=true, no callbacks: use WebSocket when the 'ws' package is
+        // available, otherwise the blocking HTTP endpoint. WS errors propagate.
+        if (await this._wsAvailable()) {
             const handle = await this._runWs(command, {
                 ...restOptions,
                 idleTimeout,
@@ -210,17 +211,14 @@ class Sandbox {
             });
             return await handle.result;
         }
-        catch (e) {
-            // Fall back to HTTP on connection errors or missing ws package
-            const name = e != null && typeof e === "object" ? e.name : "";
-            const message = e != null && typeof e === "object" ? (e.message ?? "") : "";
-            if (name === "LangSmithSandboxConnectionError" ||
-                name === "LangSmithSandboxServerReloadError" ||
-                message.includes("'ws' package")) {
-                return this._runHttp(command, restOptions);
-            }
-            throw e;
-        }
+        return this._runHttp(command, restOptions);
+    }
+    /**
+     * Whether the optional `ws` package is importable (resolved once).
+     * @internal
+     */
+    _wsAvailable() {
+        return (0, ws_execute_js_1.isWsAvailable)();
     }
     /**
      * Execute a command via WebSocket streaming.
@@ -236,6 +234,7 @@ class Sandbox {
         // spawning a second one.
         const execCommandId = commandId ?? (0, uuid_js_1.uuid7)();
         let attempt = 0;
+        const deadline = (0, ws_execute_js_1.connectDeadline)();
         // eslint-disable-next-line no-constant-condition
         while (true) {
             const [stream, control] = await (0, ws_execute_js_1.runWsStream)(dataplaneUrl, this._client.getApiKey(), command, {
@@ -248,6 +247,7 @@ class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                openTimeout: (0, ws_execute_js_1.openTimeoutFor)(deadline),
                 ...(Object.keys(clientHeaders).length > 0
                     ? { headers: clientHeaders }
                     : {}),
@@ -261,16 +261,31 @@ class Sandbox {
                 return handle;
             }
             catch (e) {
-                // Idempotent re-issue (same command_id) after an early close.
-                if (!(e instanceof errors_js_1.LangSmithStreamEndedBeforeStartedError)) {
+                // 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)) {
                     throw e;
                 }
                 attempt++;
                 if (attempt > command_handle_js_1.CommandHandle.MAX_AUTO_RECONNECTS) {
                     throw e;
                 }
-                const delay = Math.min(command_handle_js_1.CommandHandle.BACKOFF_BASE * 2 ** (attempt - 1), command_handle_js_1.CommandHandle.BACKOFF_MAX);
+                let delay = Math.min(command_handle_js_1.CommandHandle.BACKOFF_BASE * 2 ** (attempt - 1), command_handle_js_1.CommandHandle.BACKOFF_MAX);
+                const remaining = (0, ws_execute_js_1.remainingBudget)(deadline);
+                if (remaining !== undefined) {
+                    if (remaining <= 0) {
+                        throw e;
+                    }
+                    delay = Math.min(delay, remaining);
+                }
                 await new Promise((r) => setTimeout(r, delay * 1000));
+                // Never start an attempt with no budget left: openTimeoutFor would
+                // return 0, which ws forwards to Node as "no timeout at all".
+                const left = (0, ws_execute_js_1.remainingBudget)(deadline);
+                if (left !== undefined && left <= 0) {
+                    throw e;
+                }
             }
         }
     }
@@ -428,8 +443,9 @@ class Sandbox {
      */
     async stop() {
         await this._client.stopSandbox(this.name);
+        // dataplane_url stays set: it is stable across stop/start and a request on
+        // it resumes the sandbox.
         this.status = "stopped";
-        this.dataplane_url = undefined;
     }
     /**
      * Capture a snapshot from this sandbox.

package/dist/sandbox/sandbox.d.ts

@@ -78,7 +78,8 @@ export declare class Sandbox {
      * Execute a command in the sandbox.
      *
      * When `wait` is true (default) and no streaming callbacks are provided,
-     * tries WebSocket first and falls back to HTTP POST.
+     * uses WebSocket, falling back to HTTP POST only when the optional `ws`
+     * package isn't installed.
      *
      * When `wait` is false or streaming callbacks are provided, uses WebSocket
      * (required). Returns a CommandHandle for streaming output.

package/dist/sandbox/sandbox.js

@@ -2,10 +2,10 @@
  * Sandbox class for interacting with a specific sandbox instance.
  */
 import { uuid7 } from "../uuid.js";
-import { LangSmithDataplaneNotConfiguredError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
+import { LangSmithDataplaneNotConfiguredError, LangSmithSandboxConnectTimeoutError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
 import { handleSandboxHttpError } from "./helpers.js";
 import { CommandHandle } from "./command_handle.js";
-import { reconnectWsStream, runWsStream } from "./ws_execute.js";
+import { connectDeadline, isWsAvailable, openTimeoutFor, reconnectWsStream, remainingBudget, runWsStream, } from "./ws_execute.js";
 /**
  * Represents an active sandbox for running commands and file operations.
  *
@@ -196,8 +196,9 @@ export class Sandbox {
             // wait=true with callbacks: drain stream and return result
             return handle.result;
         }
-        // wait=true, no callbacks: try WS, fall back to HTTP
-        try {
+        // wait=true, no callbacks: use WebSocket when the 'ws' package is
+        // available, otherwise the blocking HTTP endpoint. WS errors propagate.
+        if (await this._wsAvailable()) {
             const handle = await this._runWs(command, {
                 ...restOptions,
                 idleTimeout,
@@ -207,17 +208,14 @@ export class Sandbox {
             });
             return await handle.result;
         }
-        catch (e) {
-            // Fall back to HTTP on connection errors or missing ws package
-            const name = e != null && typeof e === "object" ? e.name : "";
-            const message = e != null && typeof e === "object" ? (e.message ?? "") : "";
-            if (name === "LangSmithSandboxConnectionError" ||
-                name === "LangSmithSandboxServerReloadError" ||
-                message.includes("'ws' package")) {
-                return this._runHttp(command, restOptions);
-            }
-            throw e;
-        }
+        return this._runHttp(command, restOptions);
+    }
+    /**
+     * Whether the optional `ws` package is importable (resolved once).
+     * @internal
+     */
+    _wsAvailable() {
+        return isWsAvailable();
     }
     /**
      * Execute a command via WebSocket streaming.
@@ -233,6 +231,7 @@ export class Sandbox {
         // spawning a second one.
         const execCommandId = commandId ?? uuid7();
         let attempt = 0;
+        const deadline = connectDeadline();
         // eslint-disable-next-line no-constant-condition
         while (true) {
             const [stream, control] = await runWsStream(dataplaneUrl, this._client.getApiKey(), command, {
@@ -245,6 +244,7 @@ export class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                openTimeout: openTimeoutFor(deadline),
                 ...(Object.keys(clientHeaders).length > 0
                     ? { headers: clientHeaders }
                     : {}),
@@ -258,16 +258,31 @@ export class Sandbox {
                 return handle;
             }
             catch (e) {
-                // Idempotent re-issue (same command_id) after an early close.
-                if (!(e instanceof LangSmithStreamEndedBeforeStartedError)) {
+                // Idempotent re-issue (same command_id): neither an early close nor a
+                // failed connect can have started a second command.
+                if (!(e instanceof LangSmithStreamEndedBeforeStartedError) &&
+                    !(e instanceof LangSmithSandboxConnectTimeoutError)) {
                     throw e;
                 }
                 attempt++;
                 if (attempt > CommandHandle.MAX_AUTO_RECONNECTS) {
                     throw e;
                 }
-                const delay = Math.min(CommandHandle.BACKOFF_BASE * 2 ** (attempt - 1), CommandHandle.BACKOFF_MAX);
+                let delay = Math.min(CommandHandle.BACKOFF_BASE * 2 ** (attempt - 1), CommandHandle.BACKOFF_MAX);
+                const remaining = remainingBudget(deadline);
+                if (remaining !== undefined) {
+                    if (remaining <= 0) {
+                        throw e;
+                    }
+                    delay = Math.min(delay, remaining);
+                }
                 await new Promise((r) => setTimeout(r, delay * 1000));
+                // Never start an attempt with no budget left: openTimeoutFor would
+                // return 0, which ws forwards to Node as "no timeout at all".
+                const left = remainingBudget(deadline);
+                if (left !== undefined && left <= 0) {
+                    throw e;
+                }
             }
         }
     }
@@ -425,8 +440,9 @@ export class Sandbox {
      */
     async stop() {
         await this._client.stopSandbox(this.name);
+        // dataplane_url stays set: it is stable across stop/start and a request on
+        // it resumes the sandbox.
         this.status = "stopped";
-        this.dataplane_url = undefined;
     }
     /**
      * Capture a snapshot from this sandbox.

package/dist/sandbox/ws_execute.cjs

@@ -6,22 +6,72 @@
  * Install with: npm install ws
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.WSStreamControl = void 0;
+exports.WSStreamControl = exports.WS_CONNECT_BUDGET = exports.WS_OPEN_TIMEOUT = void 0;
+exports.connectDeadline = connectDeadline;
+exports.remainingBudget = remainingBudget;
+exports.openTimeoutFor = openTimeoutFor;
+exports.isWsAvailable = isWsAvailable;
 exports.buildWsUrl = buildWsUrl;
 exports.buildAuthHeaders = buildAuthHeaders;
 exports.raiseForWsError = raiseForWsError;
 exports.runWsStream = runWsStream;
 exports.reconnectWsStream = reconnectWsStream;
 const errors_js_1 = require("./errors.cjs");
-async function ensureWs() {
-    try {
-        const ws = await import("ws");
-        return { WebSocket: ws.default || ws.WebSocket || ws };
+const env_js_1 = require("../utils/env.cjs");
+/** Read a WebSocket timeout override, in seconds. `<= 0` disables it. */
+function envTimeout(name, defaultSeconds) {
+    const raw = (0, env_js_1.getLangSmithEnvironmentVariable)(name);
+    if (raw === undefined || raw.trim() === "")
+        return defaultSeconds;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        console.warn(`Ignoring invalid LANGSMITH_${name}=${raw}, using ${defaultSeconds}`);
+        return defaultSeconds;
     }
-    catch {
+    return value > 0 ? value : undefined;
+}
+// A slow cold start is recovered by the retry loop in run(), not by waiting here.
+exports.WS_OPEN_TIMEOUT = envTimeout("SANDBOX_WS_TIMEOUT_OPEN", 30);
+// Ceiling on the whole connect phase. Without it, retrying a blackholed
+// handshake costs MAX_AUTO_RECONNECTS + 1 full open timeouts plus backoff.
+exports.WS_CONNECT_BUDGET = envTimeout("SANDBOX_WS_TIMEOUT_CONNECT_BUDGET", 120);
+function nowSeconds() {
+    return performance.now() / 1000;
+}
+/** Instant after which connect attempts must stop, if bounded. */
+function connectDeadline() {
+    return exports.WS_CONNECT_BUDGET === undefined
+        ? undefined
+        : nowSeconds() + exports.WS_CONNECT_BUDGET;
+}
+/** Seconds left in the connect budget, or undefined when unbounded. */
+function remainingBudget(deadline) {
+    return deadline === undefined ? undefined : deadline - nowSeconds();
+}
+/** Per-attempt open timeout, clamped so it cannot outlive `deadline`. */
+function openTimeoutFor(deadline) {
+    if (deadline === undefined)
+        return exports.WS_OPEN_TIMEOUT;
+    const remaining = Math.max(deadline - nowSeconds(), 0);
+    return exports.WS_OPEN_TIMEOUT === undefined
+        ? remaining
+        : Math.min(exports.WS_OPEN_TIMEOUT, remaining);
+}
+// Load the optional 'ws' package once, at module load, instead of importing on
+// every call. Resolves to the WebSocket constructor, or null if 'ws' isn't
+// installed. run() reads isWsAvailable() to choose WS vs the HTTP fallback.
+const wsWebSocketPromise = import("ws").then((ws) => ws.default || ws.WebSocket || ws, () => null);
+/** Whether the optional `ws` package could be loaded (resolved once). */
+async function isWsAvailable() {
+    return (await wsWebSocketPromise) !== null;
+}
+async function ensureWs() {
+    const WebSocket = await wsWebSocketPromise;
+    if (!WebSocket) {
         throw new Error("WebSocket-based execution requires the 'ws' package. " +
             "Install it with: npm install ws");
     }
+    return { WebSocket };
 }
 // =============================================================================
 // URL and Auth Helpers
@@ -133,18 +183,42 @@ function raiseForWsError(msg, commandId = "") {
 /**
  * Create a ws WebSocket connection and return a promise that resolves when open
  * or rejects on error.
+ *
+ * A socket-level failure rejects with the retryable connect-timeout error; a
+ * non-101 response rejects with the permanent connection error.
  */
-async function connectWs(url, headers) {
+async function connectWs(url, headers, openTimeout = exports.WS_OPEN_TIMEOUT) {
     const { WebSocket: WS } = await ensureWs();
     return new Promise((resolve, reject) => {
-        const ws = new WS(url, { headers });
+        const ws = new WS(url, {
+            headers,
+            handshakeTimeout: openTimeout === undefined ? undefined : openTimeout * 1000,
+        });
+        let settled = false;
         ws.on("open", () => {
-            ws.removeAllListeners("error");
+            if (settled)
+                return;
+            settled = true;
             resolve(ws);
         });
+        // Attaching this suppresses ws's own "error" for a non-101 response, so the
+        // rejected upgrade cannot be misreported as a retryable socket failure. ws
+        // leaves cleanup to the handler once a listener is present.
+        ws.on("unexpected-response", (req, res) => {
+            res.resume?.();
+            req.destroy?.();
+            if (settled)
+                return;
+            settled = true;
+            reject(new errors_js_1.LangSmithSandboxConnectionError(`WebSocket upgrade to ${url} rejected by server (HTTP ${res.statusCode})`));
+        });
+        // Stays attached after settling so a late error has a listener and cannot
+        // become an unhandled 'error' event.
         ws.on("error", (err) => {
-            ws.removeAllListeners("open");
-            reject(new errors_js_1.LangSmithSandboxConnectionError(`Failed to connect to sandbox WebSocket: ${err.message}`));
+            if (settled)
+                return;
+            settled = true;
+            reject(new errors_js_1.LangSmithSandboxConnectTimeoutError(`Failed to connect to sandbox WebSocket: ${err.message}`));
         });
     });
 }
@@ -242,14 +316,14 @@ async function* readWsMessages(ws) {
  * data arrives in addition to yielding the messages.
  */
 async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
-    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, } = options;
+    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, openTimeout = exports.WS_OPEN_TIMEOUT, } = options;
     const wsUrl = buildWsUrl(dataplaneUrl);
     const headers = buildAuthHeaders(apiKey, extraHeaders);
     const control = new WSStreamControl();
     async function* stream() {
         let ws;
         try {
-            ws = await connectWs(wsUrl, headers);
+            ws = await connectWs(wsUrl, headers, openTimeout);
             control._bind(ws);
             // Send execute request
             const payload = {

package/dist/sandbox/ws_execute.d.ts

@@ -5,7 +5,17 @@
  * Install with: npm install ws
  */
 import type { WsMessage, WsRunOptions } from "./types.js";
+export declare const WS_OPEN_TIMEOUT: number | undefined;
+export declare const WS_CONNECT_BUDGET: number | undefined;
+/** Instant after which connect attempts must stop, if bounded. */
+export declare function connectDeadline(): number | undefined;
+/** Seconds left in the connect budget, or undefined when unbounded. */
+export declare function remainingBudget(deadline: number | undefined): number | undefined;
+/** Per-attempt open timeout, clamped so it cannot outlive `deadline`. */
+export declare function openTimeoutFor(deadline: number | undefined): number | undefined;
 type WsWebSocket = any;
+/** Whether the optional `ws` package could be loaded (resolved once). */
+export declare function isWsAvailable(): Promise<boolean>;
 /**
  * Convert a dataplane HTTP URL to a WebSocket URL for /execute/ws.
  */

package/dist/sandbox/ws_execute.js

@@ -4,16 +4,62 @@
  * Uses the `ws` npm package (optional peer dependency).
  * Install with: npm install ws
  */
-import { LangSmithCommandTimeoutError, LangSmithSandboxConnectionError, LangSmithSandboxOperationError, LangSmithSandboxServerReloadError, } from "./errors.js";
-async function ensureWs() {
-    try {
-        const ws = await import("ws");
-        return { WebSocket: ws.default || ws.WebSocket || ws };
+import { LangSmithCommandTimeoutError, LangSmithSandboxConnectionError, LangSmithSandboxConnectTimeoutError, LangSmithSandboxOperationError, LangSmithSandboxServerReloadError, } from "./errors.js";
+import { getLangSmithEnvironmentVariable } from "../utils/env.js";
+/** Read a WebSocket timeout override, in seconds. `<= 0` disables it. */
+function envTimeout(name, defaultSeconds) {
+    const raw = getLangSmithEnvironmentVariable(name);
+    if (raw === undefined || raw.trim() === "")
+        return defaultSeconds;
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        console.warn(`Ignoring invalid LANGSMITH_${name}=${raw}, using ${defaultSeconds}`);
+        return defaultSeconds;
     }
-    catch {
+    return value > 0 ? value : undefined;
+}
+// A slow cold start is recovered by the retry loop in run(), not by waiting here.
+export const WS_OPEN_TIMEOUT = envTimeout("SANDBOX_WS_TIMEOUT_OPEN", 30);
+// Ceiling on the whole connect phase. Without it, retrying a blackholed
+// handshake costs MAX_AUTO_RECONNECTS + 1 full open timeouts plus backoff.
+export const WS_CONNECT_BUDGET = envTimeout("SANDBOX_WS_TIMEOUT_CONNECT_BUDGET", 120);
+function nowSeconds() {
+    return performance.now() / 1000;
+}
+/** Instant after which connect attempts must stop, if bounded. */
+export function connectDeadline() {
+    return WS_CONNECT_BUDGET === undefined
+        ? undefined
+        : nowSeconds() + WS_CONNECT_BUDGET;
+}
+/** Seconds left in the connect budget, or undefined when unbounded. */
+export function remainingBudget(deadline) {
+    return deadline === undefined ? undefined : deadline - nowSeconds();
+}
+/** Per-attempt open timeout, clamped so it cannot outlive `deadline`. */
+export function openTimeoutFor(deadline) {
+    if (deadline === undefined)
+        return WS_OPEN_TIMEOUT;
+    const remaining = Math.max(deadline - nowSeconds(), 0);
+    return WS_OPEN_TIMEOUT === undefined
+        ? remaining
+        : Math.min(WS_OPEN_TIMEOUT, remaining);
+}
+// Load the optional 'ws' package once, at module load, instead of importing on
+// every call. Resolves to the WebSocket constructor, or null if 'ws' isn't
+// installed. run() reads isWsAvailable() to choose WS vs the HTTP fallback.
+const wsWebSocketPromise = import("ws").then((ws) => ws.default || ws.WebSocket || ws, () => null);
+/** Whether the optional `ws` package could be loaded (resolved once). */
+export async function isWsAvailable() {
+    return (await wsWebSocketPromise) !== null;
+}
+async function ensureWs() {
+    const WebSocket = await wsWebSocketPromise;
+    if (!WebSocket) {
         throw new Error("WebSocket-based execution requires the 'ws' package. " +
             "Install it with: npm install ws");
     }
+    return { WebSocket };
 }
 // =============================================================================
 // URL and Auth Helpers
@@ -124,18 +170,42 @@ export function raiseForWsError(msg, commandId = "") {
 /**
  * Create a ws WebSocket connection and return a promise that resolves when open
  * or rejects on error.
+ *
+ * A socket-level failure rejects with the retryable connect-timeout error; a
+ * non-101 response rejects with the permanent connection error.
  */
-async function connectWs(url, headers) {
+async function connectWs(url, headers, openTimeout = WS_OPEN_TIMEOUT) {
     const { WebSocket: WS } = await ensureWs();
     return new Promise((resolve, reject) => {
-        const ws = new WS(url, { headers });
+        const ws = new WS(url, {
+            headers,
+            handshakeTimeout: openTimeout === undefined ? undefined : openTimeout * 1000,
+        });
+        let settled = false;
         ws.on("open", () => {
-            ws.removeAllListeners("error");
+            if (settled)
+                return;
+            settled = true;
             resolve(ws);
         });
+        // Attaching this suppresses ws's own "error" for a non-101 response, so the
+        // rejected upgrade cannot be misreported as a retryable socket failure. ws
+        // leaves cleanup to the handler once a listener is present.
+        ws.on("unexpected-response", (req, res) => {
+            res.resume?.();
+            req.destroy?.();
+            if (settled)
+                return;
+            settled = true;
+            reject(new LangSmithSandboxConnectionError(`WebSocket upgrade to ${url} rejected by server (HTTP ${res.statusCode})`));
+        });
+        // Stays attached after settling so a late error has a listener and cannot
+        // become an unhandled 'error' event.
         ws.on("error", (err) => {
-            ws.removeAllListeners("open");
-            reject(new LangSmithSandboxConnectionError(`Failed to connect to sandbox WebSocket: ${err.message}`));
+            if (settled)
+                return;
+            settled = true;
+            reject(new LangSmithSandboxConnectTimeoutError(`Failed to connect to sandbox WebSocket: ${err.message}`));
         });
     });
 }
@@ -233,14 +303,14 @@ async function* readWsMessages(ws) {
  * data arrives in addition to yielding the messages.
  */
 export async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
-    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, } = options;
+    const { timeout = 60, env, cwd, shell = "/bin/bash", onStdout, onStderr, commandId, idleTimeout = 300, killOnDisconnect = false, ttlSeconds = 600, pty, headers: extraHeaders, openTimeout = WS_OPEN_TIMEOUT, } = options;
     const wsUrl = buildWsUrl(dataplaneUrl);
     const headers = buildAuthHeaders(apiKey, extraHeaders);
     const control = new WSStreamControl();
     async function* stream() {
         let ws;
         try {
-            ws = await connectWs(wsUrl, headers);
+            ws = await connectWs(wsUrl, headers, openTimeout);
             control._bind(ws);
             // Send execute request
             const payload = {

package/package.json

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

package/dist/utils/constants.cjs

@@ -1,4 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports._MIN_BACKEND_VERSION = void 0;
-exports._MIN_BACKEND_VERSION = "0.16.14rc1";

package/dist/utils/constants.d.ts

@@ -1 +0,0 @@
-export declare const _MIN_BACKEND_VERSION = "0.16.14rc1";

package/dist/utils/constants.js

@@ -1 +0,0 @@
-export const _MIN_BACKEND_VERSION = "0.16.14rc1";