computesdk 1.0.2 → 1.1.0

package/dist/index.d.ts

@@ -1,16 +1,12 @@
 /**
- * ComputeSDK Types
+ * Sandbox Types
  *
- * This file contains all the type definitions for the ComputeSDK.
+ * Types related to sandbox execution, filesystem, terminal operations
  */
 /**
  * Supported runtime environments
  */
 type Runtime = 'node' | 'python';
-/**
- * Supported provider types
- */
-type ProviderType = 'e2b' | 'vercel' | 'cloudflare' | 'fly' | 'auto';
 /**
  * Sandbox status types
  */
@@ -52,416 +48,496 @@ interface SandboxInfo {
     metadata?: Record<string, any>;
 }
 /**
- * Configuration for container-based providers
- */
-interface ContainerConfig {
-    /** Docker image to use */
-    image: string;
-    /** Command to run in the container */
-    command?: string[];
-    /** Environment variables for the container */
-    env?: Record<string, string>;
-    /** Ports to expose from the container */
-    ports?: number[];
-    /** Working directory in the container */
-    workdir?: string;
-}
-/**
- * Configuration for creating a compute sandbox
+ * Options for creating a sandbox
  */
-interface SandboxConfig {
-    /** Provider to use for execution */
-    provider?: ProviderType;
-    /** Runtime environment to use */
+interface CreateSandboxOptions {
+    /** Runtime environment */
     runtime?: Runtime;
-    /** Container configuration if using container-based provider */
-    container?: string | ContainerConfig;
     /** Execution timeout in milliseconds */
     timeout?: number;
+    /** Custom sandbox ID (if supported by provider) */
+    sandboxId?: string;
 }
 /**
- * Provider specification that all providers must implement
- */
-interface ComputeSpecification {
-    /** Version of the specification */
-    specificationVersion: 'v1';
-    /** Provider identifier */
-    provider: string;
-    /** Sandbox identifier */
-    sandboxId: string;
-    /** Execute code in the sandbox */
-    doExecute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
-    /** Kill the sandbox */
-    doKill(): Promise<void>;
-    /** Get information about the sandbox */
-    doGetInfo(): Promise<SandboxInfo>;
+ * 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;
 }
 /**
- * The core compute sandbox interface that all providers expose
- */
-interface ComputeSandbox {
-    /** Provider identifier */
-    provider: string;
-    /** Sandbox identifier */
-    sandboxId: string;
-    /** Execute code in the sandbox */
-    execute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
-    /** Kill the sandbox */
+ * 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>;
+}
+/**
+ * Terminal session information
+ */
+interface TerminalSession {
+    /** Terminal process ID */
+    pid: number;
+    /** Terminal command */
+    command: string;
+    /** Terminal status */
+    status: 'running' | 'exited';
+    /** Exit code (if exited) */
+    exitCode?: number;
+    /** Terminal columns */
+    cols: number;
+    /** Terminal rows */
+    rows: number;
+    /** Write data to this terminal session */
+    write(data: Uint8Array | string): Promise<void>;
+    /** Resize this terminal session */
+    resize(cols: number, rows: number): Promise<void>;
+    /** Kill this terminal session */
     kill(): Promise<void>;
-    /** Get information about the sandbox */
-    getInfo(): Promise<SandboxInfo>;
+    /** Data stream handler */
+    onData?: (data: Uint8Array) => void;
+    /** Exit handler */
+    onExit?: (exitCode: number) => void;
 }
 /**
- * Parameters for the executeSandbox function
+ * Terminal creation options
  */
-interface ExecuteSandboxParams {
-    /** Sandbox to execute in */
-    sandbox: ComputeSandbox;
-    /** Code to execute */
-    code: string;
-    /** Runtime to use */
-    runtime?: Runtime;
+interface TerminalCreateOptions {
+    /** Command to run (defaults to shell) */
+    command?: string;
+    /** Terminal columns */
+    cols?: number;
+    /** Terminal rows */
+    rows?: number;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Data stream handler */
+    onData?: (data: Uint8Array) => void;
+    /** Exit handler */
+    onExit?: (exitCode: number) => void;
 }
 /**
- * Provider registry configuration
- */
-interface ProviderRegistry {
-    /** Get a sandbox by ID */
-    sandbox(id: string): ComputeSandbox;
+ * Terminal operations interface for managing terminal sessions in a sandbox
+ */
+interface SandboxTerminal {
+    /** Create a new interactive terminal session */
+    create(options?: TerminalCreateOptions): Promise<TerminalSession>;
+    /** Get existing terminal session by ID */
+    getById(terminalId: string): Promise<TerminalSession | null>;
+    /** List active terminal sessions */
+    list(): Promise<TerminalSession[]>;
+    /** Destroy a terminal session */
+    destroy(terminalId: string): Promise<void>;
 }
 /**
- * Provider factory function type
- */
-type ProviderFactory = (config?: any) => ComputeSandbox;
+ * Factory method definitions for sandbox management operations
+ * Used by createProvider() to generate ProviderSandboxManager implementations
+ */
+interface SandboxManagerMethods<TSandbox = any, TConfig = any> {
+    /** Create a new sandbox */
+    create: (config: TConfig, options?: CreateSandboxOptions) => Promise<{
+        sandbox: TSandbox;
+        sandboxId: string;
+    }>;
+    /** Get an existing sandbox by ID */
+    getById: (config: TConfig, sandboxId: string) => Promise<{
+        sandbox: TSandbox;
+        sandboxId: string;
+    } | null>;
+    /** List all active sandboxes */
+    list: (config: TConfig) => Promise<Array<{
+        sandbox: TSandbox;
+        sandboxId: string;
+    }>>;
+    /** Destroy a sandbox */
+    destroy: (config: TConfig, sandboxId: string) => Promise<void>;
+}
 /**
- * Provider registry map type
+ * Base sandbox interface - what developers interact with
  */
-type ProviderMap = Record<string, ProviderFactory>;
+interface Sandbox {
+    /** 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>;
+    /** Execute shell commands */
+    runCommand(command: string, args?: string[]): Promise<ExecutionResult>;
+    /** Get information about the sandbox */
+    getInfo(): Promise<SandboxInfo>;
+    /** Kill the sandbox */
+    kill(): Promise<void>;
+    /** Destroy the sandbox and clean up resources */
+    destroy(): Promise<void>;
+    /** File system operations */
+    readonly filesystem: SandboxFileSystem;
+    /** Terminal operations */
+    readonly terminal: SandboxTerminal;
+}
 
 /**
- * ComputeSDK Error Handling
+ * Provider Types
  *
- * This file contains standardized error classes for the ComputeSDK.
+ * Types related to provider configuration, authentication, and resource management
  */
+
 /**
- * Base error class for all ComputeSDK errors
- */
-declare abstract class ComputeError extends Error {
-    /** Error code identifier */
-    abstract readonly code: string;
-    /** Whether the operation can be retried */
-    abstract readonly isRetryable: boolean;
-    /** Provider where the error occurred */
-    readonly provider: string;
-    /** Sandbox ID where the error occurred */
-    readonly sandboxId?: string;
-    /**
-     * Create a new ComputeError
-     *
-     * @param message Error message
-     * @param provider Provider identifier
-     * @param sandboxId Optional sandbox identifier
-     */
-    constructor(message: string, provider: string, sandboxId?: string);
+ * Provider sandbox management interface
+ */
+interface ProviderSandboxManager {
+    /** Create a new sandbox */
+    create(options?: CreateSandboxOptions): Promise<Sandbox>;
+    /** Get an existing sandbox by ID */
+    getById(sandboxId: string): Promise<Sandbox | null>;
+    /** List all active sandboxes */
+    list(): Promise<Sandbox[]>;
+    /** Destroy a sandbox */
+    destroy(sandboxId: string): Promise<void>;
 }
 /**
- * Error thrown when code execution fails
+ * Provider interface - creates and manages resources
  */
-declare class ExecutionError extends ComputeError {
-    /** Error code */
-    readonly code = "EXECUTION_ERROR";
-    /** Execution errors are generally not retryable */
-    readonly isRetryable = false;
-    /** Exit code from the failed execution */
-    readonly exitCode: number;
-    /**
-     * Create a new ExecutionError
-     *
-     * @param message Error message
-     * @param provider Provider identifier
-     * @param exitCode Exit code from the execution
-     * @param sandboxId Optional sandbox identifier
-     */
-    constructor(message: string, provider: string, exitCode: number, sandboxId?: string);
+interface Provider {
+    /** Provider name/type */
+    readonly name: string;
+    /** Sandbox management operations */
+    readonly sandbox: ProviderSandboxManager;
 }
 /**
- * Error thrown when code execution times out
+ * Configuration for the compute singleton
  */
-declare class TimeoutError extends ComputeError {
-    /** Error code */
-    readonly code = "TIMEOUT_ERROR";
-    /** Timeout errors may be retryable with a longer timeout */
-    readonly isRetryable = true;
-    /** Timeout duration in milliseconds */
-    readonly timeoutMs: number;
-    /**
-     * Create a new TimeoutError
-     *
-     * @param message Error message
-     * @param provider Provider identifier
-     * @param timeoutMs Timeout duration in milliseconds
-     * @param sandboxId Optional sandbox identifier
-     */
-    constructor(message: string, provider: string, timeoutMs: number, sandboxId?: string);
+interface ComputeConfig {
+    /** Default provider to use when none is specified */
+    provider: Provider;
 }
 /**
- * Error thrown when provider-specific operations fail
+ * Parameters for compute.sandbox.create()
  */
-declare class ProviderError extends ComputeError {
-    /** Error code */
-    readonly code = "PROVIDER_ERROR";
-    /** Provider errors may be retryable */
-    readonly isRetryable = true;
-    /** Original error from the provider */
-    readonly originalError?: Error;
-    /**
-     * Create a new ProviderError
-     *
-     * @param message Error message
-     * @param provider Provider identifier
-     * @param originalError Optional original error from the provider
-     * @param sandboxId Optional sandbox identifier
-     */
-    constructor(message: string, provider: string, originalError?: Error, sandboxId?: string);
-}
-/**
- * Error thrown when configuration is invalid
- */
-declare class ConfigurationError extends ComputeError {
-    /** Error code */
-    readonly code = "CONFIGURATION_ERROR";
-    /** Configuration errors are not retryable without changes */
-    readonly isRetryable = false;
-    /**
-     * Create a new ConfigurationError
-     *
-     * @param message Error message
-     * @param provider Provider identifier
-     * @param sandboxId Optional sandbox identifier
-     */
-    constructor(message: string, provider: string, sandboxId?: string);
+interface CreateSandboxParams {
+    /** Provider instance to use */
+    provider: Provider;
+    /** Optional sandbox creation options */
+    options?: CreateSandboxOptions;
 }
 /**
- * Error thrown when authentication fails
+ * Parameters for compute.sandbox.create() with optional provider
  */
-declare class AuthenticationError extends ComputeError {
-    /** Error code */
-    readonly code = "AUTHENTICATION_ERROR";
-    /** Authentication errors are not retryable without new credentials */
-    readonly isRetryable = false;
-    /**
-     * Create a new AuthenticationError
-     *
-     * @param message Error message
-     * @param provider Provider identifier
-     * @param sandboxId Optional sandbox identifier
-     */
-    constructor(message: string, provider: string, sandboxId?: string);
+interface CreateSandboxParamsWithOptionalProvider {
+    /** Provider instance to use (optional if default is set) */
+    provider?: Provider;
+    /** Optional sandbox creation options */
+    options?: CreateSandboxOptions;
 }
 /**
- * Error thrown when the provider is not available
- */
-declare class ProviderUnavailableError extends ComputeError {
-    /** Error code */
-    readonly code = "PROVIDER_UNAVAILABLE";
-    /** Provider unavailability may be temporary */
-    readonly isRetryable = true;
-    /**
-     * Create a new ProviderUnavailableError
-     *
-     * @param message Error message
-     * @param provider Provider identifier
-     * @param sandboxId Optional sandbox identifier
-     */
-    constructor(message: string, provider: string, sandboxId?: string);
+ * Compute singleton interface
+ */
+interface ComputeAPI {
+    /** Configuration management */
+    setConfig(config: ComputeConfig): void;
+    getConfig(): ComputeConfig | null;
+    clearConfig(): void;
+    sandbox: {
+        /** Create a sandbox from a provider (or default provider if configured) */
+        create(params: CreateSandboxParams | CreateSandboxParamsWithOptionalProvider): Promise<Sandbox>;
+        /** Get an existing sandbox by ID from a provider (or default provider if configured) */
+        getById(providerOrSandboxId: Provider | string, sandboxId?: string): Promise<Sandbox | null>;
+        /** List all active sandboxes from a provider (or default provider if configured) */
+        list(provider?: Provider): Promise<Sandbox[]>;
+        /** Destroy a sandbox via a provider (or default provider if configured) */
+        destroy(providerOrSandboxId: Provider | string, sandboxId?: string): Promise<void>;
+    };
 }
 
 /**
- * ComputeSDK Configuration Management
+ * Compute Singleton - Main API Orchestrator
  *
- * This file manages configuration and provider selection logic.
+ * Provides the unified compute.* API and delegates to specialized managers
  */
 
-declare global {
-    var DurableObject: any;
-    var WebSocketPair: any;
-}
-declare const DEFAULT_TIMEOUT = 300000;
 /**
- * Environment variable names for provider API keys
+ * Singleton instance - the main API
  */
-declare const ENV_KEYS: {
-    E2B: string;
-    VERCEL: string;
-    CLOUDFLARE: string;
-    FLY: string;
-};
-/**
- * Detect if running in Cloudflare Workers environment
- *
- * @returns True if running in Cloudflare Workers
- */
-declare function isCloudflareWorkers(): boolean;
-/**
- * Detect available providers based on environment variables
- *
- * @returns Array of available provider types
- */
-declare function detectAvailableProviders(): ProviderType[];
-/**
- * Auto-select the best provider based on available API keys
- *
- * @returns Selected provider type or undefined if none available
- */
-declare function autoSelectProvider(): ProviderType | undefined;
-/**
- * Validate and normalize container configuration
- *
- * @param container Container configuration or image string
- * @returns Normalized container configuration
- */
-declare function normalizeContainerConfig(container: string | ContainerConfig | undefined): ContainerConfig | undefined;
-/**
- * Get the appropriate runtime based on provider and configuration
- *
- * @param provider Provider type
- * @param runtime Optional runtime preference
- * @returns Selected runtime
- */
-declare function getDefaultRuntime(provider: ProviderType, runtime?: Runtime): Runtime;
-/**
- * Validate API key for selected provider
- *
- * @param provider Provider type
- * @throws AuthenticationError if API key is missing
- */
-declare function validateProviderApiKey(provider: ProviderType): void;
+declare const compute: ComputeAPI;
+
 /**
- * Normalize and validate sandbox configuration
+ * Request Handler for Web Framework Integration
  *
- * @param config User-provided configuration
- * @returns Normalized configuration with defaults applied
+ * Maps web requests to ComputeSDK operations with comprehensive support for:
+ * - Sandbox management (create, destroy, getInfo)
+ * - Code execution
+ * - Filesystem operations
+ * - Terminal operations
  */
-declare function normalizeSandboxConfig(config?: Partial<SandboxConfig>): SandboxConfig;
 
 /**
- * Utility functions for ComputeSDK
- */
-
+ * Extended request structure supporting all SDK capabilities
+ */
+interface ComputeRequest {
+    /** Type of operation to perform */
+    action: 'compute.sandbox.create' | 'compute.sandbox.destroy' | 'compute.sandbox.getInfo' | 'compute.sandbox.list' | 'compute.sandbox.runCode' | 'compute.sandbox.runCommand' | 'compute.sandbox.filesystem.readFile' | 'compute.sandbox.filesystem.writeFile' | 'compute.sandbox.filesystem.mkdir' | 'compute.sandbox.filesystem.readdir' | 'compute.sandbox.filesystem.exists' | 'compute.sandbox.filesystem.remove' | 'compute.sandbox.terminal.create' | 'compute.sandbox.terminal.getById' | 'compute.sandbox.terminal.list' | 'compute.sandbox.terminal.destroy' | 'compute.sandbox.terminal.write' | 'compute.sandbox.terminal.resize' | 'compute.sandbox.terminal.kill';
+    /** Sandbox ID (required for operations on existing sandboxes) */
+    sandboxId?: string;
+    /** Code to execute (for runCode action) */
+    code?: string;
+    /** Command to run (for runCommand action) */
+    command?: string;
+    /** Command arguments (for runCommand action) */
+    args?: string[];
+    /** Runtime environment */
+    runtime?: Runtime;
+    /** File path (for filesystem operations) */
+    path?: string;
+    /** File content (for writeFile action) */
+    content?: string;
+    /** Terminal options (for terminal.create) */
+    terminalOptions?: {
+        command?: string;
+        cols?: number;
+        rows?: number;
+        env?: Record<string, string>;
+    };
+    /** Terminal ID (for terminal operations) */
+    terminalId?: string;
+    /** Terminal input data (for terminal.write) */
+    data?: string | Uint8Array;
+    /** Terminal resize dimensions (for terminal.resize) */
+    cols?: number;
+    rows?: number;
+    /** Additional sandbox creation options */
+    options?: {
+        runtime?: Runtime;
+        timeout?: number;
+        sandboxId?: string;
+    };
+}
 /**
- * Execute code in a sandbox
+ * Response structure for compute operations
  */
-declare function executeSandbox(params: ExecuteSandboxParams): Promise<ExecutionResult>;
+interface ComputeResponse {
+    /** Whether the operation was successful */
+    success: boolean;
+    /** Error message if operation failed */
+    error?: string;
+    /** Sandbox ID involved in the operation */
+    sandboxId: string;
+    /** Provider that handled the operation */
+    provider: string;
+    /** Execution result (for runCode/runCommand actions) */
+    result?: {
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        executionTime: number;
+    };
+    /** Sandbox info (for getInfo action) */
+    info?: {
+        id: string;
+        provider: string;
+        runtime: Runtime;
+        status: string;
+        createdAt: string;
+        timeout: number;
+        metadata?: Record<string, any>;
+    };
+    /** File content (for readFile action) */
+    fileContent?: string;
+    /** Directory listing (for readdir action) */
+    files?: Array<{
+        name: string;
+        path: string;
+        isDirectory: boolean;
+        size: number;
+        lastModified: string;
+    }>;
+    /** File/directory exists (for exists action) */
+    exists?: boolean;
+    /** Sandbox list (for list action) */
+    sandboxes?: Array<{
+        sandboxId: string;
+        provider: string;
+    }>;
+    /** Terminal session (for terminal.create action) */
+    terminal?: {
+        pid: number;
+        command: string;
+        status: string;
+        cols: number;
+        rows: number;
+    };
+    /** Terminal sessions (for terminal.list action) */
+    terminals?: Array<{
+        pid: number;
+        command: string;
+        status: string;
+        cols: number;
+        rows: number;
+    }>;
+    /** WebSocket connection info (for terminal.connect action) */
+    websocket?: {
+        url: string;
+        headers?: Record<string, string>;
+        protocols?: string[];
+    };
+}
 /**
- * Retry function with exponential backoff
+ * Parameters for handleComputeRequest
  */
-declare function retry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelay?: number): Promise<T>;
-
+interface HandleComputeRequestParams {
+    /** The compute request to handle */
+    request: ComputeRequest;
+    /** Provider to use for the operation */
+    provider: Provider;
+}
 /**
- * ComputeSDK Provider Registry
+ * Handle a compute request - unified API for web frameworks
  *
- * This file implements the provider registry for managing multiple providers.
- */
-
-/**
- * Create a provider registry for managing multiple providers
+ * Maps web requests to ComputeSDK operations with full support for:
+ * - All sandbox operations via compute.sandbox.*
+ * - All filesystem operations via sandbox.filesystem.*
+ * - All terminal operations via sandbox.terminal.*
  *
- * @param providers Map of provider factories
- * @returns Provider registry instance
- */
-declare function createComputeRegistry(providers: ProviderMap): ProviderRegistry;
+ * @example
+ * ```typescript
+ * // Execute code
+ * const response = await handleComputeRequest({
+ *   request: {
+ *     action: 'sandbox.runCode',
+ *     code: 'print("hello")',
+ *     sandboxId: 'existing-sandbox-id' // optional, creates new if not provided
+ *   },
+ *   provider: e2b({ apiKey: process.env.E2B_API_KEY })
+ * });
+ *
+ * // Filesystem operations
+ * const response = await handleComputeRequest({
+ *   request: {
+ *     action: 'filesystem.writeFile',
+ *     sandboxId: 'sandbox-id',
+ *     path: '/tmp/hello.py',
+ *     content: 'print("Hello from file!")'
+ *   },
+ *   provider: e2b({ apiKey: process.env.E2B_API_KEY })
+ * });
+ * ```
+ */
+declare function handleComputeRequest(params: HandleComputeRequestParams): Promise<ComputeResponse>;
 
 /**
- * ComputeSDK Base Provider
+ * Sandbox Management - Provider-Centric Approach
  *
- * This file contains the base provider implementation that all
- * specific provider implementations extend.
+ * No registry - providers are the single source of truth
  */
 
 /**
- * Base implementation of the ComputeSandbox interface
- *
- * Provides common functionality and wraps provider-specific implementations.
+ * Sandbox manager - thin wrapper around provider APIs
  */
-declare abstract class BaseProvider implements ComputeSandbox, ComputeSpecification {
-    /** Specification version */
-    readonly specificationVersion = "v1";
-    /** Provider identifier */
-    readonly provider: string;
-    /** Sandbox identifier */
-    readonly sandboxId: string;
-    /** Execution timeout in milliseconds */
-    protected readonly timeout: number;
-    /**
-     * Create a new base provider
-     *
-     * @param provider Provider identifier
-     * @param timeout Execution timeout in milliseconds
-     */
-    constructor(provider: string, timeout: number);
-    /**
-     * Execute code in the sandbox
-     *
-     * @param code Code to execute
-     * @param runtime Optional runtime to use
-     * @returns Execution result
-     */
-    execute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
-    /**
-     * Kill the sandbox
-     *
-     * @returns Promise that resolves when the sandbox is killed
-     */
-    kill(): Promise<void>;
+declare class SandboxManager {
     /**
-     * Get information about the sandbox
-     *
-     * @returns Sandbox information
+     * Create a sandbox from a provider
      */
-    getInfo(): Promise<SandboxInfo>;
+    create(provider: Provider, options?: CreateSandboxOptions): Promise<Sandbox>;
     /**
-     * Provider-specific implementation of code execution
-     *
-     * @param code Code to execute
-     * @param runtime Optional runtime to use
-     * @returns Execution result
+     * Get an existing sandbox by ID from a provider
      */
-    abstract doExecute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
+    getById(provider: Provider, sandboxId: string): Promise<Sandbox | null>;
     /**
-     * Provider-specific implementation of sandbox termination
-     *
-     * @returns Promise that resolves when the sandbox is killed
+     * List all active sandboxes from a provider
      */
-    abstract doKill(): Promise<void>;
+    list(provider: Provider): Promise<Sandbox[]>;
     /**
-     * Provider-specific implementation of retrieving sandbox information
-     *
-     * @returns Sandbox information
+     * Destroy a sandbox via a provider
      */
-    abstract doGetInfo(): Promise<SandboxInfo>;
+    destroy(provider: Provider, sandboxId: string): Promise<void>;
 }
 
-declare class ComputeSDK {
-    /**
-     * Create a new sandbox with the specified configuration
-     *
-     * @param config Optional sandbox configuration
-     * @returns Configured sandbox instance
-     */
-    static createSandbox(config?: Partial<SandboxConfig>): ComputeSandbox;
-    /**
-     * Detect available providers based on environment variables
-     *
-     * @returns Array of available provider types
-     */
-    static detectProviders(): ProviderType[];
-}
+/**
+ * Provider Factory - Creates providers from method definitions
+ *
+ * Eliminates boilerplate by auto-generating Provider/Sandbox classes
+ * from simple method definitions with automatic feature detection.
+ */
 
 /**
- * ComputeSDK Core
+ * Flat sandbox method implementations - all operations in one place
+ */
+interface SandboxMethods<TSandbox = any, TConfig = any> {
+    create: (config: TConfig, options?: CreateSandboxOptions) => Promise<{
+        sandbox: TSandbox;
+        sandboxId: string;
+    }>;
+    getById: (config: TConfig, sandboxId: string) => Promise<{
+        sandbox: TSandbox;
+        sandboxId: string;
+    } | null>;
+    list: (config: TConfig) => Promise<Array<{
+        sandbox: TSandbox;
+        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[]) => Promise<ExecutionResult>;
+    getInfo: (sandbox: TSandbox) => Promise<SandboxInfo>;
+    filesystem?: {
+        readFile: (sandbox: TSandbox, path: string) => Promise<string>;
+        writeFile: (sandbox: TSandbox, path: string, content: string) => Promise<void>;
+        mkdir: (sandbox: TSandbox, path: string) => Promise<void>;
+        readdir: (sandbox: TSandbox, path: string) => Promise<FileEntry[]>;
+        exists: (sandbox: TSandbox, path: string) => Promise<boolean>;
+        remove: (sandbox: TSandbox, path: string) => Promise<void>;
+    };
+    terminal?: {
+        create: (sandbox: TSandbox, options?: TerminalCreateOptions) => Promise<{
+            terminal: any;
+            terminalId: string;
+        }>;
+        getById: (sandbox: TSandbox, terminalId: string) => Promise<{
+            terminal: any;
+            terminalId: string;
+        } | null>;
+        list: (sandbox: TSandbox) => Promise<Array<{
+            terminal: any;
+            terminalId: string;
+        }>>;
+        destroy: (sandbox: TSandbox, terminalId: string) => Promise<void>;
+        write: (sandbox: TSandbox, terminal: any, data: Uint8Array | string) => Promise<void>;
+        resize: (sandbox: TSandbox, terminal: any, cols: number, rows: number) => Promise<void>;
+        kill: (sandbox: TSandbox, terminal: any) => Promise<void>;
+    };
+}
+/**
+ * Provider configuration for createProvider()
+ */
+interface ProviderConfig<TSandbox = any, TConfig = any> {
+    name: string;
+    methods: {
+        sandbox: SandboxMethods<TSandbox, TConfig>;
+    };
+}
+/**
+ * Create a provider from method definitions
  *
- * A unified abstraction layer for executing code in secure,
- * isolated sandboxed environments across multiple cloud providers.
+ * Auto-generates all boilerplate classes and provides feature detection
+ * based on which methods are implemented.
  */
+declare function createProvider<TSandbox, TConfig>(providerConfig: ProviderConfig<TSandbox, TConfig>): (config: TConfig) => Provider;
 
-export { AuthenticationError, BaseProvider, ComputeError, ComputeSDK, type ComputeSandbox, type ComputeSpecification, ConfigurationError, type ContainerConfig, DEFAULT_TIMEOUT, ENV_KEYS, type ExecuteSandboxParams, ExecutionError, type ExecutionResult, ProviderError, type ProviderFactory, type ProviderMap, type ProviderRegistry, type ProviderType, ProviderUnavailableError, type Runtime, type SandboxConfig, type SandboxInfo, type SandboxStatus, TimeoutError, autoSelectProvider, createComputeRegistry, ComputeSDK as default, detectAvailableProviders, executeSandbox, getDefaultRuntime, isCloudflareWorkers, normalizeContainerConfig, normalizeSandboxConfig, retry, validateProviderApiKey };
+export { type ComputeAPI, type ComputeConfig, type ComputeRequest, type ComputeResponse, type CreateSandboxOptions, type CreateSandboxParams, type CreateSandboxParamsWithOptionalProvider, type ExecutionResult, type FileEntry, type HandleComputeRequestParams, type Provider, type ProviderConfig, type ProviderSandboxManager, type Runtime, type Sandbox, type SandboxFileSystem, type SandboxInfo, SandboxManager, type SandboxManagerMethods, type SandboxMethods, type SandboxStatus, type SandboxTerminal, type TerminalCreateOptions, type TerminalSession, compute, createProvider, handleComputeRequest };