[v2.5] Add provider registry and factory pattern

[frankbria]

Overview

Create a registry system for managing multiple sandbox providers and a factory for creating provider instances.

Design

Provider Registry

// src/e2b/providers/registry.ts

export class ProviderRegistry {
  private providers: Map<string, SandboxProvider> = new Map();
  
  register(provider: SandboxProvider): void {
    this.providers.set(provider.name, provider);
  }
  
  get(name: string): SandboxProvider | undefined {
    return this.providers.get(name);
  }
  
  list(): string[] {
    return Array.from(this.providers.keys());
  }
  
  getDefault(): SandboxProvider {
    // Return based on config or first available
  }
}

Provider Factory

// src/e2b/providers/factory.ts

export function createProvider(
  name: string, 
  config?: ProviderConfig
): SandboxProvider {
  switch (name) {
    case 'e2b':
      return new E2BProvider(config);
    case 'native':
      return new NativeProvider(config);
    case 'docker':
      return new DockerProvider(config);
    default:
      throw new Error(\`Unknown provider: \${name}\`);
  }
}

Auto-Discovery

// Auto-discover available providers on startup
async function discoverProviders(): Promise<string[]> {
  const available: string[] = [];
  
  if (await E2BProvider.isAvailable()) available.push('e2b');
  if (await NativeProvider.isAvailable()) available.push('native');
  if (await DockerProvider.isAvailable()) available.push('docker');
  
  return available;
}

Configuration

// ~/.parallel-cc/config.json
{
  "sandbox": {
    "defaultProvider": "e2b",
    "fallbackChain": ["native", "docker"],
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code"
      },
      "docker": {
        "image": "claude-code:latest"
      }
    }
  }
}

Files to Create

• src/e2b/providers/registry.ts
• src/e2b/providers/factory.ts
• src/e2b/providers/discovery.ts

Acceptance Criteria

• Registry can manage multiple providers
• Factory creates correct provider types
• Auto-discovery detects available providers
• Configuration file respected
• Fallback chain works correctly

Dependencies

• Depends on [v2.5] Define SandboxProvider interface and types #30 (SandboxProvider interface)
• Depends on [v2.5] Refactor E2B code into E2BProvider class #31 (E2BProvider)

[traycerai]

Plan

Observations

The codebase currently has a working E2B sandbox integration (v1.0) with SandboxManager tightly coupled to the E2B SDK. The file:src/e2b/sandbox-manager.ts directly imports and uses E2B's Sandbox class. No provider abstraction layer exists yet. The file:SANDBOX_INTEGRATION_PLAN.md provides comprehensive specifications for v1.5's multi-provider architecture. The ticket dependencies (#30 and #31) don't exist yet and need to be created as part of this work. The existing configuration system uses environment variables and the file:src/types.ts defines E2B-specific types.

Approach

Create a provider-agnostic architecture by introducing a SandboxProvider interface and refactoring the existing E2B implementation into an E2BProvider class. Build a registry system to manage multiple providers and a factory pattern for instantiation. Implement auto-discovery to detect available providers based on environment configuration and system capabilities. Add configuration support for provider selection, fallback chains, and provider-specific settings. Maintain 100% backward compatibility with existing E2B workflows while enabling future provider additions.

Implementation Steps

1. Create Provider Interface and Base Types

File: file:src/e2b/providers/base.ts

Define the core SandboxProvider interface that all providers must implement:

• name: string - Unique provider identifier (e.g., 'e2b', 'native', 'docker')
• isAvailable(): Promise<boolean> - Check if provider can be used (API keys, dependencies)
• create(config: ProviderConfig): Promise<SandboxInstance> - Create new sandbox
• destroy(instanceId: string): Promise<void> - Terminate sandbox
• uploadFiles(instanceId: string, files: FileList): Promise<void> - Upload files to sandbox
• downloadFiles(instanceId: string): Promise<FileList> - Download changed files
• execute(instanceId: string, command: string): AsyncGenerator<OutputChunk> - Execute command with streaming output
• isRunning(instanceId: string): Promise<boolean> - Check sandbox health
• getMetrics(instanceId: string): Promise<SandboxMetrics> - Get usage metrics

Define supporting types:

• ProviderConfig - Base configuration interface with provider-specific extensions
• SandboxInstance - Represents a running sandbox with id, provider, status, metadata
• OutputChunk - Streaming output with type: 'stdout' | 'stderr', data: string, timestamp: Date
• SandboxMetrics - Usage metrics including elapsedMinutes, estimatedCost, status
• FileList - Array of { path: string, content: Buffer | string }

Reference the existing types in file:src/types.ts for SandboxStatus, E2BSessionConfig, etc.

2. Implement E2BProvider

File: file:src/e2b/providers/e2b-provider.ts

Extract E2B-specific logic from file:src/e2b/sandbox-manager.ts into a provider implementation:

• Implement SandboxProvider interface
• Wrap existing SandboxManager methods:
  • create() → calls SandboxManager.createSandbox()
  • destroy() → calls SandboxManager.terminateSandbox()
  • isRunning() → calls SandboxManager.monitorSandboxHealth()
  • getMetrics() → calls SandboxManager.getElapsedMinutes() and getEstimatedCost()
• isAvailable() checks for E2B_API_KEY environment variable
• Store reference to SandboxManager instance for lifecycle management
• Map E2B-specific types to provider interface types
• Handle E2B SDK's Sandbox.create() and Sandbox.connect() methods
• Implement file sync using existing file:src/e2b/file-sync.ts utilities
• Implement command execution using existing file:src/e2b/claude-runner.ts logic

Configuration mapping:

• E2B_API_KEY → required for availability check
• E2B_TEMPLATE → maps to sandboxImage in E2BSessionConfig
• PARALLEL_CC_E2B_TIMEOUT → maps to timeoutMinutes

3. Create Provider Registry

File: file:src/e2b/providers/registry.ts

Implement the ProviderRegistry class as specified in the ticket:

• private providers: Map<string, SandboxProvider> - Store registered providers
• register(provider: SandboxProvider): void - Add provider to registry, validate unique names
• unregister(name: string): boolean - Remove provider from registry
• get(name: string): SandboxProvider | undefined - Retrieve provider by name
• list(): string[] - Return array of registered provider names
• getDefault(): SandboxProvider - Return default provider based on:
  1. SANDBOX_PROVIDER environment variable
  2. Configuration file setting (~/.parallel-cc/config.json)
  3. First available provider from discovery
  4. Fallback to E2B if configured
• getAvailable(): Promise<string[]> - Return names of providers where isAvailable() returns true
• Singleton pattern: static getInstance(): ProviderRegistry

Error handling:

• Throw if registering duplicate provider names
• Throw if getDefault() finds no available providers
• Log warnings for providers that fail availability checks

4. Create Provider Factory

File: file:src/e2b/providers/factory.ts

Implement the factory function as specified in the ticket:

export function createProvider(
  name: string,
  config?: ProviderConfig
): SandboxProvider

• Switch statement for known providers: 'e2b', 'native', 'docker'
• For 'e2b': instantiate E2BProvider with config
• For 'native' and 'docker': throw NotImplementedError with message "Provider '{name}' planned for future release"
• Default case: throw Error with "Unknown provider: {name}"
• Validate config matches provider requirements
• Pass logger instance from file:src/logger.ts to provider constructors

Helper function:

export function createProviderWithDefaults(
  name: string,
  logger: Logger
): SandboxProvider

• Load config from environment variables and config file
• Merge with provider-specific defaults
• Call createProvider() with merged config

5. Implement Auto-Discovery

File: file:src/e2b/providers/discovery.ts

Implement provider auto-discovery as specified in the ticket:

export async function discoverProviders(): Promise<string[]>

• Check E2B availability: E2B_API_KEY environment variable exists
• Check Native availability:
  • Platform is macOS or Linux (not Windows)
  • @anthropic-ai/sandbox-runtime package installed (check via require.resolve())
  • On Linux: verify bubblewrap command exists
• Check Docker availability:
  • docker command exists in PATH
  • Docker daemon is running (try docker info)
• Return array of available provider names
• Log discovery results at debug level

Helper functions:

• async function commandExists(cmd: string): Promise<boolean> - Check if command in PATH
• async function checkE2BAvailable(): Promise<boolean> - Validate E2B API key
• async function checkNativeAvailable(): Promise<boolean> - Check platform and dependencies
• async function checkDockerAvailable(): Promise<boolean> - Check Docker installation

Platform detection using process.platform:

• 'darwin' → macOS (native supported)
• 'linux' → Linux (native supported with bubblewrap)
• 'win32' → Windows (native NOT supported)

6. Configuration System

File: file:src/e2b/providers/config.ts

Implement configuration loading and management:

export interface SandboxConfig {
  defaultProvider?: string;
  fallbackChain?: string[];
  providers: {
    e2b?: E2BProviderConfig;
    native?: NativeProviderConfig;
    docker?: DockerProviderConfig;
  };
}

• loadConfig(): SandboxConfig - Load from ~/.parallel-cc/config.json
• saveConfig(config: SandboxConfig): void - Save to config file
• getProviderConfig(name: string): ProviderConfig | undefined - Get provider-specific config
• Merge environment variables with file config (env vars take precedence)
• Create config file with defaults if it doesn't exist
• Validate config schema using zod (already in dependencies)

Environment variable mapping:

• SANDBOX_PROVIDER → defaultProvider
• E2B_API_KEY, E2B_TEMPLATE → providers.e2b.*
• DOCKER_IMAGE, DOCKER_NETWORK → providers.docker.*

7. Implement Fallback Chain

File: file:src/e2b/providers/registry.ts (extend)

Add fallback chain support to ProviderRegistry:

• getWithFallback(name: string): Promise<SandboxProvider> - Try primary provider, fall back to chain
• Read fallback chain from config: config.fallbackChain
• Iterate through chain, check isAvailable() for each
• Return first available provider
• Throw if no providers in chain are available
• Log each fallback attempt at info level

Example flow:

1. Try primary provider 'native'
2. If unavailable, try 'docker' from fallback chain
3. If unavailable, try 'e2b' from fallback chain
4. If all fail, throw error with helpful message

8. Update SandboxManager

File: file:src/e2b/sandbox-manager.ts (refactor)

Refactor to use provider abstraction while maintaining backward compatibility:

• Keep existing public API unchanged
• Add private provider: SandboxProvider field
• Constructor accepts optional provider: SandboxProvider parameter
• If no provider specified, use ProviderRegistry.getInstance().getDefault()
• Delegate to provider methods:
  • createSandbox() → provider.create()
  • terminateSandbox() → provider.destroy()
  • monitorSandboxHealth() → provider.isRunning()
• Maintain existing tracking maps (activeSandboxes, sandboxStartTimes, etc.) for backward compatibility
• Keep E2B-specific methods for now (will be deprecated in future)

Migration strategy:

• Phase 1 (this ticket): Add provider support, keep E2B methods
• Phase 2 (future): Deprecate E2B-specific methods
• Phase 3 (future): Remove E2B-specific methods

9. Update Type Definitions

File: file:src/types.ts (extend)

Add provider-related types:

export type SandboxProviderType = 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare';

export interface ProviderConfig {
  provider: SandboxProviderType;
  timeout?: number;
  autoCleanup?: boolean;
}

export interface E2BProviderConfig extends ProviderConfig {
  provider: 'e2b';
  apiKey?: string;
  template?: string;
  timeoutMinutes?: number;
}

export interface NativeProviderConfig extends ProviderConfig {
  provider: 'native';
  allowedDomains?: string[];
  allowWritePaths?: string[];
  denyReadPaths?: string[];
}

export interface DockerProviderConfig extends ProviderConfig {
  provider: 'docker';
  image?: string;
  network?: 'none' | 'bridge' | 'host';
  memoryLimit?: string;
  cpuLimit?: number;
}

Keep existing E2B types for backward compatibility.

10. CLI Integration

File: file:src/cli.ts (extend)

Add --provider flag to sandbox-run command:

• Parse --provider <name> flag (default: from config or 'e2b')
• Use ProviderRegistry.getInstance().get(name) to get provider
• If provider not found, show available providers via registry.list()
• Pass provider to SandboxManager constructor
• Update help text to document provider options

Add new providers command:

• List all registered providers
• With --available: only show providers where isAvailable() is true
• Show provider status (available/unavailable) and reason if unavailable

11. Testing Strategy

Files: file:tests/e2b/providers/*.test.ts

Create comprehensive test suite:

registry.test.ts:

• Test provider registration and retrieval
• Test duplicate name rejection
• Test getDefault() with various configs
• Test getAvailable() filtering
• Test singleton pattern

factory.test.ts:

• Test creating E2B provider
• Test error handling for unknown providers
• Test config validation
• Test NotImplementedError for future providers

discovery.test.ts:

• Mock environment variables and command checks
• Test E2B discovery with/without API key
• Test platform detection (mock process.platform)
• Test Docker availability detection
• Test Native availability on different platforms

e2b-provider.test.ts:

• Test isAvailable() with/without API key
• Test provider interface implementation
• Test integration with existing SandboxManager
• Mock E2B SDK calls

config.test.ts:

• Test config loading from file
• Test environment variable merging
• Test config validation
• Test default config creation

Integration tests:

• Test full flow: discovery → registry → factory → provider creation
• Test fallback chain with mocked provider availability
• Test backward compatibility with existing E2B workflows

12. Documentation

File: file:docs/PROVIDERS.md (new)

Create provider documentation:

• Overview of provider architecture
• List of supported providers (E2B only for now)
• Configuration guide with examples
• Environment variable reference
• Fallback chain configuration
• Migration guide from v1.0 to v1.5
• Troubleshooting common issues

File: file:README.md (update)

Add provider section:

• Quick start with provider selection
• Link to detailed provider documentation
• Example commands with --provider flag

Architecture Diagram

sequenceDiagram
    participant CLI as CLI (sandbox-run)
    participant Registry as ProviderRegistry
    participant Discovery as Auto-Discovery
    participant Factory as Provider Factory
    participant E2BProvider as E2BProvider
    participant SandboxMgr as SandboxManager (legacy)
    
    CLI->>Registry: getInstance()
    Registry->>Discovery: discoverProviders()
    Discovery-->>Registry: ['e2b', 'docker']
    
    CLI->>Registry: get('e2b')
    Registry->>Factory: createProvider('e2b', config)
    Factory->>E2BProvider: new E2BProvider(config)
    E2BProvider->>SandboxMgr: new SandboxManager(logger, config)
    E2BProvider-->>Factory: provider instance
    Factory-->>Registry: provider instance
    Registry-->>CLI: provider instance
    
    CLI->>E2BProvider: create(config)
    E2BProvider->>SandboxMgr: createSandbox(sessionId)
    SandboxMgr-->>E2BProvider: {sandbox, sandboxId, status}
    E2BProvider-->>CLI: SandboxInstance
    
    CLI->>E2BProvider: execute(instanceId, command)
    E2BProvider->>SandboxMgr: getSandbox(sandboxId)
    E2BProvider-->>CLI: AsyncGenerator<OutputChunk>

Loading

Configuration Example

{
  "sandbox": {
    "defaultProvider": "e2b",
    "fallbackChain": ["native", "docker"],
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      },
      "native": {
        "allowedDomains": ["github.com", "api.anthropic.com"],
        "allowWritePaths": [".", ".git"],
        "denyReadPaths": ["~/.ssh", "~/.aws"]
      },
      "docker": {
        "image": "claude-code:latest",
        "network": "none",
        "memoryLimit": "4g"
      }
    }
  }
}

Backward Compatibility

All existing E2B workflows continue to work without changes:

• parallel-cc sandbox-run defaults to E2B provider
• Existing SandboxManager API unchanged
• Environment variables (E2B_API_KEY, E2B_TEMPLATE) still respected
• Database schema unchanged (provider info stored in existing execution_mode field)

New capabilities added without breaking changes:

• --provider flag is optional
• Registry auto-discovers E2B if API key present
• Fallback chain only used if explicitly configured

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a working E2B sandbox integration (v1.0) with `SandboxManager` tightly coupled to the E2B SDK. The `file:src/e2b/sandbox-manager.ts` directly imports and uses E2B's `Sandbox` class. No provider abstraction layer exists yet. The `file:SANDBOX_INTEGRATION_PLAN.md` provides comprehensive specifications for v1.5's multi-provider architecture. The ticket dependencies (#30 and #31) don't exist yet and need to be created as part of this work. The existing configuration system uses environment variables and the `file:src/types.ts` defines E2B-specific types.

## Approach

Create a provider-agnostic architecture by introducing a `SandboxProvider` interface and refactoring the existing E2B implementation into an `E2BProvider` class. Build a registry system to manage multiple providers and a factory pattern for instantiation. Implement auto-discovery to detect available providers based on environment configuration and system capabilities. Add configuration support for provider selection, fallback chains, and provider-specific settings. Maintain 100% backward compatibility with existing E2B workflows while enabling future provider additions.

## Implementation Steps

### 1. Create Provider Interface and Base Types

**File: `file:src/e2b/providers/base.ts`**

Define the core `SandboxProvider` interface that all providers must implement:

- `name: string` - Unique provider identifier (e.g., 'e2b', 'native', 'docker')
- `isAvailable(): Promise<boolean>` - Check if provider can be used (API keys, dependencies)
- `create(config: ProviderConfig): Promise<SandboxInstance>` - Create new sandbox
- `destroy(instanceId: string): Promise<void>` - Terminate sandbox
- `uploadFiles(instanceId: string, files: FileList): Promise<void>` - Upload files to sandbox
- `downloadFiles(instanceId: string): Promise<FileList>` - Download changed files
- `execute(instanceId: string, command: string): AsyncGenerator<OutputChunk>` - Execute command with streaming output
- `isRunning(instanceId: string): Promise<boolean>` - Check sandbox health
- `getMetrics(instanceId: string): Promise<SandboxMetrics>` - Get usage metrics

Define supporting types:
- `ProviderConfig` - Base configuration interface with provider-specific extensions
- `SandboxInstance` - Represents a running sandbox with `id`, `provider`, `status`, `metadata`
- `OutputChunk` - Streaming output with `type: 'stdout' | 'stderr'`, `data: string`, `timestamp: Date`
- `SandboxMetrics` - Usage metrics including `elapsedMinutes`, `estimatedCost`, `status`
- `FileList` - Array of `{ path: string, content: Buffer | string }`

Reference the existing types in `file:src/types.ts` for `SandboxStatus`, `E2BSessionConfig`, etc.

### 2. Implement E2BProvider

**File: `file:src/e2b/providers/e2b-provider.ts`**

Extract E2B-specific logic from `file:src/e2b/sandbox-manager.ts` into a provider implementation:

- Implement `SandboxProvider` interface
- Wrap existing `SandboxManager` methods:
  - `create()` → calls `SandboxManager.createSandbox()`
  - `destroy()` → calls `SandboxManager.terminateSandbox()`
  - `isRunning()` → calls `SandboxManager.monitorSandboxHealth()`
  - `getMetrics()` → calls `SandboxManager.getElapsedMinutes()` and `getEstimatedCost()`
- `isAvailable()` checks for `E2B_API_KEY` environment variable
- Store reference to `SandboxManager` instance for lifecycle management
- Map E2B-specific types to provider interface types
- Handle E2B SDK's `Sandbox.create()` and `Sandbox.connect()` methods
- Implement file sync using existing `file:src/e2b/file-sync.ts` utilities
- Implement command execution using existing `file:src/e2b/claude-runner.ts` logic

Configuration mapping:
- `E2B_API_KEY` → required for availability check
- `E2B_TEMPLATE` → maps to `sandboxImage` in `E2BSessionConfig`
- `PARALLEL_CC_E2B_TIMEOUT` → maps to `timeoutMinutes`

### 3. Create Provider Registry

**File: `file:src/e2b/providers/registry.ts`**

Implement the `ProviderRegistry` class as specified in the ticket:

- `private providers: Map<string, SandboxProvider>` - Store registered providers
- `register(provider: SandboxProvider): void` - Add provider to registry, validate unique names
- `unregister(name: string): boolean` - Remove provider from registry
- `get(name: string): SandboxProvider | undefined` - Retrieve provider by name
- `list(): string[]` - Return array of registered provider names
- `getDefault(): SandboxProvider` - Return default provider based on:
  1. `SANDBOX_PROVIDER` environment variable
  2. Configuration file setting (`~/.parallel-cc/config.json`)
  3. First available provider from discovery
  4. Fallback to E2B if configured
- `getAvailable(): Promise<string[]>` - Return names of providers where `isAvailable()` returns true
- Singleton pattern: `static getInstance(): ProviderRegistry`

Error handling:
- Throw if registering duplicate provider names
- Throw if `getDefault()` finds no available providers
- Log warnings for providers that fail availability checks

### 4. Create Provider Factory

**File: `file:src/e2b/providers/factory.ts`**

Implement the factory function as specified in the ticket:

```typescript
export function createProvider(
  name: string,
  config?: ProviderConfig
): SandboxProvider
```

- Switch statement for known providers: 'e2b', 'native', 'docker'
- For 'e2b': instantiate `E2BProvider` with config
- For 'native' and 'docker': throw `NotImplementedError` with message "Provider '{name}' planned for future release"
- Default case: throw `Error` with "Unknown provider: {name}"
- Validate config matches provider requirements
- Pass logger instance from `file:src/logger.ts` to provider constructors

Helper function:
```typescript
export function createProviderWithDefaults(
  name: string,
  logger: Logger
): SandboxProvider
```
- Load config from environment variables and config file
- Merge with provider-specific defaults
- Call `createProvider()` with merged config

### 5. Implement Auto-Discovery

**File: `file:src/e2b/providers/discovery.ts`**

Implement provider auto-discovery as specified in the ticket:

```typescript
export async function discoverProviders(): Promise<string[]>
```

- Check E2B availability: `E2B_API_KEY` environment variable exists
- Check Native availability: 
  - Platform is macOS or Linux (not Windows)
  - `@anthropic-ai/sandbox-runtime` package installed (check via `require.resolve()`)
  - On Linux: verify `bubblewrap` command exists
- Check Docker availability:
  - `docker` command exists in PATH
  - Docker daemon is running (try `docker info`)
- Return array of available provider names
- Log discovery results at debug level

Helper functions:
- `async function commandExists(cmd: string): Promise<boolean>` - Check if command in PATH
- `async function checkE2BAvailable(): Promise<boolean>` - Validate E2B API key
- `async function checkNativeAvailable(): Promise<boolean>` - Check platform and dependencies
- `async function checkDockerAvailable(): Promise<boolean>` - Check Docker installation

Platform detection using `process.platform`:
- 'darwin' → macOS (native supported)
- 'linux' → Linux (native supported with bubblewrap)
- 'win32' → Windows (native NOT supported)

### 6. Configuration System

**File: `file:src/e2b/providers/config.ts`**

Implement configuration loading and management:

```typescript
export interface SandboxConfig {
  defaultProvider?: string;
  fallbackChain?: string[];
  providers: {
    e2b?: E2BProviderConfig;
    native?: NativeProviderConfig;
    docker?: DockerProviderConfig;
  };
}
```

- `loadConfig(): SandboxConfig` - Load from `~/.parallel-cc/config.json`
- `saveConfig(config: SandboxConfig): void` - Save to config file
- `getProviderConfig(name: string): ProviderConfig | undefined` - Get provider-specific config
- Merge environment variables with file config (env vars take precedence)
- Create config file with defaults if it doesn't exist
- Validate config schema using `zod` (already in dependencies)

Environment variable mapping:
- `SANDBOX_PROVIDER` → `defaultProvider`
- `E2B_API_KEY`, `E2B_TEMPLATE` → `providers.e2b.*`
- `DOCKER_IMAGE`, `DOCKER_NETWORK` → `providers.docker.*`

### 7. Implement Fallback Chain

**File: `file:src/e2b/providers/registry.ts` (extend)**

Add fallback chain support to `ProviderRegistry`:

- `getWithFallback(name: string): Promise<SandboxProvider>` - Try primary provider, fall back to chain
- Read fallback chain from config: `config.fallbackChain`
- Iterate through chain, check `isAvailable()` for each
- Return first available provider
- Throw if no providers in chain are available
- Log each fallback attempt at info level

Example flow:
1. Try primary provider 'native'
2. If unavailable, try 'docker' from fallback chain
3. If unavailable, try 'e2b' from fallback chain
4. If all fail, throw error with helpful message

### 8. Update SandboxManager

**File: `file:src/e2b/sandbox-manager.ts` (refactor)**

Refactor to use provider abstraction while maintaining backward compatibility:

- Keep existing public API unchanged
- Add `private provider: SandboxProvider` field
- Constructor accepts optional `provider: SandboxProvider` parameter
- If no provider specified, use `ProviderRegistry.getInstance().getDefault()`
- Delegate to provider methods:
  - `createSandbox()` → `provider.create()`
  - `terminateSandbox()` → `provider.destroy()`
  - `monitorSandboxHealth()` → `provider.isRunning()`
- Maintain existing tracking maps (`activeSandboxes`, `sandboxStartTimes`, etc.) for backward compatibility
- Keep E2B-specific methods for now (will be deprecated in future)

Migration strategy:
- Phase 1 (this ticket): Add provider support, keep E2B methods
- Phase 2 (future): Deprecate E2B-specific methods
- Phase 3 (future): Remove E2B-specific methods

### 9. Update Type Definitions

**File: `file:src/types.ts` (extend)**

Add provider-related types:

```typescript
export type SandboxProviderType = 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare';

export interface ProviderConfig {
  provider: SandboxProviderType;
  timeout?: number;
  autoCleanup?: boolean;
}

export interface E2BProviderConfig extends ProviderConfig {
  provider: 'e2b';
  apiKey?: string;
  template?: string;
  timeoutMinutes?: number;
}

export interface NativeProviderConfig extends ProviderConfig {
  provider: 'native';
  allowedDomains?: string[];
  allowWritePaths?: string[];
  denyReadPaths?: string[];
}

export interface DockerProviderConfig extends ProviderConfig {
  provider: 'docker';
  image?: string;
  network?: 'none' | 'bridge' | 'host';
  memoryLimit?: string;
  cpuLimit?: number;
}
```

Keep existing E2B types for backward compatibility.

### 10. CLI Integration

**File: `file:src/cli.ts` (extend)**

Add `--provider` flag to `sandbox-run` command:

- Parse `--provider <name>` flag (default: from config or 'e2b')
- Use `ProviderRegistry.getInstance().get(name)` to get provider
- If provider not found, show available providers via `registry.list()`
- Pass provider to `SandboxManager` constructor
- Update help text to document provider options

Add new `providers` command:
```bash
```
- List all registered providers
- With `--available`: only show providers where `isAvailable()` is true
- Show provider status (available/unavailable) and reason if unavailable

### 11. Testing Strategy

**Files: `file:tests/e2b/providers/*.test.ts`**

Create comprehensive test suite:

**`registry.test.ts`:**
- Test provider registration and retrieval
- Test duplicate name rejection
- Test `getDefault()` with various configs
- Test `getAvailable()` filtering
- Test singleton pattern

**`factory.test.ts`:**
- Test creating E2B provider
- Test error handling for unknown providers
- Test config validation
- Test NotImplementedError for future providers

**`discovery.test.ts`:**
- Mock environment variables and command checks
- Test E2B discovery with/without API key
- Test platform detection (mock `process.platform`)
- Test Docker availability detection
- Test Native availability on different platforms

**`e2b-provider.test.ts`:**
- Test `isAvailable()` with/without API key
- Test provider interface implementation
- Test integration with existing `SandboxManager`
- Mock E2B SDK calls

**`config.test.ts`:**
- Test config loading from file
- Test environment variable merging
- Test config validation
- Test default config creation

Integration tests:
- Test full flow: discovery → registry → factory → provider creation
- Test fallback chain with mocked provider availability
- Test backward compatibility with existing E2B workflows

### 12. Documentation

**File: `file:docs/PROVIDERS.md` (new)**

Create provider documentation:

- Overview of provider architecture
- List of supported providers (E2B only for now)
- Configuration guide with examples
- Environment variable reference
- Fallback chain configuration
- Migration guide from v1.0 to v1.5
- Troubleshooting common issues

**File: `file:README.md` (update)**

Add provider section:
- Quick start with provider selection
- Link to detailed provider documentation
- Example commands with `--provider` flag

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CLI as CLI (sandbox-run)
    participant Registry as ProviderRegistry
    participant Discovery as Auto-Discovery
    participant Factory as Provider Factory
    participant E2BProvider as E2BProvider
    participant SandboxMgr as SandboxManager (legacy)
    
    CLI->>Registry: getInstance()
    Registry->>Discovery: discoverProviders()
    Discovery-->>Registry: ['e2b', 'docker']
    
    CLI->>Registry: get('e2b')
    Registry->>Factory: createProvider('e2b', config)
    Factory->>E2BProvider: new E2BProvider(config)
    E2BProvider->>SandboxMgr: new SandboxManager(logger, config)
    E2BProvider-->>Factory: provider instance
    Factory-->>Registry: provider instance
    Registry-->>CLI: provider instance
    
    CLI->>E2BProvider: create(config)
    E2BProvider->>SandboxMgr: createSandbox(sessionId)
    SandboxMgr-->>E2BProvider: {sandbox, sandboxId, status}
    E2BProvider-->>CLI: SandboxInstance
    
    CLI->>E2BProvider: execute(instanceId, command)
    E2BProvider->>SandboxMgr: getSandbox(sandboxId)
    E2BProvider-->>CLI: AsyncGenerator<OutputChunk>
```

## Configuration Example

```json
{
  "sandbox": {
    "defaultProvider": "e2b",
    "fallbackChain": ["native", "docker"],
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      },
      "native": {
        "allowedDomains": ["github.com", "api.anthropic.com"],
        "allowWritePaths": [".", ".git"],
        "denyReadPaths": ["~/.ssh", "~/.aws"]
      },
      "docker": {
        "image": "claude-code:latest",
        "network": "none",
        "memoryLimit": "4g"
      }
    }
  }
}
```

## Backward Compatibility

All existing E2B workflows continue to work without changes:
- `parallel-cc sandbox-run` defaults to E2B provider
- Existing `SandboxManager` API unchanged
- Environment variables (`E2B_API_KEY`, `E2B_TEMPLATE`) still respected
- Database schema unchanged (provider info stored in existing `execution_mode` field)

New capabilities added without breaking changes:
- `--provider` flag is optional
- Registry auto-discovers E2B if API key present
- Fallback chain only used if explicitly configured

---

Execution Information

Branch: main
Commit: 9698ef5

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#1 - Add native sandboxing integration option [merged]
#47 - feat(e2b): Add NPM token injection for private package access [merged]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

I have updated the Implementation Plan to reflect the recent changes in the ticket.

Previous Plan

Observations

The codebase currently has a working E2B sandbox integration (v1.0) with SandboxManager tightly coupled to the E2B SDK. The file:src/e2b/sandbox-manager.ts directly imports and uses E2B's Sandbox class. No provider abstraction layer exists yet. The file:SANDBOX_INTEGRATION_PLAN.md provides comprehensive specifications for v1.5's multi-provider architecture. The ticket dependencies (#30 and #31) don't exist yet and need to be created as part of this work. The existing configuration system uses environment variables and the file:src/types.ts defines E2B-specific types.

Approach

Create a provider-agnostic architecture by introducing a SandboxProvider interface and refactoring the existing E2B implementation into an E2BProvider class. Build a registry system to manage multiple providers and a factory pattern for instantiation. Implement auto-discovery to detect available providers based on environment configuration and system capabilities. Add configuration support for provider selection, fallback chains, and provider-specific settings. Maintain 100% backward compatibility with existing E2B workflows while enabling future provider additions.

Implementation Steps

1. Create Provider Interface and Base Types

File: file:src/e2b/providers/base.ts

Define the core SandboxProvider interface that all providers must implement:

• name: string - Unique provider identifier (e.g., 'e2b', 'native', 'docker')
• isAvailable(): Promise<boolean> - Check if provider can be used (API keys, dependencies)
• create(config: ProviderConfig): Promise<SandboxInstance> - Create new sandbox
• destroy(instanceId: string): Promise<void> - Terminate sandbox
• uploadFiles(instanceId: string, files: FileList): Promise<void> - Upload files to sandbox
• downloadFiles(instanceId: string): Promise<FileList> - Download changed files
• execute(instanceId: string, command: string): AsyncGenerator<OutputChunk> - Execute command with streaming output
• isRunning(instanceId: string): Promise<boolean> - Check sandbox health
• getMetrics(instanceId: string): Promise<SandboxMetrics> - Get usage metrics

Define supporting types:

• ProviderConfig - Base configuration interface with provider-specific extensions
• SandboxInstance - Represents a running sandbox with id, provider, status, metadata
• OutputChunk - Streaming output with type: 'stdout' | 'stderr', data: string, timestamp: Date
• SandboxMetrics - Usage metrics including elapsedMinutes, estimatedCost, status
• FileList - Array of { path: string, content: Buffer | string }

Reference the existing types in file:src/types.ts for SandboxStatus, E2BSessionConfig, etc.

2. Implement E2BProvider

File: file:src/e2b/providers/e2b-provider.ts

Extract E2B-specific logic from file:src/e2b/sandbox-manager.ts into a provider implementation:

• Implement SandboxProvider interface
• Wrap existing SandboxManager methods:
  • create() → calls SandboxManager.createSandbox()
  • destroy() → calls SandboxManager.terminateSandbox()
  • isRunning() → calls SandboxManager.monitorSandboxHealth()
  • getMetrics() → calls SandboxManager.getElapsedMinutes() and getEstimatedCost()
• isAvailable() checks for E2B_API_KEY environment variable
• Store reference to SandboxManager instance for lifecycle management
• Map E2B-specific types to provider interface types
• Handle E2B SDK's Sandbox.create() and Sandbox.connect() methods
• Implement file sync using existing file:src/e2b/file-sync.ts utilities
• Implement command execution using existing file:src/e2b/claude-runner.ts logic

Configuration mapping:

• E2B_API_KEY → required for availability check
• E2B_TEMPLATE → maps to sandboxImage in E2BSessionConfig
• PARALLEL_CC_E2B_TIMEOUT → maps to timeoutMinutes

3. Create Provider Registry

File: file:src/e2b/providers/registry.ts

Implement the ProviderRegistry class as specified in the ticket:

• private providers: Map<string, SandboxProvider> - Store registered providers
• register(provider: SandboxProvider): void - Add provider to registry, validate unique names
• unregister(name: string): boolean - Remove provider from registry
• get(name: string): SandboxProvider | undefined - Retrieve provider by name
• list(): string[] - Return array of registered provider names
• getDefault(): SandboxProvider - Return default provider based on:
  1. SANDBOX_PROVIDER environment variable
  2. Configuration file setting (~/.parallel-cc/config.json)
  3. First available provider from discovery
  4. Fallback to E2B if configured
• getAvailable(): Promise<string[]> - Return names of providers where isAvailable() returns true
• Singleton pattern: static getInstance(): ProviderRegistry

Error handling:

• Throw if registering duplicate provider names
• Throw if getDefault() finds no available providers
• Log warnings for providers that fail availability checks

4. Create Provider Factory

File: file:src/e2b/providers/factory.ts

Implement the factory function as specified in the ticket:

export function createProvider(
  name: string,
  config?: ProviderConfig
): SandboxProvider

• Switch statement for known providers: 'e2b', 'native', 'docker'
• For 'e2b': instantiate E2BProvider with config
• For 'native' and 'docker': throw NotImplementedError with message "Provider '{name}' planned for future release"
• Default case: throw Error with "Unknown provider: {name}"
• Validate config matches provider requirements
• Pass logger instance from file:src/logger.ts to provider constructors

Helper function:

export function createProviderWithDefaults(
  name: string,
  logger: Logger
): SandboxProvider

• Load config from environment variables and config file
• Merge with provider-specific defaults
• Call createProvider() with merged config

5. Implement Auto-Discovery

File: file:src/e2b/providers/discovery.ts

Implement provider auto-discovery as specified in the ticket:

export async function discoverProviders(): Promise<string[]>

• Check E2B availability: E2B_API_KEY environment variable exists
• Check Native availability:
  • Platform is macOS or Linux (not Windows)
  • @anthropic-ai/sandbox-runtime package installed (check via require.resolve())
  • On Linux: verify bubblewrap command exists
• Check Docker availability:
  • docker command exists in PATH
  • Docker daemon is running (try docker info)
• Return array of available provider names
• Log discovery results at debug level

Helper functions:

• async function commandExists(cmd: string): Promise<boolean> - Check if command in PATH
• async function checkE2BAvailable(): Promise<boolean> - Validate E2B API key
• async function checkNativeAvailable(): Promise<boolean> - Check platform and dependencies
• async function checkDockerAvailable(): Promise<boolean> - Check Docker installation

Platform detection using process.platform:

• 'darwin' → macOS (native supported)
• 'linux' → Linux (native supported with bubblewrap)
• 'win32' → Windows (native NOT supported)

6. Configuration System

File: file:src/e2b/providers/config.ts

Implement configuration loading and management:

export interface SandboxConfig {
  defaultProvider?: string;
  fallbackChain?: string[];
  providers: {
    e2b?: E2BProviderConfig;
    native?: NativeProviderConfig;
    docker?: DockerProviderConfig;
  };
}

• loadConfig(): SandboxConfig - Load from ~/.parallel-cc/config.json
• saveConfig(config: SandboxConfig): void - Save to config file
• getProviderConfig(name: string): ProviderConfig | undefined - Get provider-specific config
• Merge environment variables with file config (env vars take precedence)
• Create config file with defaults if it doesn't exist
• Validate config schema using zod (already in dependencies)

Environment variable mapping:

• SANDBOX_PROVIDER → defaultProvider
• E2B_API_KEY, E2B_TEMPLATE → providers.e2b.*
• DOCKER_IMAGE, DOCKER_NETWORK → providers.docker.*

7. Implement Fallback Chain

File: file:src/e2b/providers/registry.ts (extend)

Add fallback chain support to ProviderRegistry:

• getWithFallback(name: string): Promise<SandboxProvider> - Try primary provider, fall back to chain
• Read fallback chain from config: config.fallbackChain
• Iterate through chain, check isAvailable() for each
• Return first available provider
• Throw if no providers in chain are available
• Log each fallback attempt at info level

Example flow:

1. Try primary provider 'native'
2. If unavailable, try 'docker' from fallback chain
3. If unavailable, try 'e2b' from fallback chain
4. If all fail, throw error with helpful message

8. Update SandboxManager

File: file:src/e2b/sandbox-manager.ts (refactor)

Refactor to use provider abstraction while maintaining backward compatibility:

• Keep existing public API unchanged
• Add private provider: SandboxProvider field
• Constructor accepts optional provider: SandboxProvider parameter
• If no provider specified, use ProviderRegistry.getInstance().getDefault()
• Delegate to provider methods:
  • createSandbox() → provider.create()
  • terminateSandbox() → provider.destroy()
  • monitorSandboxHealth() → provider.isRunning()
• Maintain existing tracking maps (activeSandboxes, sandboxStartTimes, etc.) for backward compatibility
• Keep E2B-specific methods for now (will be deprecated in future)

Migration strategy:

• Phase 1 (this ticket): Add provider support, keep E2B methods
• Phase 2 (future): Deprecate E2B-specific methods
• Phase 3 (future): Remove E2B-specific methods

9. Update Type Definitions

File: file:src/types.ts (extend)

Add provider-related types:

export type SandboxProviderType = 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare';

export interface ProviderConfig {
  provider: SandboxProviderType;
  timeout?: number;
  autoCleanup?: boolean;
}

export interface E2BProviderConfig extends ProviderConfig {
  provider: 'e2b';
  apiKey?: string;
  template?: string;
  timeoutMinutes?: number;
}

export interface NativeProviderConfig extends ProviderConfig {
  provider: 'native';
  allowedDomains?: string[];
  allowWritePaths?: string[];
  denyReadPaths?: string[];
}

export interface DockerProviderConfig extends ProviderConfig {
  provider: 'docker';
  image?: string;
  network?: 'none' | 'bridge' | 'host';
  memoryLimit?: string;
  cpuLimit?: number;
}

Keep existing E2B types for backward compatibility.

10. CLI Integration

File: file:src/cli.ts (extend)

Add --provider flag to sandbox-run command:

• Parse --provider <name> flag (default: from config or 'e2b')
• Use ProviderRegistry.getInstance().get(name) to get provider
• If provider not found, show available providers via registry.list()
• Pass provider to SandboxManager constructor
• Update help text to document provider options

Add new providers command:

parallel-cc providers [--available]

• List all registered providers
• With --available: only show providers where isAvailable() is true
• Show provider status (available/unavailable) and reason if unavailable

11. Testing Strategy

Files: file:tests/e2b/providers/*.test.ts

Create comprehensive test suite:

registry.test.ts:

• Test provider registration and retrieval
• Test duplicate name rejection
• Test getDefault() with various configs
• Test getAvailable() filtering
• Test singleton pattern

factory.test.ts:

• Test creating E2B provider
• Test error handling for unknown providers
• Test config validation
• Test NotImplementedError for future providers

discovery.test.ts:

• Mock environment variables and command checks
• Test E2B discovery with/without API key
• Test platform detection (mock process.platform)
• Test Docker availability detection
• Test Native availability on different platforms

e2b-provider.test.ts:

• Test isAvailable() with/without API key
• Test provider interface implementation
• Test integration with existing SandboxManager
• Mock E2B SDK calls

config.test.ts:

• Test config loading from file
• Test environment variable merging
• Test config validation
• Test default config creation

Integration tests:

• Test full flow: discovery → registry → factory → provider creation
• Test fallback chain with mocked provider availability
• Test backward compatibility with existing E2B workflows

12. Documentation

File: file:docs/PROVIDERS.md (new)

Create provider documentation:

• Overview of provider architecture
• List of supported providers (E2B only for now)
• Configuration guide with examples
• Environment variable reference
• Fallback chain configuration
• Migration guide from v1.0 to v1.5
• Troubleshooting common issues

File: file:README.md (update)

Add provider section:

• Quick start with provider selection
• Link to detailed provider documentation
• Example commands with --provider flag

Architecture Diagram

sequenceDiagram
    participant CLI as CLI (sandbox-run)
    participant Registry as ProviderRegistry
    participant Discovery as Auto-Discovery
    participant Factory as Provider Factory
    participant E2BProvider as E2BProvider
    participant SandboxMgr as SandboxManager (legacy)
    
    CLI->>Registry: getInstance()
    Registry->>Discovery: discoverProviders()
    Discovery-->>Registry: ['e2b', 'docker']
    
    CLI->>Registry: get('e2b')
    Registry->>Factory: createProvider('e2b', config)
    Factory->>E2BProvider: new E2BProvider(config)
    E2BProvider->>SandboxMgr: new SandboxManager(logger, config)
    E2BProvider-->>Factory: provider instance
    Factory-->>Registry: provider instance
    Registry-->>CLI: provider instance
    
    CLI->>E2BProvider: create(config)
    E2BProvider->>SandboxMgr: createSandbox(sessionId)
    SandboxMgr-->>E2BProvider: {sandbox, sandboxId, status}
    E2BProvider-->>CLI: SandboxInstance
    
    CLI->>E2BProvider: execute(instanceId, command)
    E2BProvider->>SandboxMgr: getSandbox(sandboxId)
    E2BProvider-->>CLI: AsyncGenerator<OutputChunk>

Loading

Configuration Example

{
  "sandbox": {
    "defaultProvider": "e2b",
    "fallbackChain": ["native", "docker"],
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      },
      "native": {
        "allowedDomains": ["github.com", "api.anthropic.com"],
        "allowWritePaths": [".", ".git"],
        "denyReadPaths": ["~/.ssh", "~/.aws"]
      },
      "docker": {
        "image": "claude-code:latest",
        "network": "none",
        "memoryLimit": "4g"
      }
    }
  }
}

Backward Compatibility

All existing E2B workflows continue to work without changes:

• parallel-cc sandbox-run defaults to E2B provider
• Existing SandboxManager API unchanged
• Environment variables (E2B_API_KEY, E2B_TEMPLATE) still respected
• Database schema unchanged (provider info stored in existing execution_mode field)

New capabilities added without breaking changes:

• --provider flag is optional
• Registry auto-discovers E2B if API key present
• Fallback chain only used if explicitly configured

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a working E2B sandbox integration (v1.0) with `SandboxManager` tightly coupled to the E2B SDK. The `file:src/e2b/sandbox-manager.ts` directly imports and uses E2B's `Sandbox` class. No provider abstraction layer exists yet. The `file:SANDBOX_INTEGRATION_PLAN.md` provides comprehensive specifications for v1.5's multi-provider architecture. The ticket dependencies (#30 and #31) don't exist yet and need to be created as part of this work. The existing configuration system uses environment variables and the `file:src/types.ts` defines E2B-specific types.

## Approach

Create a provider-agnostic architecture by introducing a `SandboxProvider` interface and refactoring the existing E2B implementation into an `E2BProvider` class. Build a registry system to manage multiple providers and a factory pattern for instantiation. Implement auto-discovery to detect available providers based on environment configuration and system capabilities. Add configuration support for provider selection, fallback chains, and provider-specific settings. Maintain 100% backward compatibility with existing E2B workflows while enabling future provider additions.

## Implementation Steps

### 1. Create Provider Interface and Base Types

**File: `file:src/e2b/providers/base.ts`**

Define the core `SandboxProvider` interface that all providers must implement:

- `name: string` - Unique provider identifier (e.g., 'e2b', 'native', 'docker')
- `isAvailable(): Promise<boolean>` - Check if provider can be used (API keys, dependencies)
- `create(config: ProviderConfig): Promise<SandboxInstance>` - Create new sandbox
- `destroy(instanceId: string): Promise<void>` - Terminate sandbox
- `uploadFiles(instanceId: string, files: FileList): Promise<void>` - Upload files to sandbox
- `downloadFiles(instanceId: string): Promise<FileList>` - Download changed files
- `execute(instanceId: string, command: string): AsyncGenerator<OutputChunk>` - Execute command with streaming output
- `isRunning(instanceId: string): Promise<boolean>` - Check sandbox health
- `getMetrics(instanceId: string): Promise<SandboxMetrics>` - Get usage metrics

Define supporting types:
- `ProviderConfig` - Base configuration interface with provider-specific extensions
- `SandboxInstance` - Represents a running sandbox with `id`, `provider`, `status`, `metadata`
- `OutputChunk` - Streaming output with `type: 'stdout' | 'stderr'`, `data: string`, `timestamp: Date`
- `SandboxMetrics` - Usage metrics including `elapsedMinutes`, `estimatedCost`, `status`
- `FileList` - Array of `{ path: string, content: Buffer | string }`

Reference the existing types in `file:src/types.ts` for `SandboxStatus`, `E2BSessionConfig`, etc.

### 2. Implement E2BProvider

**File: `file:src/e2b/providers/e2b-provider.ts`**

Extract E2B-specific logic from `file:src/e2b/sandbox-manager.ts` into a provider implementation:

- Implement `SandboxProvider` interface
- Wrap existing `SandboxManager` methods:
  - `create()` → calls `SandboxManager.createSandbox()`
  - `destroy()` → calls `SandboxManager.terminateSandbox()`
  - `isRunning()` → calls `SandboxManager.monitorSandboxHealth()`
  - `getMetrics()` → calls `SandboxManager.getElapsedMinutes()` and `getEstimatedCost()`
- `isAvailable()` checks for `E2B_API_KEY` environment variable
- Store reference to `SandboxManager` instance for lifecycle management
- Map E2B-specific types to provider interface types
- Handle E2B SDK's `Sandbox.create()` and `Sandbox.connect()` methods
- Implement file sync using existing `file:src/e2b/file-sync.ts` utilities
- Implement command execution using existing `file:src/e2b/claude-runner.ts` logic

Configuration mapping:
- `E2B_API_KEY` → required for availability check
- `E2B_TEMPLATE` → maps to `sandboxImage` in `E2BSessionConfig`
- `PARALLEL_CC_E2B_TIMEOUT` → maps to `timeoutMinutes`

### 3. Create Provider Registry

**File: `file:src/e2b/providers/registry.ts`**

Implement the `ProviderRegistry` class as specified in the ticket:

- `private providers: Map<string, SandboxProvider>` - Store registered providers
- `register(provider: SandboxProvider): void` - Add provider to registry, validate unique names
- `unregister(name: string): boolean` - Remove provider from registry
- `get(name: string): SandboxProvider | undefined` - Retrieve provider by name
- `list(): string[]` - Return array of registered provider names
- `getDefault(): SandboxProvider` - Return default provider based on:
  1. `SANDBOX_PROVIDER` environment variable
  2. Configuration file setting (`~/.parallel-cc/config.json`)
  3. First available provider from discovery
  4. Fallback to E2B if configured
- `getAvailable(): Promise<string[]>` - Return names of providers where `isAvailable()` returns true
- Singleton pattern: `static getInstance(): ProviderRegistry`

Error handling:
- Throw if registering duplicate provider names
- Throw if `getDefault()` finds no available providers
- Log warnings for providers that fail availability checks

### 4. Create Provider Factory

**File: `file:src/e2b/providers/factory.ts`**

Implement the factory function as specified in the ticket:

```typescript
export function createProvider(
  name: string,
  config?: ProviderConfig
): SandboxProvider
```

- Switch statement for known providers: 'e2b', 'native', 'docker'
- For 'e2b': instantiate `E2BProvider` with config
- For 'native' and 'docker': throw `NotImplementedError` with message "Provider '{name}' planned for future release"
- Default case: throw `Error` with "Unknown provider: {name}"
- Validate config matches provider requirements
- Pass logger instance from `file:src/logger.ts` to provider constructors

Helper function:
```typescript
export function createProviderWithDefaults(
  name: string,
  logger: Logger
): SandboxProvider
```
- Load config from environment variables and config file
- Merge with provider-specific defaults
- Call `createProvider()` with merged config

### 5. Implement Auto-Discovery

**File: `file:src/e2b/providers/discovery.ts`**

Implement provider auto-discovery as specified in the ticket:

```typescript
export async function discoverProviders(): Promise<string[]>
```

- Check E2B availability: `E2B_API_KEY` environment variable exists
- Check Native availability: 
  - Platform is macOS or Linux (not Windows)
  - `@anthropic-ai/sandbox-runtime` package installed (check via `require.resolve()`)
  - On Linux: verify `bubblewrap` command exists
- Check Docker availability:
  - `docker` command exists in PATH
  - Docker daemon is running (try `docker info`)
- Return array of available provider names
- Log discovery results at debug level

Helper functions:
- `async function commandExists(cmd: string): Promise<boolean>` - Check if command in PATH
- `async function checkE2BAvailable(): Promise<boolean>` - Validate E2B API key
- `async function checkNativeAvailable(): Promise<boolean>` - Check platform and dependencies
- `async function checkDockerAvailable(): Promise<boolean>` - Check Docker installation

Platform detection using `process.platform`:
- 'darwin' → macOS (native supported)
- 'linux' → Linux (native supported with bubblewrap)
- 'win32' → Windows (native NOT supported)

### 6. Configuration System

**File: `file:src/e2b/providers/config.ts`**

Implement configuration loading and management:

```typescript
export interface SandboxConfig {
  defaultProvider?: string;
  fallbackChain?: string[];
  providers: {
    e2b?: E2BProviderConfig;
    native?: NativeProviderConfig;
    docker?: DockerProviderConfig;
  };
}
```

- `loadConfig(): SandboxConfig` - Load from `~/.parallel-cc/config.json`
- `saveConfig(config: SandboxConfig): void` - Save to config file
- `getProviderConfig(name: string): ProviderConfig | undefined` - Get provider-specific config
- Merge environment variables with file config (env vars take precedence)
- Create config file with defaults if it doesn't exist
- Validate config schema using `zod` (already in dependencies)

Environment variable mapping:
- `SANDBOX_PROVIDER` → `defaultProvider`
- `E2B_API_KEY`, `E2B_TEMPLATE` → `providers.e2b.*`
- `DOCKER_IMAGE`, `DOCKER_NETWORK` → `providers.docker.*`

### 7. Implement Fallback Chain

**File: `file:src/e2b/providers/registry.ts` (extend)**

Add fallback chain support to `ProviderRegistry`:

- `getWithFallback(name: string): Promise<SandboxProvider>` - Try primary provider, fall back to chain
- Read fallback chain from config: `config.fallbackChain`
- Iterate through chain, check `isAvailable()` for each
- Return first available provider
- Throw if no providers in chain are available
- Log each fallback attempt at info level

Example flow:
1. Try primary provider 'native'
2. If unavailable, try 'docker' from fallback chain
3. If unavailable, try 'e2b' from fallback chain
4. If all fail, throw error with helpful message

### 8. Update SandboxManager

**File: `file:src/e2b/sandbox-manager.ts` (refactor)**

Refactor to use provider abstraction while maintaining backward compatibility:

- Keep existing public API unchanged
- Add `private provider: SandboxProvider` field
- Constructor accepts optional `provider: SandboxProvider` parameter
- If no provider specified, use `ProviderRegistry.getInstance().getDefault()`
- Delegate to provider methods:
  - `createSandbox()` → `provider.create()`
  - `terminateSandbox()` → `provider.destroy()`
  - `monitorSandboxHealth()` → `provider.isRunning()`
- Maintain existing tracking maps (`activeSandboxes`, `sandboxStartTimes`, etc.) for backward compatibility
- Keep E2B-specific methods for now (will be deprecated in future)

Migration strategy:
- Phase 1 (this ticket): Add provider support, keep E2B methods
- Phase 2 (future): Deprecate E2B-specific methods
- Phase 3 (future): Remove E2B-specific methods

### 9. Update Type Definitions

**File: `file:src/types.ts` (extend)**

Add provider-related types:

```typescript
export type SandboxProviderType = 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare';

export interface ProviderConfig {
  provider: SandboxProviderType;
  timeout?: number;
  autoCleanup?: boolean;
}

export interface E2BProviderConfig extends ProviderConfig {
  provider: 'e2b';
  apiKey?: string;
  template?: string;
  timeoutMinutes?: number;
}

export interface NativeProviderConfig extends ProviderConfig {
  provider: 'native';
  allowedDomains?: string[];
  allowWritePaths?: string[];
  denyReadPaths?: string[];
}

export interface DockerProviderConfig extends ProviderConfig {
  provider: 'docker';
  image?: string;
  network?: 'none' | 'bridge' | 'host';
  memoryLimit?: string;
  cpuLimit?: number;
}
```

Keep existing E2B types for backward compatibility.

### 10. CLI Integration

**File: `file:src/cli.ts` (extend)**

Add `--provider` flag to `sandbox-run` command:

- Parse `--provider <name>` flag (default: from config or 'e2b')
- Use `ProviderRegistry.getInstance().get(name)` to get provider
- If provider not found, show available providers via `registry.list()`
- Pass provider to `SandboxManager` constructor
- Update help text to document provider options

Add new `providers` command:
```bash
parallel-cc providers [--available]
```
- List all registered providers
- With `--available`: only show providers where `isAvailable()` is true
- Show provider status (available/unavailable) and reason if unavailable

### 11. Testing Strategy

**Files: `file:tests/e2b/providers/*.test.ts`**

Create comprehensive test suite:

**`registry.test.ts`:**
- Test provider registration and retrieval
- Test duplicate name rejection
- Test `getDefault()` with various configs
- Test `getAvailable()` filtering
- Test singleton pattern

**`factory.test.ts`:**
- Test creating E2B provider
- Test error handling for unknown providers
- Test config validation
- Test NotImplementedError for future providers

**`discovery.test.ts`:**
- Mock environment variables and command checks
- Test E2B discovery with/without API key
- Test platform detection (mock `process.platform`)
- Test Docker availability detection
- Test Native availability on different platforms

**`e2b-provider.test.ts`:**
- Test `isAvailable()` with/without API key
- Test provider interface implementation
- Test integration with existing `SandboxManager`
- Mock E2B SDK calls

**`config.test.ts`:**
- Test config loading from file
- Test environment variable merging
- Test config validation
- Test default config creation

Integration tests:
- Test full flow: discovery → registry → factory → provider creation
- Test fallback chain with mocked provider availability
- Test backward compatibility with existing E2B workflows

### 12. Documentation

**File: `file:docs/PROVIDERS.md` (new)**

Create provider documentation:

- Overview of provider architecture
- List of supported providers (E2B only for now)
- Configuration guide with examples
- Environment variable reference
- Fallback chain configuration
- Migration guide from v1.0 to v1.5
- Troubleshooting common issues

**File: `file:README.md` (update)**

Add provider section:
- Quick start with provider selection
- Link to detailed provider documentation
- Example commands with `--provider` flag

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CLI as CLI (sandbox-run)
    participant Registry as ProviderRegistry
    participant Discovery as Auto-Discovery
    participant Factory as Provider Factory
    participant E2BProvider as E2BProvider
    participant SandboxMgr as SandboxManager (legacy)
    
    CLI->>Registry: getInstance()
    Registry->>Discovery: discoverProviders()
    Discovery-->>Registry: ['e2b', 'docker']
    
    CLI->>Registry: get('e2b')
    Registry->>Factory: createProvider('e2b', config)
    Factory->>E2BProvider: new E2BProvider(config)
    E2BProvider->>SandboxMgr: new SandboxManager(logger, config)
    E2BProvider-->>Factory: provider instance
    Factory-->>Registry: provider instance
    Registry-->>CLI: provider instance
    
    CLI->>E2BProvider: create(config)
    E2BProvider->>SandboxMgr: createSandbox(sessionId)
    SandboxMgr-->>E2BProvider: {sandbox, sandboxId, status}
    E2BProvider-->>CLI: SandboxInstance
    
    CLI->>E2BProvider: execute(instanceId, command)
    E2BProvider->>SandboxMgr: getSandbox(sandboxId)
    E2BProvider-->>CLI: AsyncGenerator<OutputChunk>
```

## Configuration Example

```json
{
  "sandbox": {
    "defaultProvider": "e2b",
    "fallbackChain": ["native", "docker"],
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      },
      "native": {
        "allowedDomains": ["github.com", "api.anthropic.com"],
        "allowWritePaths": [".", ".git"],
        "denyReadPaths": ["~/.ssh", "~/.aws"]
      },
      "docker": {
        "image": "claude-code:latest",
        "network": "none",
        "memoryLimit": "4g"
      }
    }
  }
}
```

## Backward Compatibility

All existing E2B workflows continue to work without changes:
- `parallel-cc sandbox-run` defaults to E2B provider
- Existing `SandboxManager` API unchanged
- Environment variables (`E2B_API_KEY`, `E2B_TEMPLATE`) still respected
- Database schema unchanged (provider info stored in existing `execution_mode` field)

New capabilities added without breaking changes:
- `--provider` flag is optional
- Registry auto-discovers E2B if API key present
- Fallback chain only used if explicitly configured

---

Execution Information

Branch: main
Commit: 136df60

New Plan

Observations

The codebase currently has a working E2B sandbox integration (v1.0) with SandboxManager tightly coupled to the E2B SDK. The file:src/e2b/sandbox-manager.ts directly imports and uses E2B's Sandbox class. No provider abstraction layer exists yet. The file:SANDBOX_INTEGRATION_PLAN.md provides comprehensive specifications for v1.5's multi-provider architecture. The ticket dependencies (#30 and #31) don't exist yet and need to be created as part of this work. The existing configuration system uses environment variables and the file:src/types.ts defines E2B-specific types.

Approach

Create a provider-agnostic architecture by introducing a SandboxProvider interface and refactoring the existing E2B implementation into an E2BProvider class. Build a registry system to manage multiple providers and a factory pattern for instantiation. Implement auto-discovery to detect available providers based on environment configuration and system capabilities. Add configuration support for provider selection, fallback chains, and provider-specific settings. Maintain 100% backward compatibility with existing E2B workflows while enabling future provider additions.

Implementation Steps

1. Create Provider Interface and Base Types

File: file:src/e2b/providers/base.ts

Define the core SandboxProvider interface that all providers must implement:

• name: string - Unique provider identifier (e.g., 'e2b', 'native', 'docker')
• isAvailable(): Promise<boolean> - Check if provider can be used (API keys, dependencies)
• create(config: ProviderConfig): Promise<SandboxInstance> - Create new sandbox
• destroy(instanceId: string): Promise<void> - Terminate sandbox
• uploadFiles(instanceId: string, files: FileList): Promise<void> - Upload files to sandbox
• downloadFiles(instanceId: string): Promise<FileList> - Download changed files
• execute(instanceId: string, command: string): AsyncGenerator<OutputChunk> - Execute command with streaming output
• isRunning(instanceId: string): Promise<boolean> - Check sandbox health
• getMetrics(instanceId: string): Promise<SandboxMetrics> - Get usage metrics

Define supporting types:

• ProviderConfig - Base configuration interface with provider-specific extensions
• SandboxInstance - Represents a running sandbox with id, provider, status, metadata
• OutputChunk - Streaming output with type: 'stdout' | 'stderr', data: string, timestamp: Date
• SandboxMetrics - Usage metrics including elapsedMinutes, estimatedCost, status
• FileList - Array of { path: string, content: Buffer | string }

Reference the existing types in file:src/types.ts for SandboxStatus, E2BSessionConfig, etc.

2. Implement E2BProvider

File: file:src/e2b/providers/e2b-provider.ts

Extract E2B-specific logic from file:src/e2b/sandbox-manager.ts into a provider implementation:

• Implement SandboxProvider interface
• Wrap existing SandboxManager methods:
  • create() → calls SandboxManager.createSandbox()
  • destroy() → calls SandboxManager.terminateSandbox()
  • isRunning() → calls SandboxManager.monitorSandboxHealth()
  • getMetrics() → calls SandboxManager.getElapsedMinutes() and getEstimatedCost()
• isAvailable() checks for E2B_API_KEY environment variable
• Store reference to SandboxManager instance for lifecycle management
• Map E2B-specific types to provider interface types
• Handle E2B SDK's Sandbox.create() and Sandbox.connect() methods
• Implement file sync using existing file:src/e2b/file-sync.ts utilities
• Implement command execution using existing file:src/e2b/claude-runner.ts logic

Configuration mapping:

• E2B_API_KEY → required for availability check
• E2B_TEMPLATE → maps to sandboxImage in E2BSessionConfig
• PARALLEL_CC_E2B_TIMEOUT → maps to timeoutMinutes

3. Create Provider Registry

File: file:src/e2b/providers/registry.ts

Implement the ProviderRegistry class as specified in the ticket:

• private providers: Map<string, SandboxProvider> - Store registered providers
• register(provider: SandboxProvider): void - Add provider to registry, validate unique names
• unregister(name: string): boolean - Remove provider from registry
• get(name: string): SandboxProvider | undefined - Retrieve provider by name
• list(): string[] - Return array of registered provider names
• getDefault(): SandboxProvider - Return default provider based on:
  1. SANDBOX_PROVIDER environment variable
  2. Configuration file setting (~/.parallel-cc/config.json)
  3. First available provider from discovery
  4. Fallback to E2B if configured
• getAvailable(): Promise<string[]> - Return names of providers where isAvailable() returns true
• Singleton pattern: static getInstance(): ProviderRegistry

Error handling:

• Throw if registering duplicate provider names
• Throw if getDefault() finds no available providers
• Log warnings for providers that fail availability checks

4. Create Provider Factory

File: file:src/e2b/providers/factory.ts

Implement the factory function as specified in the ticket:

export function createProvider(
  name: string,
  config?: ProviderConfig
): SandboxProvider

• Switch statement for known providers: 'e2b', 'native', 'docker'
• For 'e2b': instantiate E2BProvider with config
• For 'native' and 'docker': throw NotImplementedError with message "Provider '{name}' planned for future release"
• Default case: throw Error with "Unknown provider: {name}"
• Validate config matches provider requirements
• Pass logger instance from file:src/logger.ts to provider constructors

Helper function:

export function createProviderWithDefaults(
  name: string,
  logger: Logger
): SandboxProvider

• Load config from environment variables and config file
• Merge with provider-specific defaults
• Call createProvider() with merged config

5. Implement Auto-Discovery

File: file:src/e2b/providers/discovery.ts

Implement provider auto-discovery as specified in the ticket:

export async function discoverProviders(): Promise<string[]>

• Check E2B availability: E2B_API_KEY environment variable exists
• Check Native availability:
  • Platform is macOS or Linux (not Windows)
  • @anthropic-ai/sandbox-runtime package installed (check via require.resolve())
  • On Linux: verify bubblewrap command exists
• Check Docker availability:
  • docker command exists in PATH
  • Docker daemon is running (try docker info)
• Return array of available provider names
• Log discovery results at debug level

Helper functions:

• async function commandExists(cmd: string): Promise<boolean> - Check if command in PATH
• async function checkE2BAvailable(): Promise<boolean> - Validate E2B API key
• async function checkNativeAvailable(): Promise<boolean> - Check platform and dependencies
• async function checkDockerAvailable(): Promise<boolean> - Check Docker installation

Platform detection using process.platform:

• 'darwin' → macOS (native supported)
• 'linux' → Linux (native supported with bubblewrap)
• 'win32' → Windows (native NOT supported)

6. Configuration System

File: file:src/e2b/providers/config.ts

Implement configuration loading and management:

export interface SandboxConfig {
  defaultProvider?: string;
  fallbackChain?: string[];
  providers: {
    e2b?: E2BProviderConfig;
    native?: NativeProviderConfig;
    docker?: DockerProviderConfig;
  };
}

• loadConfig(): SandboxConfig - Load from ~/.parallel-cc/config.json
• saveConfig(config: SandboxConfig): void - Save to config file
• getProviderConfig(name: string): ProviderConfig | undefined - Get provider-specific config
• Merge environment variables with file config (env vars take precedence)
• Create config file with defaults if it doesn't exist
• Validate config schema using zod (already in dependencies)

Environment variable mapping:

• SANDBOX_PROVIDER → defaultProvider
• E2B_API_KEY, E2B_TEMPLATE → providers.e2b.*
• DOCKER_IMAGE, DOCKER_NETWORK → providers.docker.*

7. Implement Fallback Chain

File: file:src/e2b/providers/registry.ts (extend)

Add fallback chain support to ProviderRegistry:

• getWithFallback(name: string): Promise<SandboxProvider> - Try primary provider, fall back to chain
• Read fallback chain from config: config.fallbackChain
• Iterate through chain, check isAvailable() for each
• Return first available provider
• Throw if no providers in chain are available
• Log each fallback attempt at info level

Example flow:

1. Try primary provider 'native'
2. If unavailable, try 'docker' from fallback chain
3. If unavailable, try 'e2b' from fallback chain
4. If all fail, throw error with helpful message

8. Update SandboxManager

File: file:src/e2b/sandbox-manager.ts (refactor)

Refactor to use provider abstraction while maintaining backward compatibility:

• Keep existing public API unchanged
• Add private provider: SandboxProvider field
• Constructor accepts optional provider: SandboxProvider parameter
• If no provider specified, use ProviderRegistry.getInstance().getDefault()
• Delegate to provider methods:
  • createSandbox() → provider.create()
  • terminateSandbox() → provider.destroy()
  • monitorSandboxHealth() → provider.isRunning()
• Maintain existing tracking maps (activeSandboxes, sandboxStartTimes, etc.) for backward compatibility
• Keep E2B-specific methods for now (will be deprecated in future)

Migration strategy:

• Phase 1 (this ticket): Add provider support, keep E2B methods
• Phase 2 (future): Deprecate E2B-specific methods
• Phase 3 (future): Remove E2B-specific methods

9. Update Type Definitions

File: file:src/types.ts (extend)

Add provider-related types:

export type SandboxProviderType = 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare';

export interface ProviderConfig {
  provider: SandboxProviderType;
  timeout?: number;
  autoCleanup?: boolean;
}

export interface E2BProviderConfig extends ProviderConfig {
  provider: 'e2b';
  apiKey?: string;
  template?: string;
  timeoutMinutes?: number;
}

export interface NativeProviderConfig extends ProviderConfig {
  provider: 'native';
  allowedDomains?: string[];
  allowWritePaths?: string[];
  denyReadPaths?: string[];
}

export interface DockerProviderConfig extends ProviderConfig {
  provider: 'docker';
  image?: string;
  network?: 'none' | 'bridge' | 'host';
  memoryLimit?: string;
  cpuLimit?: number;
}

Keep existing E2B types for backward compatibility.

10. CLI Integration

File: file:src/cli.ts (extend)

Add --provider flag to sandbox-run command:

• Parse --provider <name> flag (default: from config or 'e2b')
• Use ProviderRegistry.getInstance().get(name) to get provider
• If provider not found, show available providers via registry.list()
• Pass provider to SandboxManager constructor
• Update help text to document provider options

Add new providers command:

• List all registered providers
• With --available: only show providers where isAvailable() is true
• Show provider status (available/unavailable) and reason if unavailable

11. Testing Strategy

Files: file:tests/e2b/providers/*.test.ts

Create comprehensive test suite:

registry.test.ts:

• Test provider registration and retrieval
• Test duplicate name rejection
• Test getDefault() with various configs
• Test getAvailable() filtering
• Test singleton pattern

factory.test.ts:

• Test creating E2B provider
• Test error handling for unknown providers
• Test config validation
• Test NotImplementedError for future providers

discovery.test.ts:

• Mock environment variables and command checks
• Test E2B discovery with/without API key
• Test platform detection (mock process.platform)
• Test Docker availability detection
• Test Native availability on different platforms

e2b-provider.test.ts:

• Test isAvailable() with/without API key
• Test provider interface implementation
• Test integration with existing SandboxManager
• Mock E2B SDK calls

config.test.ts:

• Test config loading from file
• Test environment variable merging
• Test config validation
• Test default config creation

Integration tests:

• Test full flow: discovery → registry → factory → provider creation
• Test fallback chain with mocked provider availability
• Test backward compatibility with existing E2B workflows

12. Documentation

File: file:docs/PROVIDERS.md (new)

Create provider documentation:

• Overview of provider architecture
• List of supported providers (E2B only for now)
• Configuration guide with examples
• Environment variable reference
• Fallback chain configuration
• Migration guide from v1.0 to v1.5
• Troubleshooting common issues

File: file:README.md (update)

Add provider section:

• Quick start with provider selection
• Link to detailed provider documentation
• Example commands with --provider flag

Architecture Diagram

sequenceDiagram
    participant CLI as CLI (sandbox-run)
    participant Registry as ProviderRegistry
    participant Discovery as Auto-Discovery
    participant Factory as Provider Factory
    participant E2BProvider as E2BProvider
    participant SandboxMgr as SandboxManager (legacy)
    
    CLI->>Registry: getInstance()
    Registry->>Discovery: discoverProviders()
    Discovery-->>Registry: ['e2b', 'docker']
    
    CLI->>Registry: get('e2b')
    Registry->>Factory: createProvider('e2b', config)
    Factory->>E2BProvider: new E2BProvider(config)
    E2BProvider->>SandboxMgr: new SandboxManager(logger, config)
    E2BProvider-->>Factory: provider instance
    Factory-->>Registry: provider instance
    Registry-->>CLI: provider instance
    
    CLI->>E2BProvider: create(config)
    E2BProvider->>SandboxMgr: createSandbox(sessionId)
    SandboxMgr-->>E2BProvider: {sandbox, sandboxId, status}
    E2BProvider-->>CLI: SandboxInstance
    
    CLI->>E2BProvider: execute(instanceId, command)
    E2BProvider->>SandboxMgr: getSandbox(sandboxId)
    E2BProvider-->>CLI: AsyncGenerator<OutputChunk>

Loading

Configuration Example

{
  "sandbox": {
    "defaultProvider": "e2b",
    "fallbackChain": ["native", "docker"],
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      },
      "native": {
        "allowedDomains": ["github.com", "api.anthropic.com"],
        "allowWritePaths": [".", ".git"],
        "denyReadPaths": ["~/.ssh", "~/.aws"]
      },
      "docker": {
        "image": "claude-code:latest",
        "network": "none",
        "memoryLimit": "4g"
      }
    }
  }
}

Backward Compatibility

All existing E2B workflows continue to work without changes:

• parallel-cc sandbox-run defaults to E2B provider
• Existing SandboxManager API unchanged
• Environment variables (E2B_API_KEY, E2B_TEMPLATE) still respected
• Database schema unchanged (provider info stored in existing execution_mode field)

New capabilities added without breaking changes:

• --provider flag is optional
• Registry auto-discovers E2B if API key present
• Fallback chain only used if explicitly configured

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has a working E2B sandbox integration (v1.0) with `SandboxManager` tightly coupled to the E2B SDK. The `file:src/e2b/sandbox-manager.ts` directly imports and uses E2B's `Sandbox` class. No provider abstraction layer exists yet. The `file:SANDBOX_INTEGRATION_PLAN.md` provides comprehensive specifications for v1.5's multi-provider architecture. The ticket dependencies (#30 and #31) don't exist yet and need to be created as part of this work. The existing configuration system uses environment variables and the `file:src/types.ts` defines E2B-specific types.

## Approach

Create a provider-agnostic architecture by introducing a `SandboxProvider` interface and refactoring the existing E2B implementation into an `E2BProvider` class. Build a registry system to manage multiple providers and a factory pattern for instantiation. Implement auto-discovery to detect available providers based on environment configuration and system capabilities. Add configuration support for provider selection, fallback chains, and provider-specific settings. Maintain 100% backward compatibility with existing E2B workflows while enabling future provider additions.

## Implementation Steps

### 1. Create Provider Interface and Base Types

**File: `file:src/e2b/providers/base.ts`**

Define the core `SandboxProvider` interface that all providers must implement:

- `name: string` - Unique provider identifier (e.g., 'e2b', 'native', 'docker')
- `isAvailable(): Promise<boolean>` - Check if provider can be used (API keys, dependencies)
- `create(config: ProviderConfig): Promise<SandboxInstance>` - Create new sandbox
- `destroy(instanceId: string): Promise<void>` - Terminate sandbox
- `uploadFiles(instanceId: string, files: FileList): Promise<void>` - Upload files to sandbox
- `downloadFiles(instanceId: string): Promise<FileList>` - Download changed files
- `execute(instanceId: string, command: string): AsyncGenerator<OutputChunk>` - Execute command with streaming output
- `isRunning(instanceId: string): Promise<boolean>` - Check sandbox health
- `getMetrics(instanceId: string): Promise<SandboxMetrics>` - Get usage metrics

Define supporting types:
- `ProviderConfig` - Base configuration interface with provider-specific extensions
- `SandboxInstance` - Represents a running sandbox with `id`, `provider`, `status`, `metadata`
- `OutputChunk` - Streaming output with `type: 'stdout' | 'stderr'`, `data: string`, `timestamp: Date`
- `SandboxMetrics` - Usage metrics including `elapsedMinutes`, `estimatedCost`, `status`
- `FileList` - Array of `{ path: string, content: Buffer | string }`

Reference the existing types in `file:src/types.ts` for `SandboxStatus`, `E2BSessionConfig`, etc.

### 2. Implement E2BProvider

**File: `file:src/e2b/providers/e2b-provider.ts`**

Extract E2B-specific logic from `file:src/e2b/sandbox-manager.ts` into a provider implementation:

- Implement `SandboxProvider` interface
- Wrap existing `SandboxManager` methods:
  - `create()` → calls `SandboxManager.createSandbox()`
  - `destroy()` → calls `SandboxManager.terminateSandbox()`
  - `isRunning()` → calls `SandboxManager.monitorSandboxHealth()`
  - `getMetrics()` → calls `SandboxManager.getElapsedMinutes()` and `getEstimatedCost()`
- `isAvailable()` checks for `E2B_API_KEY` environment variable
- Store reference to `SandboxManager` instance for lifecycle management
- Map E2B-specific types to provider interface types
- Handle E2B SDK's `Sandbox.create()` and `Sandbox.connect()` methods
- Implement file sync using existing `file:src/e2b/file-sync.ts` utilities
- Implement command execution using existing `file:src/e2b/claude-runner.ts` logic

Configuration mapping:
- `E2B_API_KEY` → required for availability check
- `E2B_TEMPLATE` → maps to `sandboxImage` in `E2BSessionConfig`
- `PARALLEL_CC_E2B_TIMEOUT` → maps to `timeoutMinutes`

### 3. Create Provider Registry

**File: `file:src/e2b/providers/registry.ts`**

Implement the `ProviderRegistry` class as specified in the ticket:

- `private providers: Map<string, SandboxProvider>` - Store registered providers
- `register(provider: SandboxProvider): void` - Add provider to registry, validate unique names
- `unregister(name: string): boolean` - Remove provider from registry
- `get(name: string): SandboxProvider | undefined` - Retrieve provider by name
- `list(): string[]` - Return array of registered provider names
- `getDefault(): SandboxProvider` - Return default provider based on:
  1. `SANDBOX_PROVIDER` environment variable
  2. Configuration file setting (`~/.parallel-cc/config.json`)
  3. First available provider from discovery
  4. Fallback to E2B if configured
- `getAvailable(): Promise<string[]>` - Return names of providers where `isAvailable()` returns true
- Singleton pattern: `static getInstance(): ProviderRegistry`

Error handling:
- Throw if registering duplicate provider names
- Throw if `getDefault()` finds no available providers
- Log warnings for providers that fail availability checks

### 4. Create Provider Factory

**File: `file:src/e2b/providers/factory.ts`**

Implement the factory function as specified in the ticket:

```typescript
export function createProvider(
  name: string,
  config?: ProviderConfig
): SandboxProvider
```

- Switch statement for known providers: 'e2b', 'native', 'docker'
- For 'e2b': instantiate `E2BProvider` with config
- For 'native' and 'docker': throw `NotImplementedError` with message "Provider '{name}' planned for future release"
- Default case: throw `Error` with "Unknown provider: {name}"
- Validate config matches provider requirements
- Pass logger instance from `file:src/logger.ts` to provider constructors

Helper function:
```typescript
export function createProviderWithDefaults(
  name: string,
  logger: Logger
): SandboxProvider
```
- Load config from environment variables and config file
- Merge with provider-specific defaults
- Call `createProvider()` with merged config

### 5. Implement Auto-Discovery

**File: `file:src/e2b/providers/discovery.ts`**

Implement provider auto-discovery as specified in the ticket:

```typescript
export async function discoverProviders(): Promise<string[]>
```

- Check E2B availability: `E2B_API_KEY` environment variable exists
- Check Native availability: 
  - Platform is macOS or Linux (not Windows)
  - `@anthropic-ai/sandbox-runtime` package installed (check via `require.resolve()`)
  - On Linux: verify `bubblewrap` command exists
- Check Docker availability:
  - `docker` command exists in PATH
  - Docker daemon is running (try `docker info`)
- Return array of available provider names
- Log discovery results at debug level

Helper functions:
- `async function commandExists(cmd: string): Promise<boolean>` - Check if command in PATH
- `async function checkE2BAvailable(): Promise<boolean>` - Validate E2B API key
- `async function checkNativeAvailable(): Promise<boolean>` - Check platform and dependencies
- `async function checkDockerAvailable(): Promise<boolean>` - Check Docker installation

Platform detection using `process.platform`:
- 'darwin' → macOS (native supported)
- 'linux' → Linux (native supported with bubblewrap)
- 'win32' → Windows (native NOT supported)

### 6. Configuration System

**File: `file:src/e2b/providers/config.ts`**

Implement configuration loading and management:

```typescript
export interface SandboxConfig {
  defaultProvider?: string;
  fallbackChain?: string[];
  providers: {
    e2b?: E2BProviderConfig;
    native?: NativeProviderConfig;
    docker?: DockerProviderConfig;
  };
}
```

- `loadConfig(): SandboxConfig` - Load from `~/.parallel-cc/config.json`
- `saveConfig(config: SandboxConfig): void` - Save to config file
- `getProviderConfig(name: string): ProviderConfig | undefined` - Get provider-specific config
- Merge environment variables with file config (env vars take precedence)
- Create config file with defaults if it doesn't exist
- Validate config schema using `zod` (already in dependencies)

Environment variable mapping:
- `SANDBOX_PROVIDER` → `defaultProvider`
- `E2B_API_KEY`, `E2B_TEMPLATE` → `providers.e2b.*`
- `DOCKER_IMAGE`, `DOCKER_NETWORK` → `providers.docker.*`

### 7. Implement Fallback Chain

**File: `file:src/e2b/providers/registry.ts` (extend)**

Add fallback chain support to `ProviderRegistry`:

- `getWithFallback(name: string): Promise<SandboxProvider>` - Try primary provider, fall back to chain
- Read fallback chain from config: `config.fallbackChain`
- Iterate through chain, check `isAvailable()` for each
- Return first available provider
- Throw if no providers in chain are available
- Log each fallback attempt at info level

Example flow:
1. Try primary provider 'native'
2. If unavailable, try 'docker' from fallback chain
3. If unavailable, try 'e2b' from fallback chain
4. If all fail, throw error with helpful message

### 8. Update SandboxManager

**File: `file:src/e2b/sandbox-manager.ts` (refactor)**

Refactor to use provider abstraction while maintaining backward compatibility:

- Keep existing public API unchanged
- Add `private provider: SandboxProvider` field
- Constructor accepts optional `provider: SandboxProvider` parameter
- If no provider specified, use `ProviderRegistry.getInstance().getDefault()`
- Delegate to provider methods:
  - `createSandbox()` → `provider.create()`
  - `terminateSandbox()` → `provider.destroy()`
  - `monitorSandboxHealth()` → `provider.isRunning()`
- Maintain existing tracking maps (`activeSandboxes`, `sandboxStartTimes`, etc.) for backward compatibility
- Keep E2B-specific methods for now (will be deprecated in future)

Migration strategy:
- Phase 1 (this ticket): Add provider support, keep E2B methods
- Phase 2 (future): Deprecate E2B-specific methods
- Phase 3 (future): Remove E2B-specific methods

### 9. Update Type Definitions

**File: `file:src/types.ts` (extend)**

Add provider-related types:

```typescript
export type SandboxProviderType = 'e2b' | 'native' | 'docker' | 'daytona' | 'cloudflare';

export interface ProviderConfig {
  provider: SandboxProviderType;
  timeout?: number;
  autoCleanup?: boolean;
}

export interface E2BProviderConfig extends ProviderConfig {
  provider: 'e2b';
  apiKey?: string;
  template?: string;
  timeoutMinutes?: number;
}

export interface NativeProviderConfig extends ProviderConfig {
  provider: 'native';
  allowedDomains?: string[];
  allowWritePaths?: string[];
  denyReadPaths?: string[];
}

export interface DockerProviderConfig extends ProviderConfig {
  provider: 'docker';
  image?: string;
  network?: 'none' | 'bridge' | 'host';
  memoryLimit?: string;
  cpuLimit?: number;
}
```

Keep existing E2B types for backward compatibility.

### 10. CLI Integration

**File: `file:src/cli.ts` (extend)**

Add `--provider` flag to `sandbox-run` command:

- Parse `--provider <name>` flag (default: from config or 'e2b')
- Use `ProviderRegistry.getInstance().get(name)` to get provider
- If provider not found, show available providers via `registry.list()`
- Pass provider to `SandboxManager` constructor
- Update help text to document provider options

Add new `providers` command:
```bash
```
- List all registered providers
- With `--available`: only show providers where `isAvailable()` is true
- Show provider status (available/unavailable) and reason if unavailable

### 11. Testing Strategy

**Files: `file:tests/e2b/providers/*.test.ts`**

Create comprehensive test suite:

**`registry.test.ts`:**
- Test provider registration and retrieval
- Test duplicate name rejection
- Test `getDefault()` with various configs
- Test `getAvailable()` filtering
- Test singleton pattern

**`factory.test.ts`:**
- Test creating E2B provider
- Test error handling for unknown providers
- Test config validation
- Test NotImplementedError for future providers

**`discovery.test.ts`:**
- Mock environment variables and command checks
- Test E2B discovery with/without API key
- Test platform detection (mock `process.platform`)
- Test Docker availability detection
- Test Native availability on different platforms

**`e2b-provider.test.ts`:**
- Test `isAvailable()` with/without API key
- Test provider interface implementation
- Test integration with existing `SandboxManager`
- Mock E2B SDK calls

**`config.test.ts`:**
- Test config loading from file
- Test environment variable merging
- Test config validation
- Test default config creation

Integration tests:
- Test full flow: discovery → registry → factory → provider creation
- Test fallback chain with mocked provider availability
- Test backward compatibility with existing E2B workflows

### 12. Documentation

**File: `file:docs/PROVIDERS.md` (new)**

Create provider documentation:

- Overview of provider architecture
- List of supported providers (E2B only for now)
- Configuration guide with examples
- Environment variable reference
- Fallback chain configuration
- Migration guide from v1.0 to v1.5
- Troubleshooting common issues

**File: `file:README.md` (update)**

Add provider section:
- Quick start with provider selection
- Link to detailed provider documentation
- Example commands with `--provider` flag

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CLI as CLI (sandbox-run)
    participant Registry as ProviderRegistry
    participant Discovery as Auto-Discovery
    participant Factory as Provider Factory
    participant E2BProvider as E2BProvider
    participant SandboxMgr as SandboxManager (legacy)
    
    CLI->>Registry: getInstance()
    Registry->>Discovery: discoverProviders()
    Discovery-->>Registry: ['e2b', 'docker']
    
    CLI->>Registry: get('e2b')
    Registry->>Factory: createProvider('e2b', config)
    Factory->>E2BProvider: new E2BProvider(config)
    E2BProvider->>SandboxMgr: new SandboxManager(logger, config)
    E2BProvider-->>Factory: provider instance
    Factory-->>Registry: provider instance
    Registry-->>CLI: provider instance
    
    CLI->>E2BProvider: create(config)
    E2BProvider->>SandboxMgr: createSandbox(sessionId)
    SandboxMgr-->>E2BProvider: {sandbox, sandboxId, status}
    E2BProvider-->>CLI: SandboxInstance
    
    CLI->>E2BProvider: execute(instanceId, command)
    E2BProvider->>SandboxMgr: getSandbox(sandboxId)
    E2BProvider-->>CLI: AsyncGenerator<OutputChunk>
```

## Configuration Example

```json
{
  "sandbox": {
    "defaultProvider": "e2b",
    "fallbackChain": ["native", "docker"],
    "providers": {
      "e2b": {
        "template": "anthropic-claude-code",
        "timeoutMinutes": 60
      },
      "native": {
        "allowedDomains": ["github.com", "api.anthropic.com"],
        "allowWritePaths": [".", ".git"],
        "denyReadPaths": ["~/.ssh", "~/.aws"]
      },
      "docker": {
        "image": "claude-code:latest",
        "network": "none",
        "memoryLimit": "4g"
      }
    }
  }
}
```

## Backward Compatibility

All existing E2B workflows continue to work without changes:
- `parallel-cc sandbox-run` defaults to E2B provider
- Existing `SandboxManager` API unchanged
- Environment variables (`E2B_API_KEY`, `E2B_TEMPLATE`) still respected
- Database schema unchanged (provider info stored in existing `execution_mode` field)

New capabilities added without breaking changes:
- `--provider` flag is optional
- Registry auto-discovers E2B if API key present
- Fallback chain only used if explicitly configured

---

Execution Information

Branch: main
Commit: 9698ef5