Module budget 

Budget / cost / quota contract for cluster-grade hosts.

The framework does not enforce budgets itself — it only defines the decision points and emits structured events. The host (e.g. 书安OS) implements BudgetGuard with whatever backend it likes (per-tenant counters in Redis, per-day USD caps in Postgres, etc.) and plugs it into [SessionOptions::with_budget_guard].

Decision points wired today:

1. Before each LLM call — BudgetGuard::check_before_llm. A Deny aborts the call; a SoftLimit lets the call proceed but triggers an [AgentEvent::BudgetThresholdHit] so in-session policy (hooks, custom prompts) can react.
2. After each LLM call — BudgetGuard::record_after_llm. The host updates its running spend total with the actual usage.
3. Before each tool call — BudgetGuard::check_before_tool. Same decision shape; useful for capping expensive tools per tenant.

The default trait methods are no-ops returning BudgetDecision::Allow so existing code is unaffected until a host plugs in a real impl.

See AgentEvent::BudgetThresholdHit for the event vocabulary triggered by SoftLimit.

Structs

NoopBudgetGuard

Default implementation that always allows everything. Used when no host-supplied guard is configured.

Enums

BudgetDecision

Outcome of a budget check.

Traits

BudgetGuard

Host-supplied budget / quota contract.