Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

9.5 KB
Raw Blame
/// Turning scanned entries into the figures the panel prints.
///
/// Pure on purpose — no disk, no clock beyond what it is handed — because this
/// is where every claim the panel makes is actually decided, and an arithmetic
/// bug here is invisible on screen. `test/usage_ledger_test.dart` drives these
/// directly.
library;

import 'ledger_types.dart';
import 'ledger_scanner.dart';
import 'model_pricing.dart';

/// One provider's entries, deduplicated, totalled and priced.
///
/// [sources] may hold the same exchange twice — see [LedgerEntry.dedupeKey] for
/// why resuming a session copies records into a second file — so the first stop
/// is dropping repeats. An entry with no dedupe key is always kept: no key means
/// the provider gave nothing stable to match on, and guessing that two such
/// entries are the same exchange would silently delete real spend.
ProviderLedger buildProviderLedger(
  LedgerProvider provider,
  Iterable<ScannedSource> sources,
) {
  final seen = <String>{};
  final entries = <LedgerEntry>[];
  for (final source in sources) {
    for (final entry in source.entries) {
      final key = entry.dedupeKey;
      if (key != null && !seen.add(key)) continue;
      entries.add(entry);
    }
  }
  entries.sort((a, b) => a.timestamp.compareTo(b.timestamp));
  return ledgerFromEntries(provider, entries);
}

/// The same totalling over entries that are already deduplicated and sorted.
///
/// Split out of [buildProviderLedger] so a date-range view can reuse the exact
/// arithmetic rather than growing a second copy of it — a clipped ledger that
/// summed its cost differently from the full one would be a bug nobody could
/// see, since both figures look plausible on their own.
ProviderLedger ledgerFromEntries(
  LedgerProvider provider,
  List<LedgerEntry> entries,
) {
  var totals = const UsageTotals();
  final sessions = <String>{};
  double? cost;
  var hasUnpriced = false;
  for (final entry in entries) {
    totals += entry.totals;
    sessions.add(entry.sessionId);
    // The provider's own figure wins where there is one; otherwise the model
    // name is priced. A model nothing prices leaves the running total alone and
    // raises the flag — see `ProviderLedger.hasUnpricedModel`.
    final entryCost =
        entry.costUsd ?? costOf(provider, entry.model, entry.totals);
    if (entryCost == null) {
      hasUnpriced = true;
    } else {
      cost = (cost ?? 0) + entryCost;
    }
  }

  return ProviderLedger(
    provider: provider,
    entries: entries,
    totals: totals,
    costUsd: cost,
    hasUnpricedModel: hasUnpriced,
    sessionCount: sessions.length,
  );
}

/// One provider's entries collapsed to one row per local day, oldest first.
List<LedgerDay> dailyTotals(ProviderLedger ledger) {
  final byDay = <DateTime, List<LedgerEntry>>{};
  for (final entry in ledger.entries) {
    // Local midnight, not UTC: somebody reading "yesterday" means the day they
    // had, not the one Greenwich had.
    final day = DateTime(
      entry.timestamp.year,
      entry.timestamp.month,
      entry.timestamp.day,
    );
    (byDay[day] ??= []).add(entry);
  }
  final days = byDay.keys.toList()..sort();
  return [
    for (final day in days)
      () {
        var totals = const UsageTotals();
        double? cost;
        for (final entry in byDay[day]!) {
          totals += entry.totals;
          final entryCost =
              entry.costUsd ??
              costOf(ledger.provider, entry.model, entry.totals);
          if (entryCost != null) cost = (cost ?? 0) + entryCost;
        }
        return LedgerDay(day: day, totals: totals, costUsd: cost);
      }(),
  ];
}

/// Every provider added together — what the four cards at the top of the panel
/// read from.
class UsageOverview {
  const UsageOverview({
    required this.providers,
    required this.totals,
    required this.days,
    this.costUsd,
    this.hasUnpricedModel = false,
    this.sessionCount = 0,
    this.enabledCount = 0,
    this.lastScanAt,
  });

  /// How many providers the user has switched on.
  ///
  /// Held rather than derived: a provider can be on and still have nothing to
  /// show — mid-scan, or with the CLI not installed — so "how many are on" and
  /// "how many answered" are different questions. Conflating them is what makes
  /// an empty panel unreadable.
  final int enabledCount;

  /// Every provider's ledger, in a stable order, enabled or not.
  final List<ProviderLedger> providers;

  final UsageTotals totals;

  /// One row per local day that had any spend at all, oldest first.
  final List<LedgerDay> days;

  /// The bill across every provider that could be priced.
  ///
  /// **A floor, not a total, when [hasUnpricedModel] is true.** The panel says
  /// so beside the figure rather than rounding the doubt away.
  final double? costUsd;

  final bool hasUnpricedModel;
  final int sessionCount;

  /// The most recent successful scan across the providers, for the "Updated …"
  /// line. Null before any provider has scanned.
  final DateTime? lastScanAt;

  /// Days with any spend on them. What the "Active days" card counts.
  int get activeDays => days.length;

  /// How much of the input was served from cache, 0–1, or null when there was no
  /// input at all.
  ///
  /// **Null rather than zero on an empty ledger**: a cache share of 0% is a
  /// measurement — nothing was cached — and having spent nothing yet is not
  /// that. The card prints `n/a`.
  double? get cacheShare {
    final read = totals.cacheRead;
    final fresh = totals.freshInput;
    if (read + fresh == 0) return null;
    return read / (read + fresh);
  }

  /// The heaviest day, for the intensity grid's scale. Null when there are none.
  LedgerDay? get bestDay {
    if (days.isEmpty) return null;
    return days.reduce((a, b) => b.totals.total > a.totals.total ? b : a);
  }

  int get dataProviderCount => providers.where((p) => p.hasData).length;
  bool get hasAnyData => providers.any((p) => p.hasData);
}

/// Fold every provider's ledger into one overview.
UsageOverview buildOverview({
  required List<ProviderLedger> ledgers,
  required int enabledCount,
  DateTime? lastScanAt,
}) {
  var totals = const UsageTotals();
  double? cost;
  var hasUnpriced = false;
  var sessions = 0;
  final byDay = <DateTime, LedgerDay>{};

  for (final ledger in ledgers) {
    totals += ledger.totals;
    sessions += ledger.sessionCount;
    if (ledger.hasUnpricedModel) hasUnpriced = true;
    if (ledger.costUsd != null) cost = (cost ?? 0) + ledger.costUsd!;
    for (final day in dailyTotals(ledger)) {
      final existing = byDay[day.day];
      byDay[day.day] = existing == null
          ? day
          : LedgerDay(
              day: day.day,
              totals: existing.totals + day.totals,
              costUsd: existing.costUsd == null && day.costUsd == null
                  ? null
                  : (existing.costUsd ?? 0) + (day.costUsd ?? 0),
            );
    }
  }

  final days = byDay.keys.toList()..sort();
  return UsageOverview(
    providers: ledgers,
    totals: totals,
    days: [for (final day in days) byDay[day]!],
    costUsd: cost,
    hasUnpricedModel: hasUnpriced,
    sessionCount: sessions,
    enabledCount: enabledCount,
    lastScanAt: lastScanAt,
  );
}

/// The last [count] days ending today, including the empty ones.
///
/// The gaps are the point: an intensity grid drawn only from days that had spend
/// would pack a fortnight of work into a row and hide that half of it was a
/// weekend.
List<LedgerDay> recentDays(List<LedgerDay> days, int count, {DateTime? now}) {
  final today = now ?? DateTime.now();
  final end = DateTime(today.year, today.month, today.day);
  final byDay = {for (final day in days) day.day: day};
  return [
    for (var i = count - 1; i >= 0; i--)
      () {
        final day = DateTime(end.year, end.month, end.day - i);
        return byDay[day] ?? LedgerDay(day: day, totals: const UsageTotals());
      }(),
  ];
}

/// `3.2B`, `1.2M`, `48.3k`, `912` — a token count at a glance.
///
/// ⚠️ **Billions are a real tier here, not a theoretical one.** A single heavy
/// month of Claude Code runs to thousands of millions, and `3652.0M` is a figure
/// nobody can read at a glance — which is the whole job of this function. Orca's
/// `formatUsageTokens` breaks at the same three thresholds, down to the
/// lowercase `k`.
String formatTokens(int tokens) {
  if (tokens >= 1000000000) {
    return '${(tokens / 1000000000).toStringAsFixed(1)}B';
  }
  if (tokens >= 1000000) {
    return '${(tokens / 1000000).toStringAsFixed(1)}M';
  }
  if (tokens >= 1000) {
    return '${(tokens / 1000).toStringAsFixed(1)}k';
  }
  return '$tokens';
}

/// How dark a day's cell is drawn, `0`–`4`.
///
/// Five buckets rather than a continuous alpha, as Orca does: a heatmap is read
/// by comparing squares to each other, and a smooth ramp gives the eye no steps
/// to compare. `0` is reserved for a day with nothing on it, so "quiet" and
/// "barely busy" can never render the same.
int intensityBucket(int tokens, int peak) {
  if (tokens <= 0 || peak <= 0) return 0;
  final ratio = tokens / peak;
  if (ratio <= 0.25) return 1;
  if (ratio <= 0.5) return 2;
  if (ratio <= 0.75) return 3;
  return 4;
}

/// A bill in USD, or `n/a` when nothing could be priced.
///
/// Sub-cent amounts keep four decimals rather than rounding to `$0.00`, which
/// would read as free — the exact mistake the nullable cost exists to avoid.
String formatCost(double? cost) {
  if (cost == null) return 'n/a';
  if (cost > 0 && cost < 0.01) return '\$${cost.toStringAsFixed(4)}';
  return '\$${cost.toStringAsFixed(2)}';
}