Budgets and cost controls
Budgets and cost controls limit paid work at company, agent, and project scope. They combine policy limits, reservations, live usage, final cost records, and worker-led stops so the product can show current exposure and prevent unsafe new work.
System purpose
The budget system answers two related questions: how much spend the company has recorded or may still incur, and whether a new paid operation may start. The cost view then explains that spend by time, owner, agent, project, provider, biller, and model.
See Organization work management for the company work model and Application platform operations for the operational worker model.
Budget policy model
Policy scopes and windows
A budget policy is a spend rule attached to one scope. A scope is the company, one agent, or one project that the rule protects. Company and agent controls normally use the current UTC month. Project controls normally use the project lifetime.
Each policy has a money limit, a warning point, and a choice about hard stops. It can also choose whether usage with no reliable price blocks new work. A zero limit disables enforcement rather than creating a zero-cap work lane. Company and agent monthly policies also keep their matching monthly budget settings in sync with the wider organization and agent views.
| Scope | Main product use | Normal time window | Effect of a hard stop |
|---|---|---|---|
| Company | Protect total company spend | UTC calendar month | Pause company work and stop new work in its scopes |
| Agent | Control one agent's recurring spend | UTC calendar month | Hold the agent's heartbeat work |
| Project | Control execution for one project | Project lifetime | Pause project execution |
References: server/…/budgets.ts• L78-105 server/…/budgets.ts• L836-932 ui/…/Costs.tsx• L925-1036 packages/…/budget.ts• L11-57
Reservations
A reservation is an estimate held before a run starts. Admission is the check that decides if the run may enter paid provider work. The check applies the company policy and any matching agent or project policies. It counts existing ledger spend and unfinished holds, then adds the new reservation to protect the remaining capacity.
Reservations prevent several unfinished runs from claiming the same remaining budget. The system checks the held reservation again at the final dispatch gate, after preparation may have changed the run state. That gate also confirms that the run is still eligible, the agent is ready, and no newer pause or hard stop applies. Capacity alone does not authorize dispatch while an agent is still completing a budget release. A valid native recovery may reuse the original hold only while its recovery claim still owns provider dispatch, but an ordinary duplicate dispatch cannot. A reservation can survive a timeout, restart, or month boundary until accounting closes the run. Even a zero-estimate run cannot enter a scope whose capacity is fully held. It guides admission only; it does not cap the provider bill.
References: server/…/budget-reservations.ts• L28-78 server/…/budget-reservations.ts• L80-90 server/…/budget-reservations.ts• L91-171 server/…/budgets.ts• L791-817 server/…/budgets.ts• L1140-1153
Exposure accounting
Budget exposure is the amount the system must treat as committed now. It combines settled ledger charges, known live usage from unfinished runs, effective holds, and separate unknown browser work. A run and its hold describe one operation, so the system uses the larger relevant value instead of counting both at full value.
The system keeps unknown or incomplete usage visible as a data-quality problem. Unpriced ledger events, active native recovery holds, and some unfinished browser operations can block a policy even when the known money total is below the limit. Pending terminal runs remain visible for reporting, but unfinished accounting for them does not block admission. A policy may explicitly allow unpriced usage, but that choice does not create a final ledger price.
This diagram shows how a paid request becomes held capacity, live exposure, and final accounting before the system decides whether to warn or stop work.
flowchart LR
A[Paid work request] --> B[Budget admission]
B -->|allowed| C[Reservation held]
C --> D[Provider or browser work]
D --> E[Live usage projection]
D --> F[Final receipt]
F --> G[Settled cost event]
E --> H[Exposure check]
G --> H
H --> I[Warning or hard stop]
References: server/…/budget-exposure.ts• L6-20 server/…/budget-exposure.ts• L27-69 server/…/budget-exposure.ts• L71-166 server/…/budget-reservations.ts• L135-165 server/…/budgets.ts• L248-268
Enforcement lifecycle
Thresholds and holds
The warning threshold creates an incident and informs operators without pausing work. A hard threshold creates a stronger incident, marks the scope as held, and prevents new work. Hard incidents also create a pending approval for the budget override path.
Hard stops apply to new admission first. They also create durable cancellation intent for work already admitted to the scope. The budget hold belongs to the budget system, so a later policy change or lower observed exposure can release it without removing a separate manual pause.
References: server/…/budgets.ts• L248-253 server/…/budgets.ts• L525-595 server/…/budgets.ts• L681-713 ui/…/BudgetIncidentCard.tsx• L39-97
Enforcement workers
The enforcement worker turns durable stop intent into cancellation of active work. Policy changes and threshold checks wake the worker. Startup and timed checks recover work after a process stop. Failed delivery stays pending and retries, so a worker failure does not erase a committed stop.
The worker rechecks the current policy before delivery. This prevents an old stop from acting after a valid budget change. A committed stop remains owed even if a policy is later edited or deleted. A separate accounting worker repairs unfinished cost records and wakes when terminal runs or receipt writes provide new accounting work. It waits for usable evidence instead of inventing a zero charge.
References: server/…/budgets.ts• L1140-1208 server/…/budget-enforcement-worker.ts• L18-53 server/…/budget-enforcement-worker.ts• L56-85
Incident resolution
An incident is the operator-facing record of a warning or hard stop for a policy and time window. A board user can keep the scope paused or raise the budget and resume it. Resume requires the new limit to exceed observed spend and requires blocked unpriced usage to be resolved or explicitly allowed.
Raising the budget releases the budget-owned pause and claims work that the stop cancelled for later continuation. The continuation is delivered after the stop settles. Budget-owned pauses remain separate from manual pauses, so the budget view can distinguish a spending stop from another lifecycle state.
References: server/…/budgets.ts• L415-466 server/…/budgets.ts• L1008-1136 ui/…/BudgetIncidentCard.tsx• L100-133 ui/…/Costs.tsx• L966-991
Run cost attribution
Run settlement
Run settlement converts a completed run's durable usage receipt into cost events and closes its reservation in one accounting step. It records billable evidence, token counts, provider identity, and the run's business context. A retry is safe because the same run receipt has one accounting identity.
If the provider receipt is late or incomplete, the run remains pending. This keeps the reservation and budget exposure in place until the system can account for the work. A provider failure before paid work begins releases the hold without creating a false charge.
References: server/…/run-cost-accounting.ts• L18-155 server/…/budget-reservations.ts• L80-149 server/…/budget-enforcement-worker.ts• L56-85
Attribution links
Each cost event can point to the company, agent, issue, project, goal, run, responsible user, provider, biller, and model that explain the charge. These links let the product connect spend to both the person or scope responsible and the work that produced it. If an old issue or project no longer exists, the charge remains in the company total and becomes unattributed rather than blocking accounting.
Cost reports distinguish reported, estimated, unpriced, subscription-included, and unknown billing data. This lets operators see the difference between a low bill and an incomplete bill.
References: server/…/costs.ts• L85-165 packages/…/cost_events.ts• L11-71 packages/…/cost.ts• L4-44
Product surfaces
Cost views
The Costs surface is the main read view for spend and accounting quality. It supports date ranges and shows company totals, data-quality warnings, agent and project views, user attribution, provider and biller breakdowns, finance events, decisions, and fast responses.
Provider subscription quota is shown as a separate provider concern. It does not replace the company budget, and it does not make a budget policy enforce an external provider quota.
References: ui/…/Costs.tsx• L49-60 ui/…/Costs.tsx• L261-337 ui/…/Costs.tsx• L719-751 ui/…/costs.ts• L28-58
Budget controls
The Budgets surface is the control view for policy limits and incidents. It groups policies by company, agent, and project. Operators can set a limit, view observed spend and remaining room, set a per-run reservation, choose how to treat unpriced usage, and resolve incidents.
Budget status also appears beside paused agents and projects in navigation. Detail pages can expose the same policy card near the scope it controls, while the Audit area presents Costs and Budgets as peer sections.
References: ui/…/Costs.tsx• L925-1036 ui/…/BudgetPolicyCard.tsx• L133-173 ui/…/BudgetSidebarMarker.tsx• L3-32 ui/…/AuditHub.tsx• L150-166
Budget interfaces
The server exposes read, write, and incident-resolution operations for budgets through the company cost routes. Board access is required for policy changes and incident actions. Cost reads are subject to the company's cost-read boundary, so the product follows the same access model as other company work.
References: server/…/costs.ts• L69-110 server/…/costs.ts• L223-286 server/…/costs.ts• L346-426 ui/…/budgets.ts• L10-19
Operational safeguards
Accounting serialization
Admission, reservations, settlement, and enforcement fencing for one company use shared accounting transactions. This gives financial changes one ordering point while keeping policy evaluation as durable queued work that can be retried. Policy evaluation fences aggregate publication without waiting on the resource locks used by control writers. Read views use a repeatable read snapshot so a report does not wait for or delay an accounting writer.
References: server/…/accounting-transaction.ts• L8-32 server/…/budgets.ts• L1140-1153 server/…/budgets.ts• L1211-1299
Diagnostic tracing
Budget operations can emit OpenTelemetry spans for admission, exposure, accounting, and enforcement. Tracing is optional and contains no prompt, receipt, credential, or provider error text. If span creation or export fails, the accounting operation still runs once and its result does not change.
References: server/…/budget-tracing.ts• L4-31 server/…/budget-exposure.ts• L161-166 server/…/budget-reservations.ts• L91-162
Change checklist
When these files or sections are changed, remember to consider these:
- Keep policy scope and window rules aligned between admission, exposure totals, incident status, and the Budget Policy card.
- Keep reservation ownership aligned between first admission, final dispatch checks, native recovery claim fencing, and duplicate dispatch handling.
- Keep final dispatch checks from treating available capacity as sufficient when an agent pause or lifecycle transition still blocks work.
- Keep reservation semantics aligned with live usage so one run is not counted twice and a reservation is not treated as a provider charge cap.
- Keep terminal receipt readiness, reservation closure, cost-event creation, and post-settlement budget checks in the same accounting contract.
- Keep hard-stop intent durable when changing cancellation delivery, worker startup, retry, or policy version behavior.
- Keep cancelled-work continuation claims tied to the incident and delivered only after the stop settles.
- Keep unpriced, recovering, and unknown browser signals consistent across budget blocking, cost data-quality notices, and resume checks. Keep pending terminal runs visible without making unfinished accounting block admission.
- Keep company and agent monthly budget controls aligned with their corresponding policies.
- Keep cost attribution fields and report groupings aligned when adding a new run, service, provider, biller, or business scope.
- Keep tracing optional and non-blocking when changing budget operation wrappers or adding new budget spans.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A completed run has no usable final receipt | The run stays pending and its reservation can block new work | Retry accounting or wait for the receipt; do not treat the run as free |
| A policy blocks unpriced usage | New work can stop below the visible money limit | Resolve the price or explicitly allow unpriced usage |
| A reservation is lower than the provider charge | Final spend can exceed the estimate | Use live exposure and final receipt accounting; reservations do not cap provider billing |
| A successful browser dispatch has unknown or uncapped exposure | Work can remain a budget blocker without a known charge | Keep the browser operation unknown until terminal accounting provides a usable receipt |
| Native recovery loses its dispatch claim | Recovery cannot reuse the held reservation or start provider work | Recheck and renew the native recovery claim before dispatch |
| An agent is still paused or its budget resume is not ready | A capacity check can pass but provider dispatch is denied | Wait for the agent lifecycle to become ready |
| Enforcement delivery fails after a hard stop | Active work may continue until cancellation delivery succeeds | Leave the durable stop pending and let the worker retry |
| A linked issue or project is deleted | The charge loses local attribution but must remain in company totals | Report it as unattributed instead of dropping the cost |
| An operator raises a budget to a value at or below observed spend | The scope cannot resume safely | Set a limit above observed spend and clear blocked unpriced usage |
| Tracing setup fails during a budget operation | Diagnostics are missing but accounting must continue | Keep span creation optional and execute the accounting operation once independently |
Key files
| File | Why to read it |
|---|---|
| server/…/budgets.ts | Main policy, admission, incident, pause, resume, reconciliation, and enforcement contract |
| server/…/budget-exposure.ts | Defines ledger, live usage, reservations, pending runs, and unknown browser exposure |
| server/…/budget-reservations.ts | Shows how runs claim capacity and recheck it before provider dispatch |
| server/…/run-cost-accounting.ts | Shows how receipts become ledger charges and reservations close |
| server/…/budget-enforcement-worker.ts | Shows how stop intent and unfinished accounting are recovered and retried |
| server/…/budget-tracing.ts | Shows the optional, non-blocking diagnostics boundary for budget operations |
| server/…/accounting-transaction.ts | Shows the shared ordering and read snapshot used by accounting work |
| server/…/costs.ts | Defines cost-event validation, attribution, totals, and report groupings |
| server/…/costs.ts | Maps product permissions and HTTP operations to budget and cost services |
| ui/…/Costs.tsx | Shows the operator-facing Costs, Budgets, incident, and provider surfaces |
| ui/…/BudgetPolicyCard.tsx | Shows the controls and status presented for one policy |
| ui/…/BudgetIncidentCard.tsx | Shows the operator choices for warnings and hard stops |
| packages/…/budget.ts | Defines the shared policy, summary, incident, and overview shapes |
| packages/…/cost.ts | Defines the shared cost summaries, quality signals, and attribution reports |