Agent Economics
& Cost Governance

You are building the Agent Economics & Cost Governance subsystem for an autonomous AI development factory targeting insurance companies.

The system must implement the following components with full production code — no stubs, no TODOs:

## 1. Cost Metering Engine

Create `src/economics/metering_engine.ts` that:
- Intercepts every LLM API call via a wrapping proxy class `MeteredLLMClient`
- Records: agent_id, session_id, project_id, feature_id, model, input_tokens, output_tokens,
  cache_read_tokens, latency_ms, cost_usd (computed), timestamp (ISO 8601), call_id (UUID v4)
- Publishes a structured `cost_event` to the governance audit bus within 100ms of call completion
- Exposes `getCostLedger(agentId: string): CostLedger` for real-time querying
- Token costs (per 1M): Haiku input $0.80 / output $4.00 / cache $0.08;
  Sonnet input $3.00 / output $15.00 / cache $0.30;
  Opus input $15.00 / output $75.00 / cache $1.50

## 2. Budget Controller

Create `src/economics/budget_controller.ts` that:
- Maintains in-memory budget state for all active agents and projects (backed by Redis for HA)
- Enforces configurable caps: project-level (total), agent-level (per session)
- Implements threshold actions at 60% (log), 80% (downgrade model tier), 90% (throttle dispatch),
  100% (hard pause + checkpoint state)
- Anomaly detection: if agent cost-per-task exceeds 10× its 7-day rolling average, auto-pause
- Exposes `checkBudget(agentId, estimatedCost): BudgetDecision` returning ALLOW | WARN | THROTTLE | BLOCK
- Implements budget inheritance: projects distribute to agents via EQUAL | WEIGHTED | POOL strategies

## 3. Model Router

Create `src/economics/model_router.ts` that:
- Accepts a `TaskDescriptor` (type, estimated_tokens, file_count, tool_call_count, requires_reasoning)
- Returns a `RoutingDecision` (model_tier, model_id, rationale, estimated_cost_usd)
- Routing rules:
  - estimated_tokens < 4K AND single_file → Haiku
  - estimated_tokens 4K–32K AND requires_reasoning=false → Sonnet
  - estimated_tokens > 32K OR requires_reasoning=true OR type in [ARCHITECTURE, SECURITY_REVIEW] → Opus
  - Manual override available with audit log entry
- Logs every routing decision with signals used to the audit bus

## 4. Token Optimizer

Create `src/economics/token_optimizer.ts` that:
- Implements a file content cache keyed by (path, git_sha) — invalidates on commit
- Implements a semantic result cache using cosine similarity (threshold 0.95) with 24h TTL
- Implements context compression: when conversation exceeds 75% of model context window,
  summarize oldest 50% of turns into a compressed block
- Implements batched tool calls: collect tool requests within a 50ms window, dispatch as batch
- Records cache hits as `cost_savings_event` on the audit bus with estimated savings_usd

## 5. Chargeback Engine

Create `src/economics/chargeback_engine.ts` that:
- Aggregates cost ledger data by: organization → department → project → feature → agent → session
- Generates monthly reports as `ChargebackReport` objects with line-item detail
- Exports reports as CSV and JSON
- Calculates ROI: cost_ai_usd, estimated_manual_hours (story_points × hours_per_point baseline),
  estimated_manual_cost_usd (hours × hourly_rate), roi_ratio (manual_cost / ai_cost)
- Baselines configurable: default 4 hours/story-point, $150/hour developer rate

## 6. Economics Dashboard API

Create `src/economics/dashboard_api.ts` that exposes:
- GET /economics/live — real-time cost rate ($/hr), active agents, current spend vs. budget
- GET /economics/projects/:id — project cost breakdown with budget status
- GET /economics/agents/:id/session — current session cost by agent
- GET /economics/trends?days=30 — historical daily costs with 14-day forecast
- GET /economics/chargeback?month=YYYY-MM — chargeback report for period
- WebSocket /economics/stream — real-time cost event stream for dashboard

## 7. Alert Dispatcher

Create `src/economics/alert_dispatcher.ts` that:
- Listens for threshold and anomaly events from Budget Controller
- Dispatches to: Slack (webhook URL per project), email (configurable recipients via nodemailer),
  outbound webhook (HMAC-SHA256 signed payload)
- Retries failed deliveries up to 3× with exponential backoff (1s, 2s, 4s)
- Logs all alert delivery attempts (success/failure) to audit trail

## 8. Integration

Wire all components in `src/economics/index.ts`:
- Export a single `EconomicsLayer` class that initializes all subsystems
- Accept config: `EconomicsConfig` with budget caps, model prices, cache TTLs, alert channels
- All cost events must flow through the central `GovernanceAuditBus` from the governance module
- Integrate with the Orchestration layer: wrap agent dispatch in `EconomicsLayer.authorizeDispatch()`

## Technical requirements:
- TypeScript strict mode, no `any` types
- All monetary values stored as integer cents (not floats) to avoid rounding errors
- Redis for budget state (ioredis client), PostgreSQL for cost ledger (via existing DB layer)
- All public methods must have JSDoc with parameter and return type documentation
- Unit tests in `src/economics/__tests__/` using Vitest, ≥80% coverage
- No hardcoded secrets — all config via environment variables

// Core types shared across subsystem boundaries

interface CostEvent {
  event_id: string;        // UUID v4
  event_type: 'llm_call' | 'tool_use' | 'external_api' | 'cache_hit';
  agent_id: string;
  session_id: string;
  project_id: string;
  feature_id: string | null;
  model: string;
  input_tokens: number;
  output_tokens: number;
  cache_read_tokens: number;
  cost_cents: number;         // integer cents, never float
  latency_ms: number;
  timestamp: string;          // ISO 8601
}

interface DispatchAuthorization {
  authorized: boolean;
  model_tier: 'haiku' | 'sonnet' | 'opus';
  model_id: string;
  budget_remaining_cents: number;
  throttle_active: boolean;
  block_reason: string | null;
}

interface BudgetDecision {
  decision: 'ALLOW' | 'WARN' | 'THROTTLE' | 'BLOCK';
  threshold_pct: number;
  spent_cents: number;
  cap_cents: number;
  anomaly: boolean;
}