The cost.* family (3 verbs). Every verb enters through the one front door: it is capability-checked, permission-checked, scope-checked and audited before it runs (see Security & permissions). Each entry below lists its capability, risk class (which fixes the minimum autonomy level), the minimum caller permission, its availability tier, whether it is idempotent, and any outbound egress.
Checkcost.budget.check
| Property | Value |
|---|---|
| Capability | cost.read |
| Risk class | Read - autonomy L0 |
| Min. permission | Admin |
| Availability | On demand (MCP tier 2) |
| Idempotent | Yes |
| Egress | None - in-box (pure Postgres, no outbound call) |
| Render schema | Yes - drives an inline chat artefact and a GUI panel |
the budget-vs-spend STATUS (45-ai-cost-control). Reads the workspace AI budget
(box_config key ‘ai.budget.monthly_minor’, set via the existing config.set - no new budget store,
Steering #1) + the ledger spend (SUM(cost_minor), degrading to 0 when the ledger is absent, like
cost.query) -> { budgetMinor, spentMinor, remainingMinor, overBudget, budgetSet }. A READ (the operator’s
budget lens; the M3 agent loop calls it before an LLM call - the enforcement DECISION/refusal is the loop’s,
this is the check). READ/ADMIN. {}.
Call POST /v/cost.budget.check with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool cost.budget.check.
Querycost.query
| Property | Value |
|---|---|
| Capability | cost.read |
| Risk class | Read - autonomy L0 |
| Min. permission | Admin |
| Availability | On demand (MCP tier 2) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
| Render schema | Yes - drives an inline chat artefact and a GUI panel |
The operator spend lens over ai_cost_ledger (SUM is a view, INV-6).
{}. The system/operator spend read; org-tenant spend-vs-cap is org.cost.query (delineated). If the
cost ledger is not present yet (a later milestone) this degrades to a zero-spend read, never errors.
Call POST /v/cost.query with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool cost.query.
Recordcost.record
| Property | Value |
|---|---|
| Capability | cost.write |
| Risk class | Write - autonomy L1 |
| Min. permission | Member |
| Availability | On demand (MCP tier 2) |
| Idempotent | No |
| Egress | None - in-box (pure Postgres, no outbound call) |
append an AI-cost event to the ledger (45-ai-cost-control). The governed write the M3
agent loop calls per LLM call (INV-1: one write path - not a privileged shadow insert); cost.query (the
read half, already shipped) aggregates it. APPEND-ONLY (the ledger has no UPDATE/DELETE grant). The caller
supplies the computed cost (the per-model rate is the caller’s; the ledger stores the result + the tokens).
{ costMinor, model?, inputTokens?, outputTokens?, verb? }. WRITE/MEMBER - an actor records its OWN spend
(workspace + actor scoped). The budget ENFORCEMENT gate (refuse a call over budget) is the deferred
trust-boundary half (court-gated; the budget value is workspace config via config.*).
Call POST /v/cost.record with a JSON body; returns JSON (or { error, code }). Also exposed as the MCP tool cost.record.