[v2.6+] Implement provider auto-selection heuristics

[frankbria]

Overview

Automatically select the best sandbox provider based on task characteristics when no explicit provider is specified.

Selection Criteria

Task Duration

• < 5 minutes: Native/Docker (free, instant)
• 5-30 minutes: Native/Docker or E2B

• 30 minutes: E2B (more reliable for long tasks)

Resource Requirements

• Low CPU/memory: Native
• Medium: Docker
• High/GPU: E2B (dedicated VM)

Network Requirements

• No external access: Native (most secure)
• External APIs: Docker or E2B
• Full network: E2B

User Preference

• Cost-conscious: Native > Docker > E2B
• Speed-focused: E2B (parallel VM)
• Security-focused: Native (OS-level isolation)

Implementation

// src/e2b/providers/auto-select.ts

export interface TaskHints {
  estimatedDuration?: number;  // minutes
  requiresNetwork?: boolean;
  requiresGpu?: boolean;
  resourceIntensity?: 'low' | 'medium' | 'high';
  costSensitive?: boolean;
}

export function selectProvider(
  hints: TaskHints,
  available: string[]
): string {
  // Quick tasks → prefer free providers
  if (hints.estimatedDuration && hints.estimatedDuration < 5) {
    if (available.includes('native')) return 'native';
    if (available.includes('docker')) return 'docker';
  }
  
  // Long tasks → prefer E2B for reliability
  if (hints.estimatedDuration && hints.estimatedDuration > 30) {
    if (available.includes('e2b')) return 'e2b';
  }
  
  // Cost-sensitive → prefer free options
  if (hints.costSensitive) {
    if (available.includes('native')) return 'native';
    if (available.includes('docker')) return 'docker';
  }
  
  // Default: use E2B if available
  if (available.includes('e2b')) return 'e2b';
  
  // Fallback to first available
  return available[0] || 'e2b';
}

CLI Integration

# Let parallel-cc decide
parallel-cc sandbox-run --repo . --prompt "Quick fix" --auto-provider

# Provide hints
parallel-cc sandbox-run --repo . --prompt "Long task" \
  --estimated-duration 45 \
  --cost-sensitive

Files to Create

• `src/e2b/providers/auto-select.ts`
• `tests/e2b/auto-select.test.ts`

Acceptance Criteria

• Auto-selection chooses appropriate provider
• User hints influence selection
• Fallback chain works when preferred unavailable
• Clear logging of selection reasoning
• Unit tests cover various scenarios

Dependencies

• Depends on [v2.5] Add provider registry and factory pattern #32 (Provider registry)
• Depends on [v2.5] Implement NativeProvider using srt CLI #33, [v2.5+] Implement DockerProvider #34 (Native/Docker providers)

[traycerai]

Plan

Observations

The codebase currently has E2B-only sandbox integration (v1.0) with SandboxManager handling E2B-specific operations. The multi-provider architecture outlined in file:SANDBOX_INTEGRATION_PLAN.md is planned for v1.5, but not yet implemented. Issue #36 targets v2.6+ and depends on the provider registry (#32) and native/docker providers (#33, #34) which are not yet present. The CLI uses commander.js with .option() for flags, and tests use vitest with comprehensive mocking patterns.

Approach

The implementation will create a provider auto-selection system that intelligently chooses between native, docker, and E2B providers based on task characteristics. The approach follows the existing codebase patterns: creating the auto-selection logic in file:src/e2b/providers/auto-select.ts, integrating it with the future provider registry, adding CLI flags to file:src/cli.ts using commander.js patterns, and writing comprehensive tests following the vitest patterns seen in file:tests/e2b/sandbox-manager.test.ts. The selection logic will prioritize cost-effectiveness for short tasks, reliability for long tasks, and respect user preferences.

Implementation Steps

1. Create Provider Auto-Selection Module

File: file:src/e2b/providers/auto-select.ts

Create the core auto-selection logic with the following components:

• Define TaskHints interface matching the specification:

  • estimatedDuration?: number (in minutes)
  • requiresNetwork?: boolean
  • requiresGpu?: boolean
  • resourceIntensity?: 'low' | 'medium' | 'high'
  • costSensitive?: boolean

• Implement selectProvider(hints: TaskHints, available: string[]): string function with selection logic:

  • Quick tasks (< 5 min): Prefer native → docker → e2b
  • Long tasks (> 30 min): Prefer e2b for reliability
  • Cost-sensitive: Prefer native → docker → e2b
  • GPU required: Force e2b
  • Network required: Prefer docker or e2b over native
  • Default fallback: Use e2b if available, otherwise first available provider

• Add getSelectionReasoning(hints: TaskHints, selected: string): string function to return human-readable explanation of why a provider was chosen

• Export helper function getAvailableProviders(): Promise<string[]> that checks:

  • Native: Platform is macOS/Linux (not Windows)
  • Docker: Docker daemon is running
  • E2B: E2B_API_KEY environment variable is set

2. Extend Type Definitions

File: file:src/types.ts

Add new types for auto-selection:

• Add TaskHints interface (re-export from auto-select module)
• Add ProviderSelectionResult interface:
  • provider: string
  • reasoning: string
  • hints: TaskHints
  • availableProviders: string[]

3. Integrate with CLI

File: file:src/cli.ts

Modify the sandbox run command (around line 1495) to add new options:

• Add .option('--auto-provider', 'Automatically select best provider based on task characteristics')
• Add .option('--estimated-duration <minutes>', 'Estimated task duration in minutes (helps auto-selection)', parseFloat)
• Add .option('--cost-sensitive', 'Prefer free providers (native/docker) over paid (e2b)')
• Add .option('--requires-network', 'Task requires external network access')
• Add .option('--requires-gpu', 'Task requires GPU acceleration')
• Add .option('--resource-intensity <level>', 'Resource requirements: low, medium, high')

Update SandboxRunOptions interface to include new fields:

• autoProvider?: boolean
• estimatedDuration?: number
• costSensitive?: boolean
• requiresNetwork?: boolean
• requiresGpu?: boolean
• resourceIntensity?: 'low' | 'medium' | 'high'

In handleSandboxRun function (around line 1560):

• Before creating SandboxManager, check if options.autoProvider is true
• If true, build TaskHints from CLI options
• Call getAvailableProviders() to get available providers
• Call selectProvider(hints, available) to get selected provider
• Log selection reasoning using getSelectionReasoning()
• Use selected provider to determine which sandbox implementation to use
• If --json flag is set, include selection details in JSON output

4. Add Provider Detection Utilities

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

Create platform and provider detection utilities:

• isPlatformSupported(provider: string): boolean - Check if provider is supported on current OS
• isDockerAvailable(): Promise<boolean> - Check if Docker daemon is running
• isE2BConfigured(): boolean - Check if E2B_API_KEY is set
• getNativeCapabilities(): Promise<{ bubblewrap: boolean, seatbelt: boolean }> - Check native sandbox capabilities

5. Create Comprehensive Tests

File: file:tests/e2b/auto-select.test.ts

Following the patterns from file:tests/e2b/sandbox-manager.test.ts:

• Mock platform detection and provider availability checks

• Test selection logic for various scenarios:

  • Quick tasks (< 5 min) → native/docker preferred
  • Long tasks (> 30 min) → e2b preferred
  • Cost-sensitive → free providers preferred
  • GPU required → e2b forced
  • Network required → docker/e2b preferred
  • Multiple constraints → correct priority
  • No providers available → error handling
  • Fallback chain when preferred unavailable

• Test getSelectionReasoning() returns clear explanations

• Test getAvailableProviders() correctly detects available providers

• Test edge cases: empty hints, invalid hints, conflicting hints

File: file:tests/e2b/providers/detection.test.ts

Test provider detection utilities:

• Platform detection on different OS
• Docker availability checks
• E2B configuration checks
• Native sandbox capability detection

6. Update Documentation

File: file:README.md

Add section on provider auto-selection:

• Explain --auto-provider flag
• Document task hint flags
• Provide examples of auto-selection usage
• Explain selection criteria

File: file:SANDBOX_INTEGRATION_PLAN.md

Update the multi-provider architecture section:

• Add auto-selection as a feature
• Document selection heuristics
• Add decision tree diagram

7. Add Logging and Observability

In file:src/e2b/providers/auto-select.ts:

• Log selection decision with reasoning at INFO level
• Log available providers at DEBUG level
• Log task hints at DEBUG level
• Warn when no providers are available
• Warn when selected provider may not be optimal for task

8. Integration Points

The implementation should be designed to integrate with future provider registry:

• Use string provider names that match registry keys
• Design selectProvider() to accept provider list from registry
• Make selection logic extensible for new providers (Daytona, Cloudflare)
• Ensure backward compatibility when provider registry is implemented

Selection Logic Flow

flowchart TD
    Start[Start Auto-Selection] --> CheckHints{Task Hints Provided?}
    CheckHints -->|No| UseDefault[Use Default: E2B if available]
    CheckHints -->|Yes| CheckGPU{Requires GPU?}
    
    CheckGPU -->|Yes| ForceE2B[Force E2B]
    CheckGPU -->|No| CheckDuration{Estimated Duration}
    
    CheckDuration -->|< 5 min| PreferFree[Prefer Free: Native → Docker]
    CheckDuration -->|> 30 min| PreferE2B[Prefer E2B for reliability]
    CheckDuration -->|5-30 min| CheckCost{Cost Sensitive?}
    
    CheckCost -->|Yes| PreferFree
    CheckCost -->|No| CheckNetwork{Requires Network?}
    
    CheckNetwork -->|Yes| PreferDocker[Prefer Docker/E2B]
    CheckNetwork -->|No| CheckResources{Resource Intensity}
    
    CheckResources -->|Low| PreferNative[Prefer Native]
    CheckResources -->|Medium| PreferDocker
    CheckResources -->|High| PreferE2B
    
    PreferFree --> CheckAvailable{Provider Available?}
    PreferE2B --> CheckAvailable
    PreferDocker --> CheckAvailable
    PreferNative --> CheckAvailable
    ForceE2B --> CheckAvailable
    UseDefault --> CheckAvailable
    
    CheckAvailable -->|Yes| Selected[Return Selected Provider]
    CheckAvailable -->|No| Fallback[Try Next in Chain]
    Fallback --> CheckAvailable
    
    Selected --> End[Log Reasoning & Return]

Loading

Acceptance Criteria Mapping

• ✅ Auto-selection chooses appropriate provider: Implemented in selectProvider() with comprehensive logic
• ✅ User hints influence selection: CLI flags map to TaskHints interface
• ✅ Fallback chain works: Selection logic tries alternatives when preferred unavailable
• ✅ Clear logging of selection reasoning: getSelectionReasoning() provides explanations
• ✅ Unit tests cover various scenarios: Comprehensive test suite in file:tests/e2b/auto-select.test.ts

Dependencies and Blockers

This implementation depends on:

• Issue [v2.5] Add provider registry and factory pattern #32: Provider registry - The auto-selection logic assumes a registry exists to query available providers
• Issue [v2.5] Implement NativeProvider using srt CLI #33: Native provider - Required for native sandbox selection
• Issue [v2.5+] Implement DockerProvider #34: Docker provider - Required for docker sandbox selection

Recommendation: Implement this feature after #32, #33, and #34 are completed, or create stub implementations for testing purposes.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has E2B-only sandbox integration (v1.0) with `SandboxManager` handling E2B-specific operations. The multi-provider architecture outlined in `file:SANDBOX_INTEGRATION_PLAN.md` is planned for v1.5, but not yet implemented. Issue #36 targets v2.6+ and depends on the provider registry (#32) and native/docker providers (#33, #34) which are not yet present. The CLI uses commander.js with `.option()` for flags, and tests use vitest with comprehensive mocking patterns.

## Approach

The implementation will create a provider auto-selection system that intelligently chooses between native, docker, and E2B providers based on task characteristics. The approach follows the existing codebase patterns: creating the auto-selection logic in `file:src/e2b/providers/auto-select.ts`, integrating it with the future provider registry, adding CLI flags to `file:src/cli.ts` using commander.js patterns, and writing comprehensive tests following the vitest patterns seen in `file:tests/e2b/sandbox-manager.test.ts`. The selection logic will prioritize cost-effectiveness for short tasks, reliability for long tasks, and respect user preferences.

## Implementation Steps

### 1. Create Provider Auto-Selection Module

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

Create the core auto-selection logic with the following components:

- Define `TaskHints` interface matching the specification:
  - `estimatedDuration?: number` (in minutes)
  - `requiresNetwork?: boolean`
  - `requiresGpu?: boolean`
  - `resourceIntensity?: 'low' | 'medium' | 'high'`
  - `costSensitive?: boolean`

- Implement `selectProvider(hints: TaskHints, available: string[]): string` function with selection logic:
  - **Quick tasks (< 5 min)**: Prefer `native` → `docker` → `e2b`
  - **Long tasks (> 30 min)**: Prefer `e2b` for reliability
  - **Cost-sensitive**: Prefer `native` → `docker` → `e2b`
  - **GPU required**: Force `e2b`
  - **Network required**: Prefer `docker` or `e2b` over `native`
  - **Default fallback**: Use `e2b` if available, otherwise first available provider

- Add `getSelectionReasoning(hints: TaskHints, selected: string): string` function to return human-readable explanation of why a provider was chosen

- Export helper function `getAvailableProviders(): Promise<string[]>` that checks:
  - Native: Platform is macOS/Linux (not Windows)
  - Docker: Docker daemon is running
  - E2B: `E2B_API_KEY` environment variable is set

### 2. Extend Type Definitions

**File: `file:src/types.ts`**

Add new types for auto-selection:

- Add `TaskHints` interface (re-export from auto-select module)
- Add `ProviderSelectionResult` interface:
  - `provider: string`
  - `reasoning: string`
  - `hints: TaskHints`
  - `availableProviders: string[]`

### 3. Integrate with CLI

**File: `file:src/cli.ts`**

Modify the `sandbox run` command (around line 1495) to add new options:

- Add `.option('--auto-provider', 'Automatically select best provider based on task characteristics')`
- Add `.option('--estimated-duration <minutes>', 'Estimated task duration in minutes (helps auto-selection)', parseFloat)`
- Add `.option('--cost-sensitive', 'Prefer free providers (native/docker) over paid (e2b)')`
- Add `.option('--requires-network', 'Task requires external network access')`
- Add `.option('--requires-gpu', 'Task requires GPU acceleration')`
- Add `.option('--resource-intensity <level>', 'Resource requirements: low, medium, high')`

Update `SandboxRunOptions` interface to include new fields:
- `autoProvider?: boolean`
- `estimatedDuration?: number`
- `costSensitive?: boolean`
- `requiresNetwork?: boolean`
- `requiresGpu?: boolean`
- `resourceIntensity?: 'low' | 'medium' | 'high'`

In `handleSandboxRun` function (around line 1560):

- Before creating `SandboxManager`, check if `options.autoProvider` is true
- If true, build `TaskHints` from CLI options
- Call `getAvailableProviders()` to get available providers
- Call `selectProvider(hints, available)` to get selected provider
- Log selection reasoning using `getSelectionReasoning()`
- Use selected provider to determine which sandbox implementation to use
- If `--json` flag is set, include selection details in JSON output

### 4. Add Provider Detection Utilities

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

Create platform and provider detection utilities:

- `isPlatformSupported(provider: string): boolean` - Check if provider is supported on current OS
- `isDockerAvailable(): Promise<boolean>` - Check if Docker daemon is running
- `isE2BConfigured(): boolean` - Check if E2B_API_KEY is set
- `getNativeCapabilities(): Promise<{ bubblewrap: boolean, seatbelt: boolean }>` - Check native sandbox capabilities

### 5. Create Comprehensive Tests

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

Following the patterns from `file:tests/e2b/sandbox-manager.test.ts`:

- Mock platform detection and provider availability checks
- Test selection logic for various scenarios:
  - Quick tasks (< 5 min) → native/docker preferred
  - Long tasks (> 30 min) → e2b preferred
  - Cost-sensitive → free providers preferred
  - GPU required → e2b forced
  - Network required → docker/e2b preferred
  - Multiple constraints → correct priority
  - No providers available → error handling
  - Fallback chain when preferred unavailable

- Test `getSelectionReasoning()` returns clear explanations
- Test `getAvailableProviders()` correctly detects available providers
- Test edge cases: empty hints, invalid hints, conflicting hints

**File: `file:tests/e2b/providers/detection.test.ts`**

Test provider detection utilities:
- Platform detection on different OS
- Docker availability checks
- E2B configuration checks
- Native sandbox capability detection

### 6. Update Documentation

**File: `file:README.md`**

Add section on provider auto-selection:
- Explain `--auto-provider` flag
- Document task hint flags
- Provide examples of auto-selection usage
- Explain selection criteria

**File: `file:SANDBOX_INTEGRATION_PLAN.md`**

Update the multi-provider architecture section:
- Add auto-selection as a feature
- Document selection heuristics
- Add decision tree diagram

### 7. Add Logging and Observability

In `file:src/e2b/providers/auto-select.ts`:

- Log selection decision with reasoning at INFO level
- Log available providers at DEBUG level
- Log task hints at DEBUG level
- Warn when no providers are available
- Warn when selected provider may not be optimal for task

### 8. Integration Points

The implementation should be designed to integrate with future provider registry:

- Use string provider names that match registry keys
- Design `selectProvider()` to accept provider list from registry
- Make selection logic extensible for new providers (Daytona, Cloudflare)
- Ensure backward compatibility when provider registry is implemented

## Selection Logic Flow

```mermaid
flowchart TD
    Start[Start Auto-Selection] --> CheckHints{Task Hints Provided?}
    CheckHints -->|No| UseDefault[Use Default: E2B if available]
    CheckHints -->|Yes| CheckGPU{Requires GPU?}
    
    CheckGPU -->|Yes| ForceE2B[Force E2B]
    CheckGPU -->|No| CheckDuration{Estimated Duration}
    
    CheckDuration -->|< 5 min| PreferFree[Prefer Free: Native → Docker]
    CheckDuration -->|> 30 min| PreferE2B[Prefer E2B for reliability]
    CheckDuration -->|5-30 min| CheckCost{Cost Sensitive?}
    
    CheckCost -->|Yes| PreferFree
    CheckCost -->|No| CheckNetwork{Requires Network?}
    
    CheckNetwork -->|Yes| PreferDocker[Prefer Docker/E2B]
    CheckNetwork -->|No| CheckResources{Resource Intensity}
    
    CheckResources -->|Low| PreferNative[Prefer Native]
    CheckResources -->|Medium| PreferDocker
    CheckResources -->|High| PreferE2B
    
    PreferFree --> CheckAvailable{Provider Available?}
    PreferE2B --> CheckAvailable
    PreferDocker --> CheckAvailable
    PreferNative --> CheckAvailable
    ForceE2B --> CheckAvailable
    UseDefault --> CheckAvailable
    
    CheckAvailable -->|Yes| Selected[Return Selected Provider]
    CheckAvailable -->|No| Fallback[Try Next in Chain]
    Fallback --> CheckAvailable
    
    Selected --> End[Log Reasoning & Return]
```

## Acceptance Criteria Mapping

- ✅ **Auto-selection chooses appropriate provider**: Implemented in `selectProvider()` with comprehensive logic
- ✅ **User hints influence selection**: CLI flags map to `TaskHints` interface
- ✅ **Fallback chain works**: Selection logic tries alternatives when preferred unavailable
- ✅ **Clear logging of selection reasoning**: `getSelectionReasoning()` provides explanations
- ✅ **Unit tests cover various scenarios**: Comprehensive test suite in `file:tests/e2b/auto-select.test.ts`

## Dependencies and Blockers

This implementation depends on:
- **Issue #32**: Provider registry - The auto-selection logic assumes a registry exists to query available providers
- **Issue #33**: Native provider - Required for native sandbox selection
- **Issue #34**: Docker provider - Required for docker sandbox selection

**Recommendation**: Implement this feature after #32, #33, and #34 are completed, or create stub implementations for testing purposes.

---

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]
#11 - feat: Use anthropic-claude-code E2B template with fallback installation [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.

New Plan

Observations

The codebase currently has E2B-only sandbox integration (v1.0) with SandboxManager handling E2B-specific operations. The multi-provider architecture outlined in file:SANDBOX_INTEGRATION_PLAN.md is planned for v1.5, but not yet implemented. Issue #36 targets v2.6+ and depends on the provider registry (#32) and native/docker providers (#33, #34) which are not yet present. The CLI uses commander.js with .option() for flags, and tests use vitest with comprehensive mocking patterns.

Approach

The implementation will create a provider auto-selection system that intelligently chooses between native, docker, and E2B providers based on task characteristics. The approach follows the existing codebase patterns: creating the auto-selection logic in file:src/e2b/providers/auto-select.ts, integrating it with the future provider registry, adding CLI flags to file:src/cli.ts using commander.js patterns, and writing comprehensive tests following the vitest patterns seen in file:tests/e2b/sandbox-manager.test.ts. The selection logic will prioritize cost-effectiveness for short tasks, reliability for long tasks, and respect user preferences.

Implementation Steps

1. Create Provider Auto-Selection Module

File: file:src/e2b/providers/auto-select.ts

Create the core auto-selection logic with the following components:

• Define TaskHints interface matching the specification:

  • estimatedDuration?: number (in minutes)
  • requiresNetwork?: boolean
  • requiresGpu?: boolean
  • resourceIntensity?: 'low' | 'medium' | 'high'
  • costSensitive?: boolean

• Implement selectProvider(hints: TaskHints, available: string[]): string function with selection logic:

  • Quick tasks (< 5 min): Prefer native → docker → e2b
  • Long tasks (> 30 min): Prefer e2b for reliability
  • Cost-sensitive: Prefer native → docker → e2b
  • GPU required: Force e2b
  • Network required: Prefer docker or e2b over native
  • Default fallback: Use e2b if available, otherwise first available provider

• Add getSelectionReasoning(hints: TaskHints, selected: string): string function to return human-readable explanation of why a provider was chosen

• Export helper function getAvailableProviders(): Promise<string[]> that checks:

  • Native: Platform is macOS/Linux (not Windows)
  • Docker: Docker daemon is running
  • E2B: E2B_API_KEY environment variable is set

2. Extend Type Definitions

File: file:src/types.ts

Add new types for auto-selection:

• Add TaskHints interface (re-export from auto-select module)
• Add ProviderSelectionResult interface:
  • provider: string
  • reasoning: string
  • hints: TaskHints
  • availableProviders: string[]

3. Integrate with CLI

File: file:src/cli.ts

Modify the sandbox run command (around line 1495) to add new options:

• Add .option('--auto-provider', 'Automatically select best provider based on task characteristics')
• Add .option('--estimated-duration <minutes>', 'Estimated task duration in minutes (helps auto-selection)', parseFloat)
• Add .option('--cost-sensitive', 'Prefer free providers (native/docker) over paid (e2b)')
• Add .option('--requires-network', 'Task requires external network access')
• Add .option('--requires-gpu', 'Task requires GPU acceleration')
• Add .option('--resource-intensity <level>', 'Resource requirements: low, medium, high')

Update SandboxRunOptions interface to include new fields:

• autoProvider?: boolean
• estimatedDuration?: number
• costSensitive?: boolean
• requiresNetwork?: boolean
• requiresGpu?: boolean
• resourceIntensity?: 'low' | 'medium' | 'high'

In handleSandboxRun function (around line 1560):

• Before creating SandboxManager, check if options.autoProvider is true
• If true, build TaskHints from CLI options
• Call getAvailableProviders() to get available providers
• Call selectProvider(hints, available) to get selected provider
• Log selection reasoning using getSelectionReasoning()
• Use selected provider to determine which sandbox implementation to use
• If --json flag is set, include selection details in JSON output

4. Add Provider Detection Utilities

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

Create platform and provider detection utilities:

• isPlatformSupported(provider: string): boolean - Check if provider is supported on current OS
• isDockerAvailable(): Promise<boolean> - Check if Docker daemon is running
• isE2BConfigured(): boolean - Check if E2B_API_KEY is set
• getNativeCapabilities(): Promise<{ bubblewrap: boolean, seatbelt: boolean }> - Check native sandbox capabilities

5. Create Comprehensive Tests

File: file:tests/e2b/auto-select.test.ts

Following the patterns from file:tests/e2b/sandbox-manager.test.ts:

• Mock platform detection and provider availability checks

• Test selection logic for various scenarios:

  • Quick tasks (< 5 min) → native/docker preferred
  • Long tasks (> 30 min) → e2b preferred
  • Cost-sensitive → free providers preferred
  • GPU required → e2b forced
  • Network required → docker/e2b preferred
  • Multiple constraints → correct priority
  • No providers available → error handling
  • Fallback chain when preferred unavailable

• Test getSelectionReasoning() returns clear explanations

• Test getAvailableProviders() correctly detects available providers

• Test edge cases: empty hints, invalid hints, conflicting hints

File: file:tests/e2b/providers/detection.test.ts

Test provider detection utilities:

• Platform detection on different OS
• Docker availability checks
• E2B configuration checks
• Native sandbox capability detection

6. Update Documentation

File: file:README.md

Add section on provider auto-selection:

• Explain --auto-provider flag
• Document task hint flags
• Provide examples of auto-selection usage
• Explain selection criteria

File: file:SANDBOX_INTEGRATION_PLAN.md

Update the multi-provider architecture section:

• Add auto-selection as a feature
• Document selection heuristics
• Add decision tree diagram

7. Add Logging and Observability

In file:src/e2b/providers/auto-select.ts:

• Log selection decision with reasoning at INFO level
• Log available providers at DEBUG level
• Log task hints at DEBUG level
• Warn when no providers are available
• Warn when selected provider may not be optimal for task

8. Integration Points

The implementation should be designed to integrate with future provider registry:

• Use string provider names that match registry keys
• Design selectProvider() to accept provider list from registry
• Make selection logic extensible for new providers (Daytona, Cloudflare)
• Ensure backward compatibility when provider registry is implemented

Selection Logic Flow

flowchart TD
    Start[Start Auto-Selection] --> CheckHints{Task Hints Provided?}
    CheckHints -->|No| UseDefault[Use Default: E2B if available]
    CheckHints -->|Yes| CheckGPU{Requires GPU?}
    
    CheckGPU -->|Yes| ForceE2B[Force E2B]
    CheckGPU -->|No| CheckDuration{Estimated Duration}
    
    CheckDuration -->|< 5 min| PreferFree[Prefer Free: Native → Docker]
    CheckDuration -->|> 30 min| PreferE2B[Prefer E2B for reliability]
    CheckDuration -->|5-30 min| CheckCost{Cost Sensitive?}
    
    CheckCost -->|Yes| PreferFree
    CheckCost -->|No| CheckNetwork{Requires Network?}
    
    CheckNetwork -->|Yes| PreferDocker[Prefer Docker/E2B]
    CheckNetwork -->|No| CheckResources{Resource Intensity}
    
    CheckResources -->|Low| PreferNative[Prefer Native]
    CheckResources -->|Medium| PreferDocker
    CheckResources -->|High| PreferE2B
    
    PreferFree --> CheckAvailable{Provider Available?}
    PreferE2B --> CheckAvailable
    PreferDocker --> CheckAvailable
    PreferNative --> CheckAvailable
    ForceE2B --> CheckAvailable
    UseDefault --> CheckAvailable
    
    CheckAvailable -->|Yes| Selected[Return Selected Provider]
    CheckAvailable -->|No| Fallback[Try Next in Chain]
    Fallback --> CheckAvailable
    
    Selected --> End[Log Reasoning & Return]

Loading

Acceptance Criteria Mapping

• ✅ Auto-selection chooses appropriate provider: Implemented in selectProvider() with comprehensive logic
• ✅ User hints influence selection: CLI flags map to TaskHints interface
• ✅ Fallback chain works: Selection logic tries alternatives when preferred unavailable
• ✅ Clear logging of selection reasoning: getSelectionReasoning() provides explanations
• ✅ Unit tests cover various scenarios: Comprehensive test suite in file:tests/e2b/auto-select.test.ts

Dependencies and Blockers

This implementation depends on:

• Issue [v2.5] Add provider registry and factory pattern #32: Provider registry - The auto-selection logic assumes a registry exists to query available providers
• Issue [v2.5] Implement NativeProvider using srt CLI #33: Native provider - Required for native sandbox selection
• Issue [v2.5+] Implement DockerProvider #34: Docker provider - Required for docker sandbox selection

Recommendation: Implement this feature after #32, #33, and #34 are completed, or create stub implementations for testing purposes.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase currently has E2B-only sandbox integration (v1.0) with `SandboxManager` handling E2B-specific operations. The multi-provider architecture outlined in `file:SANDBOX_INTEGRATION_PLAN.md` is planned for v1.5, but not yet implemented. Issue #36 targets v2.6+ and depends on the provider registry (#32) and native/docker providers (#33, #34) which are not yet present. The CLI uses commander.js with `.option()` for flags, and tests use vitest with comprehensive mocking patterns.

## Approach

The implementation will create a provider auto-selection system that intelligently chooses between native, docker, and E2B providers based on task characteristics. The approach follows the existing codebase patterns: creating the auto-selection logic in `file:src/e2b/providers/auto-select.ts`, integrating it with the future provider registry, adding CLI flags to `file:src/cli.ts` using commander.js patterns, and writing comprehensive tests following the vitest patterns seen in `file:tests/e2b/sandbox-manager.test.ts`. The selection logic will prioritize cost-effectiveness for short tasks, reliability for long tasks, and respect user preferences.

## Implementation Steps

### 1. Create Provider Auto-Selection Module

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

Create the core auto-selection logic with the following components:

- Define `TaskHints` interface matching the specification:
  - `estimatedDuration?: number` (in minutes)
  - `requiresNetwork?: boolean`
  - `requiresGpu?: boolean`
  - `resourceIntensity?: 'low' | 'medium' | 'high'`
  - `costSensitive?: boolean`

- Implement `selectProvider(hints: TaskHints, available: string[]): string` function with selection logic:
  - **Quick tasks (< 5 min)**: Prefer `native` → `docker` → `e2b`
  - **Long tasks (> 30 min)**: Prefer `e2b` for reliability
  - **Cost-sensitive**: Prefer `native` → `docker` → `e2b`
  - **GPU required**: Force `e2b`
  - **Network required**: Prefer `docker` or `e2b` over `native`
  - **Default fallback**: Use `e2b` if available, otherwise first available provider

- Add `getSelectionReasoning(hints: TaskHints, selected: string): string` function to return human-readable explanation of why a provider was chosen

- Export helper function `getAvailableProviders(): Promise<string[]>` that checks:
  - Native: Platform is macOS/Linux (not Windows)
  - Docker: Docker daemon is running
  - E2B: `E2B_API_KEY` environment variable is set

### 2. Extend Type Definitions

**File: `file:src/types.ts`**

Add new types for auto-selection:

- Add `TaskHints` interface (re-export from auto-select module)
- Add `ProviderSelectionResult` interface:
  - `provider: string`
  - `reasoning: string`
  - `hints: TaskHints`
  - `availableProviders: string[]`

### 3. Integrate with CLI

**File: `file:src/cli.ts`**

Modify the `sandbox run` command (around line 1495) to add new options:

- Add `.option('--auto-provider', 'Automatically select best provider based on task characteristics')`
- Add `.option('--estimated-duration <minutes>', 'Estimated task duration in minutes (helps auto-selection)', parseFloat)`
- Add `.option('--cost-sensitive', 'Prefer free providers (native/docker) over paid (e2b)')`
- Add `.option('--requires-network', 'Task requires external network access')`
- Add `.option('--requires-gpu', 'Task requires GPU acceleration')`
- Add `.option('--resource-intensity <level>', 'Resource requirements: low, medium, high')`

Update `SandboxRunOptions` interface to include new fields:
- `autoProvider?: boolean`
- `estimatedDuration?: number`
- `costSensitive?: boolean`
- `requiresNetwork?: boolean`
- `requiresGpu?: boolean`
- `resourceIntensity?: 'low' | 'medium' | 'high'`

In `handleSandboxRun` function (around line 1560):

- Before creating `SandboxManager`, check if `options.autoProvider` is true
- If true, build `TaskHints` from CLI options
- Call `getAvailableProviders()` to get available providers
- Call `selectProvider(hints, available)` to get selected provider
- Log selection reasoning using `getSelectionReasoning()`
- Use selected provider to determine which sandbox implementation to use
- If `--json` flag is set, include selection details in JSON output

### 4. Add Provider Detection Utilities

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

Create platform and provider detection utilities:

- `isPlatformSupported(provider: string): boolean` - Check if provider is supported on current OS
- `isDockerAvailable(): Promise<boolean>` - Check if Docker daemon is running
- `isE2BConfigured(): boolean` - Check if E2B_API_KEY is set
- `getNativeCapabilities(): Promise<{ bubblewrap: boolean, seatbelt: boolean }>` - Check native sandbox capabilities

### 5. Create Comprehensive Tests

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

Following the patterns from `file:tests/e2b/sandbox-manager.test.ts`:

- Mock platform detection and provider availability checks
- Test selection logic for various scenarios:
  - Quick tasks (< 5 min) → native/docker preferred
  - Long tasks (> 30 min) → e2b preferred
  - Cost-sensitive → free providers preferred
  - GPU required → e2b forced
  - Network required → docker/e2b preferred
  - Multiple constraints → correct priority
  - No providers available → error handling
  - Fallback chain when preferred unavailable

- Test `getSelectionReasoning()` returns clear explanations
- Test `getAvailableProviders()` correctly detects available providers
- Test edge cases: empty hints, invalid hints, conflicting hints

**File: `file:tests/e2b/providers/detection.test.ts`**

Test provider detection utilities:
- Platform detection on different OS
- Docker availability checks
- E2B configuration checks
- Native sandbox capability detection

### 6. Update Documentation

**File: `file:README.md`**

Add section on provider auto-selection:
- Explain `--auto-provider` flag
- Document task hint flags
- Provide examples of auto-selection usage
- Explain selection criteria

**File: `file:SANDBOX_INTEGRATION_PLAN.md`**

Update the multi-provider architecture section:
- Add auto-selection as a feature
- Document selection heuristics
- Add decision tree diagram

### 7. Add Logging and Observability

In `file:src/e2b/providers/auto-select.ts`:

- Log selection decision with reasoning at INFO level
- Log available providers at DEBUG level
- Log task hints at DEBUG level
- Warn when no providers are available
- Warn when selected provider may not be optimal for task

### 8. Integration Points

The implementation should be designed to integrate with future provider registry:

- Use string provider names that match registry keys
- Design `selectProvider()` to accept provider list from registry
- Make selection logic extensible for new providers (Daytona, Cloudflare)
- Ensure backward compatibility when provider registry is implemented

## Selection Logic Flow

```mermaid
flowchart TD
    Start[Start Auto-Selection] --> CheckHints{Task Hints Provided?}
    CheckHints -->|No| UseDefault[Use Default: E2B if available]
    CheckHints -->|Yes| CheckGPU{Requires GPU?}
    
    CheckGPU -->|Yes| ForceE2B[Force E2B]
    CheckGPU -->|No| CheckDuration{Estimated Duration}
    
    CheckDuration -->|< 5 min| PreferFree[Prefer Free: Native → Docker]
    CheckDuration -->|> 30 min| PreferE2B[Prefer E2B for reliability]
    CheckDuration -->|5-30 min| CheckCost{Cost Sensitive?}
    
    CheckCost -->|Yes| PreferFree
    CheckCost -->|No| CheckNetwork{Requires Network?}
    
    CheckNetwork -->|Yes| PreferDocker[Prefer Docker/E2B]
    CheckNetwork -->|No| CheckResources{Resource Intensity}
    
    CheckResources -->|Low| PreferNative[Prefer Native]
    CheckResources -->|Medium| PreferDocker
    CheckResources -->|High| PreferE2B
    
    PreferFree --> CheckAvailable{Provider Available?}
    PreferE2B --> CheckAvailable
    PreferDocker --> CheckAvailable
    PreferNative --> CheckAvailable
    ForceE2B --> CheckAvailable
    UseDefault --> CheckAvailable
    
    CheckAvailable -->|Yes| Selected[Return Selected Provider]
    CheckAvailable -->|No| Fallback[Try Next in Chain]
    Fallback --> CheckAvailable
    
    Selected --> End[Log Reasoning & Return]
```

## Acceptance Criteria Mapping

- ✅ **Auto-selection chooses appropriate provider**: Implemented in `selectProvider()` with comprehensive logic
- ✅ **User hints influence selection**: CLI flags map to `TaskHints` interface
- ✅ **Fallback chain works**: Selection logic tries alternatives when preferred unavailable
- ✅ **Clear logging of selection reasoning**: `getSelectionReasoning()` provides explanations
- ✅ **Unit tests cover various scenarios**: Comprehensive test suite in `file:tests/e2b/auto-select.test.ts`

## Dependencies and Blockers

This implementation depends on:
- **Issue #32**: Provider registry - The auto-selection logic assumes a registry exists to query available providers
- **Issue #33**: Native provider - Required for native sandbox selection
- **Issue #34**: Docker provider - Required for docker sandbox selection

**Recommendation**: Implement this feature after #32, #33, and #34 are completed, or create stub implementations for testing purposes.

---

Execution Information

Branch: main
Commit: 9698ef5