UsageReport

Category: Core

Source: usage_report.dart

Aggregator + data model for per-role token-usage breakdowns.

Reads persisted usage JSONL rows (written by [SessionManager.recordUsage]) and folds them into a [UsageReport] keyed by role. Used by the CLI's /usage slash command, the ACP session/usage_summary endpoint, and session-resume headers.

Classes

UsageReportRow

One row in the per-role breakdown table.

Constructor

const UsageReportRow({
    required this.role,
    required this.calls,
    required this.input,
    required this.output,
    required this.cacheRead,
    required this.cacheWrite,
  })

Properties

Property	Type	Description
role	String
calls	int
input	int
output	int
cacheRead	int
cacheWrite	int
totalTokens	int get
totalTokens	int get

UsageReport

Aggregated breakdown of a session's token usage.

Constructor

const UsageReport({this.modelLabel, this.sessionId, required this.rows})

Properties

Property	Type	Description
modelLabel	String?
sessionId	String?
rows	List<UsageReportRow>
totalCalls	int get
totalInput	int get
totalOutput	int get
totalCacheRead	int get
totalCacheWrite	int get
totalTokens	int get
totalCalls	int get
totalInput	int get
totalOutput	int get
totalCacheRead	int get
totalCacheWrite	int get
totalTokens	int get
cacheHitRate	double? get	Cache hit rate across input tokens that the model saw — uncached input plus cache reads. Returns null when no LLM call has been recorded (avoids a misleading 0%).

Functions

`UsageReport buildUsageReport({

required Iterable<Map<String, dynamic>> usageEvents, String? modelLabel, String? sessionId, })`

Builds a [UsageReport] from persisted usage rows in conversation.jsonl. Unknown roles are surfaced as their own row so the report stays truthful even if a future surface adds new roles.