computesdk 1.18.0 → 1.18.1

package/dist/index.d.mts

@@ -1064,7 +1064,7 @@ declare class Terminal {
             pty?: boolean;
         }) => Promise<TerminalInstance>;
         list: () => Promise<TerminalResponse[]>;
-        retrieve: (id: string) => Promise<TerminalResponse>;
+        retrieve: (id: string) => Promise<TerminalInstance>;
         destroy: (id: string) => Promise<void>;
     });
     /**
@@ -1089,9 +1089,9 @@ declare class Terminal {
     /**
      * Retrieve a specific terminal by ID
      * @param id - The terminal ID
-     * @returns Terminal response
+     * @returns Terminal instance
      */
-    retrieve(id: string): Promise<TerminalResponse>;
+    retrieve(id: string): Promise<TerminalInstance>;
     /**
      * Destroy a terminal by ID
      * @param id - The terminal ID
@@ -2040,6 +2040,12 @@ interface WaitForCompletionOptions {
     /** Backoff multiplier for exponential backoff (default: 1.5) */
     backoffFactor?: number;
 }
+/**
+ * Strategy for creating an overlay
+ * - 'copy': Full copy of all files (standard behavior)
+ * - 'smart': Use symlinks for immutable packages (e.g. node_modules) for instant creation
+ */
+type OverlayStrategy = 'copy' | 'smart';
 /**
  * Options for creating an overlay
  */
@@ -2050,6 +2056,8 @@ interface CreateOverlayOptions {
     target: string;
     /** Glob patterns to ignore (e.g., ["node_modules", "*.log"]) */
     ignore?: string[];
+    /** Strategy to use (default: 'smart') */
+    strategy?: OverlayStrategy;
     /** If true, wait for background copy to complete before returning (default: false) */
     waitForCompletion?: boolean | WaitForCompletionOptions;
 }
@@ -2078,6 +2086,8 @@ interface OverlayInfo {
     source: string;
     /** Relative path in sandbox */
     target: string;
+    /** Strategy used for the overlay */
+    strategy: OverlayStrategy;
     /** When the overlay was created */
     createdAt: string;
     /** Statistics about the overlay */
@@ -2094,6 +2104,7 @@ interface OverlayResponse {
     id: string;
     source: string;
     target: string;
+    strategy?: string;
     created_at: string;
     stats: {
         copied_files: number;
@@ -2166,6 +2177,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.strategy - Strategy to use ('copy' or 'smart')
      * @param options.waitForCompletion - If true or options object, wait for background copy to complete
      * @returns Overlay info with copy status
      */
@@ -2205,6 +2217,10 @@ declare class Overlay {
      * Convert API response to OverlayInfo
      */
     private toOverlayInfo;
+    /**
+     * Validate and return strategy, defaulting to 'copy' for unknown/missing values (legacy support)
+     */
+    private validateStrategy;
     /**
      * Validate and return copy status, defaulting to 'pending' for unknown values
      */
@@ -2925,11 +2941,16 @@ declare class Sandbox {
     private _token;
     private _ws;
     private WebSocketImpl;
+    private _terminals;
     constructor(config: SandboxConfig);
     /**
      * Get or create internal WebSocket manager
      */
     private ensureWebSocket;
+    /**
+     * Create and configure a TerminalInstance from response data
+     */
+    private hydrateTerminal;
     private request;
     /**
      * Check service health
@@ -3231,7 +3252,7 @@ declare class Sandbox {
     /**
      * Get terminal by ID
      */
-    getTerminal(id: string): Promise<TerminalResponse>;
+    getTerminal(id: string): Promise<TerminalInstance>;
     /**
      * List all commands executed in a terminal (exec mode only)
      * @param terminalId - The terminal ID

package/dist/index.d.ts

@@ -1064,7 +1064,7 @@ declare class Terminal {
             pty?: boolean;
         }) => Promise<TerminalInstance>;
         list: () => Promise<TerminalResponse[]>;
-        retrieve: (id: string) => Promise<TerminalResponse>;
+        retrieve: (id: string) => Promise<TerminalInstance>;
         destroy: (id: string) => Promise<void>;
     });
     /**
@@ -1089,9 +1089,9 @@ declare class Terminal {
     /**
      * Retrieve a specific terminal by ID
      * @param id - The terminal ID
-     * @returns Terminal response
+     * @returns Terminal instance
      */
-    retrieve(id: string): Promise<TerminalResponse>;
+    retrieve(id: string): Promise<TerminalInstance>;
     /**
      * Destroy a terminal by ID
      * @param id - The terminal ID
@@ -2040,6 +2040,12 @@ interface WaitForCompletionOptions {
     /** Backoff multiplier for exponential backoff (default: 1.5) */
     backoffFactor?: number;
 }
+/**
+ * Strategy for creating an overlay
+ * - 'copy': Full copy of all files (standard behavior)
+ * - 'smart': Use symlinks for immutable packages (e.g. node_modules) for instant creation
+ */
+type OverlayStrategy = 'copy' | 'smart';
 /**
  * Options for creating an overlay
  */
@@ -2050,6 +2056,8 @@ interface CreateOverlayOptions {
     target: string;
     /** Glob patterns to ignore (e.g., ["node_modules", "*.log"]) */
     ignore?: string[];
+    /** Strategy to use (default: 'smart') */
+    strategy?: OverlayStrategy;
     /** If true, wait for background copy to complete before returning (default: false) */
     waitForCompletion?: boolean | WaitForCompletionOptions;
 }
@@ -2078,6 +2086,8 @@ interface OverlayInfo {
     source: string;
     /** Relative path in sandbox */
     target: string;
+    /** Strategy used for the overlay */
+    strategy: OverlayStrategy;
     /** When the overlay was created */
     createdAt: string;
     /** Statistics about the overlay */
@@ -2094,6 +2104,7 @@ interface OverlayResponse {
     id: string;
     source: string;
     target: string;
+    strategy?: string;
     created_at: string;
     stats: {
         copied_files: number;
@@ -2166,6 +2177,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.strategy - Strategy to use ('copy' or 'smart')
      * @param options.waitForCompletion - If true or options object, wait for background copy to complete
      * @returns Overlay info with copy status
      */
@@ -2205,6 +2217,10 @@ declare class Overlay {
      * Convert API response to OverlayInfo
      */
     private toOverlayInfo;
+    /**
+     * Validate and return strategy, defaulting to 'copy' for unknown/missing values (legacy support)
+     */
+    private validateStrategy;
     /**
      * Validate and return copy status, defaulting to 'pending' for unknown values
      */
@@ -2925,11 +2941,16 @@ declare class Sandbox {
     private _token;
     private _ws;
     private WebSocketImpl;
+    private _terminals;
     constructor(config: SandboxConfig);
     /**
      * Get or create internal WebSocket manager
      */
     private ensureWebSocket;
+    /**
+     * Create and configure a TerminalInstance from response data
+     */
+    private hydrateTerminal;
     private request;
     /**
      * Check service health
@@ -3231,7 +3252,7 @@ declare class Sandbox {
     /**
      * Get terminal by ID
      */
-    getTerminal(id: string): Promise<TerminalResponse>;
+    getTerminal(id: string): Promise<TerminalInstance>;
     /**
      * List all commands executed in a terminal (exec mode only)
      * @param terminalId - The terminal ID

package/dist/index.js

@@ -1365,7 +1365,7 @@ var Terminal = class {
   /**
    * Retrieve a specific terminal by ID
    * @param id - The terminal ID
-   * @returns Terminal response
+   * @returns Terminal instance
    */
   async retrieve(id) {
     return this.retrieveHandler(id);
@@ -1975,6 +1975,7 @@ 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.strategy - Strategy to use ('copy' or 'smart')
    * @param options.waitForCompletion - If true or options object, wait for background copy to complete
    * @returns Overlay info with copy status
    */
@@ -2064,6 +2065,7 @@ Try increasing maxRetries or check if the source directory is very large.`
       id: response.id,
       source: response.source,
       target: response.target,
+      strategy: this.validateStrategy(response.strategy),
       createdAt: response.created_at,
       stats: {
         copiedFiles: response.stats.copied_files,
@@ -2074,6 +2076,16 @@ Try increasing maxRetries or check if the source directory is very large.`
       copyError: response.copy_error
     };
   }
+  /**
+   * Validate and return strategy, defaulting to 'copy' for unknown/missing values (legacy support)
+   */
+  validateStrategy(strategy) {
+    const validStrategies = ["copy", "smart"];
+    if (strategy && validStrategies.includes(strategy)) {
+      return strategy;
+    }
+    return "copy";
+  }
   /**
    * Validate and return copy status, defaulting to 'pending' for unknown values
    */
@@ -2104,6 +2116,7 @@ var Sandbox = class {
   constructor(config) {
     this._token = null;
     this._ws = null;
+    this._terminals = /* @__PURE__ */ new Map();
     this.sandboxId = config.sandboxId;
     this.provider = config.provider;
     let sandboxUrlResolved = config.sandboxUrl;
@@ -2310,6 +2323,44 @@ var Sandbox = class {
     }
     return this._ws;
   }
+  /**
+   * Create and configure a TerminalInstance from response data
+   */
+  async hydrateTerminal(data, ws) {
+    const terminal = new TerminalInstance(
+      data.id,
+      data.pty,
+      data.status,
+      data.channel || null,
+      ws || null,
+      data.encoding || "raw"
+    );
+    const terminalId = data.id;
+    terminal.setExecuteHandler(async (command, background) => {
+      return this.request(`/terminals/${terminalId}/execute`, {
+        method: "POST",
+        body: JSON.stringify({ command, background })
+      });
+    });
+    terminal.setListCommandsHandler(async () => {
+      return this.request(`/terminals/${terminalId}/commands`);
+    });
+    terminal.setRetrieveCommandHandler(async (cmdId) => {
+      return this.request(`/terminals/${terminalId}/commands/${cmdId}`);
+    });
+    terminal.setWaitCommandHandler(async (cmdId, timeout) => {
+      const params = timeout ? new URLSearchParams({ timeout: timeout.toString() }) : "";
+      const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait${params ? `?${params}` : ""}`;
+      return this.request(endpoint);
+    });
+    terminal.setDestroyHandler(async () => {
+      await this.request(`/terminals/${terminalId}`, {
+        method: "DELETE"
+      });
+      this._terminals.delete(terminalId);
+    });
+    return terminal;
+  }
   // ============================================================================
   // Private Helper Methods
   // ============================================================================
@@ -2816,37 +2867,8 @@ API request failed (${response.status}): ${error}`
         }
       });
     }
-    const terminal = new TerminalInstance(
-      response.data.id,
-      response.data.pty,
-      response.data.status,
-      response.data.channel || null,
-      ws,
-      response.data.encoding || "raw"
-    );
-    const terminalId = response.data.id;
-    terminal.setExecuteHandler(async (command, background) => {
-      return this.request(`/terminals/${terminalId}/execute`, {
-        method: "POST",
-        body: JSON.stringify({ command, background })
-      });
-    });
-    terminal.setListCommandsHandler(async () => {
-      return this.request(`/terminals/${terminalId}/commands`);
-    });
-    terminal.setRetrieveCommandHandler(async (cmdId) => {
-      return this.request(`/terminals/${terminalId}/commands/${cmdId}`);
-    });
-    terminal.setWaitCommandHandler(async (cmdId, timeout) => {
-      const params = timeout ? new URLSearchParams({ timeout: timeout.toString() }) : "";
-      const endpoint = `/terminals/${terminalId}/commands/${cmdId}/wait${params ? `?${params}` : ""}`;
-      return this.request(endpoint);
-    });
-    terminal.setDestroyHandler(async () => {
-      await this.request(`/terminals/${terminalId}`, {
-        method: "DELETE"
-      });
-    });
+    const terminal = await this.hydrateTerminal(response.data, ws);
+    this._terminals.set(terminal.id, terminal);
     return terminal;
   }
   /**
@@ -2860,7 +2882,18 @@ API request failed (${response.status}): ${error}`
    * Get terminal by ID
    */
   async getTerminal(id) {
-    return this.request(`/terminals/${id}`);
+    const cached = this._terminals.get(id);
+    if (cached) {
+      return cached;
+    }
+    const response = await this.request(`/terminals/${id}`);
+    let ws = null;
+    if (response.data.pty) {
+      ws = await this.ensureWebSocket();
+    }
+    const terminal = await this.hydrateTerminal(response.data, ws);
+    this._terminals.set(id, terminal);
+    return terminal;
   }
   // ============================================================================
   // Command Tracking (Exec Mode Terminals)
@@ -3464,6 +3497,7 @@ API request failed (${response.status}): ${error}`
       this._ws.disconnect();
       this._ws = null;
     }
+    this._terminals.clear();
   }
 };