The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
use super::route::route_for_model;
use super::types::{
BudgetStatus, CostDashboard, CostRecord, CostSource, CostSummary, DailyCostEntry, ModelStats,
TokenUsage,
};
use crate::config::CostConfig;
use anyhow::{anyhow, Context, Result};
use chrono::{Datelike, Duration, NaiveDate, Utc};
use parking_lot::{Mutex, MutexGuard};
use std::collections::{BTreeMap, HashMap};
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::Arc;
/// Cost tracker for API usage monitoring and budget enforcement.
pub struct CostTracker {
config: CostConfig,
workspace_dir: PathBuf,
storage: Arc<Mutex<CostStorage>>,
session_id: String,
session_costs: Arc<Mutex<Vec<CostRecord>>>,
}
impl CostTracker {
/// Create a new cost tracker.
pub fn new(config: CostConfig, workspace_dir: &Path) -> Result<Self> {
let storage_path = resolve_storage_path(workspace_dir)?;
let storage = CostStorage::new(workspace_dir, &storage_path);
Ok(Self {
config,
workspace_dir: workspace_dir.to_path_buf(),
storage: Arc::new(Mutex::new(storage)),
session_id: uuid::Uuid::new_v4().to_string(),
session_costs: Arc::new(Mutex::new(Vec::new())),
})
}
/// Get the session ID.
pub fn session_id(&self) -> &str {
&self.session_id
}
/// Workspace this tracker persists into.
pub fn workspace_dir(&self) -> &Path {
&self.workspace_dir
}
fn lock_storage(&self) -> MutexGuard<'_, CostStorage> {
self.storage.lock()
}
fn lock_session_costs(&self) -> MutexGuard<'_, Vec<CostRecord>> {
self.session_costs.lock()
}
// `check_budget` and `BudgetCheck` were removed with the spend cap. Nothing
// in the core refuses a request on cost any more: managed-credit
// exhaustion is enforced server-side by the backend, which returns its own
// billing error, and that is the only spend limit a user can now hit.
// Recording below is untouched — the dashboard still sees every cost.
/// Record a usage event.
///
/// Honours `cost.enabled` — when budget enforcement is disabled the call
/// is a no-op. Use [`Self::record_usage_unconditional`] for telemetry
/// paths (dashboard, observability) that must capture data even when
/// the budget enforcement path is off, so the user can flip enforcement
/// on later without losing history.
pub fn record_usage(&self, usage: TokenUsage) -> Result<()> {
if !self.config.enabled {
return Ok(());
}
self.record_usage_unconditional(usage)
}
/// Persist a usage event ignoring `cost.enabled`. Used by the dashboard
/// telemetry hook so cost history is recorded regardless of whether the
/// budget-enforcement gate is on.
pub fn record_usage_unconditional(&self, usage: TokenUsage) -> Result<()> {
if !usage.cost_usd.is_finite() || usage.cost_usd < 0.0 {
return Err(anyhow!(
"Token usage cost must be a finite, non-negative value"
));
}
let record = CostRecord::new(&self.session_id, usage);
// Persist first for durability guarantees.
{
let mut storage = self.lock_storage();
storage.add_record(record.clone())?;
}
// Then update in-memory session snapshot.
let mut session_costs = self.lock_session_costs();
session_costs.push(record);
Ok(())
}
/// Get the current cost summary.
pub fn get_summary(&self) -> Result<CostSummary> {
let (daily_cost, monthly_cost) = {
let mut storage = self.lock_storage();
storage.get_aggregated_costs()?
};
let session_costs = self.lock_session_costs();
let session_cost: f64 = non_negative_zero(
session_costs
.iter()
.map(|record| record.usage.cost_usd)
.sum(),
);
let total_tokens: u64 = session_costs
.iter()
.map(|record| record.usage.total_tokens)
.sum();
let request_count = session_costs.len();
let by_model = build_session_model_stats(&session_costs);
Ok(CostSummary {
session_cost_usd: session_cost,
daily_cost_usd: daily_cost,
monthly_cost_usd: monthly_cost,
total_tokens,
request_count,
by_model,
})
}
/// Get the daily cost for a specific date.
pub fn get_daily_cost(&self, date: NaiveDate) -> Result<f64> {
let storage = self.lock_storage();
storage.get_cost_for_date(date)
}
/// Get the monthly cost for a specific month, across all routes.
pub fn get_monthly_cost(&self, year: i32, month: u32) -> Result<f64> {
let storage = self.lock_storage();
storage.get_cost_for_month(year, month)
}
/// Get the **managed-route** monthly cost for a specific month — the
/// portion of spend the local `[cost]` budget applies to (#5016). BYOK and
/// local inference is excluded because OpenHuman never bills for it.
pub fn get_managed_monthly_cost(&self, year: i32, month: u32) -> Result<f64> {
let storage = self.lock_storage();
storage.get_managed_cost_for_month(year, month)
}
/// Get a daily cost/token history covering the last `days` calendar days,
/// ending on today (UTC) inclusive. Days with no recorded usage are
/// returned as zero-filled entries so callers can render the chart bars
/// without gap handling. Oldest day first.
///
/// `days` is clamped to the range `[1, 366]` to bound the scan window.
pub fn get_daily_history(&self, days: u32) -> Result<Vec<DailyCostEntry>> {
let span = days.clamp(1, 366) as i64;
let today = Utc::now().date_naive();
let earliest = today
.checked_sub_signed(Duration::days(span - 1))
.ok_or_else(|| anyhow!("Daily history range underflowed"))?;
let mut buckets: BTreeMap<NaiveDate, DailyCostEntry> = BTreeMap::new();
let storage = self.lock_storage();
storage.for_each_record(|record| {
let date = record.usage.timestamp.naive_utc().date();
if date < earliest || date > today {
return;
}
let entry = buckets
.entry(date)
.or_insert_with(|| DailyCostEntry::empty(date));
entry.cost_usd += record.usage.cost_usd;
entry.input_tokens = entry.input_tokens.saturating_add(record.usage.input_tokens);
entry.output_tokens = entry
.output_tokens
.saturating_add(record.usage.output_tokens);
entry.total_tokens = entry.total_tokens.saturating_add(record.usage.total_tokens);
entry.request_count += 1;
let model_entry = entry
.by_model
.entry(record.usage.model.clone())
.or_insert_with(|| ModelStats {
model: record.usage.model.clone(),
cost_usd: 0.0,
total_tokens: 0,
request_count: 0,
unpriced_request_count: 0,
});
model_entry.cost_usd += record.usage.cost_usd;
model_entry.total_tokens = model_entry
.total_tokens
.saturating_add(record.usage.total_tokens);
model_entry.request_count += 1;
if record.usage.cost_source == CostSource::Unknown {
model_entry.unpriced_request_count += 1;
}
})?;
let mut out = Vec::with_capacity(span as usize);
for offset in 0..span {
let date = earliest + Duration::days(offset);
out.push(
buckets
.remove(&date)
.unwrap_or_else(|| DailyCostEntry::empty(date)),
);
}
Ok(out)
}
/// Return recent persisted usage records, newest first.
///
/// `days` is a rolling window ending now: `days = 1` is the last 24 hours,
/// matching what the dashboard promises the user ("Newest records from the
/// last {days} days").
///
/// The window is `days * 24h` back from this instant, NOT `days - 1`.
/// [`Self::get_daily_history`] subtracts `span - 1` and is right to: it
/// compares *dates* and needs N calendar days counting today, so
/// `today - (N - 1)` is the Nth day back. Here the comparison is against an
/// *instant*, so the same `- 1` shortens the window by a full day — and at
/// `days = 1` collapses it to zero, making `earliest == now` and rejecting
/// every record ever written (#6482). Wider windows hid it: `days = 30`,
/// the dashboard's default, quietly returned 29.
///
/// `days` is clamped to `[1, 366]` and `limit` to `[1, 1000]` to keep
/// dashboard calls bounded while still allowing a detailed audit log.
pub fn get_recent_records(&self, days: u32, limit: usize) -> Result<Vec<CostRecord>> {
let span = days.clamp(1, 366) as i64;
let limit = limit.clamp(1, 1000);
let now = Utc::now();
let earliest = now
.checked_sub_signed(Duration::days(span))
.ok_or_else(|| anyhow!("Usage log range underflowed"))?;
let mut records: Vec<CostRecord> = Vec::new();
let storage = self.lock_storage();
storage.for_each_record(|record| {
if record.usage.timestamp < earliest || record.usage.timestamp > now {
return;
}
records.push(record);
})?;
records.sort_by(|a, b| {
b.usage
.timestamp
.cmp(&a.usage.timestamp)
.then_with(|| b.id.cmp(&a.id))
});
records.truncate(limit);
Ok(records)
}
/// Every record timestamped in `[from, to]`, oldest first — the input to
/// [`super::report`]. The window is capped at 366 days, like the other
/// reads, so one call never scans more history than the dashboard does.
pub fn records_between(
&self,
from: chrono::DateTime<Utc>,
to: chrono::DateTime<Utc>,
) -> Result<Vec<CostRecord>> {
let floor = to
.checked_sub_signed(Duration::days(366))
.ok_or_else(|| anyhow!("Usage report range underflowed"))?;
let from = from.max(floor);
let mut records: Vec<CostRecord> = Vec::new();
let storage = self.lock_storage();
storage.for_each_record(|record| {
if record.usage.timestamp >= from && record.usage.timestamp <= to {
records.push(record);
}
})?;
records.sort_by_key(|record| record.usage.timestamp);
Ok(records)
}
/// Build the full dashboard payload: 7-day history, period total,
/// projected monthly pace (daily avg × 30), and budget utilisation
/// derived from the configured monthly limit and warn/alert thresholds.
///
/// `warn_threshold` / `alert_threshold` are fractions of the monthly
/// budget — e.g. 0.8 (warn at 80%) and 0.95 (alert at 95%). When the
/// monthly limit is non-positive, status falls back to `Normal`.
pub fn get_dashboard(
&self,
currency: &str,
warn_threshold: f64,
alert_threshold: f64,
) -> Result<CostDashboard> {
let days = self.get_daily_history(7)?;
let period_total_usd: f64 = non_negative_zero(days.iter().map(|d| d.cost_usd).sum());
let daily_average = period_total_usd / days.len().max(1) as f64;
let monthly_pace_usd = daily_average * 30.0;
let budget_limit_monthly_usd = self.config.monthly_limit_usd.max(0.0);
let now = Utc::now();
// `month_to_date_usd` stays an all-route total: users want to see what
// their BYOK providers cost them. Budget utilisation and status,
// however, describe a limit that only gates *managed* spend (#5016) —
// driving them off the total made a pure-BYOK user's gauge fill to
// 100% against a cap that can never fire, which is the phantom limit
// reported in the issue.
let month_to_date_usd = self.get_monthly_cost(now.year(), now.month())?;
let managed_month_to_date_usd = self.get_managed_monthly_cost(now.year(), now.month())?;
let budget_utilization = if budget_limit_monthly_usd > 0.0 {
(managed_month_to_date_usd / budget_limit_monthly_usd).clamp(0.0, 1.0)
} else {
0.0
};
let budget_status = if budget_limit_monthly_usd <= 0.0 {
BudgetStatus::Normal
} else {
let warn = warn_threshold.clamp(0.0, 1.0);
let alert = alert_threshold.clamp(0.0, 1.0).max(warn);
let utilization_raw = managed_month_to_date_usd / budget_limit_monthly_usd;
if utilization_raw >= alert {
BudgetStatus::Exceeded
} else if utilization_raw >= warn {
BudgetStatus::Warning
} else {
BudgetStatus::Normal
}
};
let mut by_model_totals: HashMap<String, ModelStats> = HashMap::new();
for day in &days {
for (model, stats) in &day.by_model {
let entry = by_model_totals
.entry(model.clone())
.or_insert_with(|| ModelStats {
model: model.clone(),
cost_usd: 0.0,
total_tokens: 0,
request_count: 0,
unpriced_request_count: 0,
});
entry.cost_usd += stats.cost_usd;
entry.total_tokens = entry.total_tokens.saturating_add(stats.total_tokens);
entry.request_count += stats.request_count;
entry.unpriced_request_count += stats.unpriced_request_count;
}
}
let mut by_model: Vec<ModelStats> = by_model_totals.into_values().collect();
by_model.sort_by(|a, b| {
b.cost_usd
.partial_cmp(&a.cost_usd)
.unwrap_or(std::cmp::Ordering::Equal)
.then_with(|| a.model.cmp(&b.model))
});
Ok(CostDashboard {
days,
period_total_usd,
monthly_pace_usd,
budget_limit_monthly_usd,
month_to_date_usd,
budget_utilization,
budget_status,
currency: currency.to_string(),
by_model,
})
}
}
/// An empty `f64` sum is `-0.0`, which serialises as `-0.0` and renders as
/// "-$0.00". Every derived total goes through this.
pub(super) fn non_negative_zero(value: f64) -> f64 {
if value == 0.0 {
0.0
} else {
value
}
}
/// Rows the budget gate once wrote as `host:<agent_id>` with an estimated cost
/// of zero. The event bridge already recorded the same model call under its
/// real model, so these only double the token and request counts. Ledgers
/// written before that stopped still hold them; every read skips them.
fn is_legacy_host_duplicate(record: &CostRecord) -> bool {
record.usage.model.starts_with("host:") && record.usage.cost_source == CostSource::Estimated
}
fn resolve_storage_path(workspace_dir: &Path) -> Result<PathBuf> {
let storage_path = workspace_dir.join("state").join("costs.jsonl");
let legacy_path = workspace_dir.join(".openhuman").join("costs.db");
if !storage_path.exists() && legacy_path.exists() {
if let Some(parent) = storage_path.parent() {
fs::create_dir_all(parent)
.with_context(|| format!("Failed to create directory {}", parent.display()))?;
}
if let Err(error) = fs::rename(&legacy_path, &storage_path) {
tracing::warn!(
"Failed to move legacy cost storage from {} to {}: {error}; falling back to copy",
legacy_path.display(),
storage_path.display()
);
fs::copy(&legacy_path, &storage_path).with_context(|| {
format!(
"Failed to copy legacy cost storage from {} to {}",
legacy_path.display(),
storage_path.display()
)
})?;
}
}
Ok(storage_path)
}
fn build_session_model_stats(session_costs: &[CostRecord]) -> HashMap<String, ModelStats> {
let mut by_model: HashMap<String, ModelStats> = HashMap::new();
for record in session_costs {
let entry = by_model
.entry(record.usage.model.clone())
.or_insert_with(|| ModelStats {
model: record.usage.model.clone(),
cost_usd: 0.0,
total_tokens: 0,
request_count: 0,
unpriced_request_count: 0,
});
entry.cost_usd += record.usage.cost_usd;
entry.total_tokens += record.usage.total_tokens;
entry.request_count += 1;
if record.usage.cost_source == CostSource::Unknown {
entry.unpriced_request_count += 1;
}
}
by_model
}
/// Persistent storage for cost records.
struct CostStorage {
/// Workspace whose default backend serves the ledger when the host
/// installed none.
workspace_dir: PathBuf,
/// The legacy JSONL ledger, imported into the document ledger once.
path: PathBuf,
daily_cost_usd: f64,
monthly_cost_usd: f64,
/// Managed-route subset of `daily_cost_usd` — the only spend the local
/// `[cost]` budget may gate (#5016). BYOK/local spend is still counted in
/// the totals above so the dashboard shows it, but never here.
daily_managed_cost_usd: f64,
/// Managed-route subset of `monthly_cost_usd`. See above.
monthly_managed_cost_usd: f64,
}
impl CostStorage {
/// Open the cost ledger. The records live in documents under the acting
/// agent's scope, which is only known per call, so there is no directory
/// to make and no aggregate to prime here.
fn new(workspace_dir: &Path, path: &Path) -> Self {
Self {
workspace_dir: workspace_dir.to_path_buf(),
path: path.to_path_buf(),
daily_cost_usd: 0.0,
monthly_cost_usd: 0.0,
daily_managed_cost_usd: 0.0,
monthly_managed_cost_usd: 0.0,
}
}
fn for_each_record<F>(&self, mut on_record: F) -> Result<()>
where
F: FnMut(CostRecord),
{
let docs = super::tracker_documents::current(&self.workspace_dir)?;
self.import_legacy_once(&docs)?;
for record in docs.all()? {
if !is_legacy_host_duplicate(&record) {
on_record(record);
}
}
Ok(())
}
/// The workspace's JSONL ledger predates the backend and belongs to the
/// single-user (`local`) scope; import it into that scope once.
/// Once per process for the backend instance (see
/// `CostDocs::import_legacy_once`).
fn import_legacy_once(&self, docs: &super::tracker_documents::CostDocs) -> Result<()> {
if crate::storage::current_scope().ok() != Some(crate::storage::Scope::local()) {
return Ok(());
}
docs.import_legacy_once(&self.path)
}
fn rebuild_aggregates(&mut self, day: NaiveDate, year: i32, month: u32) -> Result<()> {
let mut daily_cost = 0.0;
let mut monthly_cost = 0.0;
let mut daily_managed_cost = 0.0;
let mut monthly_managed_cost = 0.0;
self.for_each_record(|record| {
let timestamp = record.usage.timestamp.naive_utc();
// Classified from the record's own model id, so records written by
// builds that predate #5016 are routed correctly with no migration.
let counts = route_for_model(&record.usage.model).counts_toward_budget();
if timestamp.date() == day {
daily_cost += record.usage.cost_usd;
if counts {
daily_managed_cost += record.usage.cost_usd;
}
}
if timestamp.year() == year && timestamp.month() == month {
monthly_cost += record.usage.cost_usd;
if counts {
monthly_managed_cost += record.usage.cost_usd;
}
}
})?;
self.daily_cost_usd = daily_cost;
self.monthly_cost_usd = monthly_cost;
self.daily_managed_cost_usd = daily_managed_cost;
self.monthly_managed_cost_usd = monthly_managed_cost;
Ok(())
}
/// Add a new record.
fn add_record(&mut self, record: CostRecord) -> Result<()> {
let docs = super::tracker_documents::current(&self.workspace_dir)?;
// The legacy ledger goes in before the first document, so history
// is never split across the two.
self.import_legacy_once(&docs)?;
docs.add(&record)
}
/// Get aggregated costs for current day and month, across **all** routes.
/// This is the dashboard/summary figure — use
/// [`Self::get_aggregated_managed_costs`] for anything that gates a
/// request.
fn get_aggregated_costs(&mut self) -> Result<(f64, f64)> {
// The totals are recomputed from the acting scope's records on every
// call: the scope changes per call, so a process-wide cache would leak
// one agent's spend into another's.
let now = Utc::now();
self.rebuild_aggregates(now.date_naive(), now.year(), now.month())?;
Ok((self.daily_cost_usd, self.monthly_cost_usd))
}
/// Get cost for a specific date.
fn get_cost_for_date(&self, date: NaiveDate) -> Result<f64> {
let mut cost = 0.0;
self.for_each_record(|record| {
if record.usage.timestamp.naive_utc().date() == date {
cost += record.usage.cost_usd;
}
})?;
Ok(cost)
}
/// Get cost for a specific month.
fn get_cost_for_month(&self, year: i32, month: u32) -> Result<f64> {
let mut cost = 0.0;
self.for_each_record(|record| {
let timestamp = record.usage.timestamp.naive_utc();
if timestamp.year() == year && timestamp.month() == month {
cost += record.usage.cost_usd;
}
})?;
Ok(cost)
}
/// Get **managed-route** cost for a specific month — the figure the budget
/// gauge should reflect, since only managed spend can trip the limit
/// (#5016).
fn get_managed_cost_for_month(&self, year: i32, month: u32) -> Result<f64> {
let mut cost = 0.0;
self.for_each_record(|record| {
let timestamp = record.usage.timestamp.naive_utc();
if timestamp.year() == year
&& timestamp.month() == month
&& route_for_model(&record.usage.model).counts_toward_budget()
{
cost += record.usage.cost_usd;
}
})?;
Ok(cost)
}
}
#[cfg(test)]
#[path = "tracker_tests.rs"]
mod tests;