Every call an agent makes to a language model costs money, and that money is easy to lose track of. Opbox treats AI spend as a first-class fact: each call writes one row to an append-only ledger, attributed to the model, the tokens, the verb, the actor, and the workspace. Spend is summed live from that ledger, never from a snapshot that can drift, and the workspace carries a monthly budget the agent loop can check before it spends. Money throughout is held as exact integer minor-units, so the totals are the totals.
What it does
One ledger row per AI call. Every language-model call an actor makes is recorded as a single governed write to the append-only ai_cost_ledger. The row carries the computed cost in minor-units, the model, the input and output token counts, and the verb the call was made under, scoped to the workspace and to the actor that spent it. Because the write goes through the same kernel front door as everything else (not a privileged shadow insert), an agent records its own spend under its own bounded permissions, and the ledger carries an immutable, audited trail of where the money went.
Spend summed live, never snapshotted. The spend figure is computed by summing the ledger, not read from a stored running total that can quietly fall out of step. Ask for the spend and you get the sum over the rows that exist; if the ledger is absent the figure degrades cleanly to zero rather than erroring. The number reconciles by construction because it is derived from the underlying record every time.
A per-workspace monthly budget. A workspace can set a monthly AI budget, held as the configuration value ai.budget.monthly_minor and set through the ordinary configuration verb rather than a separate budget store. The budget is a plain workspace setting an Owner controls, so there is one place the cap lives and one place to change it.
A budget-vs-spend status read. Against that budget, a single read returns the picture: the budget set for the workspace, the spend to date, the remaining headroom, and whether the workspace is over budget. The agent loop calls this read before an AI call so it can decide whether to proceed; the status is the operator’s and the loop’s lens on where the workspace sits relative to its cap. The check is a read, not a block: the decision to refuse a call that would exceed the cap is the loop’s. (A dispatch-level gate that auto-refuses a verb when over budget is the trust-boundary half that is deferred, not yet wired into the front door.)
Attribution you can query. Because each row carries the model, the tokens, and the verb, the spend can be read back as the operator’s spend lens over the workspace, aggregated from the ledger. This is the system-and-operator view of internal AI cost, distinct from per-matter billable charges, which live in the separate billing and charge families.
How you use it
Set a budget. Set the workspace’s monthly AI budget through configuration, as the ai.budget.monthly_minor value, in minor-units. There is no separate budget tool to learn: the cap is a workspace setting, and changing it is changing that one value.
Check where you stand. Read the budget-vs-spend status to see the budget, the spend to date, the remaining headroom, and whether the workspace is over budget. This is the read the agent loop performs before it spends, and the same read an operator uses to see the workspace’s position at a glance.
Read the spend. Query the spend to get the summed cost, computed live from the ledger rather than from a stored total. Use it to see what the workspace has spent and to attribute it across models and verbs.
Record a call. When an AI call is made, record it with its computed cost, the model, the input and output token counts, and the verb it ran under. In normal operation the agent loop does this automatically, one governed write per call, so the ledger stays complete without anyone keying spend by hand.
The kernel verbs behind it
Everything above runs through the kernel’s one front door: each call is permission-checked, scope-checked, and audited before it executes. These are the cost verbs.
cost.record- append one AI-cost event to the append-only ledger: the computed cost, model, token counts, and verb, scoped to the workspace and actor.cost.query- the operator’s spend lens, summed live from the ledger across one or all stores.cost.budget.check- the budget-vs-spend status read: budget set, spend, remaining, and whether the workspace is over budget.config.set- set the workspace’s monthly AI budget as theai.budget.monthly_minorconfiguration value (no separate budget store).
See the full set in the cost verb reference.