# Cost Intelligence

> This documentation covers Pro edition features available in the agents-orchestrator/agents-orchestrator private repository.

Cost Intelligence comprises two systems: the Budget Governor (hard cost controls) and the Smart Model Router (cost-aware model selection). Both operate at the per-project level and integrate with the agent launch pipeline.

---

## Budget Governor

### Purpose

The Budget Governor enforces per-project monthly token budgets. It prevents runaway costs by warning at a soft limit and blocking agent launches at a hard limit.

### Budget Configuration

Each project can have a monthly budget with two thresholds:

| Threshold | Default | Behavior |
|-----------|---------|----------|
| Soft limit | 80% of budget | Emits a warning notification. Agent proceeds. |
| Hard limit | 100% of budget | Blocks agent launch. Returns error to UI. |

Budgets are denominated in USD. The governor tracks cumulative cost for the current calendar month by summing `cost_usd` from `session_metrics` and `pro_budget_log`.

### Emergency Override

When the hard limit is reached, the UI displays a confirmation dialog with the current spend and budget. The user can authorize an emergency override that allows the next session to proceed. Overrides are logged in `pro_budget_log` with `override = true`. Each override is single-use; subsequent launches require a new override.

### SQLite Tables

Both tables reside in `agor_pro.db`.

```sql
CREATE TABLE pro_budgets (
    project_id TEXT PRIMARY KEY,
    monthly_budget_usd REAL NOT NULL,
    soft_limit_pct REAL NOT NULL DEFAULT 0.80,
    hard_limit_pct REAL NOT NULL DEFAULT 1.00,
    created_at TEXT NOT NULL DEFAULT (datetime('now')),
    updated_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE TABLE pro_budget_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    project_id TEXT NOT NULL,
    session_id TEXT NOT NULL,
    cost_usd REAL NOT NULL,
    cumulative_usd REAL NOT NULL,
    month TEXT NOT NULL,          -- YYYY-MM format
    override INTEGER NOT NULL DEFAULT 0,
    logged_at TEXT NOT NULL DEFAULT (datetime('now'))
);
```

### Commands

#### pro_budget_set

Creates or updates a budget for a project.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |
| `monthlyBudgetUsd` | `f64` | Yes | Monthly budget in USD |
| `softLimitPct` | `f64` | No | Soft limit percentage (default 0.80) |
| `hardLimitPct` | `f64` | No | Hard limit percentage (default 1.00) |

#### pro_budget_get

Returns the budget configuration for a project. Returns `null` if no budget is set.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |

#### pro_budget_check

Pre-dispatch hook. Checks whether the project can launch a new agent session.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |

**Response: `BudgetCheckResult`**

```typescript
interface BudgetCheckResult {
  allowed: boolean;
  currentSpendUsd: number;
  budgetUsd: number;
  pctUsed: number;           // 0.0 to 1.0
  softLimitReached: boolean;
  hardLimitReached: boolean;
  month: string;             // YYYY-MM
}
```

#### pro_budget_log_usage

Records cost for a completed session. Called by the agent dispatcher on session end.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |
| `sessionId` | `String` | Yes | Session identifier |
| `costUsd` | `f64` | Yes | Session cost |
| `override` | `bool` | No | Whether this was an emergency override |

#### pro_budget_reset

Resets the cumulative spend for a project's current month. Deletes all `pro_budget_log` entries for the current month.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |

#### pro_budget_list

Returns budgets and current spend for all projects.

**Response: `Vec<ProjectBudgetStatus>`**

```typescript
interface ProjectBudgetStatus {
  projectId: string;
  monthlyBudgetUsd: number;
  currentSpendUsd: number;
  pctUsed: number;
  softLimitReached: boolean;
  hardLimitReached: boolean;
}
```

### Pre-Dispatch Integration

The budget check is wired into the agent launch path:

1. User triggers agent start in AgentPane.
2. `AgentSession.startQuery()` calls `pro_budget_check` before invoking the sidecar.
3. If `softLimitReached`: toast warning, agent proceeds.
4. If `hardLimitReached`: blocks launch, shows override dialog.
5. On override confirmation: calls `pro_budget_log_usage` with `override: true`, then proceeds.
6. On session completion: `agent-dispatcher` calls `pro_budget_log_usage` with actual cost.

---

## Smart Model Router

### Purpose

The Smart Model Router recommends which model to use for a given agent session based on the project's routing profile and the agent's role. It does not force model selection -- it provides a recommendation that the user can accept or override.

### Routing Profiles

Three built-in profiles define model preferences:

#### CostSaver

Minimizes cost by preferring smaller models for routine tasks.

| Role | Recommended Model |
|------|-------------------|
| Manager | claude-sonnet-4-5-20250514 |
| Architect | claude-sonnet-4-5-20250514 |
| Tester | claude-haiku-4-5-20250514 |
| Reviewer | claude-haiku-4-5-20250514 |
| Default (no role) | claude-sonnet-4-5-20250514 |

#### QualityFirst

Maximizes output quality by preferring the most capable model.

| Role | Recommended Model |
|------|-------------------|
| Manager | claude-opus-4-5-20250514 |
| Architect | claude-opus-4-5-20250514 |
| Tester | claude-sonnet-4-5-20250514 |
| Reviewer | claude-sonnet-4-5-20250514 |
| Default (no role) | claude-opus-4-5-20250514 |

#### Balanced

Default profile. Balances cost and quality per role.

| Role | Recommended Model |
|------|-------------------|
| Manager | claude-sonnet-4-5-20250514 |
| Architect | claude-opus-4-5-20250514 |
| Tester | claude-haiku-4-5-20250514 |
| Reviewer | claude-sonnet-4-5-20250514 |
| Default (no role) | claude-sonnet-4-5-20250514 |

### Commands

#### pro_router_recommend

Returns the recommended model for a given project and role.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |
| `role` | `String` | No | Agent role (manager/architect/tester/reviewer) |

**Response:**

```typescript
interface RouterRecommendation {
  model: string;
  profile: string;       // CostSaver | QualityFirst | Balanced
  reason: string;        // Human-readable explanation
}
```

#### pro_router_set_profile

Sets the routing profile for a project.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |
| `profile` | `String` | Yes | Profile name: CostSaver, QualityFirst, or Balanced |

#### pro_router_get_profile

Returns the current routing profile for a project. Defaults to Balanced.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `projectId` | `String` | Yes | Project identifier |

#### pro_router_list_profiles

Returns all available routing profiles with their role-to-model mappings. Takes no arguments.

### Integration with Agent Launch

The router recommendation is surfaced in the AgentPane model selector. When a project has a routing profile set, the recommended model appears as a highlighted option in the dropdown. The user retains full control to select any available model.