Budgets

Budgets is the estimated action-spend guardrail layer. It is not invoice-grade billing reconciliation.

Current Surfaces

Callable	Caller	Purpose
governorPreflight	Agent	Estimate one proposed action and return allow/deny before work runs.
governorGetSpend	Human	Read monthly spend rollups for an owned agent.
governorBudgets	Human	Set the monthly budget for an owned agent.
governorOverride	Human	Add an audit-logged one-shot budget extension.
governorKillSwitch / governorReleaseKillSwitch	Human	Suspend or resume an owned agent.

Agent credentials can call governorPreflight. Budget management and kill switches stay human-only.

Agent Preflight

{
  "data": {
    "kind": "postbox.send",
    "units": 1
  }
}

Allowed response:

{
  "result": {
    "ok": true,
    "estimatedUsd": 0.0005,
    "remainingUsd": 9.991
  }
}

Denied response:

{
  "result": {
    "ok": false,
    "reason": "would exceed monthly budget",
    "estimatedUsd": 0.0005,
    "spentUsd": 10,
    "budgetUsd": 10
  }
}

How Spend Is Counted

Metered callables still debit through requireQuota(...) after successful work and credit back on downstream failure. governorPreflight is the before-action check; quota is the after-action accounting.

Usage lands in agents/{agentId}/usage/{YYYY-MM} with per-action counts and estimated USD fields. Human dashboards read rollups through governorGetSpend.

Free-launch guardrails map to per-action limits in functions/src/lib/plans.ts. Paid plan names are not active product tiers yet.