computesdk 1.8.7 → 1.9.0

package/dist/index.d.ts

@@ -1,174 +1,49 @@
-import * as _computesdk_client from '@computesdk/client';
+import { Runtime, CodeResult, RunCommandOptions, CommandResult, ProviderSandboxInfo, SandboxFileSystem, CreateSandboxOptions, FileEntry, Sandbox } from '@computesdk/client';
+export { CodeLanguage, CodeResult, CodeRunOptions, CommandExitError, CommandResult, CommandRunOptions, CreateSandboxOptions, FileEntry, RunCommandOptions, Runtime, Sandbox, SandboxConfig, SandboxFileSystem, SandboxStatus, isCommandExitError } from '@computesdk/client';
 
 /**
- * Sandbox Types
- *
- * Types related to sandbox execution, filesystem, terminal operations
+ * Information about a sandbox (provider-agnostic)
+ * @see ProviderSandboxInfo in @computesdk/client for the canonical definition
  */
-interface Provider$1 {
+type SandboxInfo = ProviderSandboxInfo;
+
+interface Provider$1<TSandbox = any> {
     readonly name: string;
     readonly sandbox: any;
 }
 /**
- * Type mapping for provider names to their sandbox types
- * Manually defined for known providers since declaration merging isn't working reliably
- */
-interface ProviderSandboxTypeMap {
-    e2b: any;
-    vercel: any;
-    daytona: any;
-}
-/**
- * Utility type to extract the native instance type from a provider
- * Uses provider name and manual type inference
- */
-type ExtractSandboxInstanceType<TProvider extends Provider$1> = TProvider extends {
-    readonly name: 'e2b';
-} ? any : TProvider extends {
-    readonly name: 'vercel';
-} ? any : TProvider extends {
-    readonly name: 'daytona';
-} ? any : any;
-/**
- * Supported runtime environments
- */
-type Runtime = 'node' | 'python';
-/**
- * Sandbox status types
- */
-type SandboxStatus = 'running' | 'stopped' | 'error';
-/**
- * Options for running commands
- */
-interface RunCommandOptions {
-    /** Run command in background (non-blocking) */
-    background?: boolean;
-}
-/**
- * Result of code execution
- */
-interface ExecutionResult {
-    /** Standard output from the execution */
-    stdout: string;
-    /** Standard error from the execution */
-    stderr: string;
-    /** Exit code from the execution */
-    exitCode: number;
-    /** Time taken for execution in milliseconds */
-    executionTime: number;
-    /** ID of the sandbox where the code was executed */
-    sandboxId: string;
-    /** Provider that executed the code */
-    provider: string;
-    /** Process ID for background jobs (if applicable) */
-    pid?: number;
-    /** Whether this command is running in background */
-    isBackground?: boolean;
-}
-/**
- * Information about a sandbox
- */
-interface SandboxInfo {
-    /** Unique identifier for the sandbox */
-    id: string;
-    /** Provider hosting the sandbox */
-    provider: string;
-    /** Runtime environment in the sandbox */
-    runtime: Runtime;
-    /** Current status of the sandbox */
-    status: SandboxStatus;
-    /** When the sandbox was created */
-    createdAt: Date;
-    /** Execution timeout in milliseconds */
-    timeout: number;
-    /** Additional provider-specific metadata */
-    metadata?: Record<string, any>;
-}
-/**
- * Options for creating a sandbox
- */
-interface CreateSandboxOptions {
-    /** Runtime environment (defaults to 'node' if not specified) */
-    runtime?: Runtime;
-    /** Execution timeout in milliseconds */
-    timeout?: number;
-    /** Custom sandbox ID (if supported by provider) */
-    sandboxId?: string;
-    /** Template ID for sandbox creation (provider-specific) */
-    templateId?: string;
-    /** Additional metadata for the sandbox */
-    metadata?: Record<string, any>;
-    /** Domain for sandbox connection (provider-specific) */
-    domain?: string;
-    /** Environment variables for the sandbox */
-    envs?: Record<string, string>;
-}
-/**
- * File system entry information
- */
-interface FileEntry {
-    /** File/directory name */
-    name: string;
-    /** Full path to the entry */
-    path: string;
-    /** Whether this is a directory */
-    isDirectory: boolean;
-    /** File size in bytes (0 for directories) */
-    size: number;
-    /** Last modified timestamp */
-    lastModified: Date;
-}
-/**
- * File system interface for sandbox operations
- */
-interface SandboxFileSystem {
-    /** Read file contents */
-    readFile(path: string): Promise<string>;
-    /** Write file contents */
-    writeFile(path: string, content: string): Promise<void>;
-    /** Create directory */
-    mkdir(path: string): Promise<void>;
-    /** List directory contents */
-    readdir(path: string): Promise<FileEntry[]>;
-    /** Check if file/directory exists */
-    exists(path: string): Promise<boolean>;
-    /** Remove file or directory */
-    remove(path: string): Promise<void>;
-}
-/**
- * Error thrown when a command exits with a non-zero status
- */
-declare class CommandExitError extends Error {
-    result: {
-        exitCode: number;
-        stdout: string;
-        stderr: string;
-        error: boolean;
-    };
-    name: string;
-    constructor(result: {
-        exitCode: number;
-        stdout: string;
-        stderr: string;
-        error: boolean;
-    });
-}
-/**
- * Type guard to check if an error is a CommandExitError
- */
-declare function isCommandExitError(error: unknown): error is CommandExitError;
-/**
- * Base sandbox interface - what developers interact with
+ * Provider sandbox interface - what external providers (e2b, railway, etc.) return
+ *
+ * This is the base interface that all provider sandboxes must implement.
+ * The gateway provider returns the full Sandbox from @computesdk/client which
+ * extends this with ComputeClient features (terminals, watchers, signals).
+ *
+ * @example Provider implementation
+ * ```typescript
+ * // In @computesdk/e2b
+ * const e2bProvider = createProvider<E2BSandbox, E2BConfig>({
+ *   name: 'e2b',
+ *   methods: {
+ *     sandbox: {
+ *       create: async (config, options) => {
+ *         const sandbox = await E2BSandbox.create({ ... });
+ *         return { sandbox, sandboxId: sandbox.id };
+ *       },
+ *       // ... other methods
+ *     }
+ *   }
+ * });
+ * ```
  */
-interface Sandbox<TSandbox = any> {
+interface ProviderSandbox<TSandbox = any> {
     /** Unique identifier for the sandbox */
     readonly sandboxId: string;
     /** Provider that created this sandbox */
     readonly provider: string;
     /** Execute code in the sandbox */
-    runCode(code: string, runtime?: Runtime): Promise<ExecutionResult>;
+    runCode(code: string, runtime?: Runtime): Promise<CodeResult>;
     /** Execute shell commands */
-    runCommand(command: string, args?: string[], options?: RunCommandOptions): Promise<ExecutionResult>;
+    runCommand(commandOrArray: string | [string, ...string[]], argsOrOptions?: string[] | RunCommandOptions, maybeOptions?: RunCommandOptions): Promise<CommandResult>;
     /** Get information about the sandbox */
     getInfo(): Promise<SandboxInfo>;
     /** Get URL for accessing the sandbox on a specific port */
@@ -186,102 +61,42 @@ interface Sandbox<TSandbox = any> {
     destroy(): Promise<void>;
     /** File system operations */
     readonly filesystem: SandboxFileSystem;
+    /**
+     * Create an interactive terminal (PTY or exec mode)
+     * @optional Available when using gateway provider
+     */
+    createTerminal?(options?: {
+        shell?: string;
+        pty?: boolean;
+        encoding?: 'utf8' | 'binary';
+    }): Promise<any>;
+    /**
+     * Create a file system watcher
+     * @optional Available when using gateway provider
+     */
+    createWatcher?(path: string, options?: {
+        recursive?: boolean;
+        includeContent?: boolean;
+    }): Promise<any>;
+    /**
+     * Send a signal to a process
+     * @optional Available when using gateway provider
+     */
+    sendSignal?(pid: number, signal: string): Promise<void>;
 }
 /**
- * Extract the sandbox type from a provider
+ * Extract the sandbox type from a provider using generic inference
  */
-type ExtractProviderSandboxType<TProvider extends Provider$1> = TProvider extends {
-    readonly __sandboxType: infer TSandbox;
-} ? TSandbox : any;
+type ExtractProviderSandboxType<TProvider> = TProvider extends Provider$1<infer TSandbox> ? TSandbox : any;
 /**
- * Typed sandbox interface that preserves the provider's native instance type
+ * Typed provider sandbox interface that preserves the provider's native instance type
  */
-interface TypedSandbox<TProvider extends Provider$1> extends Omit<Sandbox<ExtractProviderSandboxType<TProvider>>, 'getProvider'> {
+interface TypedProviderSandbox<TProvider extends Provider$1> extends Omit<ProviderSandbox<ExtractProviderSandboxType<TProvider>>, 'getProvider'> {
     /** Get the provider instance that created this sandbox with proper typing */
     getProvider(): TProvider;
     /** Get the native provider sandbox instance with proper typing */
     getInstance(): ExtractProviderSandboxType<TProvider>;
 }
-/**
- * Enhanced sandbox type that includes ComputeClient features
- *
- * When a sandbox is created with an API key/JWT, it gets wrapped with ComputeClient
- * which adds powerful features like WebSocket terminals, file watchers, and signals.
- *
- * @example
- * ```typescript
- * const sandbox = await compute.sandbox.create();
- *
- * // ComputeClient features (only available when API key is configured)
- * const terminal = await sandbox.createTerminal();
- * const watcher = await sandbox.createWatcher('/home/project');
- * const signals = await sandbox.startSignals();
- *
- * // Original sandbox features still work
- * await sandbox.runCommand('ls');
- * const instance = sandbox.getInstance();
- * ```
- */
-type ComputeEnhancedSandbox<TSandbox = any> = Sandbox<TSandbox> & {
-    /** The original provider sandbox instance */
-    __originalSandbox: Sandbox<TSandbox>;
-    /** Create a persistent terminal session with WebSocket integration */
-    createTerminal(shell?: string, encoding?: 'raw' | 'base64'): Promise<_computesdk_client.Terminal>;
-    /** Create a file watcher with real-time change notifications */
-    createWatcher(path: string, options?: {
-        includeContent?: boolean;
-        ignored?: string[];
-        encoding?: 'raw' | 'base64';
-    }): Promise<_computesdk_client.FileWatcher>;
-    /** Start the signal service for port and error monitoring */
-    startSignals(): Promise<_computesdk_client.SignalService>;
-    /** Execute a one-off command without creating a persistent terminal */
-    execute(options: {
-        command: string;
-        shell?: string;
-    }): Promise<any>;
-    /** List all active terminals */
-    listTerminals(): Promise<any[]>;
-    /** Get terminal by ID */
-    getTerminal(id: string): Promise<any>;
-    /** List all active file watchers */
-    listWatchers(): Promise<any>;
-    /** Get file watcher by ID */
-    getWatcher(id: string): Promise<any>;
-    /** Get signal service status */
-    getSignalStatus(): Promise<any>;
-    /** Create a session token (requires access token) */
-    createSessionToken(options?: {
-        description?: string;
-        expiresIn?: number;
-    }): Promise<any>;
-    /** List all session tokens (requires access token) */
-    listSessionTokens(): Promise<any>;
-    /** Get session token details (requires access token) */
-    getSessionToken(tokenId: string): Promise<any>;
-    /** Revoke a session token (requires access token) */
-    revokeSessionToken(tokenId: string): Promise<void>;
-    /** Create a magic link for browser authentication (requires access token) */
-    createMagicLink(options?: {
-        redirectUrl?: string;
-    }): Promise<any>;
-    /** Check authentication status */
-    getAuthStatus(): Promise<any>;
-    /** Get authentication information */
-    getAuthInfo(): Promise<any>;
-    /** Set authentication token manually */
-    setToken(token: string): void;
-    /** Get current authentication token */
-    getToken(): string | null;
-    /** Get current sandbox URL */
-    getSandboxUrl(): string;
-    /** Disconnect WebSocket connection */
-    disconnect(): Promise<void>;
-};
-/**
- * Typed enhanced sandbox that preserves both provider typing and ComputeClient features
- */
-type TypedEnhancedSandbox<TProvider extends Provider$1> = ComputeEnhancedSandbox<ExtractProviderSandboxType<TProvider>> & Omit<TypedSandbox<TProvider>, keyof Sandbox>;
 
 /**
  * Common options for creating snapshots
@@ -321,23 +136,26 @@ interface ListTemplatesOptions {
 }
 /**
  * Provider sandbox manager interface - handles sandbox lifecycle
+ *
+ * For most providers (e2b, railway, etc.), this returns ProviderSandbox.
+ * The gateway provider returns the full Sandbox with ComputeClient features.
  */
 interface ProviderSandboxManager<TSandbox = any> {
     /** Create a new sandbox */
-    create(options?: CreateSandboxOptions): Promise<Sandbox<TSandbox>>;
+    create(options?: CreateSandboxOptions): Promise<ProviderSandbox<TSandbox>>;
     /** Get an existing sandbox by ID */
-    getById(sandboxId: string): Promise<Sandbox<TSandbox> | null>;
+    getById(sandboxId: string): Promise<ProviderSandbox<TSandbox> | null>;
     /** List all active sandboxes */
-    list(): Promise<Sandbox<TSandbox>[]>;
+    list(): Promise<ProviderSandbox<TSandbox>[]>;
     /** Destroy a sandbox */
     destroy(sandboxId: string): Promise<void>;
 }
 /**
  * Provider template manager interface - handles template/blueprint lifecycle
  */
-interface ProviderTemplateManager<TTemplate = any> {
+interface ProviderTemplateManager<TTemplate = any, TCreateOptions extends CreateTemplateOptions = CreateTemplateOptions> {
     /** Create a new template */
-    create(options: CreateTemplateOptions | any): Promise<TTemplate>;
+    create(options: TCreateOptions): Promise<TTemplate>;
     /** List all available templates */
     list(options?: ListTemplatesOptions): Promise<TTemplate[]>;
     /** Delete a template */
@@ -368,8 +186,6 @@ interface Provider<TSandbox = any, TTemplate = any, TSnapshot = any> {
     readonly snapshot?: ProviderSnapshotManager<TSnapshot>;
     /** Get the list of supported runtime environments */
     getSupportedRuntimes(): Runtime[];
-    /** Phantom type property for TypeScript inference - not used at runtime */
-    readonly __sandboxType: TSandbox;
 }
 /**
  * Configuration for the compute singleton
@@ -406,6 +222,10 @@ interface CreateSandboxParamsWithOptionalProvider {
 }
 /**
  * Base Compute API interface (non-generic)
+ *
+ * Returns ProviderSandbox which is the common interface for all sandboxes.
+ * When using gateway provider, the returned sandbox will have full Sandbox
+ * capabilities (terminals, watchers, signals) accessible via getInstance().
  */
 interface ComputeAPI {
     /** Configuration management */
@@ -414,29 +234,31 @@ interface ComputeAPI {
     clearConfig(): void;
     sandbox: {
         /** Create a sandbox from a provider (or default provider if configured) */
-        create(params?: CreateSandboxParams | CreateSandboxParamsWithOptionalProvider): Promise<Sandbox>;
+        create(params?: CreateSandboxParams | CreateSandboxParamsWithOptionalProvider): Promise<ProviderSandbox>;
         /** Get an existing sandbox by ID from a provider (or default provider if configured) */
-        getById(providerOrSandboxId: Provider | string, sandboxId?: string): Promise<Sandbox | null>;
+        getById(providerOrSandboxId: Provider | string, sandboxId?: string): Promise<ProviderSandbox | null>;
         /** List all active sandboxes from a provider (or default provider if configured) */
-        list(provider?: Provider): Promise<Sandbox[]>;
+        list(provider?: Provider): Promise<ProviderSandbox[]>;
         /** Destroy a sandbox via a provider (or default provider if configured) */
         destroy(providerOrSandboxId: Provider | string, sandboxId?: string): Promise<void>;
     };
 }
 /**
  * Typed Compute API interface that preserves provider type information
- * When auth (apiKey/accessToken) is configured, returns enhanced sandboxes with ComputeClient features
+ *
+ * When using gateway provider, returns full Sandbox with ComputeClient features.
+ * When using other providers, returns TypedProviderSandbox.
  */
-interface TypedComputeAPI<TProvider extends Provider, TIsEnhanced extends boolean = boolean> extends Omit<ComputeAPI, 'sandbox' | 'setConfig'> {
+interface TypedComputeAPI<TProvider extends Provider> extends Omit<ComputeAPI, 'sandbox' | 'setConfig'> {
     /** Configuration management that returns typed compute instance */
     setConfig<T extends Provider>(config: ComputeConfig<T>): TypedComputeAPI<T>;
     sandbox: {
         /** Create a sandbox from the configured provider with proper typing */
-        create(params?: Omit<CreateSandboxParamsWithOptionalProvider, 'provider'>): Promise<TIsEnhanced extends true ? TypedEnhancedSandbox<TProvider> : TypedSandbox<TProvider>>;
+        create(params?: Omit<CreateSandboxParamsWithOptionalProvider, 'provider'>): Promise<TypedProviderSandbox<TProvider>>;
         /** Get an existing sandbox by ID from the configured provider with proper typing */
-        getById(sandboxId: string): Promise<TIsEnhanced extends true ? TypedEnhancedSandbox<TProvider> : TypedSandbox<TProvider> | null>;
+        getById(sandboxId: string): Promise<TypedProviderSandbox<TProvider> | null>;
         /** List all active sandboxes from the configured provider with proper typing */
-        list(): Promise<TIsEnhanced extends true ? TypedEnhancedSandbox<TProvider>[] : TypedSandbox<TProvider>[]>;
+        list(): Promise<TypedProviderSandbox<TProvider>[]>;
         /** Destroy a sandbox via the configured provider */
         destroy(sandboxId: string): Promise<void>;
     };
@@ -460,88 +282,21 @@ declare const compute: ComputeAPI;
  * import { e2b } from '@computesdk/e2b'
  * import { createCompute } from 'computesdk'
  *
- * // With API key (automatically gets access token from license server)
- * const compute = createCompute({
- *   defaultProvider: e2b({ apiKey: 'your-key' }),
- *   apiKey: 'computesdk_live_...' // Returns enhanced sandboxes
- * });
+ * // Zero-config mode (auto-detects from environment)
+ * const compute = createCompute();
+ * const sandbox = await compute.sandbox.create();
  *
- * // Or with direct access token
+ * // Explicit mode
  * const compute2 = createCompute({
  *   defaultProvider: e2b({ apiKey: 'your-key' }),
- *   accessToken: 'your-access-token' // Returns enhanced sandboxes
  * });
  *
- * const sandbox = await compute.sandbox.create();
- * const instance = sandbox.getInstance(); // ✅ Properly typed E2B Sandbox!
- * await sandbox.createTerminal(); // ✅ Enhanced sandbox features!
+ * const sandbox2 = await compute2.sandbox.create();
+ * const instance = sandbox2.getInstance(); // ✅ Properly typed!
  * ```
  */
-declare function createCompute<TProvider extends Provider>(config: ComputeConfig<TProvider> & {
-    apiKey: string;
-}): TypedComputeAPI<TProvider, true>;
-declare function createCompute<TProvider extends Provider>(config: ComputeConfig<TProvider> & {
-    accessToken: string;
-}): TypedComputeAPI<TProvider, true>;
-declare function createCompute<TProvider extends Provider>(config: ComputeConfig<TProvider> & {
-    jwt: string;
-}): TypedComputeAPI<TProvider, true>;
-declare function createCompute<TProvider extends Provider>(config: ComputeConfig<TProvider>): TypedComputeAPI<TProvider, false>;
-
-/**
- * Simplified Request Handler for Web Framework Integration
- *
- * Handles JSON requests for sandbox and code execution operations.
- * Terminal support removed - will be re-added with WebSocket VM connections.
- */
-
-/**
- * Request structure supporting sandbox and code execution capabilities
- */
-interface ComputeRequest {
-    /** Action in dot notation (e.g., 'compute.sandbox.create') */
-    action: string;
-    /** Parameters for the action */
-    sandboxId?: string;
-    code?: string;
-    command?: string;
-    args?: string[];
-    runtime?: Runtime;
-    path?: string;
-    content?: string;
-    /** Command options (for runCommand action) */
-    commandOptions?: {
-        background?: boolean;
-    };
-    /** Sandbox creation options */
-    options?: {
-        runtime?: Runtime;
-        timeout?: number;
-        sandboxId?: string;
-    };
-}
-/**
- * Response structure for compute operations
- */
-interface ComputeResponse {
-    success: boolean;
-    error?: string;
-    sandboxId: string;
-    provider: string;
-    [key: string]: any;
-}
-/**
- * Main request handler - handles HTTP requests and pre-parsed bodies
- */
-declare function handleComputeRequest(params: HandleComputeRequestParams): Promise<ComputeResponse>;
-declare function handleComputeRequest(requestOrBody: Request | ComputeRequest, provider: Provider): Promise<Response>;
-/**
- * Legacy export for backward compatibility
- */
-interface HandleComputeRequestParams {
-    request: ComputeRequest;
-    provider: Provider;
-}
+declare function createCompute(): ComputeAPI;
+declare function createCompute<TProvider extends Provider>(config: ComputeConfig<TProvider>): TypedComputeAPI<TProvider>;
 
 /**
  * Provider Factory - Creates providers from method definitions
@@ -550,15 +305,6 @@ interface HandleComputeRequestParams {
  * from simple method definitions with automatic feature detection.
  */
 
-/**
- * Helper function to handle background command execution
- * Providers can use this to implement background job support
- */
-declare function createBackgroundCommand(command: string, args?: string[], options?: RunCommandOptions): {
-    command: string;
-    args: string[];
-    isBackground: boolean;
-};
 /**
  * Flat sandbox method implementations - all operations in one place
  */
@@ -576,8 +322,8 @@ interface SandboxMethods<TSandbox = any, TConfig = any> {
         sandboxId: string;
     }>>;
     destroy: (config: TConfig, sandboxId: string) => Promise<void>;
-    runCode: (sandbox: TSandbox, code: string, runtime?: Runtime, config?: TConfig) => Promise<ExecutionResult>;
-    runCommand: (sandbox: TSandbox, command: string, args?: string[], options?: RunCommandOptions) => Promise<ExecutionResult>;
+    runCode: (sandbox: TSandbox, code: string, runtime?: Runtime, config?: TConfig) => Promise<CodeResult>;
+    runCommand: (sandbox: TSandbox, command: string, args?: string[], options?: RunCommandOptions) => Promise<CommandResult>;
     getInfo: (sandbox: TSandbox) => Promise<SandboxInfo>;
     getUrl: (sandbox: TSandbox, options: {
         port: number;
@@ -585,19 +331,19 @@ interface SandboxMethods<TSandbox = any, TConfig = any> {
     }) => Promise<string>;
     getInstance?: (sandbox: TSandbox) => TSandbox;
     filesystem?: {
-        readFile: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<string>;
-        writeFile: (sandbox: TSandbox, path: string, content: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<void>;
-        mkdir: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<void>;
-        readdir: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<FileEntry[]>;
-        exists: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<boolean>;
-        remove: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<ExecutionResult>) => Promise<void>;
+        readFile: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<CommandResult>) => Promise<string>;
+        writeFile: (sandbox: TSandbox, path: string, content: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<CommandResult>) => Promise<void>;
+        mkdir: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<CommandResult>) => Promise<void>;
+        readdir: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<CommandResult>) => Promise<FileEntry[]>;
+        exists: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<CommandResult>) => Promise<boolean>;
+        remove: (sandbox: TSandbox, path: string, runCommand: (sandbox: TSandbox, command: string, args?: string[]) => Promise<CommandResult>) => Promise<void>;
     };
 }
 /**
  * Template method implementations
  */
-interface TemplateMethods<TTemplate = any, TConfig = any> {
-    create: (config: TConfig, options: CreateTemplateOptions | any) => Promise<TTemplate>;
+interface TemplateMethods<TTemplate = any, TConfig = any, TCreateOptions extends CreateTemplateOptions = CreateTemplateOptions> {
+    create: (config: TConfig, options: TCreateOptions) => Promise<TTemplate>;
     list: (config: TConfig, options?: ListTemplatesOptions) => Promise<TTemplate[]>;
     delete: (config: TConfig, templateId: string) => Promise<void>;
 }
@@ -609,17 +355,50 @@ interface SnapshotMethods<TSnapshot = any, TConfig = any> {
     list: (config: TConfig, options?: ListSnapshotsOptions) => Promise<TSnapshot[]>;
     delete: (config: TConfig, snapshotId: string) => Promise<void>;
 }
+/**
+ * Provider execution modes
+ *
+ * - 'raw': Use raw provider methods directly (for gateway internal use)
+ * - 'direct': Use provider's native SDK directly (for providers with sandbox capabilities)
+ * - 'gateway': Route through ComputeSDK gateway (for providers without native sandbox)
+ */
+type ProviderMode = 'raw' | 'direct' | 'gateway';
 /**
  * Provider configuration for createProvider()
  */
 interface ProviderConfig<TSandbox = any, TConfig = any, TTemplate = any, TSnapshot = any> {
     name: string;
+    /**
+     * Default execution mode for this provider (defaults to 'gateway' if not specified)
+     *
+     * - 'direct': Provider has native sandbox capabilities (e.g., E2B) - uses provider SDK directly
+     * - 'gateway': Provider only has infrastructure (e.g., Railway) - routes through gateway
+     *
+     * Can be overridden at runtime with `mode` in config.
+     */
+    defaultMode?: 'direct' | 'gateway';
     methods: {
         sandbox: SandboxMethods<TSandbox, TConfig>;
         template?: TemplateMethods<TTemplate, TConfig>;
         snapshot?: SnapshotMethods<TSnapshot, TConfig>;
     };
 }
+/**
+ * Base config that all provider configs should extend
+ * Includes the `mode` option for controlling execution mode
+ */
+interface BaseProviderConfig {
+    /**
+     * Execution mode override
+     *
+     * - 'raw': Use raw provider methods directly (for gateway internal use)
+     * - 'direct': Use provider's native SDK directly
+     * - 'gateway': Route through ComputeSDK gateway
+     *
+     * If not specified, uses the provider's `defaultMode`.
+     */
+    mode?: ProviderMode;
+}
 /**
  * Create a provider from method definitions
  *
@@ -628,4 +407,184 @@ interface ProviderConfig<TSandbox = any, TConfig = any, TTemplate = any, TSnapsh
  */
 declare function createProvider<TSandbox, TConfig = any, TTemplate = any, TSnapshot = any>(providerConfig: ProviderConfig<TSandbox, TConfig, TTemplate, TSnapshot>): (config: TConfig) => Provider<TSandbox, TTemplate, TSnapshot>;
 
-export { CommandExitError, type ComputeAPI, type ComputeConfig, type ComputeEnhancedSandbox, type ComputeRequest, type ComputeResponse, type CreateSandboxOptions, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type CreateSnapshotOptions, type CreateTemplateOptions, type ExecutionResult, type ExtractSandboxInstanceType, type FileEntry, type HandleComputeRequestParams, type ListSnapshotsOptions, type ListTemplatesOptions, type Provider, type ProviderConfig, type ProviderSandboxManager, type ProviderSandboxTypeMap, type ProviderSnapshotManager, type ProviderTemplateManager, type RunCommandOptions, type Runtime, type Sandbox, type SandboxFileSystem, type SandboxInfo, type SandboxMethods, type SandboxStatus, type SnapshotMethods, type TemplateMethods, type TypedComputeAPI, type TypedEnhancedSandbox, type TypedSandbox, compute, createBackgroundCommand, createCompute, createProvider, handleComputeRequest, isCommandExitError };
+/**
+ * Gateway provider configuration
+ */
+interface GatewayConfig extends BaseProviderConfig {
+    /** Gateway URL (default: https://gateway.computesdk.com) */
+    gatewayUrl?: string;
+    /** ComputeSDK API key for authentication */
+    apiKey: string;
+    /** Backend provider name (e2b, railway, etc.) */
+    provider: string;
+    /** Provider-specific headers to pass through to gateway */
+    providerHeaders?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 30000) */
+    requestTimeout?: number;
+    /** Maximum retry attempts for transient failures (default: 3) */
+    maxRetries?: number;
+    /** Initial retry delay in milliseconds (default: 1000) */
+    retryDelay?: number;
+    /** HTTP status codes that should trigger a retry (default: [408, 429, 502, 503, 504]) */
+    retryableStatuses?: number[];
+}
+/**
+ * Gateway Provider factory
+ *
+ * Uses ClientSandbox directly as the sandbox type - no wrapper needed.
+ */
+declare const gateway: (config: GatewayConfig) => Provider<Sandbox, any, any>;
+
+/**
+ * Auto-Detection Module
+ *
+ * Automatically detects gateway mode and provider from environment variables.
+ * Enables zero-config usage of ComputeSDK.
+ */
+
+/**
+ * Check if gateway mode is enabled
+ * Gateway mode requires COMPUTESDK_API_KEY to be set
+ */
+declare function isGatewayModeEnabled(): boolean;
+/**
+ * Detect which provider to use from environment variables
+ *
+ * Detection order:
+ * 1. Check for explicit COMPUTESDK_PROVIDER override
+ * 2. Auto-detect based on PROVIDER_PRIORITY order
+ *
+ * @returns Provider name or null if none detected
+ */
+declare function detectProvider(): string | null;
+/**
+ * Build provider-specific headers from environment variables
+ * These headers are passed through to the gateway
+ */
+declare function getProviderHeaders(provider: string): Record<string, string>;
+/**
+ * Main auto-configuration function
+ * Returns configured HTTP provider or null if auto-detection not possible
+ *
+ * @throws Error if COMPUTESDK_API_KEY is set but no provider detected
+ */
+declare function autoConfigureCompute(): Provider | null;
+
+/**
+ * ComputeSDK Constants
+ *
+ * Default configuration values and provider definitions
+ */
+/**
+ * Default gateway URL for sandbox lifecycle operations
+ */
+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", "daytona", "modal", "runloop", "vercel", "cloudflare", "codesandbox", "blaxel"];
+/**
+ * Required environment variables for each provider
+ * Used to detect which provider to use from environment
+ */
+declare const PROVIDER_ENV_VARS: {
+    readonly e2b: readonly ["E2B_API_KEY"];
+    readonly railway: readonly ["RAILWAY_API_KEY", "RAILWAY_PROJECT_ID", "RAILWAY_ENVIRONMENT_ID"];
+    readonly daytona: readonly ["DAYTONA_API_KEY"];
+    readonly modal: readonly ["MODAL_TOKEN_ID", "MODAL_TOKEN_SECRET"];
+    readonly runloop: readonly ["RUNLOOP_API_KEY"];
+    readonly vercel: readonly ["VERCEL_TOKEN", "VERCEL_TEAM_ID", "VERCEL_PROJECT_ID"];
+    readonly cloudflare: readonly ["CLOUDFLARE_API_TOKEN", "CLOUDFLARE_ACCOUNT_ID"];
+    readonly codesandbox: readonly ["CSB_API_KEY"];
+    readonly blaxel: readonly ["BL_API_KEY", "BL_WORKSPACE"];
+};
+/**
+ * Type for provider names
+ */
+type ProviderName = keyof typeof PROVIDER_ENV_VARS;
+
+/**
+ * Utility functions for ComputeSDK
+ */
+/**
+ * Calculate exponential backoff delay with jitter
+ *
+ * Uses exponential backoff (2^attempt) multiplied by base delay,
+ * plus random jitter to prevent thundering herd.
+ *
+ * @param attempt - Current retry attempt (0-indexed)
+ * @param baseDelay - Base delay in milliseconds (default: 1000)
+ * @param jitterMax - Maximum random jitter in milliseconds (default: 100)
+ * @returns Delay in milliseconds
+ *
+ * @example
+ * ```typescript
+ * // First retry: 1000-1100ms
+ * calculateBackoff(0);
+ *
+ * // Second retry: 2000-2100ms
+ * calculateBackoff(1);
+ *
+ * // Third retry: 4000-4100ms
+ * calculateBackoff(2);
+ * ```
+ */
+declare function calculateBackoff(attempt: number, baseDelay?: number, jitterMax?: number): number;
+
+/**
+ * Simplified Request Handler for Web Framework Integration
+ *
+ * Handles JSON requests for sandbox and code execution operations.
+ * Terminal support removed - will be re-added with WebSocket VM connections.
+ */
+
+/**
+ * Request structure supporting sandbox and code execution capabilities
+ */
+interface ComputeRequest {
+    /** Action in dot notation (e.g., 'compute.sandbox.create') */
+    action: string;
+    /** Parameters for the action */
+    sandboxId?: string;
+    code?: string;
+    command?: string;
+    args?: string[];
+    runtime?: Runtime;
+    path?: string;
+    content?: string;
+    /** Command options (for runCommand action) */
+    commandOptions?: {
+        background?: boolean;
+    };
+    /** Sandbox creation options */
+    options?: {
+        runtime?: Runtime;
+        timeout?: number;
+        sandboxId?: string;
+    };
+}
+/**
+ * Response structure for compute operations
+ */
+interface ComputeResponse {
+    success: boolean;
+    error?: string;
+    sandboxId: string;
+    provider: string;
+    [key: string]: any;
+}
+/**
+ * Main request handler - handles HTTP requests and pre-parsed bodies
+ */
+declare function handleComputeRequest(params: HandleComputeRequestParams): Promise<ComputeResponse>;
+declare function handleComputeRequest(requestOrBody: Request | ComputeRequest, provider: Provider): Promise<Response>;
+/**
+ * Legacy export for backward compatibility
+ */
+interface HandleComputeRequestParams {
+    request: ComputeRequest;
+    provider: Provider;
+}
+
+export { type BaseProviderConfig, type ComputeAPI, type ComputeConfig, type ComputeRequest, type ComputeResponse, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type CreateSnapshotOptions, type CreateTemplateOptions, GATEWAY_URL, type GatewayConfig, type HandleComputeRequestParams, type ListSnapshotsOptions, type ListTemplatesOptions, PROVIDER_ENV_VARS, PROVIDER_PRIORITY, type Provider, type ProviderConfig, type ProviderMode, type ProviderName, type ProviderSandbox, type ProviderSandboxManager, type ProviderSnapshotManager, type ProviderTemplateManager, type SandboxInfo, type SandboxMethods, type SnapshotMethods, type TemplateMethods, type TypedComputeAPI, type TypedProviderSandbox, autoConfigureCompute, calculateBackoff, compute, createCompute, createProvider, detectProvider, gateway, getProviderHeaders, handleComputeRequest, isGatewayModeEnabled };