feat(budget): implement cost and session budget tracking (per-plan and per-session) #9999

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

Background: As agent plans grow in complexity and LLM API costs increase, teams need visibility into how much each plan and session costs. Without budget tracking, there is no foundation for enforcement, alerting, or cost attribution. This issue establishes the core tracking layer — recording token usage and estimated cost per plan execution and per session — which the enforcement layer (session budget enforcement) will build upon.

Acceptance criteria:

  • BudgetTracker class records token usage and estimated cost per plan execution
  • SessionBudgetTracker aggregates costs across all plan executions within a session
  • Both trackers expose current_cost, token_count, and budget_remaining properties
  • Cost estimation supports configurable per-token pricing by model
  • Budget limits are configurable via PlanConfig and SessionConfig
  • Tracker state is serializable (JSON) for persistence and audit logging
  • Unit tests achieve ≥ 97% coverage

Metadata

  • Commit Message: feat(budget): implement cost and session budget tracking per-plan and per-session
  • Branch: feat/budget-cost-session-tracking

Subtasks

  • Define BudgetTracker dataclass with token_count, estimated_cost, budget_limit fields
  • Define SessionBudgetTracker that aggregates multiple BudgetTracker instances
  • Implement record_usage(tokens: int, model: str) method with cost calculation
  • Add ModelPricing config mapping model names to per-token costs (input/output)
  • Integrate BudgetTracker into plan execution lifecycle hooks
  • Implement JSON serialization/deserialization for audit log support
  • Write unit tests for cost calculation, aggregation, and serialization

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**: As agent plans grow in complexity and LLM API costs increase, teams need visibility into how much each plan and session costs. Without budget tracking, there is no foundation for enforcement, alerting, or cost attribution. This issue establishes the core tracking layer — recording token usage and estimated cost per plan execution and per session — which the enforcement layer (session budget enforcement) will build upon. **Acceptance criteria**: - [ ] `BudgetTracker` class records token usage and estimated cost per plan execution - [ ] `SessionBudgetTracker` aggregates costs across all plan executions within a session - [ ] Both trackers expose `current_cost`, `token_count`, and `budget_remaining` properties - [ ] Cost estimation supports configurable per-token pricing by model - [ ] Budget limits are configurable via `PlanConfig` and `SessionConfig` - [ ] Tracker state is serializable (JSON) for persistence and audit logging - [ ] Unit tests achieve ≥ 97% coverage ## Metadata - **Commit Message**: `feat(budget): implement cost and session budget tracking per-plan and per-session` - **Branch**: `feat/budget-cost-session-tracking` ## Subtasks - [ ] Define `BudgetTracker` dataclass with `token_count`, `estimated_cost`, `budget_limit` fields - [ ] Define `SessionBudgetTracker` that aggregates multiple `BudgetTracker` instances - [ ] Implement `record_usage(tokens: int, model: str)` method with cost calculation - [ ] Add `ModelPricing` config mapping model names to per-token costs (input/output) - [ ] Integrate `BudgetTracker` into plan execution lifecycle hooks - [ ] Implement JSON serialization/deserialization for audit log support - [ ] Write unit tests for cost calculation, aggregation, and serialization ## 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#9999
No description provided.