Budgets

Budgets prevent runaway spending. Every goal can have token, dollar, and session limits — plus approval gates that pause execution and require human sign-off before continuing.

Budget Fields

Set budgets when creating a goal:

goals({
  action: "create",
  goal: {
    title: "Ad campaign optimization",
    budget: {
      maxTokens: 5000000,    // 5M token ceiling
      maxCost: 100,           // $100 total spend
      maxSessions: 50,        // Max 50 agent sessions
      approvalGate: 50        // Pause at $50 and ask
    },
    // ...phases, etc.
  }
})

Usage is tracked automatically:

Budget Enforcement

The budget system checks are enforced at two points:

1. Phase advancement — When an agent calls complete_phase, the budget is checked. If exceeded, advancement is blocked.
2. Explicit checks — Agents can call budget_check proactively.

Checking budget status

goals({ action: "budget_check", goalId: "g_abc123" })

Response when budget is OK:

{
  "allow": true,
  "budgetStatus": "Budget: $12.50 / $100.00 (12.5%)",
  "budget": { "maxCost": 100, "usedCost": 12.5 }
}

Response when budget is exceeded:

{
  "allow": false,
  "reason": "cost $101.20 exceeds limit $100.00",
  "remaining": -1.20,
  "field": "cost"
}

Recording spend

Agents record spend against a goal's budget:

goals({
  action: "record_spend",
  goalId: "g_abc123",
  cost: {
    tokens: 150000,    // Tokens used this session
    dollars: 2.50,     // Dollar cost
    sessions: 1        // One session
  }
})

This increments the usedTokens, usedCost, and usedSessions counters.

Approval Gates

Approval gates are the safety net for expensive goals. When spending reaches the gate threshold, the goal pauses automatically and notifies the user.

How it works

1. Goal budget includes approvalGate: 50 (pause at $50)
2. Agent records spend that crosses the threshold
3. Budget check returns gateReached: true
4. Goal is paused with message: "Approval required: cost $51.20 reached gate threshold $50.00"
5. Human reviews and approves

Approving a goal

Via CLI:

reeve goal approve <goal-id>

Via agent tool:

goals({ action: "approve", goalId: "g_abc123" })

What happens on approval

Approval doesn't just unlock — it raises the gate by 50%:

• Gate was $50 → now $75
• Gate was $75 → now $112.50
• This lets the goal continue without immediately hitting the gate again

If the goal was paused, it's automatically resumed after approval.

Object-form approval gates

For fine-grained control, set the gate as an object:

budget: {
  maxCost: 200,
  maxTokens: 10000000,
  approvalGate: {
    cost: 50,       // Pause at $50
    tokens: 5000000 // Also pause at 5M tokens
  }
}

Either threshold being reached triggers the pause.

Budget Status Formatting

The engine provides human-readable budget summaries:

Budget: $12.50 / $100.00 (12.5%) | 1.2M / 5M tokens (24%) | Gate: $50

This appears in:

• Goal context injection (agent sees it in heartbeats)
• CLI reeve goal status output
• Dashboard goal detail view

Example: Progressive Budget with Gates

goals({
  action: "create",
  goal: {
    title: "Full-funnel marketing sprint",
    budget: {
      maxCost: 500,          // Hard ceiling: $500
      maxTokens: 50000000,   // 50M tokens
      approvalGate: 100      // First gate at $100
    },
    phases: [
      { name: "Research & plan", type: "once" },        // ~$10
      { name: "Build creatives", type: "once" },        // ~$30
      { name: "Launch campaigns", type: "once" },       // ~$50
      { name: "Monitor & optimize", type: "loop" }      // ~$10/day
    ]
  }
})

Expected flow:

1. Research + build ≈ $40 → under gate, no pause
2. Launch campaigns pushes to $90 → under gate, no pause
3. Monitoring pushes to $105 → gate hit, goal pauses
4. Human approves → gate raises to $150, goal resumes
5. Monitoring continues to $155 → gate hit again
6. Human approves → gate raises to $225, goal resumes
7. Eventually completes under $500 ceiling