Run-Level Cost / Budget Ceiling

Background

Long-running agent loops without a budget can rack up real-money bills. The simplest defense is a run-level ceiling: cumulative cost is tracked, and any call that would push past the cap is rejected before being executed. The token-budget context manager handles per-turn truncation; this is its dollar-cost sibling.

Problem statement

Implement BudgetGuard(budget) with add(cost) -> bool:

• If total_cost + cost <= budget: accumulate and return True.
• Else: do not accumulate and return False.

Expose total_cost as a public attribute.

Input

• budget — float, total allowed cost.
• add(cost) — cost is a non-negative float.

Output

• add returns bool — whether the cost was admitted.
• total_cost — the running sum of accepted costs.

Examples

Example 1 — under budget

g = BudgetGuard(10.0)
g.add(3.0)  → True   total_cost = 3.0
g.add(4.0)  → True   total_cost = 7.0

Example 2 — exceeds budget → reject without accumulating

g = BudgetGuard(10.0)
g.add(8.0)  → True   total_cost = 8.0
g.add(5.0)  → False  total_cost = 8.0   (unchanged)

Example 3 — exactly at budget allowed

g = BudgetGuard(10.0)
g.add(10.0) → True   total_cost = 10.0

Constraints

• Rejection (False) must leave total_cost unchanged — don't accumulate then refund.
• total_cost initialises to 0.0.

Notes

• Estimated vs actual. Production guards distinguish "estimated cost" (passed in advance) from "actual cost" (charged after). Refunds and over-commit reservations require slightly more state.
• Per-user budgets. Real systems hold one BudgetGuard per user/session in a Redis-backed store, not one per process.