computesdk 1.13.0 → 1.16.0

package/dist/index.d.mts

@@ -1109,8 +1109,10 @@ declare class Terminal {
 interface ServerStartOptions {
     /** Unique server identifier (URL-safe) */
     slug: string;
-    /** Command to start the server */
-    command: string;
+    /** Install command to run before starting (optional, runs blocking, e.g., "npm install") */
+    install?: string;
+    /** Command to start the server (e.g., "npm run dev") */
+    start: string;
     /** Working directory (optional) */
     path?: string;
     /** Path to .env file relative to path (optional) */
@@ -1139,14 +1141,22 @@ interface ServerStartOptions {
  * // Start a basic server
  * const server = await sandbox.server.start({
  *   slug: 'api',
- *   command: 'npm start',
+ *   start: 'npm start',
+ *   path: '/app',
+ * });
+ *
+ * // Start with install command (runs before start)
+ * const server = await sandbox.server.start({
+ *   slug: 'web',
+ *   install: 'npm install',
+ *   start: 'npm run dev',
  *   path: '/app',
  * });
  *
  * // Start with supervisor settings (auto-restart on failure)
  * const server = await sandbox.server.start({
  *   slug: 'web',
- *   command: 'node server.js',
+ *   start: 'node server.js',
  *   path: '/app',
  *   environment: { NODE_ENV: 'production', PORT: '3000' },
  *   restart_policy: 'on-failure',
@@ -1167,6 +1177,24 @@ interface ServerStartOptions {
  * await sandbox.server.restart('api');
  * ```
  */
+/**
+ * Options for retrieving server logs
+ */
+interface ServerLogsOptions {
+    /** Which output stream to return: 'stdout', 'stderr', or 'combined' (default) */
+    stream?: ServerLogStream;
+}
+/**
+ * Server logs info returned from the logs method
+ */
+interface ServerLogsInfo {
+    /** Server slug identifier */
+    slug: string;
+    /** Which stream was returned */
+    stream: ServerLogStream;
+    /** The captured logs */
+    logs: string;
+}
 declare class Server {
     private startHandler;
     private listHandler;
@@ -1174,6 +1202,7 @@ declare class Server {
     private stopHandler;
     private restartHandler;
     private updateStatusHandler;
+    private logsHandler;
     constructor(handlers: {
         start: (options: ServerStartOptions) => Promise<ServerResponse>;
         list: () => Promise<ServersListResponse>;
@@ -1181,10 +1210,15 @@ declare class Server {
         stop: (slug: string) => Promise<ServerStopResponse | void>;
         restart: (slug: string) => Promise<ServerResponse>;
         updateStatus: (slug: string, status: ServerStatus) => Promise<void>;
+        logs: (slug: string, options?: ServerLogsOptions) => Promise<ServerLogsResponse>;
     });
     /**
      * Start a new managed server with optional supervisor settings
      *
+     * **Install Phase:**
+     * If `install` is provided, it runs blocking before `start` (e.g., "npm install").
+     * The server status will be `installing` during this phase.
+     *
      * **Restart Policies:**
      * - `never` (default): No automatic restart on exit
      * - `on-failure`: Restart only on non-zero exit code
@@ -1202,14 +1236,15 @@ declare class Server {
      * // Basic server
      * const server = await sandbox.server.start({
      *   slug: 'web',
-     *   command: 'npm run dev',
+     *   start: 'npm run dev',
      *   path: '/app',
      * });
      *
-     * // With supervisor settings
+     * // With install command
      * const server = await sandbox.server.start({
      *   slug: 'api',
-     *   command: 'node server.js',
+     *   install: 'npm install',
+     *   start: 'node server.js',
      *   environment: { NODE_ENV: 'production' },
      *   restart_policy: 'always',
      *   max_restarts: 0, // unlimited
@@ -1245,6 +1280,26 @@ declare class Server {
      * @param status - New status
      */
     updateStatus(slug: string, status: ServerStatus): Promise<void>;
+    /**
+     * Retrieve captured output (logs) for a managed server
+     * @param slug - The server slug
+     * @param options - Options for log retrieval
+     * @returns Server logs info
+     *
+     * @example
+     * ```typescript
+     * // Get combined logs (default)
+     * const logs = await sandbox.server.logs('api');
+     * console.log(logs.logs);
+     *
+     * // Get only stdout
+     * const stdout = await sandbox.server.logs('api', { stream: 'stdout' });
+     *
+     * // Get only stderr
+     * const stderr = await sandbox.server.logs('api', { stream: 'stderr' });
+     * ```
+     */
+    logs(slug: string, options?: ServerLogsOptions): Promise<ServerLogsInfo>;
 }
 
 /**
@@ -1779,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
@@ -1791,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
  */
@@ -1803,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
@@ -1821,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
@@ -1850,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>;
 }
 
 /**
@@ -1925,9 +2024,22 @@ declare class Child {
 /**
  * Overlay - Resource namespace for filesystem overlay operations
  *
- * Overlays enable instant sandbox setup from template directories by symlinking
- * files first for instant access, then copying heavy directories in the background.
+ * 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
  */
@@ -1936,6 +2048,10 @@ interface CreateOverlayOptions {
     source: string;
     /** Relative path in sandbox where overlay will be mounted */
     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
@@ -1945,11 +2061,11 @@ type OverlayCopyStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
  * Statistics about an overlay
  */
 interface OverlayStats {
-    /** Number of symlinked files */
-    symlinkedFiles: number;
-    /** Number of symlinked directories */
-    symlinkedDirs: number;
-    /** Paths that were skipped (e.g., .git) */
+    /** Number of copied files */
+    copiedFiles: number;
+    /** Number of copied directories (heavy dirs copied in background) */
+    copiedDirs: number;
+    /** Paths that were skipped (e.g., .git, ignored patterns) */
     skipped: string[];
 }
 /**
@@ -1980,8 +2096,8 @@ interface OverlayResponse {
     target: string;
     created_at: string;
     stats: {
-        symlinked_files: number;
-        symlinked_dirs: number;
+        copied_files: number;
+        copied_dirs: number;
         skipped: string[];
     };
     copy_status: string;
@@ -2005,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();
  *
@@ -2032,13 +2158,15 @@ declare class Overlay {
     /**
      * Create a new overlay from a template directory
      *
-     * The overlay symlinks files from the source directory into the target path,
-     * allowing instant access to template files. Heavy directories (node_modules,
-     * .venv, etc.) are copied in the background.
+     * The overlay copies files from the source directory into the target path
+     * for better isolation. Heavy directories (node_modules, .venv, etc.) are
+     * copied in the background. Use the `ignore` option to exclude files/directories.
      *
      * @param options - Overlay creation options
      * @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>;
@@ -2061,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
      */
@@ -2513,6 +2653,7 @@ interface TerminalResponse {
 /**
  * Server status types
  *
+ * - `installing`: Running install command (e.g., npm install) before starting
  * - `starting`: Initial startup of the server process
  * - `running`: Server process is running
  * - `ready`: Server is running and ready to accept traffic
@@ -2520,7 +2661,7 @@ interface TerminalResponse {
  * - `stopped`: Server was intentionally stopped
  * - `restarting`: Server is being automatically restarted by the supervisor
  */
-type ServerStatus = 'starting' | 'running' | 'ready' | 'failed' | 'stopped' | 'restarting';
+type ServerStatus = 'installing' | 'starting' | 'running' | 'ready' | 'failed' | 'stopped' | 'restarting';
 /**
  * Server restart policy
  * - `never`: No automatic restart (default)
@@ -2534,8 +2675,10 @@ type RestartPolicy = 'never' | 'on-failure' | 'always';
 interface ServerInfo {
     /** Unique server identifier */
     slug: string;
+    /** Install command (optional, runs blocking before start) */
+    install?: string;
     /** Command used to start the server */
-    command: string;
+    start: string;
     /** Working directory path */
     path: string;
     /** Original path before resolution */
@@ -2599,6 +2742,22 @@ interface ServerStopResponse {
         slug: string;
     };
 }
+/**
+ * Server logs stream type
+ */
+type ServerLogStream = 'stdout' | 'stderr' | 'combined';
+/**
+ * Server logs response
+ */
+interface ServerLogsResponse {
+    status: string;
+    message: string;
+    data: {
+        slug: string;
+        stream: ServerLogStream;
+        logs: string;
+    };
+}
 /**
  * Server status update response
  */
@@ -3097,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
@@ -3176,7 +3355,8 @@ declare class Sandbox {
      *
      * @param options - Server configuration
      * @param options.slug - Unique server identifier
-     * @param options.command - Command to start the server
+     * @param options.install - Install command (optional, runs blocking before start, e.g., "npm install")
+     * @param options.start - Command to start the server (e.g., "npm run dev")
      * @param options.path - Working directory (optional)
      * @param options.env_file - Path to .env file relative to path (optional)
      * @param options.environment - Inline environment variables (merged with env_file if both provided)
@@ -3190,14 +3370,15 @@ declare class Sandbox {
      * // Basic server
      * await sandbox.startServer({
      *   slug: 'web',
-     *   command: 'npm run dev',
+     *   start: 'npm run dev',
      *   path: '/app',
      * });
      *
-     * // With supervisor settings
+     * // With install command and supervisor settings
      * await sandbox.startServer({
      *   slug: 'api',
-     *   command: 'node server.js',
+     *   install: 'npm install',
+     *   start: 'node server.js',
      *   path: '/app',
      *   environment: { NODE_ENV: 'production', PORT: '3000' },
      *   restart_policy: 'on-failure',
@@ -3209,7 +3390,8 @@ declare class Sandbox {
      */
     startServer(options: {
         slug: string;
-        command: string;
+        install?: string;
+        start: string;
         path?: string;
         env_file?: string;
         environment?: Record<string, string>;
@@ -3233,6 +3415,14 @@ declare class Sandbox {
      * @param slug - Server slug
      */
     restartServer(slug: string): Promise<ServerResponse>;
+    /**
+     * Get logs for a managed server
+     * @param slug - Server slug
+     * @param options - Options for log retrieval
+     */
+    getServerLogs(slug: string, options?: {
+        stream?: ServerLogStream;
+    }): Promise<ServerLogsResponse>;
     /**
      * Update server status (internal use)
      * @param slug - Server slug