computesdk 1.18.0 → 1.18.2

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
@@ -3590,6 +3611,7 @@ declare const PROVIDER_AUTH: {
     readonly cloudflare: readonly [readonly ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"]];
     readonly codesandbox: readonly [readonly ["CSB_API_KEY"]];
     readonly blaxel: readonly [readonly ["BL_API_KEY", "BL_WORKSPACE"]];
+    readonly namespace: readonly [readonly ["NSC_TOKEN"]];
 };
 /**
  * All supported provider names (excluding gateway which is special)
@@ -3705,6 +3727,9 @@ interface ExplicitComputeConfig {
         apiKey?: string;
         workspace?: string;
     };
+    namespace?: {
+        token?: string;
+    };
 }
 /**
  * Options for creating a sandbox via the gateway
@@ -3721,6 +3746,8 @@ interface CreateSandboxOptions {
     namespace?: string;
     /** Docker image to use for the sandbox (for infrastructure providers like Railway) */
     image?: string;
+    /** Provider-specific snapshot to create from (e.g., Vercel snapshots) */
+    snapshotId?: string;
 }
 /**
  * Options for finding or creating a named sandbox
@@ -3896,7 +3923,7 @@ declare const GATEWAY_URL = "https://gateway.computesdk.com";
  * Provider detection priority order
  * When multiple provider credentials are detected, use the first one in this list
  */
-declare const PROVIDER_PRIORITY: readonly ["e2b", "railway", "render", "daytona", "modal", "runloop", "vercel", "cloudflare", "codesandbox", "blaxel"];
+declare const PROVIDER_PRIORITY: readonly ["e2b", "railway", "render", "daytona", "modal", "runloop", "vercel", "cloudflare", "codesandbox", "blaxel", "namespace"];
 /**
  * Required environment variables for each provider
  * @deprecated Use PROVIDER_AUTH from provider-config instead
@@ -3912,6 +3939,7 @@ declare const PROVIDER_ENV_VARS: {
     readonly cloudflare: readonly ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"];
     readonly codesandbox: readonly ["CSB_API_KEY"];
     readonly blaxel: readonly ["BL_API_KEY", "BL_WORKSPACE"];
+    readonly namespace: readonly ["NSC_TOKEN"];
 };
 
 export { type CallableCompute, type CodeResult$1 as CodeResult, CommandExitError, type CommandResult$1 as CommandResult, type CreateSandboxOptions$1 as CreateSandboxOptions, type ExplicitComputeConfig, type FileEntry, FileWatcher, GATEWAY_URL, Sandbox as GatewaySandbox, MessageType, PROVIDER_AUTH, PROVIDER_DASHBOARD_URLS, PROVIDER_ENV_MAP, PROVIDER_ENV_VARS, PROVIDER_HEADERS, PROVIDER_NAMES, PROVIDER_PRIORITY, type ProviderName, type ProviderSandboxInfo, type RunCommandOptions, type Runtime, Sandbox, type SandboxFileSystem, type SandboxInfo$1 as SandboxInfo, type Sandbox$1 as SandboxInterface, type SandboxStatus, SignalService, TerminalInstance, type WebSocketConstructor, autoConfigureCompute, buildProviderHeaders, compute, decodeBinaryMessage, detectProvider, encodeBinaryMessage, getMissingEnvVars, getProviderConfigFromEnv, getProviderHeaders, isCommandExitError, isGatewayModeEnabled, isProviderAuthComplete, isValidProvider };

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
@@ -3590,6 +3611,7 @@ declare const PROVIDER_AUTH: {
     readonly cloudflare: readonly [readonly ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"]];
     readonly codesandbox: readonly [readonly ["CSB_API_KEY"]];
     readonly blaxel: readonly [readonly ["BL_API_KEY", "BL_WORKSPACE"]];
+    readonly namespace: readonly [readonly ["NSC_TOKEN"]];
 };
 /**
  * All supported provider names (excluding gateway which is special)
@@ -3705,6 +3727,9 @@ interface ExplicitComputeConfig {
         apiKey?: string;
         workspace?: string;
     };
+    namespace?: {
+        token?: string;
+    };
 }
 /**
  * Options for creating a sandbox via the gateway
@@ -3721,6 +3746,8 @@ interface CreateSandboxOptions {
     namespace?: string;
     /** Docker image to use for the sandbox (for infrastructure providers like Railway) */
     image?: string;
+    /** Provider-specific snapshot to create from (e.g., Vercel snapshots) */
+    snapshotId?: string;
 }
 /**
  * Options for finding or creating a named sandbox
@@ -3896,7 +3923,7 @@ declare const GATEWAY_URL = "https://gateway.computesdk.com";
  * Provider detection priority order
  * When multiple provider credentials are detected, use the first one in this list
  */
-declare const PROVIDER_PRIORITY: readonly ["e2b", "railway", "render", "daytona", "modal", "runloop", "vercel", "cloudflare", "codesandbox", "blaxel"];
+declare const PROVIDER_PRIORITY: readonly ["e2b", "railway", "render", "daytona", "modal", "runloop", "vercel", "cloudflare", "codesandbox", "blaxel", "namespace"];
 /**
  * Required environment variables for each provider
  * @deprecated Use PROVIDER_AUTH from provider-config instead
@@ -3912,6 +3939,7 @@ declare const PROVIDER_ENV_VARS: {
     readonly cloudflare: readonly ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"];
     readonly codesandbox: readonly ["CSB_API_KEY"];
     readonly blaxel: readonly ["BL_API_KEY", "BL_WORKSPACE"];
+    readonly namespace: readonly ["NSC_TOKEN"];
 };
 
 export { type CallableCompute, type CodeResult$1 as CodeResult, CommandExitError, type CommandResult$1 as CommandResult, type CreateSandboxOptions$1 as CreateSandboxOptions, type ExplicitComputeConfig, type FileEntry, FileWatcher, GATEWAY_URL, Sandbox as GatewaySandbox, MessageType, PROVIDER_AUTH, PROVIDER_DASHBOARD_URLS, PROVIDER_ENV_MAP, PROVIDER_ENV_VARS, PROVIDER_HEADERS, PROVIDER_NAMES, PROVIDER_PRIORITY, type ProviderName, type ProviderSandboxInfo, type RunCommandOptions, type Runtime, Sandbox, type SandboxFileSystem, type SandboxInfo$1 as SandboxInfo, type Sandbox$1 as SandboxInterface, type SandboxStatus, SignalService, TerminalInstance, type WebSocketConstructor, autoConfigureCompute, buildProviderHeaders, compute, decodeBinaryMessage, detectProvider, encodeBinaryMessage, getMissingEnvVars, getProviderConfigFromEnv, getProviderHeaders, isCommandExitError, isGatewayModeEnabled, isProviderAuthComplete, isValidProvider };

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();
   }
 };
 
@@ -3481,7 +3515,8 @@ var PROVIDER_AUTH = {
   runloop: [["RUNLOOP_API_KEY"]],
   cloudflare: [["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"]],
   codesandbox: [["CSB_API_KEY"]],
-  blaxel: [["BL_API_KEY", "BL_WORKSPACE"]]
+  blaxel: [["BL_API_KEY", "BL_WORKSPACE"]],
+  namespace: [["NSC_TOKEN"]]
 };
 var PROVIDER_NAMES = Object.keys(PROVIDER_AUTH);
 var PROVIDER_HEADERS = {
@@ -3523,6 +3558,9 @@ var PROVIDER_HEADERS = {
   blaxel: {
     apiKey: "X-BL-API-Key",
     workspace: "X-BL-Workspace"
+  },
+  namespace: {
+    token: "X-Namespace-Token"
   }
 };
 var PROVIDER_ENV_MAP = {
@@ -3564,6 +3602,9 @@ var PROVIDER_ENV_MAP = {
   blaxel: {
     BL_API_KEY: "apiKey",
     BL_WORKSPACE: "workspace"
+  },
+  namespace: {
+    NSC_TOKEN: "token"
   }
 };
 var PROVIDER_DASHBOARD_URLS = {
@@ -3576,7 +3617,8 @@ var PROVIDER_DASHBOARD_URLS = {
   runloop: "https://runloop.ai/dashboard",
   cloudflare: "https://dash.cloudflare.com/profile/api-tokens",
   codesandbox: "https://codesandbox.io/dashboard/settings",
-  blaxel: "https://blaxel.ai/dashboard"
+  blaxel: "https://blaxel.ai/dashboard",
+  namespace: "https://cloud.namespace.so"
 };
 function isValidProvider(name) {
   return name in PROVIDER_AUTH;
@@ -3644,7 +3686,8 @@ var PROVIDER_PRIORITY = [
   "vercel",
   "cloudflare",
   "codesandbox",
-  "blaxel"
+  "blaxel",
+  "namespace"
 ];
 var PROVIDER_ENV_VARS = {
   e2b: ["E2B_API_KEY"],
@@ -3656,7 +3699,8 @@ var PROVIDER_ENV_VARS = {
   vercel: ["VERCEL_TOKEN", "VERCEL_TEAM_ID", "VERCEL_PROJECT_ID"],
   cloudflare: ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"],
   codesandbox: ["CSB_API_KEY"],
-  blaxel: ["BL_API_KEY", "BL_WORKSPACE"]
+  blaxel: ["BL_API_KEY", "BL_WORKSPACE"],
+  namespace: ["NSC_TOKEN"]
 };
 
 // src/auto-detect.ts
@@ -3773,6 +3817,11 @@ function getProviderHeaders(provider) {
         headers["X-Blaxel-Workspace"] = process.env.BL_WORKSPACE;
       }
       break;
+    case "namespace":
+      if (process.env.NSC_TOKEN) {
+        headers["X-Namespace-Token"] = process.env.NSC_TOKEN;
+      }
+      break;
   }
   return headers;
 }
@@ -3809,6 +3858,7 @@ To fix this, set one of the following:
   Cloudflare: export CLOUDFLARE_API_TOKEN=xxx CLOUDFLARE_ACCOUNT_ID=xxx
   CodeSandbox: export CSB_API_KEY=xxx
   Blaxel:     export BL_API_KEY=xxx BL_WORKSPACE=xxx
+  Namespace:  export NSC_TOKEN=xxx
 
 Or set COMPUTESDK_PROVIDER to specify explicitly:
   export COMPUTESDK_PROVIDER=e2b