agent-orchestrator/docs/pro/features/cost-intelligence.md

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.

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

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>

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:

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.