TOKEN-BUDGET-PROTOCOL — Token + Cost Budget Enforcement¶
Status: live · Version: 1.0.0 · Camada: 7 · Rule 16 (canonical)
Purpose¶
Every capsule MUST declare budget_tokens and budget_dollars. This protocol defines how those budgets are evaluated, consumed, and enforced.
Budget hierarchy¶
Project annual cap (BUDGET.md)
↓
Quarterly cap
↓
Wave cap (CAPACITY-PLAN)
↓
Story cap (sum of capsule budgets)
↓
Per-capsule cap (handoff-capsule.constraints.budget_*)
↓
Per-agent per-invocation cap (AGENT-MANIFEST.budget.hard_cap_*)
Lower bounds are HARDER than higher bounds. A capsule cannot request more than the agent's hard cap.
Token accounting¶
Each LLM call emits a token_consumed event with:
- agent_id
- capsule_id
- tokens_input, tokens_output
- cost_dollars (from rate card)
- model (for rate lookup)
Aggregated per capsule, per story, per agent, per wave, per quarter, per year.
Enforcement points¶
| Where | What happens |
|---|---|
| Capsule acceptance (Phase 0) | reject if budget_tokens > receiver.hard_cap_tokens |
| Every checkpoint | warn if consumed > 75% capsule_budget |
| Per-skill invocation | reject if consumed_so_far + estimated_skill_cost > capsule_budget |
| Hard cap reached | CIRCUIT-BREAKER fires; HALT |
| Wave cap reached | freeze new story acceptance |
| Quarterly cap reached | engineering-lead approval required for new spend |
Estimation¶
For each skill, an avg_cost_dollars field (in _skills-registry.yaml) provides estimate. Cumulative estimate compared against remaining budget.
Rate card¶
| Model | Input $/MTok | Output $/MTok |
|---|---|---|
| Claude Haiku 4.5 | $1 | $5 |
| Claude Sonnet 4.6 | $3 | $15 |
| Claude Opus 4.7 | $15 | $75 |
Rate card updated quarterly OR on provider price change (whichever first).
Failure modes¶
| Mode | Action |
|---|---|
| Burst over budget | Halt mid-skill if possible; emit warning event |
| Slow leak | Quarterly review catches; budget revision via ADR |
| Provider rate spike | TECH-DEBT row opened automatically |
Reporting¶
Daily aggregate emitted to dashboard (PIXEL-AGENTS): - tokens per hour - cost per hour - top-3 most expensive agents - top-3 most expensive stories
Cross-references¶
- BUDGET.md template (per-project caps)
- CAPACITY-PLAN.md template (wave caps)
- CIRCUIT-BREAKER (C9) — hard enforcement
- COST-POLICY.yaml (rate card source of truth)
- handoff-capsule.schema.json (budget fields)