[v1.1] Budget limits and cost controls

[frankbria]

Problem

Users have no way to limit E2B spending, leading to potential surprise costs for long-running or many parallel tasks.

Proposed Solution

Session Budget Limits

# Limit single session
parallel-cc sandbox-run --repo . --prompt "Task" --budget 0.50

# Limit is in USD
# Session terminates if limit reached

Global Budget Limits

# Set global monthly limit
parallel-cc config set budget.monthly-limit 10.00

# Set per-session default
parallel-cc config set budget.per-session 1.00

Notifications

• Warning at 50% of budget
• Warning at 80% of budget
• Hard stop at 100%

Cost Tracking

• Track actual costs per session
• Daily/weekly/monthly reports
• Cost breakdown by task type

Database Schema

ALTER TABLE sessions ADD COLUMN budget_limit REAL;
ALTER TABLE sessions ADD COLUMN cost_estimate REAL;
ALTER TABLE sessions ADD COLUMN actual_cost REAL;

CREATE TABLE budget_tracking (
  id TEXT PRIMARY KEY,
  period TEXT, -- 'daily', 'weekly', 'monthly'
  period_start TEXT,
  budget_limit REAL,
  spent REAL,
  created_at TEXT
);

Files to Modify

• src/cli.ts - Add budget flags
• src/e2b/sandbox-manager.ts - Monitor and enforce limits
• src/db.ts - Budget tracking tables

Acceptance Criteria

• Per-session budget limits work
• Global budget limits configurable
• Cost tracking persisted to database
• Warnings issued at configurable thresholds
• parallel-cc budget-status shows current spending

Dependencies

None

[traycerai]

Plan

Observations

The codebase already has foundational cost tracking infrastructure in SandboxManager with calculateEstimatedCost() method using E2B pricing (~$0.10/hour). The database uses SQLite with a migration system (v0.5, v1.0) and the sessions table already tracks E2B sandboxes. The CLI uses Commander.js for command structure. No configuration management system exists for user settings beyond the install command. The timeout enforcement system in SandboxManager provides a pattern for budget limit enforcement.

Approach

Implement budget controls as a v1.1 database migration adding budget columns to sessions and a new budget_tracking table. Extend SandboxManager to enforce per-session budget limits during execution with warnings at 50%/80% thresholds. Create a configuration module for persistent global budget settings stored in ~/.parallel-cc/config.json. Add CLI commands: config set/get for global limits, --budget flag to sandbox-run, and budget-status for spending reports. Leverage existing cost calculation and timeout enforcement patterns for consistency.

Implementation Steps

1. Database Schema Changes

Create migration file file:migrations/v1.1.0.sql:

• Add columns to sessions table:

  • budget_limit REAL - Per-session budget in USD
  • cost_estimate REAL - Estimated cost based on runtime
  • actual_cost REAL - Actual cost from E2B API (future enhancement)

• Create budget_tracking table:

  • id TEXT PRIMARY KEY
  • period TEXT - 'daily', 'weekly', 'monthly'
  • period_start TEXT - ISO timestamp
  • budget_limit REAL - Budget limit for period
  • spent REAL - Amount spent in period
  • created_at TEXT
  • Add indexes on period and period_start

• Update schema_metadata to version 1.1.0

Update file:src/db.ts:

• Add hasV11Columns() method to check for budget columns
• Add createBudgetTrackingRecord() method
• Add getBudgetTracking() method with period filters
• Add updateBudgetSpent() method to increment spent amount
• Add getCurrentPeriodBudget() method for monthly/daily/weekly tracking
• Update createE2BSession() to accept optional budget_limit parameter
• Add updateSessionCost() method to update cost_estimate and actual_cost
• Update migrateToLatest() to include v1.1.0 migration

2. Type Definitions

Update file:src/types.ts:

• Add BudgetPeriod type: 'daily' | 'weekly' | 'monthly'
• Add BudgetTrackingRow interface matching database schema
• Add BudgetTracking interface with TypeScript types
• Add BudgetConfig interface:
  • monthlyLimit?: number
  • perSessionDefault?: number
  • warningThresholds?: number[] (default: [0.5, 0.8])
• Add BudgetStatus interface for budget-status command:
  • currentPeriod: { period: string, start: string, limit: number, spent: number }
  • sessions: Array<{ sessionId, sandboxId, budgetLimit, costEstimate }>
  • totalSpent: number
  • remainingBudget: number
• Extend E2BSession interface to include budget fields
• Add BudgetExceededError class extending Error

3. Configuration Management

Create new file file:src/config.ts:

• Define CONFIG_PATH = '~/.parallel-cc/config.json'

• Create ConfigManager class:

  • load() - Read and parse config file
  • save() - Write config to file
  • get(key: string) - Get config value with dot notation support
  • set(key: string, value: unknown) - Set config value
  • getAll() - Return entire config object
  • getBudgetConfig() - Return budget-specific config
  • setBudgetConfig(config: Partial<BudgetConfig>) - Update budget settings

• Default config structure:

  {
    budget: {
      monthlyLimit: null,
      perSessionDefault: null,
      warningThresholds: [0.5, 0.8]
    }
  }

4. Budget Enforcement in SandboxManager

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

• Add budgetLimit?: number to constructor config

• Add sessionBudgetLimits: Map<string, number> to track per-session limits

• Add budgetWarningsIssued: Map<string, Set<number>> for threshold tracking

• Create checkBudgetLimit(sandboxId: string): BudgetWarning | null method:

  • Calculate current cost using getEstimatedCost()
  • Get budget limit from sessionBudgetLimits
  • Check against warning thresholds (50%, 80%)
  • Return warning object if threshold reached
  • Throw BudgetExceededError if 100% reached

• Update enforceTimeout() to also call checkBudgetLimit()

• Update createSandbox() to accept optional budgetLimit parameter

• Add setBudgetLimit(sandboxId: string, limit: number) method

• Update calculateEstimatedCost() to be public (already private)

5. CLI Command Updates

Update file:src/cli.ts:

Add config commands:

parallel-cc config set <key> <value>
  - Set configuration value (e.g., budget.monthly-limit 10.00)
  - Validate budget values are positive numbers
  - Save to ~/.parallel-cc/config.json

parallel-cc config get <key>
  - Get configuration value
  - Support dot notation (budget.monthly-limit)

parallel-cc config list
  - Display all configuration values
  - Format budget values as currency

Update sandbox-run command:

• Add --budget <amount> option for per-session limit in USD
• Before creating sandbox, check global monthly budget:
  • Load config using ConfigManager
  • Query current month's spending from budget_tracking
  • If monthly limit set and exceeded, exit with error
• Pass budget limit to sandboxManager.createSandbox()
• During execution monitoring loop:
  • Call sandboxManager.checkBudgetLimit() periodically
  • Display warnings at 50%/80% thresholds
  • Terminate sandbox if budget exceeded
• After execution:
  • Calculate final cost estimate
  • Update session cost in database
  • Update monthly budget tracking

Add budget-status command:

parallel-cc budget-status [options]
  --period <period>  Show specific period (daily/weekly/monthly)
  --json            Output as JSON

Display:
  - Current period budget (monthly by default)
  - Total spent this period
  - Remaining budget
  - Active sessions with costs
  - Recent completed sessions
  - Cost breakdown by day/week

6. Budget Tracking Integration

Create new file file:src/budget-tracker.ts:

• Create BudgetTracker class:
  • Constructor accepts SessionDB instance
  • recordSessionCost(sessionId: string, cost: number) - Update session and period tracking
  • checkMonthlyLimit(configManager: ConfigManager): boolean - Verify monthly budget
  • getCurrentPeriodSpending(period: BudgetPeriod): number - Get current spending
  • getOrCreatePeriodRecord(period: BudgetPeriod): BudgetTracking - Ensure period record exists
  • generateBudgetReport(period: BudgetPeriod): BudgetStatus - Compile status report

7. Warning System

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

• Modify checkBudgetLimit() to return BudgetWarning object:

  • type: 'budget' | 'timeout'
  • level: 'soft' | 'hard'
  • percentage: number
  • message: string
  • currentCost: string
  • budgetLimit: string

• In sandbox-run command execution loop:

  • Check budget every 5 minutes (similar to timeout checks)
  • Log warnings to console with chalk colors
  • Store warnings in session output_log

8. Cost Calculation Improvements

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

• Enhance calculateEstimatedCost():

  • Make method public
  • Add optional actualCost parameter for future E2B API integration
  • Return object: { estimated: string, actual?: string }
  • Document E2B pricing tiers (Hobby vs Pro)

• Add getCostBreakdown(sandboxId: string) method:

  • Return elapsed time, cost per minute, total cost
  • Include sandbox tier information

9. Migration and Backward Compatibility

Update file:src/db.ts:

• Ensure v1.1.0 migration is backward compatible:

  • All new columns are nullable
  • Existing sessions work without budget limits
  • Default budget_limit to NULL (no limit)

• Add validation in createE2BSession():

  • If budget_limit provided, must be positive number
  • Log warning if budget_limit < estimated minimum cost

10. Testing Considerations

While not writing tests, document expected behavior:

• Budget enforcement should terminate sandbox gracefully
• Warnings should appear at exact threshold percentages
• Monthly budget should reset on first day of month
• Config file should handle concurrent access safely
• Budget tracking should survive database migrations

11. Documentation Updates

Update file:README.md:

• Add budget limits section with examples
• Document config commands
• Explain budget tracking and cost estimation
• Add troubleshooting for budget-related errors

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI
    participant ConfigManager
    participant SandboxManager
    participant BudgetTracker
    participant Database

    User->>CLI: sandbox-run --budget 0.50
    CLI->>ConfigManager: load config
    ConfigManager-->>CLI: monthly limit: $10
    CLI->>Database: get current month spending
    Database-->>CLI: spent: $8.50
    CLI->>CLI: check: $8.50 + $0.50 < $10 ✓
    CLI->>SandboxManager: createSandbox(budgetLimit: 0.50)
    SandboxManager->>Database: create E2B session
    
    loop Every 5 minutes
        SandboxManager->>SandboxManager: checkBudgetLimit()
        alt 50% threshold
            SandboxManager->>CLI: warning: 50% budget used
            CLI->>User: display warning
        else 80% threshold
            SandboxManager->>CLI: warning: 80% budget used
            CLI->>User: display warning
        else 100% exceeded
            SandboxManager->>SandboxManager: terminateSandbox()
            SandboxManager->>CLI: BudgetExceededError
            CLI->>User: error: budget exceeded
        end
    end
    
    SandboxManager-->>CLI: execution complete
    CLI->>BudgetTracker: recordSessionCost($0.45)
    BudgetTracker->>Database: update session cost
    BudgetTracker->>Database: update monthly tracking
    CLI->>User: success + cost report

Loading

Key Files to Modify

• file:migrations/v1.1.0.sql - New migration
• file:src/db.ts - Budget tracking methods
• file:src/types.ts - Budget type definitions
• file:src/config.ts - New configuration manager
• file:src/budget-tracker.ts - New budget tracking logic
• file:src/e2b/sandbox-manager.ts - Budget enforcement
• file:src/cli.ts - New commands and flags
• file:README.md - Documentation updates

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase already has foundational cost tracking infrastructure in `SandboxManager` with `calculateEstimatedCost()` method using E2B pricing (~$0.10/hour). The database uses SQLite with a migration system (v0.5, v1.0) and the sessions table already tracks E2B sandboxes. The CLI uses Commander.js for command structure. No configuration management system exists for user settings beyond the install command. The timeout enforcement system in `SandboxManager` provides a pattern for budget limit enforcement.

## Approach

Implement budget controls as a v1.1 database migration adding budget columns to sessions and a new budget_tracking table. Extend `SandboxManager` to enforce per-session budget limits during execution with warnings at 50%/80% thresholds. Create a configuration module for persistent global budget settings stored in `~/.parallel-cc/config.json`. Add CLI commands: `config set/get` for global limits, `--budget` flag to `sandbox-run`, and `budget-status` for spending reports. Leverage existing cost calculation and timeout enforcement patterns for consistency.

## Implementation Steps

### 1. Database Schema Changes

Create migration file `file:migrations/v1.1.0.sql`:

- Add columns to sessions table:
  - `budget_limit REAL` - Per-session budget in USD
  - `cost_estimate REAL` - Estimated cost based on runtime
  - `actual_cost REAL` - Actual cost from E2B API (future enhancement)

- Create budget_tracking table:
  - `id TEXT PRIMARY KEY`
  - `period TEXT` - 'daily', 'weekly', 'monthly'
  - `period_start TEXT` - ISO timestamp
  - `budget_limit REAL` - Budget limit for period
  - `spent REAL` - Amount spent in period
  - `created_at TEXT`
  - Add indexes on `period` and `period_start`

- Update schema_metadata to version 1.1.0

Update `file:src/db.ts`:

- Add `hasV11Columns()` method to check for budget columns
- Add `createBudgetTrackingRecord()` method
- Add `getBudgetTracking()` method with period filters
- Add `updateBudgetSpent()` method to increment spent amount
- Add `getCurrentPeriodBudget()` method for monthly/daily/weekly tracking
- Update `createE2BSession()` to accept optional `budget_limit` parameter
- Add `updateSessionCost()` method to update cost_estimate and actual_cost
- Update `migrateToLatest()` to include v1.1.0 migration

### 2. Type Definitions

Update `file:src/types.ts`:

- Add `BudgetPeriod` type: `'daily' | 'weekly' | 'monthly'`
- Add `BudgetTrackingRow` interface matching database schema
- Add `BudgetTracking` interface with TypeScript types
- Add `BudgetConfig` interface:
  - `monthlyLimit?: number`
  - `perSessionDefault?: number`
  - `warningThresholds?: number[]` (default: [0.5, 0.8])
- Add `BudgetStatus` interface for budget-status command:
  - `currentPeriod: { period: string, start: string, limit: number, spent: number }`
  - `sessions: Array<{ sessionId, sandboxId, budgetLimit, costEstimate }>`
  - `totalSpent: number`
  - `remainingBudget: number`
- Extend `E2BSession` interface to include budget fields
- Add `BudgetExceededError` class extending Error

### 3. Configuration Management

Create new file `file:src/config.ts`:

- Define `CONFIG_PATH = '~/.parallel-cc/config.json'`
- Create `ConfigManager` class:
  - `load()` - Read and parse config file
  - `save()` - Write config to file
  - `get(key: string)` - Get config value with dot notation support
  - `set(key: string, value: unknown)` - Set config value
  - `getAll()` - Return entire config object
  - `getBudgetConfig()` - Return budget-specific config
  - `setBudgetConfig(config: Partial<BudgetConfig>)` - Update budget settings

- Default config structure:
  ```typescript
  {
    budget: {
      monthlyLimit: null,
      perSessionDefault: null,
      warningThresholds: [0.5, 0.8]
    }
  }
  ```

### 4. Budget Enforcement in SandboxManager

Update `file:src/e2b/sandbox-manager.ts`:

- Add `budgetLimit?: number` to constructor config
- Add `sessionBudgetLimits: Map<string, number>` to track per-session limits
- Add `budgetWarningsIssued: Map<string, Set<number>>` for threshold tracking

- Create `checkBudgetLimit(sandboxId: string): BudgetWarning | null` method:
  - Calculate current cost using `getEstimatedCost()`
  - Get budget limit from `sessionBudgetLimits`
  - Check against warning thresholds (50%, 80%)
  - Return warning object if threshold reached
  - Throw `BudgetExceededError` if 100% reached

- Update `enforceTimeout()` to also call `checkBudgetLimit()`
- Update `createSandbox()` to accept optional `budgetLimit` parameter
- Add `setBudgetLimit(sandboxId: string, limit: number)` method
- Update `calculateEstimatedCost()` to be public (already private)

### 5. CLI Command Updates

Update `file:src/cli.ts`:

#### Add config commands:

```
parallel-cc config set <key> <value>
  - Set configuration value (e.g., budget.monthly-limit 10.00)
  - Validate budget values are positive numbers
  - Save to ~/.parallel-cc/config.json

parallel-cc config get <key>
  - Get configuration value
  - Support dot notation (budget.monthly-limit)

parallel-cc config list
  - Display all configuration values
  - Format budget values as currency
```

#### Update sandbox-run command:

- Add `--budget <amount>` option for per-session limit in USD
- Before creating sandbox, check global monthly budget:
  - Load config using `ConfigManager`
  - Query current month's spending from `budget_tracking`
  - If monthly limit set and exceeded, exit with error
- Pass budget limit to `sandboxManager.createSandbox()`
- During execution monitoring loop:
  - Call `sandboxManager.checkBudgetLimit()` periodically
  - Display warnings at 50%/80% thresholds
  - Terminate sandbox if budget exceeded
- After execution:
  - Calculate final cost estimate
  - Update session cost in database
  - Update monthly budget tracking

#### Add budget-status command:

```
parallel-cc budget-status [options]
  --period <period>  Show specific period (daily/weekly/monthly)
  --json            Output as JSON

Display:
  - Current period budget (monthly by default)
  - Total spent this period
  - Remaining budget
  - Active sessions with costs
  - Recent completed sessions
  - Cost breakdown by day/week
```

### 6. Budget Tracking Integration

Create new file `file:src/budget-tracker.ts`:

- Create `BudgetTracker` class:
  - Constructor accepts `SessionDB` instance
  - `recordSessionCost(sessionId: string, cost: number)` - Update session and period tracking
  - `checkMonthlyLimit(configManager: ConfigManager): boolean` - Verify monthly budget
  - `getCurrentPeriodSpending(period: BudgetPeriod): number` - Get current spending
  - `getOrCreatePeriodRecord(period: BudgetPeriod): BudgetTracking` - Ensure period record exists
  - `generateBudgetReport(period: BudgetPeriod): BudgetStatus` - Compile status report

### 7. Warning System

Update `file:src/e2b/sandbox-manager.ts`:

- Modify `checkBudgetLimit()` to return `BudgetWarning` object:
  - `type: 'budget' | 'timeout'`
  - `level: 'soft' | 'hard'`
  - `percentage: number`
  - `message: string`
  - `currentCost: string`
  - `budgetLimit: string`

- In `sandbox-run` command execution loop:
  - Check budget every 5 minutes (similar to timeout checks)
  - Log warnings to console with chalk colors
  - Store warnings in session output_log

### 8. Cost Calculation Improvements

Update `file:src/e2b/sandbox-manager.ts`:

- Enhance `calculateEstimatedCost()`:
  - Make method public
  - Add optional `actualCost` parameter for future E2B API integration
  - Return object: `{ estimated: string, actual?: string }`
  - Document E2B pricing tiers (Hobby vs Pro)

- Add `getCostBreakdown(sandboxId: string)` method:
  - Return elapsed time, cost per minute, total cost
  - Include sandbox tier information

### 9. Migration and Backward Compatibility

Update `file:src/db.ts`:

- Ensure v1.1.0 migration is backward compatible:
  - All new columns are nullable
  - Existing sessions work without budget limits
  - Default budget_limit to NULL (no limit)

- Add validation in `createE2BSession()`:
  - If budget_limit provided, must be positive number
  - Log warning if budget_limit < estimated minimum cost

### 10. Testing Considerations

While not writing tests, document expected behavior:

- Budget enforcement should terminate sandbox gracefully
- Warnings should appear at exact threshold percentages
- Monthly budget should reset on first day of month
- Config file should handle concurrent access safely
- Budget tracking should survive database migrations

### 11. Documentation Updates

Update `file:README.md`:

- Add budget limits section with examples
- Document config commands
- Explain budget tracking and cost estimation
- Add troubleshooting for budget-related errors

## Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant CLI
    participant ConfigManager
    participant SandboxManager
    participant BudgetTracker
    participant Database

    User->>CLI: sandbox-run --budget 0.50
    CLI->>ConfigManager: load config
    ConfigManager-->>CLI: monthly limit: $10
    CLI->>Database: get current month spending
    Database-->>CLI: spent: $8.50
    CLI->>CLI: check: $8.50 + $0.50 < $10 ✓
    CLI->>SandboxManager: createSandbox(budgetLimit: 0.50)
    SandboxManager->>Database: create E2B session
    
    loop Every 5 minutes
        SandboxManager->>SandboxManager: checkBudgetLimit()
        alt 50% threshold
            SandboxManager->>CLI: warning: 50% budget used
            CLI->>User: display warning
        else 80% threshold
            SandboxManager->>CLI: warning: 80% budget used
            CLI->>User: display warning
        else 100% exceeded
            SandboxManager->>SandboxManager: terminateSandbox()
            SandboxManager->>CLI: BudgetExceededError
            CLI->>User: error: budget exceeded
        end
    end
    
    SandboxManager-->>CLI: execution complete
    CLI->>BudgetTracker: recordSessionCost($0.45)
    BudgetTracker->>Database: update session cost
    BudgetTracker->>Database: update monthly tracking
    CLI->>User: success + cost report
```

## Key Files to Modify

- `file:migrations/v1.1.0.sql` - New migration
- `file:src/db.ts` - Budget tracking methods
- `file:src/types.ts` - Budget type definitions
- `file:src/config.ts` - New configuration manager
- `file:src/budget-tracker.ts` - New budget tracking logic
- `file:src/e2b/sandbox-manager.ts` - Budget enforcement
- `file:src/cli.ts` - New commands and flags
- `file:README.md` - Documentation updates

---

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]

---

🧪 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!

[frankbria]

Closed with PR #52