[v1.5] Refactor E2B code into E2BProvider class

[frankbria]

Overview

Extract existing E2B logic from sandbox-manager.ts and file-sync.ts into a new E2BProvider class that implements the SandboxProvider interface.

Scope

Move to E2BProvider

• Sandbox creation logic
• File upload/download operations
• Execution handling
• Health monitoring
• Reconnection logic

Keep in SandboxManager

• Provider registry
• Provider selection
• Session tracking
• High-level orchestration

Implementation

// src/e2b/providers/e2b-provider.ts

import { SandboxProvider, SandboxConfig, SandboxInstance } from './types.js';
import { Sandbox } from 'e2b';

export class E2BProvider implements SandboxProvider {
  readonly name = 'e2b';
  readonly version = '1.0.0';
  
  private sandboxes: Map<string, Sandbox> = new Map();
  
  async create(config: SandboxConfig): Promise<SandboxInstance> {
    // Move logic from SandboxManager.createSandbox()
  }
  
  async destroy(instanceId: string): Promise<void> {
    // Move logic from SandboxManager.terminateSandbox()
  }
  
  // ... implement remaining interface methods
}

Migration Steps

1. Create E2BProvider class skeleton
2. Move createSandbox logic
3. Move terminateSandbox logic
4. Move file upload/download
5. Update SandboxManager to use E2BProvider
6. Verify all tests pass
7. Remove dead code from old locations

Files to Modify

• src/e2b/providers/e2b-provider.ts - New provider class
• src/e2b/sandbox-manager.ts - Refactor to use provider
• src/e2b/file-sync.ts - May be split into provider

Acceptance Criteria

• E2BProvider implements full SandboxProvider interface
• All existing tests pass
• No behavior changes for CLI users
• Code is cleaner and more modular
• Good test coverage for E2BProvider

Dependencies

• Depends on [v1.5] Define SandboxProvider interface and types #30 (SandboxProvider interface)

[traycerai]

Plan

Observations

The codebase currently has E2B-specific logic tightly coupled in SandboxManager and file-sync.ts. The v1.0 implementation successfully delivered E2B sandbox integration with 441 passing tests and 87.5% coverage. The v1.5 roadmap calls for extracting this into a provider-agnostic architecture. The SandboxProvider interface doesn't exist yet (issue #30 dependency), and there's no providers/ directory structure. The current implementation includes comprehensive security features (shell injection prevention, path validation) and robust error handling that must be preserved during refactoring.

Approach

This refactoring follows the Extract Class pattern to create E2BProvider implementing the SandboxProvider interface. The strategy is to move E2B-specific operations (sandbox lifecycle, file operations, execution) into the provider while keeping orchestration logic (provider registry, session tracking) in SandboxManager. This maintains backward compatibility while enabling future multi-provider support. The implementation will be incremental: define interface → create provider skeleton → migrate methods → update tests → verify no behavior changes.

Implementation Steps

1. Define SandboxProvider Interface and Types

File: file:src/e2b/providers/types.ts (new)

Create the provider abstraction layer with these interfaces:

• SandboxProvider interface with methods:

  • readonly name: string - Provider identifier (e.g., 'e2b')
  • readonly version: string - Provider version
  • create(config: SandboxConfig): Promise<SandboxInstance> - Create sandbox
  • destroy(instanceId: string): Promise<void> - Terminate sandbox
  • uploadFiles(instanceId: string, tarballPath: string, remotePath: string): Promise<UploadResult> - Upload files
  • downloadFiles(instanceId: string, remotePath: string, localPath: string): Promise<DownloadResult> - Download changed files
  • execute(instanceId: string, command: string, options?: ExecuteOptions): Promise<ExecutionResult> - Execute command
  • isRunning(instanceId: string): Promise<boolean> - Check if sandbox is running
  • reconnect(instanceId: string): Promise<SandboxInstance | null> - Reconnect to existing sandbox
  • extendTimeout(instanceId: string, additionalMinutes: number): Promise<boolean> - Extend timeout

• SandboxConfig interface with E2B-specific fields:

  • sessionId: string
  • apiKey?: string
  • template: string (e.g., 'anthropic-claude-code')
  • timeoutMs: number
  • metadata?: Record<string, string>

• SandboxInstance interface:

  • id: string - Sandbox identifier
  • provider: string - Provider name
  • createdAt: Date
  • metadata?: Record<string, unknown>

• ExecuteOptions, ExecutionResult, UploadResult, DownloadResult types

Reference the ROADMAP.md interface structure and existing types in file:src/types.ts.

2. Create E2BProvider Class Skeleton

File: file:src/e2b/providers/e2b-provider.ts (new)

Create the provider class structure:

import { SandboxProvider, SandboxConfig, SandboxInstance } from './types.js';
import { Sandbox } from 'e2b';
import type { Logger } from '../../logger.js';

export class E2BProvider implements SandboxProvider {
  readonly name = 'e2b';
  readonly version = '1.0.0';
  
  private sandboxes: Map<string, Sandbox> = new Map();
  private logger: Logger;
  
  constructor(logger: Logger) {
    this.logger = logger;
  }
  
  // Implement all interface methods (initially as stubs)
}

3. Move createSandbox Logic to E2BProvider.create()

Migrate the sandbox creation logic from file:src/e2b/sandbox-manager.ts lines 128-188:

• Move API key validation logic
• Move Sandbox.create() call with configuration
• Move sandbox tracking to internal sandboxes Map
• Preserve error handling for authentication, quota, and network errors
• Keep security features: metadata sanitization
• Return SandboxInstance instead of raw Sandbox object

The SandboxManager should call provider.create() and track the returned instance.

4. Move terminateSandbox Logic to E2BProvider.destroy()

Migrate termination logic from file:src/e2b/sandbox-manager.ts lines 332-395:

• Move sandbox.kill() call with timeout wrapper
• Move cleanup from internal sandboxes Map
• Preserve error handling and best-effort cleanup
• Return success/error status
• Keep logging for termination events

The SandboxManager should call provider.destroy() and update session tracking.

5. Move Reconnection Logic to E2BProvider.reconnect()

Migrate reconnection from file:src/e2b/sandbox-manager.ts lines 419-462:

• Move Sandbox.connect() call
• Move API key validation
• Track reconnected sandbox in internal Map
• Preserve error handling for 404, authentication, timeout errors
• Return SandboxInstance | null

6. Move File Upload Logic to E2BProvider.uploadFiles()

Migrate upload logic from file:src/e2b/file-sync.ts lines 285-343 and 353-436:

• Move simple upload for small files (< 50MB)
• Move resumable upload with checkpoints for large files
• Move tarball extraction in sandbox
• Preserve security: remote path validation (lines 103-139)
• Keep timeout wrappers for upload operations
• Return UploadResult with metadata

The file sync module should call provider.uploadFiles() with the tarball path.

7. Move File Download Logic to E2BProvider.downloadFiles()

Migrate download logic from file:src/e2b/file-sync.ts lines 446-643:

• Move git status checking for changed files
• Move tarball creation in sandbox
• Move base64 encoding/decoding for binary safety
• Move tarball download and extraction
• Preserve security: path validation, gzip verification
• Keep error handling for tar command failures
• Return DownloadResult with file count and size

8. Move Health Monitoring to E2BProvider.isRunning()

Migrate health check from file:src/e2b/sandbox-manager.ts lines 197-260:

• Move sandbox.isRunning() call with timeout wrapper
• Move reconnection attempt if sandbox not in cache
• Return boolean health status
• Preserve 30-second timeout for health checks

The SandboxManager should call provider.isRunning() for health monitoring.

9. Move Timeout Extension to E2BProvider.extendTimeout()

Migrate timeout extension from file:src/e2b/sandbox-manager.ts lines 507-543:

• Move sandbox.setTimeout() call
• Move timeout validation (max 24 hours)
• Keep timeout wrapper for the API call
• Return success boolean

10. Refactor SandboxManager to Use E2BProvider

File: file:src/e2b/sandbox-manager.ts

Transform SandboxManager into a provider orchestrator:

• Add private provider: SandboxProvider field
• Accept provider in constructor: constructor(logger: Logger, provider: SandboxProvider, config?: E2BSessionConfig)
• Update createSandbox() to call provider.create() and track session metadata
• Update terminateSandbox() to call provider.destroy() and cleanup session tracking
• Update monitorSandboxHealth() to call provider.isRunning()
• Update getOrReconnectSandbox() to call provider.reconnect()
• Update extendTimeout() to call provider.extendTimeout()
• Keep high-level orchestration: timeout enforcement (lines 268-324), cost calculation (lines 484-489), session tracking (sandboxStartTimes, timeoutWarningsIssued)
• Preserve security functions: sanitizePrompt(), validateFilePath() (keep as static utilities)

11. Update File Sync to Use Provider

File: file:src/e2b/file-sync.ts

Refactor file sync functions to accept provider:

• Update uploadToSandbox() signature: uploadToSandbox(tarballPath: string, provider: SandboxProvider, instanceId: string, remotePath: string)
• Update downloadChangedFiles() signature: downloadChangedFiles(provider: SandboxProvider, instanceId: string, remotePath: string, localPath: string)
• Call provider.uploadFiles() and provider.downloadFiles() instead of direct E2B SDK calls
• Keep helper functions: createTarball(), verifyUpload(), scanForCredentials(), buildExclusionList(), etc.
• Preserve all security validations: validateRemotePath(), validatePath()

12. Create Provider Factory Pattern

File: file:src/e2b/providers/factory.ts (new)

Create provider registry and factory:

export class ProviderFactory {
  private static providers = new Map<string, () => SandboxProvider>();
  
  static register(name: string, factory: () => SandboxProvider): void
  static create(name: string, logger: Logger): SandboxProvider
  static getAvailableProviders(): string[]
}

Register E2BProvider:

ProviderFactory.register('e2b', () => new E2BProvider(logger));

13. Update Tests for E2BProvider

File: file:tests/e2b/providers/e2b-provider.test.ts (new)

Create comprehensive tests for E2BProvider:

• Test all interface methods: create(), destroy(), uploadFiles(), downloadFiles(), isRunning(), reconnect(), extendTimeout()
• Mock E2B SDK (Sandbox.create, Sandbox.connect)
• Test error handling: authentication, quota, network errors
• Test security: path validation, prompt sanitization
• Verify sandbox tracking in internal Map
• Test concurrent operations

File: file:tests/e2b/sandbox-manager.test.ts

Update existing tests to use provider:

• Mock E2BProvider instead of E2B SDK directly
• Update test setup to inject provider into SandboxManager
• Verify SandboxManager calls provider methods correctly
• Keep all existing test cases (82 tests should still pass)
• Add tests for provider orchestration logic

File: file:tests/e2b/file-sync.test.ts

Update file sync tests:

• Mock provider instead of E2B SDK
• Update function signatures to pass provider
• Keep all existing test cases
• Verify provider methods are called with correct parameters

14. Update Integration Tests

Files: file:tests/e2b/integration.test.ts, file:tests/e2b/e2e-workflow.test.ts

Update integration tests to use provider architecture:

• Create E2BProvider instance for tests
• Pass provider to SandboxManager and file sync functions
• Verify end-to-end workflows still work
• Keep all existing test scenarios

15. Create Provider Index and Exports

File: file:src/e2b/providers/index.ts (new)

Export provider types and classes:

export * from './types.js';
export * from './e2b-provider.js';
export * from './factory.js';

16. Update Main Exports

File: file:src/e2b/index.ts (new or update existing)

Export provider module:

export * from './sandbox-manager.js';
export * from './file-sync.js';
export * from './providers/index.js';

17. Verify Backward Compatibility

Test that existing code using SandboxManager still works:

• CLI commands: sandbox-run, sandbox-logs, sandbox-download, sandbox-kill
• Verify no breaking changes in public APIs
• Ensure all 441 existing tests pass
• Check that E2B sessions work identically to v1.0

18. Update Documentation

File: file:docs/E2B_GUIDE.md

Add section on provider architecture:

• Explain the provider abstraction
• Document how to use E2BProvider directly
• Show provider factory usage
• Note that this is preparation for v1.5 multi-provider support

19. Clean Up Dead Code

Remove duplicated logic from old locations:

• Remove E2B-specific code from SandboxManager that's now in E2BProvider
• Keep only orchestration logic in SandboxManager
• Remove direct E2B SDK imports from file-sync (use provider instead)
• Update imports throughout codebase

20. Final Verification

Run complete test suite:

• All 441+ tests should pass
• No behavior changes for end users
• Code coverage should remain ≥85%
• Security features preserved (shell injection prevention, path validation)
• Performance should be equivalent to v1.0

Architecture Diagram

sequenceDiagram
    participant CLI as CLI Command
    participant SM as SandboxManager
    participant EP as E2BProvider
    participant E2B as E2B SDK
    participant FS as FileSync

    CLI->>SM: createSandbox(sessionId)
    SM->>EP: create(config)
    EP->>E2B: Sandbox.create(template, opts)
    E2B-->>EP: sandbox instance
    EP->>EP: Track in sandboxes Map
    EP-->>SM: SandboxInstance
    SM->>SM: Track session metadata
    SM-->>CLI: { sandbox, sandboxId, status }

    CLI->>FS: uploadToSandbox(tarball, provider, instanceId)
    FS->>EP: uploadFiles(instanceId, tarballPath, remotePath)
    EP->>E2B: sandbox.files.write()
    EP->>E2B: sandbox.commands.run(tar extract)
    EP-->>FS: UploadResult
    FS-->>CLI: success

    CLI->>SM: monitorSandboxHealth(sandboxId)
    SM->>EP: isRunning(instanceId)
    EP->>E2B: sandbox.isRunning()
    E2B-->>EP: boolean
    EP-->>SM: boolean
    SM-->>CLI: SandboxHealthCheck

    CLI->>SM: terminateSandbox(sandboxId)
    SM->>EP: destroy(instanceId)
    EP->>E2B: sandbox.kill()
    EP->>EP: Remove from sandboxes Map
    EP-->>SM: void
    SM->>SM: Cleanup session tracking
    SM-->>CLI: SandboxTerminationResult

Loading

Key Design Decisions

1. Provider owns sandbox instances: The E2BProvider maintains the sandboxes Map, not SandboxManager. This ensures provider encapsulation.

2. SandboxManager orchestrates: High-level concerns (timeout enforcement, cost tracking, session metadata) stay in SandboxManager.

3. File sync uses provider: File operations go through provider interface, not direct E2B SDK calls.

4. Security preserved: All validation functions (sanitizePrompt, validateFilePath, validateRemotePath) remain and are used by both provider and manager.

5. Backward compatibility: Existing code using SandboxManager continues to work by injecting E2BProvider as default.

6. Incremental migration: Each method is moved independently, allowing tests to pass at each step.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has E2B-specific logic tightly coupled in `SandboxManager` and `file-sync.ts`. The v1.0 implementation successfully delivered E2B sandbox integration with 441 passing tests and 87.5% coverage. The v1.5 roadmap calls for extracting this into a provider-agnostic architecture. The `SandboxProvider` interface doesn't exist yet (issue #30 dependency), and there's no `providers/` directory structure. The current implementation includes comprehensive security features (shell injection prevention, path validation) and robust error handling that must be preserved during refactoring.

## Approach

This refactoring follows the Extract Class pattern to create `E2BProvider` implementing the `SandboxProvider` interface. The strategy is to move E2B-specific operations (sandbox lifecycle, file operations, execution) into the provider while keeping orchestration logic (provider registry, session tracking) in `SandboxManager`. This maintains backward compatibility while enabling future multi-provider support. The implementation will be incremental: define interface → create provider skeleton → migrate methods → update tests → verify no behavior changes.

## Implementation Steps

### 1. Define SandboxProvider Interface and Types

**File:** `file:src/e2b/providers/types.ts` (new)

Create the provider abstraction layer with these interfaces:

- `SandboxProvider` interface with methods:
  - `readonly name: string` - Provider identifier (e.g., 'e2b')
  - `readonly version: string` - Provider version
  - `create(config: SandboxConfig): Promise<SandboxInstance>` - Create sandbox
  - `destroy(instanceId: string): Promise<void>` - Terminate sandbox
  - `uploadFiles(instanceId: string, tarballPath: string, remotePath: string): Promise<UploadResult>` - Upload files
  - `downloadFiles(instanceId: string, remotePath: string, localPath: string): Promise<DownloadResult>` - Download changed files
  - `execute(instanceId: string, command: string, options?: ExecuteOptions): Promise<ExecutionResult>` - Execute command
  - `isRunning(instanceId: string): Promise<boolean>` - Check if sandbox is running
  - `reconnect(instanceId: string): Promise<SandboxInstance | null>` - Reconnect to existing sandbox
  - `extendTimeout(instanceId: string, additionalMinutes: number): Promise<boolean>` - Extend timeout

- `SandboxConfig` interface with E2B-specific fields:
  - `sessionId: string`
  - `apiKey?: string`
  - `template: string` (e.g., 'anthropic-claude-code')
  - `timeoutMs: number`
  - `metadata?: Record<string, string>`

- `SandboxInstance` interface:
  - `id: string` - Sandbox identifier
  - `provider: string` - Provider name
  - `createdAt: Date`
  - `metadata?: Record<string, unknown>`

- `ExecuteOptions`, `ExecutionResult`, `UploadResult`, `DownloadResult` types

Reference the ROADMAP.md interface structure and existing types in `file:src/types.ts`.

### 2. Create E2BProvider Class Skeleton

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

Create the provider class structure:

```typescript
import { SandboxProvider, SandboxConfig, SandboxInstance } from './types.js';
import { Sandbox } from 'e2b';
import type { Logger } from '../../logger.js';

export class E2BProvider implements SandboxProvider {
  readonly name = 'e2b';
  readonly version = '1.0.0';
  
  private sandboxes: Map<string, Sandbox> = new Map();
  private logger: Logger;
  
  constructor(logger: Logger) {
    this.logger = logger;
  }
  
  // Implement all interface methods (initially as stubs)
}
```

### 3. Move createSandbox Logic to E2BProvider.create()

Migrate the sandbox creation logic from `file:src/e2b/sandbox-manager.ts` lines 128-188:

- Move API key validation logic
- Move `Sandbox.create()` call with configuration
- Move sandbox tracking to internal `sandboxes` Map
- Preserve error handling for authentication, quota, and network errors
- Keep security features: metadata sanitization
- Return `SandboxInstance` instead of raw Sandbox object

The `SandboxManager` should call `provider.create()` and track the returned instance.

### 4. Move terminateSandbox Logic to E2BProvider.destroy()

Migrate termination logic from `file:src/e2b/sandbox-manager.ts` lines 332-395:

- Move `sandbox.kill()` call with timeout wrapper
- Move cleanup from internal `sandboxes` Map
- Preserve error handling and best-effort cleanup
- Return success/error status
- Keep logging for termination events

The `SandboxManager` should call `provider.destroy()` and update session tracking.

### 5. Move Reconnection Logic to E2BProvider.reconnect()

Migrate reconnection from `file:src/e2b/sandbox-manager.ts` lines 419-462:

- Move `Sandbox.connect()` call
- Move API key validation
- Track reconnected sandbox in internal Map
- Preserve error handling for 404, authentication, timeout errors
- Return `SandboxInstance | null`

### 6. Move File Upload Logic to E2BProvider.uploadFiles()

Migrate upload logic from `file:src/e2b/file-sync.ts` lines 285-343 and 353-436:

- Move simple upload for small files (< 50MB)
- Move resumable upload with checkpoints for large files
- Move tarball extraction in sandbox
- Preserve security: remote path validation (lines 103-139)
- Keep timeout wrappers for upload operations
- Return `UploadResult` with metadata

The file sync module should call `provider.uploadFiles()` with the tarball path.

### 7. Move File Download Logic to E2BProvider.downloadFiles()

Migrate download logic from `file:src/e2b/file-sync.ts` lines 446-643:

- Move git status checking for changed files
- Move tarball creation in sandbox
- Move base64 encoding/decoding for binary safety
- Move tarball download and extraction
- Preserve security: path validation, gzip verification
- Keep error handling for tar command failures
- Return `DownloadResult` with file count and size

### 8. Move Health Monitoring to E2BProvider.isRunning()

Migrate health check from `file:src/e2b/sandbox-manager.ts` lines 197-260:

- Move `sandbox.isRunning()` call with timeout wrapper
- Move reconnection attempt if sandbox not in cache
- Return boolean health status
- Preserve 30-second timeout for health checks

The `SandboxManager` should call `provider.isRunning()` for health monitoring.

### 9. Move Timeout Extension to E2BProvider.extendTimeout()

Migrate timeout extension from `file:src/e2b/sandbox-manager.ts` lines 507-543:

- Move `sandbox.setTimeout()` call
- Move timeout validation (max 24 hours)
- Keep timeout wrapper for the API call
- Return success boolean

### 10. Refactor SandboxManager to Use E2BProvider

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

Transform `SandboxManager` into a provider orchestrator:

- Add `private provider: SandboxProvider` field
- Accept provider in constructor: `constructor(logger: Logger, provider: SandboxProvider, config?: E2BSessionConfig)`
- Update `createSandbox()` to call `provider.create()` and track session metadata
- Update `terminateSandbox()` to call `provider.destroy()` and cleanup session tracking
- Update `monitorSandboxHealth()` to call `provider.isRunning()`
- Update `getOrReconnectSandbox()` to call `provider.reconnect()`
- Update `extendTimeout()` to call `provider.extendTimeout()`
- Keep high-level orchestration: timeout enforcement (lines 268-324), cost calculation (lines 484-489), session tracking (sandboxStartTimes, timeoutWarningsIssued)
- Preserve security functions: `sanitizePrompt()`, `validateFilePath()` (keep as static utilities)

### 11. Update File Sync to Use Provider

**File:** `file:src/e2b/file-sync.ts`

Refactor file sync functions to accept provider:

- Update `uploadToSandbox()` signature: `uploadToSandbox(tarballPath: string, provider: SandboxProvider, instanceId: string, remotePath: string)`
- Update `downloadChangedFiles()` signature: `downloadChangedFiles(provider: SandboxProvider, instanceId: string, remotePath: string, localPath: string)`
- Call `provider.uploadFiles()` and `provider.downloadFiles()` instead of direct E2B SDK calls
- Keep helper functions: `createTarball()`, `verifyUpload()`, `scanForCredentials()`, `buildExclusionList()`, etc.
- Preserve all security validations: `validateRemotePath()`, `validatePath()`

### 12. Create Provider Factory Pattern

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

Create provider registry and factory:

```typescript
export class ProviderFactory {
  private static providers = new Map<string, () => SandboxProvider>();
  
  static register(name: string, factory: () => SandboxProvider): void
  static create(name: string, logger: Logger): SandboxProvider
  static getAvailableProviders(): string[]
}
```

Register E2BProvider:
```typescript
ProviderFactory.register('e2b', () => new E2BProvider(logger));
```

### 13. Update Tests for E2BProvider

**File:** `file:tests/e2b/providers/e2b-provider.test.ts` (new)

Create comprehensive tests for E2BProvider:

- Test all interface methods: `create()`, `destroy()`, `uploadFiles()`, `downloadFiles()`, `isRunning()`, `reconnect()`, `extendTimeout()`
- Mock E2B SDK (`Sandbox.create`, `Sandbox.connect`)
- Test error handling: authentication, quota, network errors
- Test security: path validation, prompt sanitization
- Verify sandbox tracking in internal Map
- Test concurrent operations

**File:** `file:tests/e2b/sandbox-manager.test.ts`

Update existing tests to use provider:

- Mock `E2BProvider` instead of E2B SDK directly
- Update test setup to inject provider into `SandboxManager`
- Verify `SandboxManager` calls provider methods correctly
- Keep all existing test cases (82 tests should still pass)
- Add tests for provider orchestration logic

**File:** `file:tests/e2b/file-sync.test.ts`

Update file sync tests:

- Mock provider instead of E2B SDK
- Update function signatures to pass provider
- Keep all existing test cases
- Verify provider methods are called with correct parameters

### 14. Update Integration Tests

**Files:** `file:tests/e2b/integration.test.ts`, `file:tests/e2b/e2e-workflow.test.ts`

Update integration tests to use provider architecture:

- Create `E2BProvider` instance for tests
- Pass provider to `SandboxManager` and file sync functions
- Verify end-to-end workflows still work
- Keep all existing test scenarios

### 15. Create Provider Index and Exports

**File:** `file:src/e2b/providers/index.ts` (new)

Export provider types and classes:

```typescript
export * from './types.js';
export * from './e2b-provider.js';
export * from './factory.js';
```

### 16. Update Main Exports

**File:** `file:src/e2b/index.ts` (new or update existing)

Export provider module:

```typescript
export * from './sandbox-manager.js';
export * from './file-sync.js';
export * from './providers/index.js';
```

### 17. Verify Backward Compatibility

Test that existing code using `SandboxManager` still works:

- CLI commands: `sandbox-run`, `sandbox-logs`, `sandbox-download`, `sandbox-kill`
- Verify no breaking changes in public APIs
- Ensure all 441 existing tests pass
- Check that E2B sessions work identically to v1.0

### 18. Update Documentation

**File:** `file:docs/E2B_GUIDE.md`

Add section on provider architecture:

- Explain the provider abstraction
- Document how to use `E2BProvider` directly
- Show provider factory usage
- Note that this is preparation for v1.5 multi-provider support

### 19. Clean Up Dead Code

Remove duplicated logic from old locations:

- Remove E2B-specific code from `SandboxManager` that's now in `E2BProvider`
- Keep only orchestration logic in `SandboxManager`
- Remove direct E2B SDK imports from file-sync (use provider instead)
- Update imports throughout codebase

### 20. Final Verification

Run complete test suite:

- All 441+ tests should pass
- No behavior changes for end users
- Code coverage should remain ≥85%
- Security features preserved (shell injection prevention, path validation)
- Performance should be equivalent to v1.0

## Architecture Diagram

```mermaid
sequenceDiagram
    participant CLI as CLI Command
    participant SM as SandboxManager
    participant EP as E2BProvider
    participant E2B as E2B SDK
    participant FS as FileSync

    CLI->>SM: createSandbox(sessionId)
    SM->>EP: create(config)
    EP->>E2B: Sandbox.create(template, opts)
    E2B-->>EP: sandbox instance
    EP->>EP: Track in sandboxes Map
    EP-->>SM: SandboxInstance
    SM->>SM: Track session metadata
    SM-->>CLI: { sandbox, sandboxId, status }

    CLI->>FS: uploadToSandbox(tarball, provider, instanceId)
    FS->>EP: uploadFiles(instanceId, tarballPath, remotePath)
    EP->>E2B: sandbox.files.write()
    EP->>E2B: sandbox.commands.run(tar extract)
    EP-->>FS: UploadResult
    FS-->>CLI: success

    CLI->>SM: monitorSandboxHealth(sandboxId)
    SM->>EP: isRunning(instanceId)
    EP->>E2B: sandbox.isRunning()
    E2B-->>EP: boolean
    EP-->>SM: boolean
    SM-->>CLI: SandboxHealthCheck

    CLI->>SM: terminateSandbox(sandboxId)
    SM->>EP: destroy(instanceId)
    EP->>E2B: sandbox.kill()
    EP->>EP: Remove from sandboxes Map
    EP-->>SM: void
    SM->>SM: Cleanup session tracking
    SM-->>CLI: SandboxTerminationResult
```

## Key Design Decisions

1. **Provider owns sandbox instances**: The `E2BProvider` maintains the `sandboxes` Map, not `SandboxManager`. This ensures provider encapsulation.

2. **SandboxManager orchestrates**: High-level concerns (timeout enforcement, cost tracking, session metadata) stay in `SandboxManager`.

3. **File sync uses provider**: File operations go through provider interface, not direct E2B SDK calls.

4. **Security preserved**: All validation functions (`sanitizePrompt`, `validateFilePath`, `validateRemotePath`) remain and are used by both provider and manager.

5. **Backward compatibility**: Existing code using `SandboxManager` continues to work by injecting `E2BProvider` as default.

6. **Incremental migration**: Each method is moved independently, allowing tests to pass at each step.

---

Execution Information

Branch: main
Commit: 136df60

---

💡 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]
#5 - feat(v1.0): E2B Sandbox Integration - Autonomous Claude Code Execution [merged]
#11 - feat: Use anthropic-claude-code E2B template with fallback installation [merged]
#18 - test: Add comprehensive E2E tests for E2B workflow [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!