feat(budget): sliding-window cost accounting for agent exchanges

[mfethe1]

Implements the accounting half of the loop-protection policy decided in wayfinder ticket mfethe1/agent-mesh#7.

Draft — this crate has no consumer yet, by design. It stops at a seam; see Deliberately not implemented.

Why

Buzz already has throttles — thread depth capped at 100, tiered rate limits (human 60 / agent 120–600 msg/min), in-flight deadlines, session rotation. It has no termination condition. Two agents that open fresh threads at each other never accumulate thread_metadata.depth, so they run at a rate-limited 120 messages a minute indefinitely, each one a paid LLM call.

What

crates/buzz-budget budgets the thing that actually matters: measured cost_usd from the kind:44200 turn metric (NIP-AM).

• $5 per (channel, agent-pair) per rolling hour. The pair is unordered — A→B and B→A share one budget, because a runaway is a property of the pair, not a direction.
• Self-healing. The window slides; there is no reset step.
• Human-triggered turns are never charged. Cutting off someone who is sitting there watching is the failure this policy exists to avoid.

Four modules: ingest (wire → values, the only part that knows Nostr), origin (attributes a turn to its trigger), Ledger (the sliding window), Supervisor (composes them so a caller cannot get the order wrong).

Deliberately not implemented

Enforcement. record() returns a Verdict; acting on it is the caller's job. Buzz's owner commands are !shutdown (kills the whole harness), !cancel (one turn) and !rotate (session) — none can mute a single peer, so enforcing this needs a new buzz-acp command. Keeping the accounting pure means that decision can land without touching this code.

Also absent: the relay subscription loop, which needs an enforcement host (ticket block#7 OQ7.3).

Known limitations, carried honestly

• Attribution fails open. An observation gap yields no trigger, which is not charged — so a dropped subscription disables the budget rather than tripping it.
• The attribution boundary is end-of-turn. The metric carries no turn start, so a message arriving mid-turn is attributed to the turn it did not trigger, and one owner message can free two turns. Errs toward under-charging. The durable fix is a turn-start or trigger field on NIP-AM (Improve message markdown display and formatting block/buzz#7 OQ7.5).
• A harness reporting no cost_usd is invisible to the budget (Improve message markdown display and formatting block/buzz#7 OQ7.2).

Review

Both axes of /code-review ran against this branch and found two real bugs, since fixed in 72d86f0:

• Security — turn_end was taken from the agent's own encrypted payload and never checked, so a future-dated metric wiped the pair's window. A runaway could zero its own budget. Now tied to the signed created_at.
• Correctness — trigger consumption was per channel rather than per agent, so with two agents in one channel the first metric ate the other's trigger. Relay reordering alone disabled the budget.

Verified at runtime, not just tested

cargo run -p buzz-budget --example runaway drives the supervisor with a real tracing subscriber. Two of the policy's claims hold under observation, and one does not:

Claim	Observed
D5 — human turns never blocked	40 owner-driven turns @ $2.50: 0 blocked, $0.00 charged ✅
D4 — self-healing, no reset	after the window slid, spend reset and the verdict returned to Allow ✅
D4 — runaway leaves a sawtooth in the logs	❌ no sawtooth — spend climbs monotonically $5.40 → $18.00 across 22 consecutive WARN lines

The sawtooth is a property of enforcement, not accounting. Until something acts on the verdict, the "diagnosable signature" D4 promised is a continuous alarm — arguably worse than the silent drain it was meant to replace. That is a flaw in the decision's reasoning rather than in this code, recorded as #7 OQ7.6.

Checks

41 tests + 1 doctest passing. cargo clippy clean, cargo fmt --check clean. #![deny(unsafe_code)] and #![warn(missing_docs)] per CONTRIBUTING.md.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 619c8990-e8af-4f2a-a854-6cc4b38dbd4a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}