langsmith 0.8.7 → 0.8.9

package/dist/index.cjs

@@ -35,6 +35,6 @@ Object.defineProperty(exports, "UnprocessableEntityError", { enumerable: true, g
 Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return error_js_1.RateLimitError; } });
 Object.defineProperty(exports, "InternalServerError", { enumerable: true, get: function () { return error_js_1.InternalServerError; } });
 // Update using pnpm bump-version
-exports.__version__ = "0.8.7";
+exports.__version__ = "0.8.9";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 exports.LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/index.d.ts

@@ -7,5 +7,5 @@ export { computeRunIdForSecondaryReplica, uuid7, uuid7FromTime, } from "./uuid.j
 export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, type CacheConfig, type CacheMetrics, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
-export declare const __version__ = "0.8.7";
+export declare const __version__ = "0.8.9";
 export declare const LS_MESSAGE_VIEW_EXCLUDE: "ls_message_view_exclude";

package/dist/index.js

@@ -7,6 +7,6 @@ export { isTracingEnabled } from "./utils/guard.js";
 export { Cache, PromptCache, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 export { LangsmithError, APIError, APIUserAbortError, APIConnectionError, APIConnectionTimeoutError, BadRequestError, AuthenticationError, PermissionDeniedError, NotFoundError, ConflictError, UnprocessableEntityError, RateLimitError, InternalServerError, } from "./_openapi_client/core/error.js";
 // Update using pnpm bump-version
-export const __version__ = "0.8.7";
+export const __version__ = "0.8.9";
 // Metadata key to hide a traced run from LangSmith's Messages View.
 export const LS_MESSAGE_VIEW_EXCLUDE = "ls_message_view_exclude";

package/dist/sandbox/command_handle.cjs

@@ -8,6 +8,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CommandHandle = void 0;
 const errors_js_1 = require("./errors.cjs");
+/**
+ * Whether a 'started' frame proves *this* command was reattached to.
+ *
+ * A command and its WebSocket are separate things: the command keeps running on
+ * the server and the socket is only this client's attachment to it. The server
+ * acknowledges every successful reattachment with 'started', which for a command
+ * that produces no output is the only evidence it landed. One naming a different
+ * command is not evidence, and must not clear the reconnect budget.
+ */
+function acknowledgesReconnect(msg, commandId) {
+    const acked = msg.command_id;
+    if (acked === commandId)
+        return true;
+    console.warn(`Ignoring reconnect acknowledgement for command ${String(acked)} while attached to ${String(commandId)}`);
+    return false;
+}
 /**
  * Async handle to a running command with streaming output and auto-reconnect.
  *
@@ -107,6 +123,12 @@ class CommandHandle {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_reconnectAttempts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
         Object.defineProperty(this, "_onStdout", {
             enumerable: true,
             configurable: true,
@@ -192,7 +214,12 @@ class CommandHandle {
             return;
         for await (const msg of this._stream) {
             const msgType = msg.type;
-            if (msgType === "stdout" || msgType === "stderr") {
+            if (msgType === "started") {
+                if (acknowledgesReconnect(msg, this._commandId)) {
+                    this._reconnectAttempts = 0;
+                }
+            }
+            else if (msgType === "stdout" || msgType === "stderr") {
                 const chunk = {
                     stream: msgType,
                     data: msg.data,
@@ -227,11 +254,11 @@ class CommandHandle {
      * - After kill():                  no reconnect, error propagates
      */
     async *[Symbol.asyncIterator]() {
-        let reconnectAttempts = 0;
+        this._reconnectAttempts = 0;
         while (true) {
             try {
                 for await (const chunk of this._iterStream()) {
-                    reconnectAttempts = 0; // Reset on successful data
+                    this._reconnectAttempts = 0; // Reset on successful data
                     if (chunk.stream === "stdout") {
                         this._lastStdoutOffset =
                             chunk.offset + new TextEncoder().encode(chunk.data).length;
@@ -247,21 +274,21 @@ class CommandHandle {
                 return; // Stream ended normally (exit message received)
             }
             catch (e) {
-                const eName = e != null && typeof e === "object" ? e.name : "";
-                if (eName !== "LangSmithSandboxConnectionError" &&
-                    eName !== "LangSmithSandboxServerReloadError") {
+                // instanceof, not a name check: subclasses (connect timeout, server
+                // reload) must stay retryable here.
+                if (!(e instanceof errors_js_1.LangSmithSandboxConnectionError)) {
                     throw e;
                 }
                 if (this._control && this._control.killed) {
                     throw e;
                 }
-                reconnectAttempts++;
-                if (reconnectAttempts > CommandHandle.MAX_AUTO_RECONNECTS) {
-                    throw new errors_js_1.LangSmithSandboxConnectionError(`Lost connection ${reconnectAttempts} times in succession, giving up`);
+                this._reconnectAttempts++;
+                if (this._reconnectAttempts > CommandHandle.MAX_AUTO_RECONNECTS) {
+                    throw new errors_js_1.LangSmithSandboxConnectionError(`Failed to reattach to the command ${this._reconnectAttempts} times in succession, giving up`);
                 }
-                const isHotReload = eName === "LangSmithSandboxServerReloadError";
+                const isHotReload = e instanceof errors_js_1.LangSmithSandboxServerReloadError;
                 if (!isHotReload) {
-                    const delay = Math.min(CommandHandle.BACKOFF_BASE * 2 ** (reconnectAttempts - 1), CommandHandle.BACKOFF_MAX);
+                    const delay = Math.min(CommandHandle.BACKOFF_BASE * 2 ** (this._reconnectAttempts - 1), CommandHandle.BACKOFF_MAX);
                     await new Promise((r) => setTimeout(r, delay * 1000));
                 }
                 if (this._commandId === null) {

package/dist/sandbox/command_handle.d.ts

@@ -45,6 +45,7 @@ export declare class CommandHandle {
     private _lastStdoutOffset;
     private _lastStderrOffset;
     private _started;
+    private _reconnectAttempts;
     private _onStdout?;
     private _onStderr?;
     /**

package/dist/sandbox/command_handle.js

@@ -4,7 +4,23 @@
  *
  * Port of Python's AsyncCommandHandle to TypeScript.
  */
-import { LangSmithSandboxConnectionError, LangSmithSandboxOperationError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
+import { LangSmithSandboxConnectionError, LangSmithSandboxServerReloadError, LangSmithSandboxOperationError, LangSmithStreamEndedBeforeStartedError, } from "./errors.js";
+/**
+ * Whether a 'started' frame proves *this* command was reattached to.
+ *
+ * A command and its WebSocket are separate things: the command keeps running on
+ * the server and the socket is only this client's attachment to it. The server
+ * acknowledges every successful reattachment with 'started', which for a command
+ * that produces no output is the only evidence it landed. One naming a different
+ * command is not evidence, and must not clear the reconnect budget.
+ */
+function acknowledgesReconnect(msg, commandId) {
+    const acked = msg.command_id;
+    if (acked === commandId)
+        return true;
+    console.warn(`Ignoring reconnect acknowledgement for command ${String(acked)} while attached to ${String(commandId)}`);
+    return false;
+}
 /**
  * Async handle to a running command with streaming output and auto-reconnect.
  *
@@ -104,6 +120,12 @@ export class CommandHandle {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_reconnectAttempts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
         Object.defineProperty(this, "_onStdout", {
             enumerable: true,
             configurable: true,
@@ -189,7 +211,12 @@ export class CommandHandle {
             return;
         for await (const msg of this._stream) {
             const msgType = msg.type;
-            if (msgType === "stdout" || msgType === "stderr") {
+            if (msgType === "started") {
+                if (acknowledgesReconnect(msg, this._commandId)) {
+                    this._reconnectAttempts = 0;
+                }
+            }
+            else if (msgType === "stdout" || msgType === "stderr") {
                 const chunk = {
                     stream: msgType,
                     data: msg.data,
@@ -224,11 +251,11 @@ export class CommandHandle {
      * - After kill():                  no reconnect, error propagates
      */
     async *[Symbol.asyncIterator]() {
-        let reconnectAttempts = 0;
+        this._reconnectAttempts = 0;
         while (true) {
             try {
                 for await (const chunk of this._iterStream()) {
-                    reconnectAttempts = 0; // Reset on successful data
+                    this._reconnectAttempts = 0; // Reset on successful data
                     if (chunk.stream === "stdout") {
                         this._lastStdoutOffset =
                             chunk.offset + new TextEncoder().encode(chunk.data).length;
@@ -244,21 +271,21 @@ export class CommandHandle {
                 return; // Stream ended normally (exit message received)
             }
             catch (e) {
-                const eName = e != null && typeof e === "object" ? e.name : "";
-                if (eName !== "LangSmithSandboxConnectionError" &&
-                    eName !== "LangSmithSandboxServerReloadError") {
+                // instanceof, not a name check: subclasses (connect timeout, server
+                // reload) must stay retryable here.
+                if (!(e instanceof LangSmithSandboxConnectionError)) {
                     throw e;
                 }
                 if (this._control && this._control.killed) {
                     throw e;
                 }
-                reconnectAttempts++;
-                if (reconnectAttempts > CommandHandle.MAX_AUTO_RECONNECTS) {
-                    throw new LangSmithSandboxConnectionError(`Lost connection ${reconnectAttempts} times in succession, giving up`);
+                this._reconnectAttempts++;
+                if (this._reconnectAttempts > CommandHandle.MAX_AUTO_RECONNECTS) {
+                    throw new LangSmithSandboxConnectionError(`Failed to reattach to the command ${this._reconnectAttempts} times in succession, giving up`);
                 }
-                const isHotReload = eName === "LangSmithSandboxServerReloadError";
+                const isHotReload = e instanceof LangSmithSandboxServerReloadError;
                 if (!isHotReload) {
-                    const delay = Math.min(CommandHandle.BACKOFF_BASE * 2 ** (reconnectAttempts - 1), CommandHandle.BACKOFF_MAX);
+                    const delay = Math.min(CommandHandle.BACKOFF_BASE * 2 ** (this._reconnectAttempts - 1), CommandHandle.BACKOFF_MAX);
                     await new Promise((r) => setTimeout(r, delay * 1000));
                 }
                 if (this._commandId === null) {

package/dist/sandbox/errors.cjs

@@ -7,7 +7,7 @@
  * properties for specific handling when needed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LangSmithSandboxServerReloadError = 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.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = void 0;
 /**
  * Base exception for sandbox client errors.
  */
@@ -372,6 +372,21 @@ class LangSmithStreamEndedBeforeStartedError extends LangSmithSandboxOperationEr
     }
 }
 exports.LangSmithStreamEndedBeforeStartedError = 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.
+ */
+class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+    constructor(message) {
+        super(message);
+        this.name = "LangSmithSandboxConnectTimeoutError";
+    }
+}
+exports.LangSmithSandboxConnectTimeoutError = LangSmithSandboxConnectTimeoutError;
 /**
  * Raised when the sandbox server is reloading (close code 1001).
  *

package/dist/sandbox/errors.d.ts

@@ -165,6 +165,17 @@ export declare class LangSmithCommandTimeoutError extends LangSmithSandboxOperat
 export declare class LangSmithStreamEndedBeforeStartedError extends LangSmithSandboxOperationError {
     constructor(message: string);
 }
+/**
+ * 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 declare class LangSmithSandboxConnectTimeoutError extends LangSmithSandboxConnectionError {
+    constructor(message: string);
+}
 /**
  * Raised when the sandbox server is reloading (close code 1001).
  *

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

@@ -234,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, {
@@ -246,6 +247,7 @@ class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                openTimeout: (0, ws_execute_js_1.openTimeoutFor)(deadline),
                 ...(Object.keys(clientHeaders).length > 0
                     ? { headers: clientHeaders }
                     : {}),
@@ -259,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;
+                }
             }
         }
     }
@@ -426,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.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 { isWsAvailable, 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.
  *
@@ -231,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, {
@@ -243,6 +244,7 @@ export class Sandbox {
                 killOnDisconnect,
                 ttlSeconds,
                 pty,
+                openTimeout: openTimeoutFor(deadline),
                 ...(Object.keys(clientHeaders).length > 0
                     ? { headers: clientHeaders }
                     : {}),
@@ -256,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;
+                }
             }
         }
     }
@@ -423,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,7 +6,10 @@
  * 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;
@@ -14,6 +17,46 @@ exports.raiseForWsError = raiseForWsError;
 exports.runWsStream = runWsStream;
 exports.reconnectWsStream = reconnectWsStream;
 const errors_js_1 = require("./errors.cjs");
+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;
+    }
+    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.
@@ -140,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}`));
         });
     });
 }
@@ -249,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 = {
@@ -315,8 +382,10 @@ async function runWsStream(dataplaneUrl, apiKey, command, options = {}) {
  * Reconnect to an existing command over WebSocket.
  *
  * Returns a tuple of [async_message_iterator, control], same as runWsStream.
- * The iterator yields stdout, stderr, exit, and error messages.
- * No 'started' message is sent on reconnection.
+ * The iterator yields the server's 'started' acknowledgement, then stdout,
+ * stderr, exit, and error messages. That acknowledgement is the only evidence a
+ * reattachment landed for a command producing no output, so it is forwarded
+ * rather than dropped.
  */
 async function reconnectWsStream(dataplaneUrl, apiKey, commandId, options = {}) {
     const { stdoutOffset = 0, stderrOffset = 0, headers: extraHeaders } = options;
@@ -338,7 +407,9 @@ async function reconnectWsStream(dataplaneUrl, apiKey, commandId, options = {})
             // Read messages until exit or error
             for await (const msg of readWsMessages(ws)) {
                 const msgType = msg.type;
-                if (msgType === "stdout" || msgType === "stderr") {
+                if (msgType === "started" ||
+                    msgType === "stdout" ||
+                    msgType === "stderr") {
                     yield msg;
                 }
                 else if (msgType === "exit") {