dvcrn Agent Budget Governance
Prevent runaway API spending in multi-agent systems. Each agent gets a daily output token budget. Exceed it and you get warnings. Keep exceeding it and you lose mesh spawn privileges.
How It Works
Agent completes task → tokens logged to BUDGET.json
↓
Heartbeat runs budget_audit.py
↓
├── Under 80%: ✅ Green — business as usual
├── 80-100%: 🟡 Yellow — warning logged
├── 100-200%: 🔴 Red — alert to orchestrator
└── 200%+ or 3 consecutive days over: ⛔ Demotion — mesh privileges revoked
Budget File Format
Each agent has agents/<name>/BUDGET.json:
{
"daily_limit": 50000,
"today": "2026-03-01",
"used_today": 23450,
"consecutive_over_days": 0,
"demoted": false
}
Running the Audit
python3 scripts/budget_audit.py # Full audit with alerts
python3 scripts/budget_audit.py --json # Machine-readable output
python3 scripts/budget_audit.py --reset-only # Just reset daily counters
Governance Rules
- Daily reset at midnight (configurable timezone)
- Yellow at 80% — logged, no action
- Red at 100% — logged, orchestrator alerted
- Demotion at 200% OR 3 consecutive days over budget
- Rehabilitation — demoted agent must go 7 clean days, then orchestrator manually restores privileges
Demotion Mechanics
Demotion removes an agent's subagents.allowAgents list in openclaw.json, preventing them from spawning other agents. They can still be spawned by the orchestrator.
Files
scripts/budget_audit.py— Audit script (run from heartbeat or cron)references/GOVERNANCE.md— Full governance framework documentation