computesdk 1.15.0 → 1.17.0

package/dist/index.mjs

@@ -1802,6 +1802,7 @@ var Run = class {
   constructor(handlers) {
     this.codeHandler = handlers.code;
     this.commandHandler = handlers.command;
+    this.waitHandler = handlers.wait;
   }
   /**
    * Execute code with automatic language detection
@@ -1825,10 +1826,38 @@ var Run = class {
    * @param options.background - Run in background (optional)
    * @param options.cwd - Working directory for the command (optional)
    * @param options.env - Environment variables (optional)
+   * @param options.waitForCompletion - If true (with background), wait for command to complete
    * @returns Command execution result with stdout, stderr, exit code, and duration
    */
   async command(command, options) {
-    return this.commandHandler(command, options);
+    const result = await this.commandHandler(command, options);
+    if (options?.background && options?.waitForCompletion && result.cmdId && result.terminalId) {
+      if (!this.waitHandler) {
+        throw new Error("Wait handler not configured");
+      }
+      const waitOptions = typeof options.waitForCompletion === "object" ? options.waitForCompletion : void 0;
+      return this.waitHandler(result.terminalId, result.cmdId, waitOptions);
+    }
+    return result;
+  }
+  /**
+   * Wait for a background command to complete
+   *
+   * Uses the configured wait handler to block until the command
+   * is complete or fails (typically via server-side long-polling).
+   * Throws an error if the command fails or times out.
+   *
+   * @param terminalId - Terminal ID from background command result
+   * @param cmdId - Command ID from background command result
+   * @param options - Wait options passed to the handler
+   * @returns Command result with final status
+   * @throws Error if command fails or times out
+   */
+  async waitForCompletion(terminalId, cmdId, options) {
+    if (!this.waitHandler) {
+      throw new Error("Wait handler not configured");
+    }
+    return this.waitHandler(terminalId, cmdId, options);
   }
 };
 
@@ -1893,11 +1922,17 @@ var Overlay = class {
    * @param options.source - Absolute path to source directory
    * @param options.target - Relative path in sandbox
    * @param options.ignore - Glob patterns to ignore (e.g., ["node_modules", "*.log"])
+   * @param options.waitForCompletion - If true or options object, wait for background copy to complete
    * @returns Overlay info with copy status
    */
   async create(options) {
     const response = await this.createHandler(options);
-    return this.toOverlayInfo(response);
+    const overlay = this.toOverlayInfo(response);
+    if (options.waitForCompletion) {
+      const waitOptions = typeof options.waitForCompletion === "object" ? options.waitForCompletion : void 0;
+      return this.waitForCompletion(overlay.id, waitOptions);
+    }
+    return overlay;
   }
   /**
    * List all overlays for the current sandbox
@@ -1926,6 +1961,48 @@ var Overlay = class {
   async destroy(id) {
     return this.destroyHandler(id);
   }
+  /**
+   * Wait for an overlay's background copy to complete
+   *
+   * Polls the overlay status with exponential backoff until the copy
+   * is complete or fails. Throws an error if the copy fails or times out.
+   *
+   * @param id - Overlay ID
+   * @param options - Polling options
+   * @returns Overlay info with final copy status
+   * @throws Error if copy fails or times out
+   */
+  async waitForCompletion(id, options = {}) {
+    const maxRetries = options.maxRetries ?? 60;
+    const initialDelayMs = options.initialDelayMs ?? 500;
+    const maxDelayMs = options.maxDelayMs ?? 5e3;
+    const backoffFactor = options.backoffFactor ?? 1.5;
+    let currentDelay = initialDelayMs;
+    for (let i = 0; i < maxRetries; i++) {
+      const overlay = await this.retrieve(id);
+      if (overlay.copyStatus === "complete") {
+        return overlay;
+      }
+      if (overlay.copyStatus === "failed") {
+        throw new Error(
+          `Overlay copy failed: ${overlay.copyError || "Unknown error"}
+Overlay ID: ${id}`
+        );
+      }
+      if (i < maxRetries - 1) {
+        await new Promise((resolve) => setTimeout(resolve, currentDelay));
+        currentDelay = Math.min(currentDelay * backoffFactor, maxDelayMs);
+      }
+    }
+    const finalOverlay = await this.retrieve(id);
+    throw new Error(
+      `Overlay copy timed out after ${maxRetries} attempts.
+Overlay ID: ${id}
+Current status: ${finalOverlay.copyStatus}
+
+Try increasing maxRetries or check if the source directory is very large.`
+    );
+  }
   /**
    * Convert API response to OverlayInfo
    */
@@ -1969,6 +2046,7 @@ function isCommandExitError(error) {
 }
 
 // src/client/index.ts
+var MAX_TUNNEL_TIMEOUT_SECONDS = 300;
 var Sandbox = class {
   constructor(config) {
     this._token = null;
@@ -2087,8 +2165,15 @@ var Sandbox = class {
           stdout: result.data.stdout,
           stderr: result.data.stderr,
           exitCode: result.data.exit_code ?? 0,
-          durationMs: result.data.duration_ms ?? 0
+          durationMs: result.data.duration_ms ?? 0,
+          // Include cmdId and terminalId for background commands
+          cmdId: result.data.cmd_id,
+          terminalId: result.data.terminal_id,
+          status: result.data.status
         };
+      },
+      wait: async (terminalId, cmdId, options) => {
+        return this.waitForCommandCompletion(terminalId, cmdId, options);
       }
     });
     this.server = new Server({
@@ -2759,6 +2844,47 @@ API request failed (${response.status}): ${error}`
     const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait${params ? `?${params}` : ""}`;
     return this.request(endpoint);
   }
+  /**
+   * Wait for a background command to complete using long-polling
+   *
+   * Uses the server's long-polling endpoint with configurable timeout.
+   * The tunnel supports up to 5 minutes (300 seconds) via X-Request-Timeout header.
+   *
+   * @param terminalId - The terminal ID
+   * @param cmdId - The command ID
+   * @param options - Wait options (timeoutSeconds, default 300)
+   * @returns Command result with final status
+   * @throws Error if command fails or times out
+   * @internal
+   */
+  async waitForCommandCompletion(terminalId, cmdId, options) {
+    const timeoutSeconds = options?.timeoutSeconds ?? MAX_TUNNEL_TIMEOUT_SECONDS;
+    const response = await this.waitForCommandWithTimeout(terminalId, cmdId, timeoutSeconds);
+    return {
+      stdout: response.data.stdout,
+      stderr: response.data.stderr,
+      exitCode: response.data.exit_code ?? 0,
+      durationMs: response.data.duration_ms ?? 0,
+      cmdId: response.data.cmd_id,
+      terminalId,
+      status: response.data.status
+    };
+  }
+  /**
+   * Wait for a command with extended timeout support
+   * Uses X-Request-Timeout header for tunnel timeout configuration
+   * @internal
+   */
+  async waitForCommandWithTimeout(terminalId, cmdId, timeoutSeconds) {
+    const params = new URLSearchParams({ timeout: timeoutSeconds.toString() });
+    const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait?${params}`;
+    const requestTimeout = Math.min(timeoutSeconds, MAX_TUNNEL_TIMEOUT_SECONDS);
+    return this.request(endpoint, {
+      headers: {
+        "X-Request-Timeout": requestTimeout.toString()
+      }
+    });
+  }
   // ============================================================================
   // File Watchers
   // ============================================================================
@@ -3733,7 +3859,8 @@ Get your API key at: https://computesdk.com/dashboard`
     apiKey: computesdkApiKey,
     gatewayUrl: config.gatewayUrl || GATEWAY_URL,
     provider: config.provider,
-    providerHeaders
+    providerHeaders,
+    WebSocket: config.WebSocket
   };
 }
 
@@ -3874,7 +4001,7 @@ var ComputeManager = class {
             ...name && { name },
             ...namespace && { namespace }
           },
-          WebSocket: globalThis.WebSocket,
+          WebSocket: config.WebSocket || globalThis.WebSocket,
           destroyHandler: async () => {
             await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
               method: "DELETE"
@@ -3900,7 +4027,7 @@ var ComputeManager = class {
           provider,
           token: token || config.apiKey,
           metadata,
-          WebSocket: globalThis.WebSocket,
+          WebSocket: config.WebSocket || globalThis.WebSocket,
           destroyHandler: async () => {
             await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
               method: "DELETE"
@@ -3956,7 +4083,7 @@ var ComputeManager = class {
             name: result.data.name,
             namespace: result.data.namespace
           },
-          WebSocket: globalThis.WebSocket,
+          WebSocket: config.WebSocket || globalThis.WebSocket,
           destroyHandler: async () => {
             await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
               method: "DELETE"
@@ -3993,7 +4120,7 @@ var ComputeManager = class {
             name,
             namespace
           },
-          WebSocket: globalThis.WebSocket,
+          WebSocket: config.WebSocket || globalThis.WebSocket,
           destroyHandler: async () => {
             await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
               method: "DELETE"