Reserve budget before a costly operation (LLM call, tool invocation, external action). Returns a reservation_id to commit or release later. If decision is not ALLOW, do not proceed with the operation. For lightweight preflight checks without reserving, use cycles_decide instead.

Commit actual usage after an operation completes. Always call this after cycles_reserve whether the operation succeeded or failed. Finalizes the budget charge and releases any unused reserved amount back to the pool.

Release a reservation without committing. Use when an operation is cancelled, skipped, or fails before execution. Returns the released budget amount back to the pool.

Extend the TTL of an active reservation. Use as a heartbeat for long-running operations to prevent the reservation from expiring. Does not change the reserved amount.

Lightweight preflight check — ask whether an action would be allowed without reserving budget. Does not create a reservation. Use at workflow start to decide strategy. For concurrency-safe budget locking, use cycles_reserve instead.

Check current budget balance for a scope. Returns remaining, reserved, spent, allocated, and debt amounts. At least one subject filter (tenant, workspace, app, workflow, agent, or toolset) is required. Do not use as a substitute for cycles_reserve — balances can change between check and action.

List reservations, optionally filtered by status (ACTIVE, COMMITTED, RELEASED, EXPIRED) or subject fields. Useful for debugging stuck reservations or auditing budget usage.

Get details of a specific reservation by ID. Returns status, subject, action, reserved amount, timestamps, and affected scopes. Useful for debugging and monitoring long-running operations.

Record a usage event directly without the reserve/commit lifecycle. Use for fire-and-forget metering of completed operations where pre-estimation is not available. The event is applied atomically to all derived scopes.