Description
LLM and Embedding Spend Caps guard paid AI and adjacent intelligence calls against runaway daily cost. Before a consumer spends, it asks the neutral CostCapEnforcerCore to compare the estimate with the configured per-source and company-wide umbrella totals. In block mode a genuine projected overage is rejected; observe mode calculates and records the same signals without blocking; off mode avoids the ledger entirely.
Configuration is resolved per company with env-free defaults selected by the composition root. Hosted enforcement can use a conservative company umbrella while local operation remains observe-only. The same core also exposes per-principal daily totals, allowing an agent's own spend grant to be enforced separately from the company aggregate. Database failures fail open so a cost-governance outage does not wedge the underlying knowledge workflow.
Selling Points
- Caps reduce the risk that a runaway agent, enrichment job, or repeated provider call consumes an uncontrolled shared-key budget.
- Per-source and umbrella lines distinguish one expensive workflow from whole-company daily exposure.
- Observe mode lets operators measure real usage and threshold behavior before enabling blocking.
- Per-agent totals support individual spend grants without removing company-wide accountability.
- Fail-open behavior keeps a metering database fault from becoming a platform-wide availability incident.
User Story
A hosted workspace has AI spend enforcement enabled. Before an agent Chat turn, the composition estimates the call and checks both the agent's daily allowance and the company umbrella. If the projected amount exceeds a binding cap, the turn is stopped with a reason; otherwise it runs, and the completed result's usage is recorded into the ledger.
Extension Surface
Configurable is the first true rung. packages/cost-cap/src/config.ts defines off, observe, and block modes plus daily, umbrella, and threshold settings, while per-company rows can override the selected defaults. Consumers change behavior through configuration, not by replacing the enforcement algorithm. Structural adapters exist, but there is no external cap-policy plugin registry.
Capabilities & Limits
- Checks projected per-source and umbrella spend and blocks only in explicit block mode.
- Reads per-principal daily totals for agent-specific allowances.
- Supports company rows and NULL-company system aggregates with tenant-safe SQL semantics.
- Limits: pre-call checks use an estimate; authoritative accounting must record actual result usage after completion.
- Limits: database or logger failure permits the call, an intentional availability-first posture that may temporarily exceed a cap.
Implementation Map
packages/cost-cap/src/core.tspackages/cost-cap/src/config.tspackages/cost-cap/src/queries.tspackages/cost-cap/src/adapters/dotabases-adapter.tspackages/cost-cap/src/adapters/fsrs-adapter.ts