Description
Spend Tracking and Threshold Alerts records completed AI and intelligence costs into a daily ledger partitioned by company, source, date, and optional principal. Each record atomically increments spend and count, stores optional provenance metadata, and returns the previous and new totals. The core compares that transition with the configured threshold so an alert fires only when a line crosses the boundary, not on every later record above it.
A closed source registry keeps spend buckets consistent across Dotabase AI fill, embeddings, Chat dispatch, media processing, repo enrichment, search reranking, link checks, and FSRS work. Thin consumer adapters translate their local USD and result shapes onto the neutral core. An optional onAlertCrossed callback lets the composition root emit platform events while the package itself remains independent of the event bus.
Selling Points
- Actual post-call spend produces a defensible ledger instead of relying on pre-call estimates as final cost.
- Atomic increments preserve totals under concurrent jobs and return the before/after values needed for exact crossing detection.
- Named source buckets show which workflow consumed the budget without splitting company-wide umbrella accountability.
- Edge-triggered alerts avoid repetitive noise once spend is already above a threshold.
- Injected callbacks and database seams let multiple consumers integrate without coupling the package to their runtime stacks.
User Story
Universal Search completes a Voyage rerank call and derives its cost from returned token usage and model. The composition records that amount under search_rerank. When the daily line first reaches the configured percentage, the core logs the crossing and the adapter invokes the alert callback; later calls continue updating the ledger without emitting the same crossing repeatedly.
Extension Surface
Extensible is the first true rung. packages/cost-cap/src/adapters/dotabases-adapter.ts and packages/cost-cap/src/adapters/fsrs-adapter.ts adapt distinct consumer contracts over the same core, while CostCapDbLike and CostCapAlertCallback in packages/cost-cap/src/contracts.ts and packages/cost-cap/src/core.ts are injected seams. New source tokens require an in-repo registry change, so this is not a public plugin axis.
Capabilities & Limits
- Atomically aggregates daily spend and record counts by company, source, and optional agent principal.
- Computes daily and umbrella totals and first-crossing alert signals.
- Preserves optional metadata such as external or repository references and handles two database driver result shapes.
- Limits: only sources in the closed
COST_CAP_SOURCEScensus are accepted by typed adapters. - Limits: callbacks and logging are best-effort, and record failures are swallowed to preserve fail-open behavior.
Implementation Map
packages/cost-cap/src/core.tspackages/cost-cap/src/queries.tspackages/cost-cap/src/source.tspackages/cost-cap/src/adapters/dotabases-adapter.tspackages/cost-cap/src/adapters/fsrs-adapter.ts