Skip to content

Commit 93c7bef

Browse files
committed
feat(grok): read cacheCreationTokens and document interrupted turns
Grok started writing `cacheCreationTokens` alongside `cachedReadTokens` around CLI 0.2.118 and still writes it in 1.0.0. The adapter hardcoded `cache_creation_input_tokens: 0`, so the field would be dropped the moment it went non-zero. Every turn observed so far reports it as zero, so there is no sample proving whether it sits inside `inputTokens` or beside it. `cachedReadTokens` is provably inside — session totals match `logs/unified.jsonl`, where `cached_prompt_tokens` is part of `prompt_tokens` — so the sibling field is carved out of the same total. That keeps the three parts summing back to `inputTokens`, which is the invariant the adapter already relies on. Also documents two limits that surfaced while checking real logs: a session killed mid-turn never writes `turn_completed`, so its usage cannot be reported at all, and `logs/unified.jsonl` cannot stand in for it because it records no per-request model id.
1 parent 343c50e commit 93c7bef

3 files changed

Lines changed: 62 additions & 9 deletions

File tree

‎docs/guide/grok/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ $GROK_HOME/ # or ~/.grok
3939
└── summary.json # optional metadata
4040
```
4141

42-
Only rows with `sessionUpdate == "turn_completed"` and a usable usage breakdown are counted. In-progress turns are not included until they complete. `logs/unified.jsonl` is not used in this version.
42+
Only rows with `sessionUpdate == "turn_completed"` and a usable usage breakdown are counted. In-progress turns are not included until they complete, and a session killed mid-turn never records one, so its usage cannot be reported. `logs/unified.jsonl` is not used as a source: it has no per-request model id, so its tokens cannot be priced or attributed to a model.
4343

4444
## Report Views
4545

@@ -53,7 +53,7 @@ These views support `--json`, `--compact`, `--mode`, and `--offline`.
5353

5454
## What Gets Calculated
5555

56-
- **Token usage** - Grok records OpenAI-style usage where `inputTokens` includes cache. ccusage stores uncached input as `input − cachedRead`, cache as cache read, and full `outputTokens` as output.
56+
- **Token usage** - Grok records OpenAI-style usage where `inputTokens` includes cache. ccusage splits it into uncached input, cache read (`cachedReadTokens`) and cache write (`cacheCreationTokens`), and stores the full `outputTokens` as output.
5757
- **Reasoning tokens** - `reasoningTokens` are a subset of `outputTokens`, so they are already counted in the total. They are **not** added on top of output for either tokens or cost.
5858
- **Precomputed cost** - Grok records `costUsdTicks` on each completed turn, in units of 1e-10 USD. ccusage uses it as the invoice cost, so `display` and the default `auto` report exactly what Grok billed.
5959
- **Pricing** - `calculate`, and `auto` for turns that recorded no ticks, fall back to LiteLLM estimates. Model ids such as `grok-4.5-build` try candidates with the trailing `-build` stripped and `xai/` / `x-ai/` prefixes. A `turn_completed` row aggregates several API requests, so this fallback cannot reproduce Grok's per-request long-context tiering and only approximates the invoice.

‎rust/adapters/grok/README.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,11 @@ Runtime root priority: a non-empty `GROK_HOME` → `~/.grok`.
3030
Path discovery stays inside the adapter, matching Grok Build CLI's official
3131
environment variable and default home.
3232

33-
In-progress turns are not counted until `turn_completed` is written.
34-
`logs/unified.jsonl` is not used in v1.
33+
In-progress turns are not counted until `turn_completed` is written. A session
34+
killed mid-turn never gets that row, so its usage is invisible here even though
35+
`logs/unified.jsonl` recorded the underlying requests. That log is not used as a
36+
source: it carries no per-request model id, so its tokens cannot be priced or
37+
attributed.
3538

3639
## Token mapping
3740

@@ -43,7 +46,7 @@ Grok records OpenAI-style usage where `inputTokens` includes cache:
4346
| `cachedReadTokens` | `cache_read_input_tokens` | |
4447
| `outputTokens` | `output_tokens` | as recorded |
4548
| `reasoningTokens` | dropped | already inside `outputTokens`; counting it again would inflate the total |
46-
| — | `cache_creation_input_tokens` | always `0` |
49+
| `cacheCreationTokens` | `cache_creation_input_tokens` | carved out of the uncached remainder |
4750
| `costUsdTicks` | `cost_usd` | fixed-point USD, one tick is 1e-10 USD |
4851

4952
`costUsdTicks` is the invoice cost, so `display` and the default `auto` report what

‎rust/adapters/grok/src/parser.rs‎

Lines changed: 54 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,8 @@ struct GrokUsage {
7474
#[serde(default, deserialize_with = "jsonl::lenient_u64")]
7575
cached_read_tokens: u64,
7676
#[serde(default, deserialize_with = "jsonl::lenient_u64")]
77+
cache_creation_tokens: u64,
78+
#[serde(default, deserialize_with = "jsonl::lenient_u64")]
7779
reasoning_tokens: u64,
7880
#[serde(default, deserialize_with = "jsonl::lenient_u64")]
7981
total_tokens: u64,
@@ -93,6 +95,8 @@ struct GrokModelUsage {
9395
#[serde(default, deserialize_with = "jsonl::lenient_u64")]
9496
cached_read_tokens: u64,
9597
#[serde(default, deserialize_with = "jsonl::lenient_u64")]
98+
cache_creation_tokens: u64,
99+
#[serde(default, deserialize_with = "jsonl::lenient_u64")]
96100
reasoning_tokens: u64,
97101
#[serde(default, deserialize_with = "jsonl::lenient_u64")]
98102
total_tokens: u64,
@@ -156,6 +160,19 @@ pub(super) fn split_tokens(input: u64, cached: u64) -> (u64, u64) {
156160
(uncached, cache)
157161
}
158162

163+
/// Split `inputTokens` into its uncached, cache-read and cache-write parts.
164+
///
165+
/// `cachedReadTokens` is provably a subset of `inputTokens`: session totals match
166+
/// `logs/unified.jsonl`, where `cached_prompt_tokens` is part of `prompt_tokens`.
167+
/// `cacheCreationTokens` arrived later and has only ever been observed as zero, so
168+
/// it is treated as a sibling subset rather than an extra bucket on top; that keeps
169+
/// the three parts summing back to `inputTokens` either way.
170+
fn split_input_tokens(input: u64, cached_read: u64, cache_creation: u64) -> (u64, u64, u64) {
171+
let (uncached, cache_read) = split_tokens(input, cached_read);
172+
let cache_creation = cache_creation.min(uncached);
173+
(uncached - cache_creation, cache_read, cache_creation)
174+
}
175+
159176
/// Pricing lookup candidates for a raw Grok model id (e.g. `grok-4.5-build`).
160177
pub(super) fn pricing_candidates(raw_model: &str) -> Vec<String> {
161178
let mut candidates = Vec::new();
@@ -222,17 +239,25 @@ pub(super) fn parse_session_files(
222239

223240
let model_rows = model_usage_rows(usage, meta.default_model.as_deref());
224241
for (raw_model, model_usage) in model_rows {
225-
let (uncached, cache) =
226-
split_tokens(model_usage.input_tokens, model_usage.cached_read_tokens);
242+
let (uncached, cache, cache_creation) = split_input_tokens(
243+
model_usage.input_tokens,
244+
model_usage.cached_read_tokens,
245+
model_usage.cache_creation_tokens,
246+
);
227247
let output_tokens = model_usage.output_tokens;
228248
let reasoning_tokens = model_usage.reasoning_tokens;
229-
if uncached == 0 && cache == 0 && output_tokens == 0 && reasoning_tokens == 0 {
249+
if uncached == 0
250+
&& cache == 0
251+
&& cache_creation == 0
252+
&& output_tokens == 0
253+
&& reasoning_tokens == 0
254+
{
230255
continue;
231256
}
232257
let usage_raw = TokenUsageRaw {
233258
input_tokens: uncached,
234259
output_tokens,
235-
cache_creation_input_tokens: 0,
260+
cache_creation_input_tokens: cache_creation,
236261
cache_read_input_tokens: cache,
237262
speed: None,
238263
cache_creation: None,
@@ -323,6 +348,7 @@ fn model_usage_rows(
323348
input_tokens: usage.input_tokens,
324349
output_tokens: usage.output_tokens,
325350
cached_read_tokens: usage.cached_read_tokens,
351+
cache_creation_tokens: usage.cache_creation_tokens,
326352
reasoning_tokens: usage.reasoning_tokens,
327353
total_tokens: usage.total_tokens,
328354
cost_usd_ticks: usage.cost_usd_ticks,
@@ -941,6 +967,30 @@ mod tests {
941967
assert_eq!(entries[0].missing_pricing_model, None);
942968
}
943969

970+
#[test]
971+
fn splits_cache_creation_out_of_the_uncached_input() {
972+
assert_eq!(split_input_tokens(100, 40, 25), (35, 40, 25));
973+
// Nothing to carve out when the field is absent, which is every turn observed so far.
974+
assert_eq!(split_input_tokens(100, 40, 0), (60, 40, 0));
975+
// A cache-write larger than the remaining input is clamped rather than wrapping.
976+
assert_eq!(split_input_tokens(100, 40, 999), (0, 40, 60));
977+
}
978+
979+
#[test]
980+
fn reads_cache_creation_tokens() {
981+
let line = r#"{"timestamp":1750000000,"params":{"sessionId":"sess-1","update":{"sessionUpdate":"turn_completed","usage":{"inputTokens":100,"outputTokens":20,"cachedReadTokens":40,"cacheCreationTokens":25,"reasoningTokens":10,"modelUsage":{"grok-4.5-build":{"inputTokens":100,"outputTokens":20,"cachedReadTokens":40,"cacheCreationTokens":25,"reasoningTokens":10}}}},"_meta":{"eventId":"evt-cc"}}}"#;
982+
let entries = parse_lines(line, None);
983+
984+
assert_eq!(entries.len(), 1);
985+
assert_eq!(entries[0].data.message.usage.input_tokens, 35);
986+
assert_eq!(entries[0].data.message.usage.cache_read_input_tokens, 40);
987+
assert_eq!(
988+
entries[0].data.message.usage.cache_creation_input_tokens,
989+
25
990+
);
991+
assert_eq!(entries[0].data.message.usage.output_tokens, 20);
992+
}
993+
944994
#[test]
945995
fn auto_prefers_recorded_ticks_while_calculate_recomputes() {
946996
let key = "xai/grok-4.5".to_string();

0 commit comments

Comments
 (0)