Register a new agent in the budget system with a priority weight and an initial token budget. Call this once per agent before recording spend or requesting reallocation for it. Priority is relative: higher priority agents can pull spare budget from equal-or-lower priority agents during reallocation, but budget never flows from a higher-priority agent to a lower-priority one. Re-registering an existing agent_id resets its contract and ledger entry.

Record tokens actually consumed by a registered agent for a task, as raw input/output token counts (not dollar cost). If this pushes the agent over its remaining budget, the library automatically attempts priority-weighted reallocation to cover the shortfall from eligible donor agents before failing. The response reports whether reallocation was triggered and, if so, exactly which donor agents gave up how many tokens. Fails with a structured budget_exceeded error if no combination of donors can cover the shortfall - it never silently overspends.

Return a single agent's current remaining token budget, along with its allocated total, consumed total, priority, and protected minimum reserve. Use this to check whether an agent is close to starved before deciding whether to request a reallocation.

The core allocation-decision tool. Given an agent that needs additional tokens right now, run the library's priority-weighted borrowing logic to pull spare budget from eligible donor agents - starting with the lowest-priority, most-idle ones - and apply it for real. A donor is only eligible if its priority is <= the needy agent's priority (budget never flows from a more important agent to a less important one) and it never gives up tokens below its own protected min_reserve. Returns a concrete plan: which agents gave up how many tokens, which agent received them, why each donor was eligible, and how much of the requested amount could not be covered (if any). This performs a real reallocation against the live ledger, not a dry-run simulation - call get_remaining_budget first if you only want to inspect state without moving tokens.

Return the full current state of every registered agent - priority, allocated budget, consumed tokens, remaining budget, and min_reserve - as structured JSON. Use this for a system-wide view before deciding whether a reallocation is needed, or to let an orchestrator/human inspect overall budget health across all agents at once.