agent-budget-controller · packages

A CLI that installs a global `agent-budget` binary for managing agent budgets — defining budgets, checking remaining spend, listing active scopes, generating spend reports, simulating pre-flight checks, and manually resetting budgets.

A budget enforcement engine that provides pre-flight cost checks, real-time spend recording, and per-scope state machine transitions (Active → Warned → Degraded → Stopped) with auto-downgrade to cheaper models and expensive tool filtering. Exports a `BudgetController` class that orchestrates spend tracking, pricing, and policy evaluation, and pairs with `@reaatech/agent-budget-spend-tracker` and `@reaatech/agent-budget-pricing` at runtime.

A Fastify plugin that adds budget-aware routing to LLM Router, filtering model candidates by remaining budget and blocking requests when budgets are exhausted. It installs as the highest-priority strategy in the routing chain, evaluating before semantic and latency-based routing, and requires `@reaatech/agent-budget-engine` and `@reaatech/agent-budget-spend-tracker` at runtime.

Express/Fastify middleware and a direct SDK (`BudgetInterceptor`) that enforces per-scope budgets on agent requests by checking estimated cost, auto-downgrading models, filtering expensive tools, and recording spend — all before the LLM call reaches your application code.

Converts OpenTelemetry GenAI spans into budget-tracked spend entries in real time by feeding span attributes to a `BudgetController`. Provides a `SpanListener` class that you call with span data from any OTel-compatible tracer.

A pricing engine that computes LLM token costs using built-in or custom pricing tables, with LRU-cached lookups and model name normalization. Exports a `PricingEngine` class with `computeCost`, `estimateCost`, and `lookup` methods, plus a `ModelNormalizer` for alias resolution.

A circular-buffer-based in-memory spend tracker that records cost events and provides O(1) per-scope spend lookups, sliding-window rate calculations, cost projections, and anomaly detection—exposed as a `SpendStore` class with zero external dependencies.

Zod-validated TypeScript types, enums, and error classes defining budget scopes, policies, enforcement actions, spend entries, and state transitions for the agent-budget-controller ecosystem. Exports interfaces, enums, and Zod schemas with zero runtime dependencies beyond `zod`.