Motivation
Buzz can run multiple agents across channels, sessions, schedules, and background activity. That makes it easy for API usage to grow without the owner noticing until the provider bill arrives.
Owners need two connected controls:
- An enforceable API budget for each agent.
- A clear view of total agent spend across daily, weekly, and monthly windows.
Visibility alone is not enough. A dashboard can explain a large bill after the fact, but it cannot prevent one. Conversely, a per-agent limit is difficult to manage without seeing the overall portfolio.
Proposed solution
Add an owner-only Usage & Budgets surface that builds on the existing NIP-AM agent-turn metrics.
1. Per-agent budgets
Let the owner configure one or more USD limits for each agent:
Each configured limit should support:
- a warning threshold before the limit is reached;
- a hard-stop mode that allows the current turn to finish but prevents the next billable turn from starting;
- a visible paused state explaining which budget was reached, the spend counted, and when the budget resets;
- an explicit owner override by raising the limit, disabling it, or resuming after review;
- enforcement across every channel, session, scheduled task, heartbeat, retry, and worker for that agent.
A restart, additional worker, or parallel session must not create a fresh budget. The limit belongs to the agent identity and owner, not to one process or channel.
2. Owner-wide spend dashboard
Show the owner:
- total agent spend today, this week, and this month;
- spend by agent;
- spend by provider, model, and harness where that evidence is available;
- current budget consumption and remaining amount for each agent;
- a clear warning when usage or cost data is partial, delayed, estimated, or unavailable.
Daily, weekly, and monthly boundaries should use the owner’s configured timezone. Weekly boundaries should be explicit rather than silently assuming a locale.
3. Safe accounting and enforcement
NIP-AM already distinguishes known and unknown usage fields. Budget handling should preserve that discipline:
- never treat unknown cost as
$0;
- distinguish provider-reported cost from a Buzz estimate;
- identify the provider/model/pricing source used for any estimate;
- avoid double-counting cumulative metrics, retries, session rotation, or cross-device archive sync;
- state clearly that the provider’s own billing dashboard and invoice remain authoritative.
For a hard budget, incomplete accounting should fail safely. If Buzz cannot determine whether the next turn would violate the budget, it should pause before that turn and tell the owner why, rather than silently spending past the limit.
4. Notifications and recovery
- Notify the owner when a warning threshold or hard limit is reached.
- Do not let an agent caught by a limit enter a retry or respawn loop.
- Resume automatically only when the applicable calendar window resets; otherwise require an explicit owner action.
- Preserve a lightweight audit trail of budget changes, limit hits, overrides, and resumes.
Alternatives considered
- Rely only on provider dashboards: providers show account-level billing, but not consistently by Buzz agent, channel, scheduled task, or workflow.
- Ship usage charts without enforcement: useful for analysis, but it does not prevent surprise bills.
- Use token limits only: token prices vary by provider, model, cache class, and time. Tokens remain useful diagnostic evidence, but they are not a reliable cross-provider budget unit.
- Stop the current turn immediately: risks corrupting work or leaving tools and external actions half-complete. Preventing the next billable turn is safer and more predictable.
Additional context
Acceptance criteria
- An owner can set daily, weekly, and monthly USD limits independently for an agent.
- The owner can see aggregate spend for today, this week, and this month, with a per-agent breakdown.
- A hard-limited agent cannot start another billable turn after reaching its limit.
- The budget applies across all of that agent’s channels, sessions, workers, retries, and scheduled activity.
- Unknown or incomplete cost is never displayed or enforced as zero.
- The UI distinguishes reported, estimated, partial, and unavailable spend.
- The owner can identify why an agent is paused and either wait for reset or explicitly override the budget.
Motivation
Buzz can run multiple agents across channels, sessions, schedules, and background activity. That makes it easy for API usage to grow without the owner noticing until the provider bill arrives.
Owners need two connected controls:
Visibility alone is not enough. A dashboard can explain a large bill after the fact, but it cannot prevent one. Conversely, a per-agent limit is difficult to manage without seeing the overall portfolio.
Proposed solution
Add an owner-only Usage & Budgets surface that builds on the existing NIP-AM agent-turn metrics.
1. Per-agent budgets
Let the owner configure one or more USD limits for each agent:
Each configured limit should support:
A restart, additional worker, or parallel session must not create a fresh budget. The limit belongs to the agent identity and owner, not to one process or channel.
2. Owner-wide spend dashboard
Show the owner:
Daily, weekly, and monthly boundaries should use the owner’s configured timezone. Weekly boundaries should be explicit rather than silently assuming a locale.
3. Safe accounting and enforcement
NIP-AM already distinguishes known and unknown usage fields. Budget handling should preserve that discipline:
$0;For a hard budget, incomplete accounting should fail safely. If Buzz cannot determine whether the next turn would violate the budget, it should pause before that turn and tell the owner why, rather than silently spending past the limit.
4. Notifications and recovery
Alternatives considered
Additional context
Acceptance criteria