Expand description
Append-only, per-LLM-call token-usage log.
Each agent LLM call appends one TokenUsageRecord (as a JSON line) to the
session’s token-usage.jsonl, written into the session’s own directory next
to session.json. Unlike session.token_usage — a single snapshot that is
overwritten on every call — this log keeps the full per-round history so
cache effectiveness and cost can be analyzed offline: confirming the 1-hour
prompt-cache TTL keeps hitting across pauses, or measuring the cold round
right after a context compression.
The record bridges two sources: the prompt-side budget snapshot
(TokenBudgetUsage, already on the session) and the server-returned stream
stats — notably cache_creation_input_tokens, which is NOT part of
TokenBudgetUsage and would otherwise only exist in the logs.
Structs§
- Token
Usage Record - One per-LLM-call usage record. Flattened for line-oriented analysis (jq / DuckDB / pandas over the JSONL).