budget-set

1# Budget Set
2 
3Help the user define a spend budget and turn it into a live cost guardrail on the
4Agent Monitor dashboard.
5 
6## Input
7 
8The user provides: **$ARGUMENTS**
9 
10This is the budget to set — e.g. `"$50/month"`, `"$10/week"`, or `"200000 tokens"`.
11If a period is omitted, treat it as a monthly budget and say so. If no number is
12given, read current spend first and propose a target.
13 
14## Data Sources
15 
16| Endpoint | Returns |
17|----------|---------|
18| `GET /api/pricing/cost` | `{ total_cost, breakdown: [{ model, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, cost, matched_rule }] }` — current spend, used to size the budget and compute the blended $/token rate |
19| `GET /api/alerts/rules` | `{ rules: [{ id, name, rule_type, config, enabled, cooldown_seconds }] }` — existing rules, so you don't create a duplicate guardrail |
20| `POST /api/alerts/rules` | Create a rule. Body: `{ name, rule_type, config, enabled?, cooldown_seconds? }`. Returns `{ rule }` |
21 
22## How a budget becomes a rule
23 
24The dashboard's alerting engine fires on **tokens**, not dollars. The spend-relevant
25rule type is **`token_threshold`**, whose config is `{ total_tokens }` — it fires when
26a session's cumulative tokens (input + output + cache_read + cache_write) cross the
27threshold. To turn a **dollar** budget into a token ceiling:
28 
29```
30blended_rate_per_token = total_cost / total_tokens          # from /api/pricing/cost
31token_ceiling          = budget_dollars / blended_rate_per_token
32```
33…