feat(budget): implement session budget enforcement (halt execution when budget exceeded) #10001

Open
opened 2026-04-16 11:36:43 +00:00 by HAL9000 · 0 comments
Owner

Background: Budget tracking alone (#9999) is insufficient for cost governance — the system must actively halt plan execution when a configured budget limit is exceeded. Without enforcement, runaway agent loops or unexpectedly expensive plans can incur unbounded costs. This issue implements the enforcement layer that integrates with the plan executor to raise BudgetExceededError and cleanly halt execution when per-plan or per-session limits are breached.

Acceptance criteria:

  • BudgetExceededError exception is defined with budget_type, limit, and actual_cost fields
  • Plan executor checks budget after each LLM call and raises BudgetExceededError when limit is exceeded
  • Session-level enforcement halts all subsequent plan executions in the session when session budget is exceeded
  • Enforcement is configurable: strict mode (halt immediately) vs warn mode (log warning, continue)
  • Partial results are preserved and returned when execution is halted mid-plan
  • Unit tests achieve ≥ 97% coverage; integration tests verify halt behavior end-to-end

Metadata

  • Commit Message: feat(budget): implement session budget enforcement to halt execution when exceeded
  • Branch: feat/budget-session-enforcement

Subtasks

  • Define BudgetExceededError with budget_type (plan | session), limit, actual_cost fields
  • Add enforcement_mode: Literal["strict", "warn"] to BudgetConfig
  • Integrate budget check into plan executor after each LLM API call
  • Implement session-level gate that blocks new plan executions when session budget is exhausted
  • Implement partial result capture and return on BudgetExceededError
  • Add structured log event budget.exceeded with cost details for observability
  • Write unit tests for both enforcement modes and integration tests for end-to-end halt behavior

Definition of Done

  • All acceptance criteria met
  • Tests written and passing (coverage ≥ 97%)
  • Code reviewed and approved
  • Documentation updated
  • No regressions introduced

Parent Epic

Child of and blocks #8569 — Epic: Cost Budgets, Safety Profiles & Plugin Architecture (v3.6.0)


Automated by CleverAgents Bot
Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor
Worker: [AUTO-EPIC-2]

**Background**: Budget tracking alone (#9999) is insufficient for cost governance — the system must actively halt plan execution when a configured budget limit is exceeded. Without enforcement, runaway agent loops or unexpectedly expensive plans can incur unbounded costs. This issue implements the enforcement layer that integrates with the plan executor to raise `BudgetExceededError` and cleanly halt execution when per-plan or per-session limits are breached. **Acceptance criteria**: - [ ] `BudgetExceededError` exception is defined with `budget_type`, `limit`, and `actual_cost` fields - [ ] Plan executor checks budget after each LLM call and raises `BudgetExceededError` when limit is exceeded - [ ] Session-level enforcement halts all subsequent plan executions in the session when session budget is exceeded - [ ] Enforcement is configurable: `strict` mode (halt immediately) vs `warn` mode (log warning, continue) - [ ] Partial results are preserved and returned when execution is halted mid-plan - [ ] Unit tests achieve ≥ 97% coverage; integration tests verify halt behavior end-to-end ## Metadata - **Commit Message**: `feat(budget): implement session budget enforcement to halt execution when exceeded` - **Branch**: `feat/budget-session-enforcement` ## Subtasks - [ ] Define `BudgetExceededError` with `budget_type` (`plan` | `session`), `limit`, `actual_cost` fields - [ ] Add `enforcement_mode: Literal["strict", "warn"]` to `BudgetConfig` - [ ] Integrate budget check into plan executor after each LLM API call - [ ] Implement session-level gate that blocks new plan executions when session budget is exhausted - [ ] Implement partial result capture and return on `BudgetExceededError` - [ ] Add structured log event `budget.exceeded` with cost details for observability - [ ] Write unit tests for both enforcement modes and integration tests for end-to-end halt behavior ## Definition of Done - [ ] All acceptance criteria met - [ ] Tests written and passing (coverage ≥ 97%) - [ ] Code reviewed and approved - [ ] Documentation updated - [ ] No regressions introduced ## Parent Epic Child of and blocks #8569 — Epic: Cost Budgets, Safety Profiles & Plugin Architecture (v3.6.0) --- **Automated by CleverAgents Bot** Supervisor: Epic Planning | Agent: epic-planning-pool-supervisor Worker: [AUTO-EPIC-2]
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#10001
No description provided.