langsmith 0.5.8 → 0.5.9

package/dist/experimental/sandbox/client.cjs

@@ -530,21 +530,24 @@ class SandboxClient {
      * ```
      */
     async createSandbox(templateName, options = {}) {
-        const { name, timeout = 30 } = options;
+        const { name, timeout = 30, waitForReady = true } = options;
         const url = `${this._baseUrl}/boxes`;
         const payload = {
             template_name: templateName,
-            wait_for_ready: true,
-            timeout,
+            wait_for_ready: waitForReady,
         };
+        if (waitForReady) {
+            payload.timeout = timeout;
+        }
         if (name) {
             payload.name = name;
         }
+        const httpTimeout = waitForReady ? (timeout + 30) * 1000 : 30 * 1000;
         const response = await this._fetch(url, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(payload),
-            signal: AbortSignal.timeout((timeout + 30) * 1000),
+            signal: AbortSignal.timeout(httpTimeout),
         });
         if (!response.ok) {
             await (0, helpers_js_1.handleSandboxCreationError)(response);
@@ -635,5 +638,64 @@ class SandboxClient {
             await (0, helpers_js_1.handleClientHttpError)(response);
         }
     }
+    /**
+     * Get the provisioning status of a sandbox.
+     *
+     * This is a lightweight endpoint designed for polling during async creation.
+     * Use this instead of getSandbox() when you only need the status.
+     *
+     * @param name - Sandbox name.
+     * @returns ResourceStatus with status and optional status_message.
+     * @throws LangSmithResourceNotFoundError if sandbox not found.
+     */
+    async getSandboxStatus(name) {
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/status`;
+        const response = await this._fetch(url);
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new errors_js_1.LangSmithResourceNotFoundError(`Sandbox '${name}' not found`, "sandbox");
+            }
+            await (0, helpers_js_1.handleClientHttpError)(response);
+        }
+        return (await response.json());
+    }
+    /**
+     * Wait for a sandbox to become ready.
+     *
+     * Polls getSandboxStatus() until the sandbox reaches "ready" or "failed" status,
+     * then returns the full Sandbox object.
+     *
+     * @param name - Sandbox name.
+     * @param options - Polling options (timeout, pollInterval).
+     * @returns Ready Sandbox.
+     * @throws LangSmithResourceCreationError if sandbox status becomes "failed".
+     * @throws LangSmithResourceTimeoutError if timeout expires while still provisioning.
+     * @throws LangSmithResourceNotFoundError if sandbox not found.
+     *
+     * @example
+     * ```typescript
+     * const sandbox = await client.createSandbox("python-sandbox", { waitForReady: false });
+     * // ... do other work ...
+     * const readySandbox = await client.waitForSandbox(sandbox.name);
+     * ```
+     */
+    async waitForSandbox(name, options = {}) {
+        const { timeout = 120, pollInterval = 1.0 } = options;
+        const deadline = Date.now() + timeout * 1000;
+        let lastStatus = "provisioning";
+        while (Date.now() < deadline) {
+            const statusResult = await this.getSandboxStatus(name);
+            lastStatus = statusResult.status;
+            if (statusResult.status === "ready") {
+                return this.getSandbox(name);
+            }
+            if (statusResult.status === "failed") {
+                throw new errors_js_1.LangSmithResourceCreationError(statusResult.status_message ?? `Sandbox '${name}' creation failed`, "sandbox");
+            }
+            // Wait before polling again
+            await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
+        }
+        throw new errors_js_1.LangSmithResourceTimeoutError(`Sandbox '${name}' did not become ready within ${timeout}s`, "sandbox", lastStatus);
+    }
 }
 exports.SandboxClient = SandboxClient;

package/dist/experimental/sandbox/client.d.ts

@@ -1,7 +1,7 @@
 /**
  * Main SandboxClient class for interacting with the sandbox server API.
  */
-import type { CreatePoolOptions, CreateSandboxOptions, CreateTemplateOptions, CreateVolumeOptions, Pool, SandboxClientConfig, SandboxTemplate, UpdatePoolOptions, UpdateTemplateOptions, UpdateVolumeOptions, Volume } from "./types.js";
+import type { CreatePoolOptions, CreateSandboxOptions, CreateTemplateOptions, CreateVolumeOptions, Pool, ResourceStatus, SandboxClientConfig, SandboxTemplate, UpdatePoolOptions, UpdateTemplateOptions, UpdateVolumeOptions, Volume, WaitForSandboxOptions } from "./types.js";
 import { Sandbox } from "./sandbox.js";
 /**
  * Client for interacting with the Sandbox Server API.
@@ -237,4 +237,36 @@ export declare class SandboxClient {
      * @throws LangSmithResourceNotFoundError if sandbox not found.
      */
     deleteSandbox(name: string): Promise<void>;
+    /**
+     * Get the provisioning status of a sandbox.
+     *
+     * This is a lightweight endpoint designed for polling during async creation.
+     * Use this instead of getSandbox() when you only need the status.
+     *
+     * @param name - Sandbox name.
+     * @returns ResourceStatus with status and optional status_message.
+     * @throws LangSmithResourceNotFoundError if sandbox not found.
+     */
+    getSandboxStatus(name: string): Promise<ResourceStatus>;
+    /**
+     * Wait for a sandbox to become ready.
+     *
+     * Polls getSandboxStatus() until the sandbox reaches "ready" or "failed" status,
+     * then returns the full Sandbox object.
+     *
+     * @param name - Sandbox name.
+     * @param options - Polling options (timeout, pollInterval).
+     * @returns Ready Sandbox.
+     * @throws LangSmithResourceCreationError if sandbox status becomes "failed".
+     * @throws LangSmithResourceTimeoutError if timeout expires while still provisioning.
+     * @throws LangSmithResourceNotFoundError if sandbox not found.
+     *
+     * @example
+     * ```typescript
+     * const sandbox = await client.createSandbox("python-sandbox", { waitForReady: false });
+     * // ... do other work ...
+     * const readySandbox = await client.waitForSandbox(sandbox.name);
+     * ```
+     */
+    waitForSandbox(name: string, options?: WaitForSandboxOptions): Promise<Sandbox>;
 }

package/dist/experimental/sandbox/client.js

@@ -5,7 +5,7 @@ import { getLangSmithEnvironmentVariable } from "../../utils/env.js";
 import { _getFetchImplementation } from "../../singletons/fetch.js";
 import { AsyncCaller } from "../../utils/async_caller.js";
 import { Sandbox } from "./sandbox.js";
-import { LangSmithResourceNameConflictError, LangSmithResourceNotFoundError, LangSmithSandboxAPIError, } from "./errors.js";
+import { LangSmithResourceCreationError, LangSmithResourceNameConflictError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithSandboxAPIError, } from "./errors.js";
 import { handleClientHttpError, handleConflictError, handlePoolError, handleResourceInUseError, handleSandboxCreationError, handleVolumeCreationError, } from "./helpers.js";
 /**
  * Get the default sandbox API endpoint from environment.
@@ -527,21 +527,24 @@ export class SandboxClient {
      * ```
      */
     async createSandbox(templateName, options = {}) {
-        const { name, timeout = 30 } = options;
+        const { name, timeout = 30, waitForReady = true } = options;
         const url = `${this._baseUrl}/boxes`;
         const payload = {
             template_name: templateName,
-            wait_for_ready: true,
-            timeout,
+            wait_for_ready: waitForReady,
         };
+        if (waitForReady) {
+            payload.timeout = timeout;
+        }
         if (name) {
             payload.name = name;
         }
+        const httpTimeout = waitForReady ? (timeout + 30) * 1000 : 30 * 1000;
         const response = await this._fetch(url, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(payload),
-            signal: AbortSignal.timeout((timeout + 30) * 1000),
+            signal: AbortSignal.timeout(httpTimeout),
         });
         if (!response.ok) {
             await handleSandboxCreationError(response);
@@ -632,4 +635,63 @@ export class SandboxClient {
             await handleClientHttpError(response);
         }
     }
+    /**
+     * Get the provisioning status of a sandbox.
+     *
+     * This is a lightweight endpoint designed for polling during async creation.
+     * Use this instead of getSandbox() when you only need the status.
+     *
+     * @param name - Sandbox name.
+     * @returns ResourceStatus with status and optional status_message.
+     * @throws LangSmithResourceNotFoundError if sandbox not found.
+     */
+    async getSandboxStatus(name) {
+        const url = `${this._baseUrl}/boxes/${encodeURIComponent(name)}/status`;
+        const response = await this._fetch(url);
+        if (!response.ok) {
+            if (response.status === 404) {
+                throw new LangSmithResourceNotFoundError(`Sandbox '${name}' not found`, "sandbox");
+            }
+            await handleClientHttpError(response);
+        }
+        return (await response.json());
+    }
+    /**
+     * Wait for a sandbox to become ready.
+     *
+     * Polls getSandboxStatus() until the sandbox reaches "ready" or "failed" status,
+     * then returns the full Sandbox object.
+     *
+     * @param name - Sandbox name.
+     * @param options - Polling options (timeout, pollInterval).
+     * @returns Ready Sandbox.
+     * @throws LangSmithResourceCreationError if sandbox status becomes "failed".
+     * @throws LangSmithResourceTimeoutError if timeout expires while still provisioning.
+     * @throws LangSmithResourceNotFoundError if sandbox not found.
+     *
+     * @example
+     * ```typescript
+     * const sandbox = await client.createSandbox("python-sandbox", { waitForReady: false });
+     * // ... do other work ...
+     * const readySandbox = await client.waitForSandbox(sandbox.name);
+     * ```
+     */
+    async waitForSandbox(name, options = {}) {
+        const { timeout = 120, pollInterval = 1.0 } = options;
+        const deadline = Date.now() + timeout * 1000;
+        let lastStatus = "provisioning";
+        while (Date.now() < deadline) {
+            const statusResult = await this.getSandboxStatus(name);
+            lastStatus = statusResult.status;
+            if (statusResult.status === "ready") {
+                return this.getSandbox(name);
+            }
+            if (statusResult.status === "failed") {
+                throw new LangSmithResourceCreationError(statusResult.status_message ?? `Sandbox '${name}' creation failed`, "sandbox");
+            }
+            // Wait before polling again
+            await new Promise((resolve) => setTimeout(resolve, pollInterval * 1000));
+        }
+        throw new LangSmithResourceTimeoutError(`Sandbox '${name}' did not become ready within ${timeout}s`, "sandbox", lastStatus);
+    }
 }

package/dist/experimental/sandbox/errors.cjs

@@ -7,7 +7,7 @@
  * properties for specific handling when needed.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithSandboxCreationError = 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.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.
  */
@@ -215,8 +215,44 @@ class LangSmithQuotaExceededError extends LangSmithSandboxError {
 }
 exports.LangSmithQuotaExceededError = LangSmithQuotaExceededError;
 // =============================================================================
-// Sandbox Creation Errors
+// Resource Creation Errors
 // =============================================================================
+/**
+ * Raised when resource provisioning fails (general-purpose).
+ */
+class LangSmithResourceCreationError extends LangSmithSandboxError {
+    constructor(message, resourceType, errorType) {
+        super(message);
+        /**
+         * Type of resource that failed (e.g., "sandbox", "volume").
+         */
+        Object.defineProperty(this, "resourceType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Machine-readable error type (ImagePull, CrashLoop, SandboxConfig, Unschedulable).
+         */
+        Object.defineProperty(this, "errorType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "LangSmithResourceCreationError";
+        this.resourceType = resourceType;
+        this.errorType = errorType;
+    }
+    toString() {
+        if (this.errorType) {
+            return `${super.toString()} [${this.errorType}]`;
+        }
+        return super.toString();
+    }
+}
+exports.LangSmithResourceCreationError = LangSmithResourceCreationError;
 /**
  * Raised when sandbox creation fails.
  */

package/dist/experimental/sandbox/errors.d.ts

@@ -92,6 +92,21 @@ export declare class LangSmithQuotaExceededError extends LangSmithSandboxError {
     quotaType?: string;
     constructor(message: string, quotaType?: string);
 }
+/**
+ * Raised when resource provisioning fails (general-purpose).
+ */
+export declare class LangSmithResourceCreationError extends LangSmithSandboxError {
+    /**
+     * Type of resource that failed (e.g., "sandbox", "volume").
+     */
+    resourceType?: string;
+    /**
+     * Machine-readable error type (ImagePull, CrashLoop, SandboxConfig, Unschedulable).
+     */
+    errorType?: string;
+    constructor(message: string, resourceType?: string, errorType?: string);
+    toString(): string;
+}
 /**
  * Raised when sandbox creation fails.
  */

package/dist/experimental/sandbox/errors.js

@@ -201,8 +201,43 @@ export class LangSmithQuotaExceededError extends LangSmithSandboxError {
     }
 }
 // =============================================================================
-// Sandbox Creation Errors
+// Resource Creation Errors
 // =============================================================================
+/**
+ * Raised when resource provisioning fails (general-purpose).
+ */
+export class LangSmithResourceCreationError extends LangSmithSandboxError {
+    constructor(message, resourceType, errorType) {
+        super(message);
+        /**
+         * Type of resource that failed (e.g., "sandbox", "volume").
+         */
+        Object.defineProperty(this, "resourceType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * Machine-readable error type (ImagePull, CrashLoop, SandboxConfig, Unschedulable).
+         */
+        Object.defineProperty(this, "errorType", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = "LangSmithResourceCreationError";
+        this.resourceType = resourceType;
+        this.errorType = errorType;
+    }
+    toString() {
+        if (this.errorType) {
+            return `${super.toString()} [${this.errorType}]`;
+        }
+        return super.toString();
+    }
+}
 /**
  * Raised when sandbox creation fails.
  */

package/dist/experimental/sandbox/index.cjs

@@ -24,7 +24,7 @@
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = exports.LangSmithSandboxCreationError = exports.LangSmithQuotaExceededError = exports.LangSmithValidationError = exports.LangSmithResourceNameConflictError = exports.LangSmithResourceAlreadyExistsError = exports.LangSmithResourceInUseError = exports.LangSmithResourceTimeoutError = exports.LangSmithResourceNotFoundError = exports.LangSmithSandboxConnectionError = exports.LangSmithSandboxAuthenticationError = exports.LangSmithSandboxAPIError = exports.LangSmithSandboxError = exports.Sandbox = exports.SandboxClient = void 0;
+exports.LangSmithDataplaneNotConfiguredError = exports.LangSmithSandboxOperationError = exports.LangSmithSandboxNotReadyError = 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 = exports.Sandbox = exports.SandboxClient = void 0;
 // Emit warning on import (alpha feature)
 console.warn("langsmith/experimental/sandbox is in alpha. " +
     "This feature is experimental, and breaking changes are expected.");
@@ -49,6 +49,8 @@ Object.defineProperty(exports, "LangSmithResourceNameConflictError", { enumerabl
 // Validation and quota errors
 Object.defineProperty(exports, "LangSmithValidationError", { enumerable: true, get: function () { return errors_js_1.LangSmithValidationError; } });
 Object.defineProperty(exports, "LangSmithQuotaExceededError", { enumerable: true, get: function () { return errors_js_1.LangSmithQuotaExceededError; } });
+// Resource creation errors
+Object.defineProperty(exports, "LangSmithResourceCreationError", { enumerable: true, get: function () { return errors_js_1.LangSmithResourceCreationError; } });
 // Sandbox-specific errors
 Object.defineProperty(exports, "LangSmithSandboxCreationError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxCreationError; } });
 Object.defineProperty(exports, "LangSmithSandboxNotReadyError", { enumerable: true, get: function () { return errors_js_1.LangSmithSandboxNotReadyError; } });

package/dist/experimental/sandbox/index.d.ts

@@ -24,5 +24,5 @@
  */
 export { SandboxClient } from "./client.js";
 export { Sandbox } from "./sandbox.js";
-export type { ExecutionResult, ResourceSpec, VolumeMountSpec, Volume, SandboxTemplate, Pool, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, CreateVolumeOptions, CreateTemplateOptions, UpdateTemplateOptions, CreatePoolOptions, UpdateVolumeOptions, UpdatePoolOptions, } from "./types.js";
-export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";
+export type { ExecutionResult, ResourceSpec, ResourceStatus, VolumeMountSpec, Volume, SandboxTemplate, Pool, SandboxData, SandboxClientConfig, RunOptions, CreateSandboxOptions, WaitForSandboxOptions, CreateVolumeOptions, CreateTemplateOptions, UpdateTemplateOptions, CreatePoolOptions, UpdateVolumeOptions, UpdatePoolOptions, } from "./types.js";
+export { LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationError, LangSmithSandboxConnectionError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, LangSmithValidationError, LangSmithQuotaExceededError, LangSmithResourceCreationError, LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";

package/dist/experimental/sandbox/index.js

@@ -36,5 +36,7 @@ LangSmithSandboxError, LangSmithSandboxAPIError, LangSmithSandboxAuthenticationE
 LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithResourceInUseError, LangSmithResourceAlreadyExistsError, LangSmithResourceNameConflictError, 
 // Validation and quota errors
 LangSmithValidationError, LangSmithQuotaExceededError, 
+// Resource creation errors
+LangSmithResourceCreationError, 
 // Sandbox-specific errors
 LangSmithSandboxCreationError, LangSmithSandboxNotReadyError, LangSmithSandboxOperationError, LangSmithDataplaneNotConfiguredError, } from "./errors.js";

package/dist/experimental/sandbox/sandbox.cjs

@@ -48,6 +48,20 @@ class Sandbox {
             writable: true,
             value: void 0
         });
+        /** Provisioning status ("provisioning", "ready", "failed"). */
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Human-readable status message (e.g., error details when failed). */
+        Object.defineProperty(this, "status_message", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /** Unique identifier (UUID). Remains constant even if name changes. */
         Object.defineProperty(this, "id", {
             enumerable: true,
@@ -78,6 +92,8 @@ class Sandbox {
         this.name = data.name;
         this.template_name = data.template_name;
         this.dataplane_url = data.dataplane_url;
+        this.status = data.status;
+        this.status_message = data.status_message;
         this.id = data.id;
         this.created_at = data.created_at;
         this.updated_at = data.updated_at;
@@ -85,9 +101,14 @@ class Sandbox {
     }
     /**
      * Validate and return the dataplane URL.
+     * @throws LangSmithSandboxNotReadyError if sandbox status is not "ready".
      * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
      */
     requireDataplaneUrl() {
+        if (this.status && this.status !== "ready") {
+            throw new errors_js_1.LangSmithSandboxNotReadyError(`Sandbox '${this.name}' is not ready (status: ${this.status}). ` +
+                "Use waitForSandbox() to wait for the sandbox to become ready.");
+        }
         if (!this.dataplane_url) {
             throw new errors_js_1.LangSmithDataplaneNotConfiguredError(`Sandbox '${this.name}' does not have a dataplane_url configured. ` +
                 "Runtime operations require a dataplane URL.");

package/dist/experimental/sandbox/sandbox.d.ts

@@ -27,6 +27,10 @@ export declare class Sandbox {
     readonly template_name: string;
     /** URL for data plane operations (file I/O, command execution). */
     readonly dataplane_url?: string;
+    /** Provisioning status ("provisioning", "ready", "failed"). */
+    readonly status?: string;
+    /** Human-readable status message (e.g., error details when failed). */
+    readonly status_message?: string;
     /** Unique identifier (UUID). Remains constant even if name changes. */
     readonly id?: string;
     /** Timestamp when the sandbox was created. */
@@ -36,6 +40,7 @@ export declare class Sandbox {
     private _client;
     /**
      * Validate and return the dataplane URL.
+     * @throws LangSmithSandboxNotReadyError if sandbox status is not "ready".
      * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
      */
     private requireDataplaneUrl;

package/dist/experimental/sandbox/sandbox.js

@@ -1,7 +1,7 @@
 /**
  * Sandbox class for interacting with a specific sandbox instance.
  */
-import { LangSmithDataplaneNotConfiguredError } from "./errors.js";
+import { LangSmithDataplaneNotConfiguredError, LangSmithSandboxNotReadyError, } from "./errors.js";
 import { handleSandboxHttpError } from "./helpers.js";
 /**
  * Represents an active sandbox for running commands and file operations.
@@ -45,6 +45,20 @@ export class Sandbox {
             writable: true,
             value: void 0
         });
+        /** Provisioning status ("provisioning", "ready", "failed"). */
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Human-readable status message (e.g., error details when failed). */
+        Object.defineProperty(this, "status_message", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /** Unique identifier (UUID). Remains constant even if name changes. */
         Object.defineProperty(this, "id", {
             enumerable: true,
@@ -75,6 +89,8 @@ export class Sandbox {
         this.name = data.name;
         this.template_name = data.template_name;
         this.dataplane_url = data.dataplane_url;
+        this.status = data.status;
+        this.status_message = data.status_message;
         this.id = data.id;
         this.created_at = data.created_at;
         this.updated_at = data.updated_at;
@@ -82,9 +98,14 @@ export class Sandbox {
     }
     /**
      * Validate and return the dataplane URL.
+     * @throws LangSmithSandboxNotReadyError if sandbox status is not "ready".
      * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
      */
     requireDataplaneUrl() {
+        if (this.status && this.status !== "ready") {
+            throw new LangSmithSandboxNotReadyError(`Sandbox '${this.name}' is not ready (status: ${this.status}). ` +
+                "Use waitForSandbox() to wait for the sandbox to become ready.");
+        }
         if (!this.dataplane_url) {
             throw new LangSmithDataplaneNotConfiguredError(`Sandbox '${this.name}' does not have a dataplane_url configured. ` +
                 "Runtime operations require a dataplane URL.");

package/dist/experimental/sandbox/types.d.ts

@@ -64,6 +64,15 @@ export interface Pool {
     created_at?: string;
     updated_at?: string;
 }
+/**
+ * Lightweight provisioning status for any async-created resource.
+ */
+export interface ResourceStatus {
+    /** One of "provisioning", "ready", "failed". */
+    status: string;
+    /** Human-readable details when failed. */
+    status_message?: string;
+}
 /**
  * Data representing a sandbox instance from the API.
  */
@@ -72,6 +81,8 @@ export interface SandboxData {
     name: string;
     template_name: string;
     dataplane_url?: string;
+    status?: string;
+    status_message?: string;
     created_at?: string;
     updated_at?: string;
 }
@@ -137,6 +148,28 @@ export interface CreateSandboxOptions {
      * Timeout in seconds when waiting for ready.
      */
     timeout?: number;
+    /**
+     * Whether to wait for the sandbox to be ready before returning.
+     * When false, returns immediately with status "provisioning".
+     * Use getSandboxStatus() or waitForSandbox() to poll for readiness.
+     * Default: true.
+     */
+    waitForReady?: boolean;
+}
+/**
+ * Options for waiting for a sandbox to become ready.
+ */
+export interface WaitForSandboxOptions {
+    /**
+     * Maximum time in seconds to wait for the sandbox to become ready.
+     * Default: 120.
+     */
+    timeout?: number;
+    /**
+     * Time in seconds between status polls.
+     * Default: 1.0.
+     */
+    pollInterval?: number;
 }
 /**
  * Options for creating a volume.

package/dist/index.cjs

@@ -18,4 +18,4 @@ Object.defineProperty(exports, "PromptCache", { enumerable: true, get: function
 Object.defineProperty(exports, "configureGlobalPromptCache", { enumerable: true, get: function () { return index_js_1.configureGlobalPromptCache; } });
 Object.defineProperty(exports, "promptCacheSingleton", { enumerable: true, get: function () { return index_js_1.promptCacheSingleton; } });
 // Update using yarn bump-version
-exports.__version__ = "0.5.8";
+exports.__version__ = "0.5.9";

package/dist/index.d.ts

@@ -5,4 +5,4 @@ export { overrideFetchImplementation } from "./singletons/fetch.js";
 export { getDefaultProjectName } from "./utils/project.js";
 export { uuid7, uuid7FromTime } from "./uuid.js";
 export { Cache, PromptCache, type CacheConfig, type CacheMetrics, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
-export declare const __version__ = "0.5.8";
+export declare const __version__ = "0.5.9";

package/dist/index.js

@@ -5,4 +5,4 @@ export { getDefaultProjectName } from "./utils/project.js";
 export { uuid7, uuid7FromTime } from "./uuid.js";
 export { Cache, PromptCache, configureGlobalPromptCache, promptCacheSingleton, } from "./utils/prompt_cache/index.js";
 // Update using yarn bump-version
-export const __version__ = "0.5.8";
+export const __version__ = "0.5.9";

package/dist/run_trees.cjs

@@ -418,6 +418,15 @@ class RunTree {
             execution_order: child_execution_order,
             child_execution_order: child_execution_order,
         });
+        // Propagate all parent metadata; child metadata takes precedence.
+        const parentMeta = this.extra?.metadata ?? {};
+        const childMeta = child.extra?.metadata ?? {};
+        if (Object.keys(parentMeta).length > 0) {
+            child.extra = {
+                ...child.extra,
+                metadata: { ...parentMeta, ...childMeta },
+            };
+        }
         // Copy context vars over into the new run tree.
         if (constants_js_1._LC_CONTEXT_VARIABLES_KEY in this) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -480,14 +489,12 @@ class RunTree {
                 }
             }
         }
+        const parent_run_id = run.parent_run?.id ?? run.parent_run_id;
         let child_runs;
-        let parent_run_id;
         if (!excludeChildRuns) {
             child_runs = run.child_runs.map((child_run) => this._convertToCreate(child_run, runtimeEnv, excludeChildRuns));
-            parent_run_id = undefined;
         }
         else {
-            parent_run_id = run.parent_run?.id ?? run.parent_run_id;
             child_runs = [];
         }
         return {

package/dist/run_trees.js

@@ -412,6 +412,15 @@ export class RunTree {
             execution_order: child_execution_order,
             child_execution_order: child_execution_order,
         });
+        // Propagate all parent metadata; child metadata takes precedence.
+        const parentMeta = this.extra?.metadata ?? {};
+        const childMeta = child.extra?.metadata ?? {};
+        if (Object.keys(parentMeta).length > 0) {
+            child.extra = {
+                ...child.extra,
+                metadata: { ...parentMeta, ...childMeta },
+            };
+        }
         // Copy context vars over into the new run tree.
         if (_LC_CONTEXT_VARIABLES_KEY in this) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -474,14 +483,12 @@ export class RunTree {
                 }
             }
         }
+        const parent_run_id = run.parent_run?.id ?? run.parent_run_id;
         let child_runs;
-        let parent_run_id;
         if (!excludeChildRuns) {
             child_runs = run.child_runs.map((child_run) => this._convertToCreate(child_run, runtimeEnv, excludeChildRuns));
-            parent_run_id = undefined;
         }
         else {
-            parent_run_id = run.parent_run?.id ?? run.parent_run_id;
             child_runs = [];
         }
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "packageManager": "yarn@1.22.19",
   "files": [