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.

12.6 KB
Raw Blame
/// What Codex has spent on this computer, read out of its own rollout logs.
///
/// Codex appends JSON lines to `~/.codex/sessions/<y>/<m>/<d>/rollout-*.jsonl`
/// and reports usage in `event_msg` records of type `token_count`.
///
/// ⚠️ **Codex reports CUMULATIVE totals, and Claude reports per-turn figures.**
/// That single difference is most of this file. A scanner that summed
/// `total_token_usage` across a session's records would bill a 40-turn session
/// forty times over — every record repeats everything before it. The billable
/// increment is `last_token_usage` where it exists, and the difference between
/// consecutive totals where it does not.
library;

import 'dart:convert';
import 'dart:io';

import 'ledger_scanner.dart';
import 'ledger_types.dart';
import 'jsonl_ledger_scan.dart';

import '../../core/runtime_platform.dart';

class CodexLedgerScanner implements LedgerScanner {
  CodexLedgerScanner({String? home, Map<String, String>? environment})
    : _environment = environment,
      _home = home ?? homeDirectory(environment);

  final String? _home;
  final Map<String, String>? _environment;

  @override
  LedgerProvider get provider => LedgerProvider.codex;

  /// `CODEX_HOME` first, because a machine that sets it means it. Falls back to
  /// `~/.codex`, and reads `archived_sessions/` beside `sessions/` so a session
  /// Codex has since filed away still counts — it was paid for either way.
  List<String> get roots {
    final env = _environment ?? RuntimePlatform.environment;
    final codexHome = env['CODEX_HOME']?.trim();
    final base = codexHome != null && codexHome.isNotEmpty
        ? codexHome
        : (_home == null ? null : '$_home/.codex');
    if (base == null) return const [];
    return ['$base/sessions', '$base/archived_sessions'];
  }

  @override
  Future<LedgerScanResult> scan(Map<String, ScannedSource> previous) async {
    final roots = this.roots;
    if (roots.isEmpty) {
      return const LedgerScanResult.unavailable(
        'No home directory to read Codex conversations from',
      );
    }
    return scanJsonlUsage(
      provider: provider,
      roots: roots,
      previous: previous,
      missingMessage: 'No Codex conversations on this computer',
      parse: _parse,
    );
  }

  Future<List<LedgerEntry>> _parse(File file, int length) async {
    final context = CodexParseContext(
      sessionId: file.uri.pathSegments.last.replaceAll('.jsonl', ''),
    );
    final entries = <LedgerEntry>[];
    await for (final line in readJsonlLines(file, length)) {
      final entry = parseCodexLine(line, context);
      if (entry != null) entries.add(entry);
    }
    return entries;
  }
}

/// What a rollout file has told us so far.
///
/// Mutable and carried down the file because Codex names the model and the
/// working directory in `turn_context` records that arrive *before* the usage
/// they apply to. A parser that looked only at the usage record would price
/// every Codex token as an unknown model.
class CodexParseContext {
  CodexParseContext({required this.sessionId});

  String sessionId;
  String? sessionCwd;
  String? currentCwd;
  String? currentModel;

  /// The last cumulative reading, against which the next one is a delta.
  CodexRawUsage? previousTotals;
}

/// Codex's own five buckets, before normalisation.
class CodexRawUsage {
  const CodexRawUsage({
    required this.input,
    required this.cached,
    required this.output,
    required this.reasoning,
    required this.total,
  });

  /// ⚠️ **Cache-INCLUSIVE**, unlike everything downstream — see
  /// [UsageTotals.freshInput].
  final int input;
  final int cached;
  final int output;
  final int reasoning;
  final int total;

  int get magnitude => input + cached + output + reasoning;

  bool sameAs(CodexRawUsage other) =>
      input == other.input &&
      cached == other.cached &&
      output == other.output &&
      reasoning == other.reasoning;

  bool isMonotonicAfter(CodexRawUsage previous) =>
      input >= previous.input &&
      cached >= previous.cached &&
      output >= previous.output &&
      reasoning >= previous.reasoning;

  CodexRawUsage minus(CodexRawUsage? previous) => CodexRawUsage(
    input: _clamp(input - (previous?.input ?? 0)),
    cached: _clamp(cached - (previous?.cached ?? 0)),
    output: _clamp(output - (previous?.output ?? 0)),
    reasoning: _clamp(reasoning - (previous?.reasoning ?? 0)),
    total: _clamp(total - (previous?.total ?? 0)),
  );

  CodexRawUsage plus(CodexRawUsage other) => CodexRawUsage(
    input: input + other.input,
    cached: cached + other.cached,
    output: output + other.output,
    reasoning: reasoning + other.reasoning,
    total: total + other.total,
  );

  /// Onto the shared shape: fresh input with the cache hits taken out.
  ///
  /// Clamped because the two figures come off the wire independently and a
  /// partial record can report more cached than input; a negative bucket would
  /// subtract from the machine's total.
  UsageTotals toTotals() => UsageTotals(
    freshInput: _clamp(input - cached),
    // Reasoning is billed at the output rate and Codex already counts it inside
    // `output_tokens`; adding it again would bill the same thinking twice. It is
    // carried separately as a subset.
    output: output,
    reasoning: reasoning,
    cacheRead: cached,
    // Codex reports `cache_write_input_tokens`, and it is deliberately dropped:
    // OpenAI's prompt caching writes for free, so a bucket here would show a
    // token count that is never billed and inflate every Codex total.
  );

  String get tuple => '$input,$cached,$output,$reasoning,$total';

  static int _clamp(int value) => value > 0 ? value : 0;
}

int _tokens(Object? value) =>
    value is num && value.isFinite && value > 0 ? value.toInt() : 0;

CodexRawUsage? _rawUsage(Object? value) {
  if (value is! Map<String, Object?>) return null;
  final input = _tokens(value['input_tokens']);
  final cached = _tokens(
    value['cached_input_tokens'] ?? value['cache_read_input_tokens'],
  );
  final output = _tokens(value['output_tokens']);
  final reasoning = _tokens(value['reasoning_output_tokens']);
  final total = _tokens(value['total_tokens']);
  return CodexRawUsage(
    input: input,
    cached: cached,
    output: output,
    reasoning: reasoning,
    // Legacy logs omit `total_tokens`. Reasoning is already inside output, so
    // input+output matches Codex pricing rather than counting it twice.
    total: total > 0 ? total : input + output,
  );
}

/// Whether a total that went BACKWARDS is a stale snapshot rather than a reset.
///
/// Codex rewrites its totals after a compaction or a resume, so a smaller figure
/// can mean either "the session restarted, count from here" or "this record is
/// an out-of-order echo of an earlier state". Ported from Orca's
/// `looksLikeStaleRegression`: a total still within 2% of the previous one, or
/// one that the last increment would carry back over it, is an echo — and an
/// echo must be dropped rather than treated as a new baseline, which would
/// re-bill everything after it.
bool _looksLikeStaleRegression(
  CodexRawUsage current,
  CodexRawUsage previous,
  CodexRawUsage last,
) {
  final previousTotal = previous.magnitude;
  final currentTotal = current.magnitude;
  final lastTotal = last.magnitude;
  if (previousTotal <= 0 || currentTotal <= 0 || lastTotal <= 0) return false;
  return currentTotal * 100 >= previousTotal * 98 ||
      currentTotal + lastTotal * 2 >= previousTotal;
}

/// The outcome of reading one `token_count` record.
sealed class CodexDelta {
  const CodexDelta();
}

/// A billable increment, plus the totals the next record is measured against.
class CodexIncrement extends CodexDelta {
  const CodexIncrement(this.delta, this.nextTotals);
  final CodexRawUsage delta;
  final CodexRawUsage? nextTotals;
}

/// The session restarted its count. Nothing to bill; just move the baseline.
class CodexBaseline extends CodexDelta {
  const CodexBaseline(this.nextTotals);
  final CodexRawUsage nextTotals;
}

/// What to bill for a `token_count` record, or null when the answer is nothing.
///
/// Ported from Orca's `resolveCodexUsageDelta`, whose ordering matters: the
/// `last_token_usage` payload is the billable increment and the totals are only
/// the baseline, because totals are mutable snapshots after a compaction.
CodexDelta? resolveCodexDelta(
  CodexRawUsage? total,
  CodexRawUsage? last,
  CodexRawUsage? previous,
) {
  if (total != null && last != null && previous != null) {
    if (total.sameAs(previous)) return null;
    if (!total.isMonotonicAfter(previous) &&
        _looksLikeStaleRegression(total, previous, last)) {
      return null;
    }
    return CodexIncrement(last, total);
  }
  if (total != null && last != null) return CodexIncrement(last, total);
  if (total != null && previous != null) {
    if (total.sameAs(previous)) return null;
    if (!total.isMonotonicAfter(previous)) return CodexBaseline(total);
    return CodexIncrement(total.minus(previous), total);
  }
  if (total != null) return CodexIncrement(total, total);
  if (last != null && previous != null) {
    return CodexIncrement(last, previous.plus(last));
  }
  if (last != null) return CodexIncrement(last, null);
  return null;
}

/// One rollout line as a ledger entry, or null when it carries no billable
/// usage. Advances [context] as a side effect.
LedgerEntry? parseCodexLine(String line, CodexParseContext context) {
  final Object? decoded;
  try {
    decoded = jsonDecode(line);
  } on FormatException {
    return null;
  }
  if (decoded is! Map<String, Object?>) return null;
  final payload = decoded['payload'];
  if (payload is! Map<String, Object?>) return null;

  switch (decoded['type']) {
    case 'session_meta':
      final id = payload['id'];
      if (id is String && id.isNotEmpty) context.sessionId = id;
      context.sessionCwd = payload['cwd'] as String?;
      context.currentCwd ??= context.sessionCwd;
      return null;
    case 'turn_context':
      context.currentCwd =
          (payload['cwd'] as String?) ??
          context.currentCwd ??
          context.sessionCwd;
      context.currentModel = _model(payload) ?? context.currentModel;
      return null;
    case 'event_msg':
      break;
    default:
      return null;
  }

  if (payload['type'] != 'token_count') return null;
  final timestamp = DateTime.tryParse('${decoded['timestamp']}');
  if (timestamp == null) return null;

  final info = payload['info'];
  // Codex emits `token_count` snapshots with a null `info` purely to carry a
  // rate-limit update. Treating those as malformed would make an active session
  // look flaky and raise scan errors for a perfectly valid log.
  if (info is! Map<String, Object?>) return null;

  final total = _rawUsage(info['total_token_usage']);
  final last = _rawUsage(info['last_token_usage']);
  final resolved = resolveCodexDelta(total, last, context.previousTotals);
  if (resolved == null) return null;
  if (resolved is CodexBaseline) {
    context.previousTotals = resolved.nextTotals;
    return null;
  }

  final increment = resolved as CodexIncrement;
  context.previousTotals = increment.nextTotals;
  final totals = increment.delta.toTotals();
  if (totals.isEmpty) return null;

  return LedgerEntry(
    provider: LedgerProvider.codex,
    sessionId: context.sessionId,
    timestamp: timestamp,
    totals: totals,
    model: _model(payload) ?? context.currentModel,
    directory: context.currentCwd ?? context.sessionCwd,
    // Keyed on the record's OWN fields — timestamp plus both usage tuples — and
    // never on the session id, because resuming copies these records verbatim
    // into a new rollout file while rewriting `session_meta.id`. Keying on the
    // session would let the copy through as a second charge.
    dedupeKey:
        '${decoded['timestamp']}|${total?.tuple ?? ''}|${last?.tuple ?? ''}',
  );
}

/// The model named on a record, wherever this Codex version chose to put it.
String? _model(Map<String, Object?> record) {
  for (final key in ['model', 'model_name']) {
    final value = record[key];
    if (value is String && value.isNotEmpty) return value;
  }
  final info = record['info'];
  if (info is Map<String, Object?>) {
    for (final key in ['model', 'model_name']) {
      final value = info[key];
      if (value is String && value.isNotEmpty) return value;
    }
    final metadata = info['metadata'];
    if (metadata is Map<String, Object?>) {
      final value = metadata['model'];
      if (value is String && value.isNotEmpty) return value;
    }
  }
  final metadata = record['metadata'];
  if (metadata is Map<String, Object?>) {
    final value = metadata['model'];
    if (value is String && value.isNotEmpty) return value;
  }
  return null;
}