UsageStats

Category: Core

Source: usage_stats.dart

Cumulative token-usage accounting shared by the agent loop, subagent runner, title generator, and session persistence.

Status: part of the proposed core data model — see docs/plans/2026-04-29-harness-layers.md.

UsageStats is mutable and meant to be aggregated across many LLM calls within a session (or a subagent's lifetime). [record] folds a single UsageInfo into the running totals. [merge] folds another UsageStats (e.g. a finished subagent) into the parent's totals.

Use [snapshot] when you need to hand the current values to a sink that shouldn't observe later mutations.

Classes

UsageStats

Constructor

UsageStats({
    this.inputTokens = 0,
    this.outputTokens = 0,
    this.cacheReadTokens = 0,
    this.cacheCreationTokens = 0,
    this.turnCount = 0,
  })

Properties

Property	Type	Description
inputTokens	int
outputTokens	int
cacheReadTokens	int
cacheCreationTokens	int
turnCount	int
totalTokens	int get	Sum of every counted token, billable or otherwise. Useful for the status-bar style "tokens used" indicator that doesn't need to distinguish cache reads from prompt tokens.
billedInputTokens	int get	Total input the model "saw" — uncached input plus cache reads. The denominator for hit-rate calculations.
cacheHitRate	double? get	Cache hit rate as a fraction of total input the model saw, or null when no LLM call has been recorded yet (avoids a misleading 0%).
totalTokens	int get	Sum of every counted token, billable or otherwise. Useful for the status-bar style "tokens used" indicator that doesn't need to distinguish cache reads from prompt tokens.
billedInputTokens	int get	Total input the model "saw" — uncached input plus cache reads. The denominator for hit-rate calculations.
cacheHitRate	double? get	Cache hit rate as a fraction of total input the model saw, or null when no LLM call has been recorded yet (avoids a misleading 0%).

Methods

void record(UsageInfo usage)

Folds a single [UsageInfo] chunk into the running totals. Increments [turnCount] every call regardless of whether the provider reported cache stats — turnCount measures LLM calls, not cache events.

void merge(UsageStats other)

Folds another [UsageStats] into this one. Used to roll subagent totals into a parent's accumulator.

UsageStats snapshot()

Returns an immutable copy of the current totals. Use this when handing values to a sink that must not see later mutations.

static UsageStats fromJson(Map<String, dynamic> json)

String toString()