computesdk 1.15.0 → 1.16.0

package/dist/index.d.mts

@@ -1834,6 +1834,12 @@ interface CommandResult {
     stderr: string;
     exitCode: number;
     durationMs: number;
+    /** Command ID (present for background commands) */
+    cmdId?: string;
+    /** Terminal ID (present for background commands) */
+    terminalId?: string;
+    /** Command status (present for background commands) */
+    status?: 'running' | 'completed' | 'failed';
 }
 /**
  * Supported languages for code execution
@@ -1846,6 +1852,13 @@ interface CodeRunOptions {
     /** Programming language (optional - will auto-detect if not specified) */
     language?: CodeLanguage;
 }
+/**
+ * Options for waiting for command completion
+ */
+interface CommandWaitOptions {
+    /** Timeout in seconds to wait for command completion (default: 300, max: 300) */
+    timeoutSeconds?: number;
+}
 /**
  * Command execution options
  */
@@ -1858,6 +1871,8 @@ interface CommandRunOptions {
     cwd?: string;
     /** Environment variables (optional) */
     env?: Record<string, string>;
+    /** If true, wait for background command to complete before returning (default: false) */
+    waitForCompletion?: boolean | CommandWaitOptions;
 }
 /**
  * Run - Resource namespace for executing code and commands
@@ -1876,14 +1891,28 @@ interface CommandRunOptions {
  * const result = await sandbox.run.command('ls -la');
  * console.log(result.stdout);
  * console.log(result.exitCode);
+ *
+ * // Run a command in background and wait for completion
+ * const result = await sandbox.run.command('npm install', {
+ *   background: true,
+ *   waitForCompletion: true, // blocks until command completes
+ * });
+ * console.log(result.exitCode);
+ *
+ * // Run in background without waiting (fire-and-forget)
+ * const result = await sandbox.run.command('npm install', { background: true });
+ * console.log(result.cmdId); // command ID for manual tracking
+ * console.log(result.terminalId); // terminal ID for manual tracking
  * ```
  */
 declare class Run {
     private codeHandler;
     private commandHandler;
+    private waitHandler?;
     constructor(handlers: {
         code: (code: string, options?: CodeRunOptions) => Promise<CodeResult>;
         command: (command: string, options?: CommandRunOptions) => Promise<CommandResult>;
+        wait?: (terminalId: string, cmdId: string, options?: CommandWaitOptions) => Promise<CommandResult>;
     });
     /**
      * Execute code with automatic language detection
@@ -1905,9 +1934,24 @@ declare class Run {
      * @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
      */
     command(command: string, options?: CommandRunOptions): Promise<CommandResult>;
+    /**
+     * 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
+     */
+    waitForCompletion(terminalId: string, cmdId: string, options?: CommandWaitOptions): Promise<CommandResult>;
 }
 
 /**
@@ -1983,6 +2027,19 @@ declare class Child {
  * Overlays enable instant sandbox setup from template directories by copying
  * files directly for isolation, with heavy directories copied in the background.
  */
+/**
+ * Options for waiting for overlay copy completion
+ */
+interface WaitForCompletionOptions {
+    /** Maximum number of retry attempts (default: 60) */
+    maxRetries?: number;
+    /** Initial delay between retries in milliseconds (default: 500) */
+    initialDelayMs?: number;
+    /** Maximum delay between retries in milliseconds (default: 5000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier for exponential backoff (default: 1.5) */
+    backoffFactor?: number;
+}
 /**
  * Options for creating an overlay
  */
@@ -1993,6 +2050,8 @@ interface CreateOverlayOptions {
     target: string;
     /** Glob patterns to ignore (e.g., ["node_modules", "*.log"]) */
     ignore?: string[];
+    /** If true, wait for background copy to complete before returning (default: false) */
+    waitForCompletion?: boolean | WaitForCompletionOptions;
 }
 /**
  * Copy status for overlay background operations
@@ -2062,6 +2121,16 @@ interface OverlayListResponse {
  * });
  * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
  *
+ * // Create an overlay and wait for background copy to complete
+ * const overlay = await sandbox.filesystem.overlay.create({
+ *   source: '/templates/nextjs',
+ *   target: 'project',
+ *   waitForCompletion: true, // blocks until copy is complete
+ * });
+ *
+ * // Wait for an existing overlay's copy to complete
+ * const overlay = await sandbox.filesystem.overlay.waitForCompletion('overlay-id');
+ *
  * // List all overlays
  * const overlays = await sandbox.filesystem.overlay.list();
  *
@@ -2097,6 +2166,7 @@ declare class Overlay {
      * @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
      */
     create(options: CreateOverlayOptions): Promise<OverlayInfo>;
@@ -2119,6 +2189,18 @@ declare class Overlay {
      * @param id - Overlay ID
      */
     destroy(id: string): Promise<void>;
+    /**
+     * 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
+     */
+    waitForCompletion(id: string, options?: WaitForCompletionOptions): Promise<OverlayInfo>;
     /**
      * Convert API response to OverlayInfo
      */
@@ -3174,6 +3256,26 @@ declare class Sandbox {
      * @throws {Error} If terminal is in PTY mode, command not found, or timeout occurs
      */
     waitForCommand(terminalId: string, cmdId: string, timeout?: number): Promise<CommandDetailsResponse>;
+    /**
+     * 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
+     */
+    private waitForCommandCompletion;
+    /**
+     * Wait for a command with extended timeout support
+     * Uses X-Request-Timeout header for tunnel timeout configuration
+     * @internal
+     */
+    private waitForCommandWithTimeout;
     /**
      * Create a new file watcher with WebSocket integration
      * @param path - Path to watch

package/dist/index.d.ts

@@ -1834,6 +1834,12 @@ interface CommandResult {
     stderr: string;
     exitCode: number;
     durationMs: number;
+    /** Command ID (present for background commands) */
+    cmdId?: string;
+    /** Terminal ID (present for background commands) */
+    terminalId?: string;
+    /** Command status (present for background commands) */
+    status?: 'running' | 'completed' | 'failed';
 }
 /**
  * Supported languages for code execution
@@ -1846,6 +1852,13 @@ interface CodeRunOptions {
     /** Programming language (optional - will auto-detect if not specified) */
     language?: CodeLanguage;
 }
+/**
+ * Options for waiting for command completion
+ */
+interface CommandWaitOptions {
+    /** Timeout in seconds to wait for command completion (default: 300, max: 300) */
+    timeoutSeconds?: number;
+}
 /**
  * Command execution options
  */
@@ -1858,6 +1871,8 @@ interface CommandRunOptions {
     cwd?: string;
     /** Environment variables (optional) */
     env?: Record<string, string>;
+    /** If true, wait for background command to complete before returning (default: false) */
+    waitForCompletion?: boolean | CommandWaitOptions;
 }
 /**
  * Run - Resource namespace for executing code and commands
@@ -1876,14 +1891,28 @@ interface CommandRunOptions {
  * const result = await sandbox.run.command('ls -la');
  * console.log(result.stdout);
  * console.log(result.exitCode);
+ *
+ * // Run a command in background and wait for completion
+ * const result = await sandbox.run.command('npm install', {
+ *   background: true,
+ *   waitForCompletion: true, // blocks until command completes
+ * });
+ * console.log(result.exitCode);
+ *
+ * // Run in background without waiting (fire-and-forget)
+ * const result = await sandbox.run.command('npm install', { background: true });
+ * console.log(result.cmdId); // command ID for manual tracking
+ * console.log(result.terminalId); // terminal ID for manual tracking
  * ```
  */
 declare class Run {
     private codeHandler;
     private commandHandler;
+    private waitHandler?;
     constructor(handlers: {
         code: (code: string, options?: CodeRunOptions) => Promise<CodeResult>;
         command: (command: string, options?: CommandRunOptions) => Promise<CommandResult>;
+        wait?: (terminalId: string, cmdId: string, options?: CommandWaitOptions) => Promise<CommandResult>;
     });
     /**
      * Execute code with automatic language detection
@@ -1905,9 +1934,24 @@ declare class Run {
      * @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
      */
     command(command: string, options?: CommandRunOptions): Promise<CommandResult>;
+    /**
+     * 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
+     */
+    waitForCompletion(terminalId: string, cmdId: string, options?: CommandWaitOptions): Promise<CommandResult>;
 }
 
 /**
@@ -1983,6 +2027,19 @@ declare class Child {
  * Overlays enable instant sandbox setup from template directories by copying
  * files directly for isolation, with heavy directories copied in the background.
  */
+/**
+ * Options for waiting for overlay copy completion
+ */
+interface WaitForCompletionOptions {
+    /** Maximum number of retry attempts (default: 60) */
+    maxRetries?: number;
+    /** Initial delay between retries in milliseconds (default: 500) */
+    initialDelayMs?: number;
+    /** Maximum delay between retries in milliseconds (default: 5000) */
+    maxDelayMs?: number;
+    /** Backoff multiplier for exponential backoff (default: 1.5) */
+    backoffFactor?: number;
+}
 /**
  * Options for creating an overlay
  */
@@ -1993,6 +2050,8 @@ interface CreateOverlayOptions {
     target: string;
     /** Glob patterns to ignore (e.g., ["node_modules", "*.log"]) */
     ignore?: string[];
+    /** If true, wait for background copy to complete before returning (default: false) */
+    waitForCompletion?: boolean | WaitForCompletionOptions;
 }
 /**
  * Copy status for overlay background operations
@@ -2062,6 +2121,16 @@ interface OverlayListResponse {
  * });
  * console.log(overlay.copyStatus); // 'pending' | 'in_progress' | 'complete' | 'failed'
  *
+ * // Create an overlay and wait for background copy to complete
+ * const overlay = await sandbox.filesystem.overlay.create({
+ *   source: '/templates/nextjs',
+ *   target: 'project',
+ *   waitForCompletion: true, // blocks until copy is complete
+ * });
+ *
+ * // Wait for an existing overlay's copy to complete
+ * const overlay = await sandbox.filesystem.overlay.waitForCompletion('overlay-id');
+ *
  * // List all overlays
  * const overlays = await sandbox.filesystem.overlay.list();
  *
@@ -2097,6 +2166,7 @@ declare class Overlay {
      * @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
      */
     create(options: CreateOverlayOptions): Promise<OverlayInfo>;
@@ -2119,6 +2189,18 @@ declare class Overlay {
      * @param id - Overlay ID
      */
     destroy(id: string): Promise<void>;
+    /**
+     * 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
+     */
+    waitForCompletion(id: string, options?: WaitForCompletionOptions): Promise<OverlayInfo>;
     /**
      * Convert API response to OverlayInfo
      */
@@ -3174,6 +3256,26 @@ declare class Sandbox {
      * @throws {Error} If terminal is in PTY mode, command not found, or timeout occurs
      */
     waitForCommand(terminalId: string, cmdId: string, timeout?: number): Promise<CommandDetailsResponse>;
+    /**
+     * 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
+     */
+    private waitForCommandCompletion;
+    /**
+     * Wait for a command with extended timeout support
+     * Uses X-Request-Timeout header for tunnel timeout configuration
+     * @internal
+     */
+    private waitForCommandWithTimeout;
     /**
      * Create a new file watcher with WebSocket integration
      * @param path - Path to watch

package/dist/index.js

@@ -1855,6 +1855,7 @@ var Run = class {
   constructor(handlers) {
     this.codeHandler = handlers.code;
     this.commandHandler = handlers.command;
+    this.waitHandler = handlers.wait;
   }
   /**
    * Execute code with automatic language detection
@@ -1878,10 +1879,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);
   }
 };
 
@@ -1946,11 +1975,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
@@ -1979,6 +2014,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
    */
@@ -2022,6 +2099,7 @@ function isCommandExitError(error) {
 }
 
 // src/client/index.ts
+var MAX_TUNNEL_TIMEOUT_SECONDS = 300;
 var Sandbox = class {
   constructor(config) {
     this._token = null;
@@ -2140,8 +2218,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({
@@ -2812,6 +2897,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
   // ============================================================================