The best way to control Claude Code, Codex and more from any computer or phone
fix(server): Codex usage keeps requests from interrupted turns (#29415)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 2, 2026 at 18:29 UTC
84547b988de6a591d3514cc38ee649b046bc9fe8
6 files changed
+502
-82
apps/server/src/provider/Drivers/codexUsage.test.ts
+146
-1
@@ -1,7 +1,18 @@
1
import { describe, expect, it } from "@effect/vitest";
2
import { totalTokens } from "@t3tools/provider-core/server/usage";
3
4
-import { codexUsageFormat, initialCodexScanState, parseCodexLine } from "./codexUsage.ts";
4
+import {
5
+ type CodexScanState,
6
+ codexUsageFormat,
7
+ initialCodexScanState,
8
+ parseCodexLine as parseCodexRecords,
9
+} from "./codexUsage.ts";
10
+
11
+function parseCodexLine(line: string, state: CodexScanState) {
12
+ const records = parseCodexRecords(line, state);
13
+ expect(records.length).toBeLessThanOrEqual(1);
14
+ return records[0] ?? null;
15
+}
16
17
describe("parseCodexLine", () => {
18
const sessionMeta = JSON.stringify({
@@ -326,6 +337,119 @@ describe("parseCodexLine", () => {
337
expect(codexUsageFormat.readMalformedRecords?.(state)).toBe(1);
338
});
339
340
+ it("bills only the reported request when usage records sit between reconciling snapshots", () => {
341
+ const state = initialCodexScanState();
342
+ const usageRecord = (usage: unknown) =>
343
+ JSON.stringify({
344
+ type: "token_usage_record",
345
+ timestamp: "2026-08-01T05:17:45.000Z",
346
+ payload: { usage },
347
+ });
348
+ parseCodexLine(turnContext, state);
349
+ parseCodexLine(counted(counters(100, 20), counters(100, 20)), state);
350
+ for (const usage of [counters(40, 5), counters(60, 15), counters(30, 3)]) {
351
+ expect(parseCodexLine(usageRecord(usage), state)).toBeNull();
352
+ }
353
+ expect(
354
+ parseCodexLine(counted(counters(100, 20), counters(200, 40)), state)?.totals.outputTokens,
355
+ ).toBe(20);
356
+ // Records explained by an earlier snapshot cannot bridge a later gap.
357
+ parseCodexLine(usageRecord(counters(10, 2)), state);
358
+ expect(parseCodexLine(counted(counters(10, 2), counters(340, 65)), state)).toBeNull();
359
+ expect(state.malformedRecords).toBe(1);
360
+ });
361
+
362
+ it("bills each interrupted turn's request with the model, tier and time it was read under", () => {
363
+ const state = initialCodexScanState();
364
+ const line = (type: string, time: string, payload: Record<string, unknown>) =>
365
+ JSON.stringify({ type, timestamp: `2026-11-0${time}Z`, payload });
366
+ const context = (time: string, turn_id: string, model: string) =>
367
+ line("turn_context", time, { turn_id, model });
368
+ const tier = (time: string, service_tier: string) =>
369
+ line("event_msg", time, {
370
+ type: "thread_settings_applied",
371
+ thread_settings: { service_tier },
372
+ });
373
+ const request = (time: string, usage: unknown) => line("token_usage_record", time, { usage });
374
+ const snapshot = (time: string, last: unknown, total: unknown) =>
375
+ line("event_msg", time, {
376
+ type: "token_count",
377
+ info: { last_token_usage: last, total_token_usage: total },
378
+ });
379
+ const parsed = [
380
+ line("session_meta", "1T23:59:50", { id: "session-a", model_provider: "openai" }),
381
+ context("1T23:59:50", "turn-1", "gpt-6-sol"),
382
+ request("1T23:59:51", counters(100, 20)),
383
+ snapshot("1T23:59:52", counters(100, 20), counters(100, 20)),
384
+ // One interrupted turn whose requests straddle midnight.
385
+ request("1T23:59:59", counters(150, 10)),
386
+ request("2T00:00:01", counters(50, 5)),
387
+ tier("2T00:00:02", "priority"),
388
+ context("2T00:00:02", "turn-2", "gpt-6-astra"),
389
+ request("2T00:00:03", counters(50, 5)),
390
+ request("2T00:00:04", counters(30, 5)),
391
+ tier("2T00:00:05", "default"),
392
+ context("2T00:00:05", "turn-3", "gpt-6-sol"),
393
+ request("2T00:00:06", counters(200, 30)),
394
+ snapshot("2T00:00:07", counters(200, 30), counters(580, 75)),
395
+ ].flatMap((value) => parseCodexRecords(value, state));
396
+
397
+ const at = (time: string) => Date.parse(`2026-11-0${time}Z`);
398
+ expect(
399
+ parsed.map((record) => ({
400
+ tokens: totalTokens(record.totals),
401
+ model: record.model,
402
+ speed: record.speed,
403
+ timestampMs: record.timestampMs,
404
+ unresolvedServiceTierTurnId: record.unresolvedServiceTierTurnId,
405
+ })),
406
+ ).toEqual([
407
+ {
408
+ tokens: 120,
409
+ model: "gpt-6-sol",
410
+ speed: "standard",
411
+ timestampMs: at("1T23:59:52"),
412
+ unresolvedServiceTierTurnId: "turn-1",
413
+ },
414
+ {
415
+ tokens: 160,
416
+ model: "gpt-6-sol",
417
+ speed: "standard",
418
+ timestampMs: at("1T23:59:59"),
419
+ unresolvedServiceTierTurnId: "turn-1",
420
+ },
421
+ {
422
+ tokens: 55,
423
+ model: "gpt-6-sol",
424
+ speed: "standard",
425
+ timestampMs: at("2T00:00:01"),
426
+ unresolvedServiceTierTurnId: "turn-1",
427
+ },
428
+ {
429
+ tokens: 55,
430
+ model: "gpt-6-astra",
431
+ speed: "fast",
432
+ timestampMs: at("2T00:00:03"),
433
+ unresolvedServiceTierTurnId: undefined,
434
+ },
435
+ {
436
+ tokens: 35,
437
+ model: "gpt-6-astra",
438
+ speed: "fast",
439
+ timestampMs: at("2T00:00:04"),
440
+ unresolvedServiceTierTurnId: undefined,
441
+ },
442
+ {
443
+ tokens: 230,
444
+ model: "gpt-6-sol",
445
+ speed: "standard",
446
+ timestampMs: at("2T00:00:07"),
447
+ unresolvedServiceTierTurnId: undefined,
448
+ },
449
+ ]);
450
+ expect(state.malformedRecords).toBe(0);
451
+ });
452
+
453
it("does not bill a context-window estimate or lose the following real request", () => {
454
const state = initialCodexScanState();
455
parseCodexLine(turnContext, state);
@@ -664,5 +788,26 @@ describe("parseCodexLine", () => {
788
skipped: codexUsageFormat.readMalformedRecords?.(state),
789
}).toEqual({ processed: [120, 0, 120, 35], skipped: 0 });
790
});
791
+
792
+ it("bills the child's first request when its turn is interrupted before any snapshot", () => {
793
+ const state = initialCodexScanState();
794
+ const forkInstant = "2026-08-01T05:00:00.000Z";
795
+ const request = (timestamp: string, usage: unknown) =>
796
+ JSON.stringify({ type: "token_usage_record", timestamp, payload: { usage } });
797
+ const billed = [
798
+ meta({ id: "child", timestamp: forkInstant, forkedFromId: "parent" }),
799
+ stamped(forkInstant, turnContext),
800
+ request("2026-08-01T05:00:00.001Z", counters(100, 20)),
801
+ stamped("2026-08-01T05:00:00.001Z", counted(counters(100, 20), counters(100, 20))),
802
+ request("2026-08-01T05:00:06.000Z", counters(150, 10)),
803
+ request("2026-08-01T05:00:10.000Z", counters(200, 30)),
804
+ stamped("2026-08-01T05:00:10.000Z", counted(counters(200, 30), counters(450, 60))),
805
+ ].flatMap((line) => parseCodexRecords(line, state));
806
+
807
+ expect({
808
+ processed: billed.map((record) => totalTokens(record.totals)),
809
+ skipped: codexUsageFormat.readMalformedRecords?.(state),
810
+ }).toEqual({ processed: [160, 230], skipped: 0 });
811
+ });
812
});
813
});
apps/server/src/provider/Drivers/codexUsage.ts
+149
-54
@@ -5,7 +5,6 @@ import * as Schema from "effect/Schema";
5
6
import {
7
parseTimestampMs,
8
- totalTokens,
8
type ProviderUsageReader,
9
type TranscriptUsageFormat,
10
type UsageRecord,
@@ -58,6 +57,7 @@ function readCodexTokenUsage(value: unknown): CodexTokenUsage | null {
57
// A zeroed baseline rebases the counters, so the sequence start measured against it is forgotten.
58
function rebaseCodexUsage(state: CodexScanState, cumulative: CodexTokenUsage) {
59
state.lastCumulativeUsage = cumulative;
60
+ delete state.unreportedRequests;
61
if (cumulative.input_tokens + cumulative.output_tokens === 0) delete state.sequenceStartSignature;
62
}
63
@@ -67,18 +67,66 @@ function advanceCodexUsage(previous: CodexTokenUsage | null, last: CodexTokenUsa
67
);
68
}
69
70
+const CodexSpeed = Schema.Literals(["standard", "fast", "ultrafast"]);
71
+
72
+// What a request is billed as is fixed when it is read, not when a later snapshot reconciles it.
73
+const CodexUnreportedRequest = Schema.Struct({
74
+ timestampMs: Schema.Finite,
75
+ model: Schema.String,
76
+ turnId: Schema.String,
77
+ speed: CodexSpeed,
78
+ sawThreadSettings: Schema.Boolean,
79
+ usage: CodexTokenUsage,
80
+});
81
+type CodexUnreportedRequest = typeof CodexUnreportedRequest.Type;
82
+type CodexRequestAttribution = Omit<CodexUnreportedRequest, "usage">;
83
+
84
+// An interrupted turn can end before a snapshot reports its last request. Bill those requests only
85
+// when the `token_usage_record`s since the previous snapshot explain the whole gap; `last` is the
86
+// final one.
87
+function unreportedRequests(
88
+ previous: CodexTokenUsage | null,
89
+ cumulative: CodexTokenUsage,
90
+ last: CodexTokenUsage,
91
+ pending: readonly CodexUnreportedRequest[] | undefined,
92
+) {
93
+ if (
94
+ previous === null ||
95
+ pending === undefined ||
96
+ CODEX_USAGE_FIELDS.some(
97
+ (key) =>
98
+ cumulative[key] - previous[key] !==
99
+ pending.reduce((sum, request) => sum + request.usage[key], 0),
100
+ )
101
+ ) {
102
+ return null;
103
+ }
104
+ const final = pending.at(-1)!;
105
+ const remainder = readCodexTokenUsage(
106
+ Object.fromEntries(CODEX_USAGE_FIELDS.map((key) => [key, final.usage[key] - last[key]])),
107
+ );
108
+ if (remainder === null) return null;
109
+ return [...pending.slice(0, -1), { ...final, usage: remainder }].filter(
110
+ (request) => request.usage.input_tokens + request.usage.output_tokens > 0,
111
+ );
112
+}
113
+
114
/**
115
* Codex `token_count` events carry no model or service tier, so both are carried forward: the model
116
* from the most recent `turn_context`, the tier from the most recent `thread_settings_applied`.
117
*/
118
export const CodexScanState = Schema.Struct({
119
model: Schema.mutableKey(Schema.String),
76
- speed: Schema.mutableKey(Schema.Literals(["standard", "fast", "ultrafast"])),
120
+ speed: Schema.mutableKey(CodexSpeed),
121
sessionId: Schema.mutableKey(Schema.String),
122
lastUsageSignature: Schema.mutableKey(Schema.NullOr(Schema.String)),
123
lastCumulativeUsage: Schema.mutableKey(Schema.NullOr(CodexTokenUsage)),
124
// Optional so scan states cached before this field existed stay valid.
125
sequenceStartSignature: Schema.mutableKey(Schema.optionalKey(Schema.String)),
126
+ // `token_usage_record` usage since the last cumulative snapshot, one entry per record.
127
+ unreportedRequests: Schema.mutableKey(
128
+ Schema.optionalKey(Schema.mutable(Schema.Array(CodexUnreportedRequest))),
129
+ ),
130
malformedRecords: Schema.mutableKey(TokenCount),
131
sawSessionMeta: Schema.mutableKey(Schema.Boolean),
132
modelProvider: Schema.mutableKey(Schema.String),
@@ -120,32 +168,44 @@ function isForkedSessionMeta(payload: Record<string, unknown>): boolean {
168
return typeof (spawn as Record<string, unknown>)["parent_thread_id"] === "string";
169
}
170
171
+// The first usage line past the copied burst ends suppression for the rest of the rollout.
172
+function isForkCopy(state: CodexScanState, timestampMs: number): boolean {
173
+ if (!state.suppressingForkCopies) return false;
174
+ if (timestampMs - state.forkCopyAnchorMs < FORK_COPY_MAX_GAP_MS) {
175
+ state.forkCopyAnchorMs = timestampMs;
176
+ return true;
177
+ }
178
+ state.suppressingForkCopies = false;
179
+ state.lastUsageSignature = null;
180
+ return false;
181
+}
182
+
183
/**
184
* Cumulative counters validate request deltas. Older events without cumulative counters use
185
* normalized consecutive-request deduplication.
186
*/
127
-export function parseCodexLine(line: string, state: CodexScanState): UsageRecord | null {
187
+export function parseCodexLine(line: string, state: CodexScanState): readonly UsageRecord[] {
188
let parsed: unknown;
189
try {
190
parsed = JSON.parse(line);
191
} catch {
132
- return null;
192
+ return [];
193
}
194
return parseCodexRecord(parsed, state);
195
}
196
137
-function parseCodexRecord(parsed: unknown, state: CodexScanState): UsageRecord | null {
138
- if (typeof parsed !== "object" || parsed === null) return null;
197
+function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly UsageRecord[] {
198
+ if (typeof parsed !== "object" || parsed === null) return [];
199
200
const record = parsed as Record<string, unknown>;
201
const payload = record["payload"];
142
- if (typeof payload !== "object" || payload === null) return null;
202
+ if (typeof payload !== "object" || payload === null) return [];
203
const payloadRecord = payload as Record<string, unknown>;
204
const payloadType = payloadRecord["type"];
205
206
if (record["type"] === "session_meta") {
207
// Only the first meta identifies this session; copied ancestor metas would misattribute later records.
148
- if (state.sawSessionMeta) return null;
208
+ if (state.sawSessionMeta) return [];
209
state.sawSessionMeta = true;
210
const id = payloadRecord["id"] ?? payloadRecord["session_id"];
211
if (typeof id === "string") state.sessionId = id;
@@ -157,7 +217,7 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): UsageRecord |
217
state.suppressingForkCopies = true;
218
state.forkCopyAnchorMs = metaTimestampMs;
219
}
160
- return null;
220
+ return [];
221
}
222
223
if (record["type"] === "turn_context") {
@@ -169,7 +229,18 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): UsageRecord |
229
payloadRecord["model"].length > 0
230
? payloadRecord["turn_id"]
231
: "";
172
- return null;
232
+ return [];
233
+ }
234
+
235
+ // Several of these may sit between two snapshots, so they only explain a gap in the counters.
236
+ if (record["type"] === "token_usage_record") {
237
+ const timestampMs = parseTimestampMs(record["timestamp"]);
238
+ const usage = readCodexTokenUsage(payloadRecord["usage"]);
239
+ if (timestampMs === null || usage === null || state.model.length === 0) return [];
240
+ // Copied history is already billed in the parent.
241
+ if (isForkCopy(state, timestampMs)) return [];
242
+ (state.unreportedRequests ??= []).push({ ...codexAttribution(state, timestampMs), usage });
243
+ return [];
244
}
245
246
if (payloadType === "thread_settings_applied") {
@@ -178,53 +249,49 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): UsageRecord |
249
if (typeof settings === "object" && settings !== null) {
250
state.speed = codexSpeed((settings as Record<string, unknown>)["service_tier"]);
251
}
181
- return null;
252
+ return [];
253
}
254
184
- if (payloadType !== "token_count") return null;
255
+ if (payloadType !== "token_count") return [];
256
257
const info = payloadRecord["info"];
187
- if (typeof info !== "object" || info === null) return null;
258
+ if (typeof info !== "object" || info === null) return [];
259
const infoRecord = info as Record<string, unknown>;
260
261
// Codex may re-emit these counters after the model or timestamp becomes available.
262
const timestampMs = parseTimestampMs(record["timestamp"]);
192
- if (timestampMs === null || state.model.length === 0) return null;
263
+ if (timestampMs === null || state.model.length === 0) return [];
264
265
const last = readCodexTokenUsage(infoRecord["last_token_usage"]);
266
const rawCumulative = infoRecord["total_token_usage"];
267
const hasCumulative = rawCumulative !== undefined && rawCumulative !== null;
268
const cumulative = hasCumulative ? readCodexTokenUsage(rawCumulative) : null;
269
199
- if (state.suppressingForkCopies) {
200
- if (timestampMs - state.forkCopyAnchorMs < FORK_COPY_MAX_GAP_MS) {
201
- state.forkCopyAnchorMs = timestampMs;
202
- // Copied history is already billed in the parent, but establishes the child's baseline.
203
- const signature = last === null ? null : JSON.stringify(last);
204
- if (cumulative !== null) rebaseCodexUsage(state, cumulative);
205
- else if (!hasCumulative && last !== null && signature !== state.lastUsageSignature) {
206
- state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, last);
207
- }
208
- state.lastUsageSignature = signature;
209
- return null;
270
+ if (isForkCopy(state, timestampMs)) {
271
+ // Copied history is already billed in the parent, but establishes the child's baseline.
272
+ const signature = last === null ? null : JSON.stringify(last);
273
+ if (cumulative !== null) rebaseCodexUsage(state, cumulative);
274
+ else if (!hasCumulative && last !== null && signature !== state.lastUsageSignature) {
275
+ state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, last);
276
}
211
- state.suppressingForkCopies = false;
212
- state.lastUsageSignature = null;
277
+ state.lastUsageSignature = signature;
278
+ return [];
279
}
280
281
const previous = state.lastCumulativeUsage;
282
+ const pending = state.unreportedRequests;
283
// A valid snapshot remains the next baseline even when its paired request is malformed.
284
if (cumulative !== null) rebaseCodexUsage(state, cumulative);
285
if (last === null || (hasCumulative && cumulative === null)) {
286
state.malformedRecords += 1;
220
- return null;
287
+ return [];
288
}
289
290
// Zero-component counters report context size, not a request: fill_to_context_window, or the
291
// post-compaction marker whose total is the new context size (its cumulative may reset to zero).
292
if (last.input_tokens + last.output_tokens === 0) {
293
state.lastUsageSignature = null;
227
- return null;
294
+ return [];
295
}
296
297
if (
@@ -232,15 +299,16 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): UsageRecord |
299
previous !== null &&
300
CODEX_USAGE_FIELDS.every((key) => cumulative[key] === previous[key])
301
) {
235
- return null;
302
+ return [];
303
}
304
305
if (last.total_tokens !== last.input_tokens + last.output_tokens) {
306
state.malformedRecords += 1;
240
- return null;
307
+ return [];
308
}
309
310
const signature = JSON.stringify(last);
311
+ let unreported: readonly CodexUnreportedRequest[] = [];
312
if (cumulative !== null) {
313
// A session resumed in a new Codex process restarts its cumulative counters at this request.
314
const restarted = CODEX_USAGE_FIELDS.every((key) => cumulative[key] === last[key]);
@@ -248,7 +316,7 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): UsageRecord |
316
// Only the same event is a replay; a later request can restart with identical counters.
317
if (restarted && sequenceStart === state.sequenceStartSignature) {
318
state.lastCumulativeUsage = previous;
251
- return null;
319
+ return [];
320
}
321
// Forks and paginated continuations can inherit totals without copying a counter snapshot.
322
// Only bill the latest request, and require the unseen prefix to be valid usage too.
@@ -259,26 +327,51 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): UsageRecord |
327
) !== null
328
: CODEX_USAGE_FIELDS.every((key) => cumulative[key] - previous[key] === last[key]);
329
if (!restarted && !reconciled) {
262
- state.malformedRecords += 1;
263
- return null;
330
+ const bridged = unreportedRequests(previous, cumulative, last, pending);
331
+ if (bridged === null) {
332
+ state.malformedRecords += 1;
333
+ return [];
334
+ }
335
+ unreported = bridged;
336
}
337
if (restarted) state.sequenceStartSignature = sequenceStart;
338
} else {
267
- if (signature === state.lastUsageSignature) return null;
339
+ if (signature === state.lastUsageSignature) return [];
340
// Advance expected totals for billed legacy requests so a cumulative re-emission is stale.
341
const advanced = advanceCodexUsage(previous, last);
342
if (advanced === null) {
343
state.malformedRecords += 1;
272
- return null;
344
+ return [];
345
}
346
state.lastCumulativeUsage = advanced;
347
}
348
state.lastUsageSignature = signature;
349
278
- const inputTokens = last.input_tokens;
279
- const cachedInputTokens = last.cached_input_tokens;
280
- const cacheCreationTokens = last.cache_write_input_tokens;
281
- const outputTokens = last.output_tokens;
350
+ return [
351
+ ...unreported.map((request) => codexRequestRecord(state, request.usage, request)),
352
+ codexRequestRecord(state, last, codexAttribution(state, timestampMs)),
353
+ ];
354
+}
355
+
356
+function codexAttribution(state: CodexScanState, timestampMs: number): CodexRequestAttribution {
357
+ return {
358
+ timestampMs,
359
+ model: state.model,
360
+ turnId: state.turnId,
361
+ speed: state.speed,
362
+ sawThreadSettings: state.sawThreadSettings,
363
+ };
364
+}
365
+
366
+function codexRequestRecord(
367
+ state: CodexScanState,
368
+ usage: CodexTokenUsage,
369
+ { timestampMs, model, turnId, speed, sawThreadSettings }: CodexRequestAttribution,
370
+): UsageRecord {
371
+ const inputTokens = usage.input_tokens;
372
+ const cachedInputTokens = usage.cached_input_tokens;
373
+ const cacheCreationTokens = usage.cache_write_input_tokens;
374
+ const outputTokens = usage.output_tokens;
375
376
const totals: UsageTokenTotals = {
377
// Codex reports `input_tokens` inclusive of the cached portion.
@@ -287,24 +380,22 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): UsageRecord |
380
cacheCreationTokens,
381
outputTokens,
382
// Reported inside output_tokens, surfaced separately for the token mix.
290
- reasoningTokens: last.reasoning_output_tokens,
383
+ reasoningTokens: usage.reasoning_output_tokens,
384
};
385
293
- if (totalTokens(totals) === 0) return null;
294
-
386
return {
387
provider: "codex",
388
timestampMs,
298
- model: state.model,
389
+ model,
390
sessionId: state.sessionId,
391
totals,
392
reportedCostUsd: null,
302
- speed: state.speed,
303
- ...(!state.sawThreadSettings &&
393
+ speed,
394
+ ...(!sawThreadSettings &&
395
state.modelProvider === "openai" &&
396
state.sessionId.length > 0 &&
306
- state.turnId.length > 0
307
- ? { unresolvedServiceTierTurnId: state.turnId }
397
+ turnId.length > 0
398
+ ? { unresolvedServiceTierTurnId: turnId }
399
: {}),
400
dedupeKey: null,
401
};
@@ -317,9 +408,6 @@ function codexSpeed(serviceTier: unknown): UsageSpeed {
408
return "standard";
409
}
410
320
-const orEmpty = (record: UsageRecord | null): readonly UsageRecord[] =>
321
- record === null ? [] : [record];
322
-
411
export const codexUsageFormat: TranscriptUsageFormat<CodexScanState> = {
412
selectFields: {
413
type: true,
@@ -335,12 +423,19 @@ export const codexUsageFormat: TranscriptUsageFormat<CodexScanState> = {
423
forked_from_id: true,
424
source: { subagent: { thread_spawn: { parent_thread_id: true } } },
425
info: { last_token_usage: true, total_token_usage: true },
426
+ usage: true,
427
},
428
},
429
// Metadata lines carry model, tier and session even without usage.
341
- usageMarkers: ['"token_count"', '"turn_context"', '"thread_settings_applied"', '"session_meta"'],
342
- parseLine: (line, state) => orEmpty(parseCodexLine(line, state)),
343
- parseProjected: (projected, state) => orEmpty(parseCodexRecord(projected, state)),
430
+ usageMarkers: [
431
+ '"token_count"',
432
+ '"token_usage_record"',
433
+ '"turn_context"',
434
+ '"thread_settings_applied"',
435
+ '"session_meta"',
436
+ ],
437
+ parseLine: parseCodexLine,
438
+ parseProjected: parseCodexRecord,
439
state: { initial: initialCodexScanState, schema: CodexScanState },
440
readMalformedRecords: (state) => state.malformedRecords,
441
// A rollout that moved after it was read leaves a copy in both places.
apps/server/src/usage/UsageService.test.ts
+103
-3
@@ -2624,7 +2624,7 @@ describe("UsageService", () => {
2624
}).pipe(Effect.scoped),
2625
);
2626
2627
- it.live.each([4, 5, 6, 7, 8])(
2627
+ it.live.each([4, 5, 6, 7, 8, 10])(
2628
"upgrades a v%s cache: reparses live Codex usage, keeps deleted rollouts and the old file",
2629
(version) =>
2630
Effect.gen(function* () {
@@ -2691,7 +2691,7 @@ describe("UsageService", () => {
2691
delete file.cs.lastCumulativeUsage;
2692
delete file.cs.malformedRecords;
2693
}
2694
- if (version === 8 && path === livePath) {
2694
+ if (version >= 8 && path === livePath) {
2695
file.r = [];
2696
file.mr = 1;
2697
file.cs.malformedRecords = 1;
@@ -2723,7 +2723,7 @@ describe("UsageService", () => {
2723
60 + 20 * (version === 4 ? 1 : 2),
2724
);
2725
yield* upgraded.awaitPersisted;
2726
- assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v10.json");
2726
+ assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v11.json");
2727
assert.strictEqual(
2728
yield* Effect.promise(() => NodeFSP.readFile(legacyPath, "utf8")),
2729
legacy,
@@ -2750,6 +2750,106 @@ describe("UsageService", () => {
2750
}).pipe(Effect.scoped),
2751
);
2752
2753
+ it.live("re-parses a clean v10 Codex rollout that grew after an interrupted request", () =>
2754
+ Effect.gen(function* () {
2755
+ const { home, settings } = yield* setup;
2756
+ const sessions = NodePath.join(home, "codex", "sessions");
2757
+ const live = NodePath.join(sessions, "live.jsonl");
2758
+ const usage = (input: number, output: number) => ({
2759
+ input_tokens: input,
2760
+ output_tokens: output,
2761
+ total_tokens: input + output,
2762
+ });
2763
+ const lines = (values: readonly unknown[]) =>
2764
+ values.map((value) => `${encodeUnknownJsonString(value)}\n`).join("");
2765
+ const request = (second: number, last: unknown) => ({
2766
+ type: "token_usage_record",
2767
+ timestamp: `2026-08-01T10:00:0${second}Z`,
2768
+ payload: { usage: last },
2769
+ });
2770
+ const tokenCount = (second: number, last: unknown, total: unknown) => ({
2771
+ type: "event_msg",
2772
+ timestamp: `2026-08-01T10:00:0${second}Z`,
2773
+ payload: {
2774
+ type: "token_count",
2775
+ info: { last_token_usage: last, total_token_usage: total },
2776
+ },
2777
+ });
2778
+ yield* Effect.promise(async () => {
2779
+ await NodeFSP.mkdir(sessions, { recursive: true });
2780
+ await NodeFSP.writeFile(
2781
+ live,
2782
+ lines([
2783
+ { type: "session_meta", payload: { id: "live" } },
2784
+ { type: "turn_context", payload: { turn_id: "turn-1", model: "gpt-6-astra" } },
2785
+ request(1, usage(100, 20)),
2786
+ tokenCount(1, usage(100, 20), usage(100, 20)),
2787
+ // Interrupted after this request finished: no token_count reports it.
2788
+ request(2, usage(150, 10)),
2789
+ ]),
2790
+ );
2791
+ });
2792
+
2793
+ yield* Effect.gen(function* () {
2794
+ const { stateDir } = yield* ServerConfig.ServerConfig;
2795
+ const tokens = (summary: UsageSummary) =>
2796
+ summary.buckets.reduce((sum, bucket) => sum + totalTokens(bucket.totals), 0);
2797
+ const first = yield* UsageService.make;
2798
+ assert.strictEqual(tokens(yield* first.readSummary(WINDOW)), 120);
2799
+ yield* first.awaitPersisted;
2800
+
2801
+ yield* Effect.promise(async () => {
2802
+ const cachePath = NodePath.join(stateDir, SCAN_CACHE_FILE_NAME);
2803
+ const document = decodeUnknownJsonString(await NodeFSP.readFile(cachePath, "utf8")) as {
2804
+ files: Record<string, { cs: Record<string, unknown> }>;
2805
+ };
2806
+ // The v10 parser ignored `token_usage_record`, so its clean state held nothing pending.
2807
+ for (const file of Object.values(document.files)) {
2808
+ file.cs = Object.fromEntries(
2809
+ Object.entries(file.cs).filter(([key]) => !key.startsWith("unreported")),
2810
+ );
2811
+ }
2812
+ await NodeFSP.rm(cachePath);
2813
+ await NodeFSP.writeFile(
2814
+ NodePath.join(stateDir, "usage-scan-cache-v10.json"),
2815
+ encodeUnknownJsonString({ ...document, version: 10 }),
2816
+ );
2817
+ await NodeFSP.appendFile(
2818
+ live,
2819
+ lines([
2820
+ { type: "turn_context", payload: { turn_id: "turn-2", model: "gpt-6-astra" } },
2821
+ request(5, usage(200, 30)),
2822
+ tokenCount(5, usage(200, 30), usage(450, 60)),
2823
+ ]),
2824
+ );
2825
+ });
2826
+
2827
+ const upgraded = yield* UsageService.make;
2828
+ const summary = yield* upgraded.readSummary(WINDOW);
2829
+ assert.deepStrictEqual(
2830
+ {
2831
+ tokens: tokens(summary),
2832
+ malformedRecords: summary.sources.find(
2833
+ (source) => source.fingerprint.provider === "codex",
2834
+ )?.malformedRecords,
2835
+ },
2836
+ { tokens: 510, malformedRecords: 0 },
2837
+ );
2838
+ }).pipe(
2839
+ Effect.provide(
2840
+ layerService({
2841
+ prefix: "usage-service-cache-v10-interrupted-test",
2842
+ home,
2843
+ settings,
2844
+ ratesDocument: {
2845
+ "gpt-6-astra": { input_cost_per_token: 0, output_cost_per_token: 1 },
2846
+ },
2847
+ }),
2848
+ ),
2849
+ );
2850
+ }).pipe(Effect.scoped),
2851
+ );
2852
+
2853
it.live("preserves saved tokens, costs and sessions after transcript cleanup and restart", () =>
2854
Effect.gen(function* () {
2855
const { transcript, settings, home } = yield* setup;
apps/server/src/usage/usageScanCache.test.ts
+15
-15
@@ -161,7 +161,7 @@ describe("scan cache round trip", () => {
161
expect(restored).toEqual(original);
162
});
163
164
- it.each([5, 6, 7, 8])(
164
+ it.each([5, 6, 7, 8, 10])(
165
"retains v%s history and compatible positions but invalidates obsolete state",
166
(version) => {
167
const original = cacheWith([["/gone.jsonl", 100, [record({ speed: "fast" })]]]);
@@ -218,25 +218,25 @@ describe("scan cache round trip", () => {
218
};
219
220
const restored = decodeScanCache(JSON.parse(JSON.stringify(legacy)), TEST_FORMAT_MAP);
221
- expect(restored.get("/gone.jsonl")).toEqual({
222
- ...original.get("/gone.jsonl"),
223
- size: -1,
224
- position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
225
- });
226
- expect(restored.get("/gone-codex.jsonl")).toEqual({
227
- ...original.get("/gone-codex.jsonl"),
228
- size: -1,
229
- position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
230
- });
231
- expect(restored.get("/clean-codex.jsonl")).toEqual(
232
- version >= 8
233
- ? cleanCodex
221
+ expect(restored.get("/gone.jsonl")).toEqual(
222
+ version >= 10
223
+ ? original.get("/gone.jsonl")
224
: {
235
- ...cleanCodex,
225
+ ...original.get("/gone.jsonl"),
226
size: -1,
227
position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
228
},
229
);
230
+ expect(restored.get("/gone-codex.jsonl")).toEqual({
231
+ ...original.get("/gone-codex.jsonl"),
232
+ size: -1,
233
+ position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
234
+ });
235
+ expect(restored.get("/clean-codex.jsonl")).toEqual({
236
+ ...cleanCodex,
237
+ size: version >= 8 ? cleanCodex.size : -1,
238
+ position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
239
+ });
240
expect(restored.get("/gone-pi.jsonl")).toEqual(
241
version >= 6
242
? original.get("/gone-pi.jsonl")
apps/server/src/usage/usageScanCache.ts
+12
-8
@@ -9,7 +9,7 @@ import * as Schema from "effect/Schema";
9
import { CLAUDE_SYNTHETIC_MODEL } from "../provider/Drivers/claudeUsage.ts";
10
import { GUARD_LENGTH, type TranscriptParsePosition } from "./usageTranscriptReader.ts";
11
12
-const USAGE_SCAN_CACHE_VERSION = 10 as const;
12
+const USAGE_SCAN_CACHE_VERSION = 11 as const;
13
const SPEED_COMPATIBLE_SINCE_VERSION = 4;
14
15
/**
@@ -17,8 +17,9 @@ const SPEED_COMPATIBLE_SINCE_VERSION = 4;
17
* replace it, dropping saved usage for deleted transcripts. Separate files keep
18
* both.
19
*/
20
-export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v10.json";
20
+export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v11.json";
21
export const LEGACY_SCAN_CACHE_FILE_NAMES = [
22
+ "usage-scan-cache-v10.json",
23
"usage-scan-cache-v9.json",
24
"usage-scan-cache-v8.json",
25
"usage-scan-cache-v7.json",
@@ -291,16 +292,19 @@ export function decodeScanCache(
292
continue;
293
}
294
// Keep history for deleted rollouts, but re-parse incompatible reducer state.
294
- // v9 repairs skipped initial Codex requests; clean v8 entries can still resume.
295
+ // v9 and v11 repair skipped Codex requests; clean v8+ entries stay served while unchanged.
296
// v10 adds Claude advisor calls, which no older Claude entry holds.
297
const legacy =
298
(entry.p === "claude" && version < 10) ||
299
(format.state !== undefined &&
300
(version < 6 ||
300
- (entry.p === "codex" && (version < 8 || (version < 9 && malformedRecords > 0)))));
301
+ (entry.p === "codex" && (version < 8 || (version < 11 && malformedRecords > 0)))));
302
// A corrupt state disqualifies the entry: resuming with it would attach
303
// appended usage to the wrong model or replay fork-copied history.
304
if (!legacy && !isValidState.get(entry.p)?.(entry.cs)) continue;
305
+ // Before v11 a clean scan could end past an interrupted request whose usage its state dropped,
306
+ // so a grown file re-parses whole instead of resuming.
307
+ const resumable = !legacy && !(entry.p === "codex" && version < 11);
308
309
const provider = entry.p;
310
const records = decodeRecords(entry.r, provider);
@@ -314,14 +318,14 @@ export function decodeScanCache(
318
records,
319
tailRecords,
320
malformedRecords,
317
- position: legacy
318
- ? { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null }
319
- : {
321
+ position: resumable
322
+ ? {
323
resumeOffset: entry.o,
324
guardLength: entry.gl,
325
guardHash: entry.gh,
326
state: entry.cs,
324
- },
327
+ }
328
+ : { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
329
});
330
}
331
apps/server/src/usage/usageTranscriptReader.test.ts
+77
-1
@@ -7,7 +7,7 @@ import * as NodePath from "node:path";
7
import * as NodeZlib from "node:zlib";
8
9
import { afterEach, assert, beforeEach, describe, it } from "@effect/vitest";
10
-import type { TranscriptUsageFormat } from "@t3tools/provider-core/server/usage";
10
+import { totalTokens, type TranscriptUsageFormat } from "@t3tools/provider-core/server/usage";
11
import * as Schema from "effect/Schema";
12
13
import { TEST_FORMATS } from "./usageTestFormats.ts";
@@ -381,6 +381,82 @@ describe("readTranscriptRecords resume", () => {
381
},
382
);
383
384
+ it.each([
385
+ { mode: "buffered", streamingThresholdBytes: Infinity },
386
+ { mode: "streaming", streamingThresholdBytes: 0 },
387
+ ])(
388
+ "bills a Codex request whose turn was interrupted before its token_count ($mode)",
389
+ async (options) => {
390
+ const path = NodePath.join(dir, "rollout.jsonl");
391
+ const usage = (input: number, output: number) => ({
392
+ input_tokens: input,
393
+ cached_input_tokens: 0,
394
+ cache_write_input_tokens: 0,
395
+ output_tokens: output,
396
+ reasoning_output_tokens: 0,
397
+ total_tokens: input + output,
398
+ });
399
+ const context = (turn: number) => ({
400
+ type: "turn_context",
401
+ timestamp: `2026-11-02T10:00:0${turn * 4 - 4}.000Z`,
402
+ payload: { turn_id: `turn-${turn}`, model: "gpt-6-sol" },
403
+ });
404
+ const request = (turn: number, id: number, timestamp: string, last: unknown) => ({
405
+ type: "token_usage_record",
406
+ timestamp,
407
+ payload: { turn_id: `turn-${turn}`, response_id: `resp_${id}`, usage: last },
408
+ });
409
+ const tokenCount = (timestamp: string, last: unknown, total: unknown) => ({
410
+ type: "event_msg",
411
+ timestamp,
412
+ payload: {
413
+ type: "token_count",
414
+ info: { last_token_usage: last, total_token_usage: total },
415
+ },
416
+ });
417
+ const lines = [
418
+ {
419
+ type: "session_meta",
420
+ timestamp: "2026-11-02T10:00:00.000Z",
421
+ payload: { id: "aborted-turn-repro", model_provider: "openai" },
422
+ },
423
+ context(1),
424
+ request(1, 1, "2026-11-02T10:00:01.000Z", usage(100, 20)),
425
+ tokenCount("2026-11-02T10:00:01.001Z", usage(100, 20), usage(100, 20)),
426
+ // Interrupted after this request finished: no token_count reports it.
427
+ request(1, 2, "2026-11-02T10:00:02.000Z", usage(150, 10)),
428
+ {
429
+ type: "event_msg",
430
+ timestamp: "2026-11-02T10:00:03.000Z",
431
+ payload: { type: "turn_aborted", turn_id: "turn-1", reason: "interrupted" },
432
+ },
433
+ context(2),
434
+ request(2, 3, "2026-11-02T10:00:05.000Z", usage(200, 30)),
435
+ tokenCount("2026-11-02T10:00:05.001Z", usage(200, 30), usage(450, 60)),
436
+ ];
437
+ // Lines longer than a read chunk take the projected path when streaming.
438
+ const padding = "x".repeat(256 * 1024);
439
+ await NodeFSP.writeFile(
440
+ path,
441
+ lines.map((line) => `${JSON.stringify({ padding, ...line })}\n`).join(""),
442
+ );
443
+
444
+ const result = await readTranscriptRecords(path, TEST_FORMATS.codex, undefined, options);
445
+ assert.isNotNull(result);
446
+ const requests = [...result.records, ...result.tailRecords]
447
+ .map((record) => totalTokens(record.totals))
448
+ .toSorted((a, b) => a - b);
449
+ assert.deepStrictEqual(
450
+ {
451
+ billedTokens: requests.reduce((sum, tokens) => sum + tokens, 0),
452
+ requests,
453
+ malformedRecords: result.malformedRecords,
454
+ },
455
+ { billedTokens: 510, requests: [120, 160, 230], malformedRecords: 0 },
456
+ );
457
+ },
458
+ );
459
+
460
it("re-parses from the start when the guard bytes no longer match", async () => {
461
const path = NodePath.join(dir, "claude.jsonl");
462
await NodeFSP.writeFile(path, claudeLine(1, 5));