The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 19:45 UTC
fix(usage): count Codex request ledgers and replace archived cache entries (#35497)
Yash Singh committed
Nov 12, 2026 at 12:53 UTC
b42841808d47194de2713d8322e7222809c88166
7 files changed
+159
-21
apps/server/src/provider/Drivers/codexUsage.test.ts
+55
@@ -450,6 +450,61 @@ describe("parseCodexLine", () => {
450
expect(state.malformedRecords).toBe(0);
451
});
452
453
+ it("bills request-ledger usage through resumed context counters and compaction", () => {
454
+ const state = initialCodexScanState();
455
+ const request = (response_id: string, usage: unknown) =>
456
+ JSON.stringify({
457
+ type: "token_usage_record",
458
+ timestamp: "2026-08-01T05:17:45.000Z",
459
+ payload: { response_id, usage },
460
+ });
461
+ parseCodexLine(sessionMeta, state);
462
+ parseCodexLine(turnContext, state);
463
+ parseCodexLine(counted(counters(100, 20), counters(1000, 200)), state);
464
+ // Resume restores older context counters, while the request ledger continues.
465
+ expect(
466
+ parseCodexLine(request("response-1", counters(80, 10)), state)?.totals.outputTokens,
467
+ ).toBe(10);
468
+ expect(parseCodexLine(counted(counters(80, 10), counters(580, 110)), state)).toBeNull();
469
+ // Rate-limit refreshes repeat the snapshot without another request.
470
+ expect(parseCodexLine(counted(counters(80, 10), counters(580, 110)), state)).toBeNull();
471
+ expect(
472
+ parseCodexLine(request("compaction", counters(90, 15)), state)?.totals.outputTokens,
473
+ ).toBe(15);
474
+ parseCodexLine(turnContext, state);
475
+ expect(
476
+ parseCodexLine(counted({ ...counters(0, 0), total_tokens: 40 }, counters(580, 110)), state),
477
+ ).toBeNull();
478
+ expect(parseCodexLine(request("response-2", counters(30, 5)), state)?.totals.outputTokens).toBe(
479
+ 5,
480
+ );
481
+ expect(parseCodexLine(counted(counters(30, 5), counters(610, 115)), state)).toBeNull();
482
+ expect(state.malformedRecords).toBe(0);
483
+ // A later turn from an older CLI can still report usage through snapshots alone.
484
+ parseCodexLine(turnContext, state);
485
+ expect(
486
+ parseCodexLine(counted(counters(20, 2), counters(630, 117)), state)?.totals.outputTokens,
487
+ ).toBe(2);
488
+ expect(
489
+ parseCodexLine(request("interrupted", counters(40, 4)), state)?.totals.outputTokens,
490
+ ).toBe(4);
491
+ parseCodexLine(turnContext, state);
492
+ expect(
493
+ parseCodexLine(counted(counters(10, 1), counters(680, 122)), state)?.totals.outputTokens,
494
+ ).toBe(1);
495
+ expect(parseCodexLine(request("", counters(15, 3)), state)).toBeNull();
496
+ parseCodexLine(turnContext, state);
497
+ const transition = parseCodexRecords(request("upgraded", counters(25, 5)), state);
498
+ expect(transition.map((record) => record.totals.outputTokens)).toEqual([3, 5]);
499
+ expect(parseCodexLine(counted(counters(25, 5), counters(720, 130)), state)).toBeNull();
500
+ expect(parseCodexLine(request("", counters(10, 1)), state)).toBeNull();
501
+ expect(
502
+ parseCodexLine(counted(counters(10, 1), counters(730, 131)), state)?.totals.outputTokens,
503
+ ).toBe(1);
504
+ expect(parseCodexLine(counted(counters(10, 1), counters(730, 131)), state)).toBeNull();
505
+ expect(state.malformedRecords).toBe(0);
506
+ });
507
+
508
it("does not bill a context-window estimate or lose the following real request", () => {
509
const state = initialCodexScanState();
510
parseCodexLine(turnContext, state);
apps/server/src/provider/Drivers/codexUsage.ts
+30
-3
@@ -127,6 +127,7 @@ export const CodexScanState = Schema.Struct({
127
unreportedRequests: Schema.mutableKey(
128
Schema.optionalKey(Schema.mutable(Schema.Array(CodexUnreportedRequest))),
129
),
130
+ requestLedgerActive: Schema.mutableKey(Schema.optionalKey(Schema.Boolean)),
131
malformedRecords: Schema.mutableKey(TokenCount),
132
sawSessionMeta: Schema.mutableKey(Schema.Boolean),
133
modelProvider: Schema.mutableKey(Schema.String),
@@ -181,8 +182,8 @@ function isForkCopy(state: CodexScanState, timestampMs: number): boolean {
182
}
183
184
/**
184
- * Cumulative counters validate request deltas. Older events without cumulative counters use
185
- * normalized consecutive-request deduplication.
185
+ * Identified request-ledger entries report spending independently of context snapshots.
186
+ * Legacy snapshots validate request deltas against cumulative counters.
187
*/
188
export function parseCodexLine(line: string, state: CodexScanState): readonly UsageRecord[] {
189
let parsed: unknown;
@@ -221,6 +222,7 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
222
}
223
224
if (record["type"] === "turn_context") {
225
+ state.requestLedgerActive = false;
226
if (typeof payloadRecord["model"] === "string") state.model = payloadRecord["model"];
227
// Model carry is useful for usage, but history recovery needs this context's own identity.
228
state.turnId =
@@ -232,13 +234,31 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
234
return [];
235
}
236
235
- // Several of these may sit between two snapshots, so they only explain a gap in the counters.
237
+ // Request ledgers include spending that context snapshots can omit.
238
if (record["type"] === "token_usage_record") {
239
const timestampMs = parseTimestampMs(record["timestamp"]);
240
const usage = readCodexTokenUsage(payloadRecord["usage"]);
241
if (timestampMs === null || usage === null || state.model.length === 0) return [];
242
// Copied history is already billed in the parent.
243
if (isForkCopy(state, timestampMs)) return [];
244
+ const responseId = payloadRecord["response_id"];
245
+ if (typeof responseId === "string" && responseId.length > 0) {
246
+ const pending = state.unreportedRequests ?? [];
247
+ state.requestLedgerActive = true;
248
+ for (const request of pending) {
249
+ state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, request.usage);
250
+ }
251
+ state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, usage);
252
+ delete state.unreportedRequests;
253
+ return [
254
+ ...pending.map((request) => codexRequestRecord(state, request.usage, request)),
255
+ {
256
+ ...codexRequestRecord(state, usage, codexAttribution(state, timestampMs)),
257
+ dedupeKey: JSON.stringify(["codex", state.sessionId, responseId]),
258
+ },
259
+ ];
260
+ }
261
+ state.requestLedgerActive = false;
262
(state.unreportedRequests ??= []).push({ ...codexAttribution(state, timestampMs), usage });
263
return [];
264
}
@@ -278,6 +298,12 @@ function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly Usag
298
return [];
299
}
300
301
+ // Context snapshots can rewind on resume and omit compaction spending; identified requests are authoritative.
302
+ if (state.requestLedgerActive) {
303
+ if (cumulative !== null) rebaseCodexUsage(state, cumulative);
304
+ return [];
305
+ }
306
+
307
const previous = state.lastCumulativeUsage;
308
const pending = state.unreportedRequests;
309
// A valid snapshot remains the next baseline even when its paired request is malformed.
@@ -418,6 +444,7 @@ export const codexUsageFormat: TranscriptUsageFormat<CodexScanState> = {
444
session_id: true,
445
model_provider: true,
446
turn_id: true,
447
+ response_id: true,
448
model: true,
449
thread_settings: { service_tier: true },
450
forked_from_id: true,
apps/server/src/usage/UsageService.test.ts
+49
-3
@@ -577,9 +577,55 @@ describe("UsageService", () => {
577
assert.strictEqual(totalOutputTokens(rewritten), 71);
578
assert.deepStrictEqual((yield* service.readSummary(WINDOW)).buckets, rewritten.buckets);
579
yield* service.awaitPersisted;
580
+ const { stateDir } = yield* ServerConfig.ServerConfig;
581
+ const cachePath = NodePath.join(stateDir, SCAN_CACHE_FILE_NAME);
582
+ const originalPath = (yield* Effect.promise(() => NodeFSP.realpath(compressedPath))).slice(
583
+ 0,
584
+ -4,
585
+ );
586
+ yield* Effect.promise(async () => {
587
+ const document = decodeUnknownJsonString(await NodeFSP.readFile(cachePath, "utf8")) as {
588
+ files: Record<
589
+ string,
590
+ { cs: Record<string, unknown>; r: unknown[]; t: unknown[]; mr: number }
591
+ >;
592
+ };
593
+ const archived = document.files[await NodeFSP.realpath(compressedPath)];
594
+ assert.ok(archived);
595
+ document.files[originalPath] = {
596
+ ...archived,
597
+ r: [],
598
+ t: [],
599
+ mr: 1,
600
+ cs: { ...archived.cs, malformedRecords: 1 },
601
+ };
602
+ await NodeFSP.writeFile(cachePath, encodeUnknownJsonString(document));
603
+ });
604
const restarted = yield* UsageService.make;
581
- assert.deepStrictEqual((yield* restarted.readSummary(WINDOW)).buckets, rewritten.buckets);
605
+ const restored = yield* restarted.readSummary(WINDOW);
606
+ assert.deepStrictEqual(restored.buckets, rewritten.buckets);
607
+ assert.strictEqual(
608
+ restored.sources.find((source) => source.fingerprint.provider === "codex")
609
+ ?.malformedRecords,
610
+ 0,
611
+ );
612
yield* restarted.awaitPersisted;
613
+ yield* Effect.promise(async () => {
614
+ const document = decodeUnknownJsonString(await NodeFSP.readFile(cachePath, "utf8")) as {
615
+ files: Record<string, unknown>;
616
+ };
617
+ assert.strictEqual(document.files[originalPath], undefined);
618
+ await NodeFSP.rm(compressedPath);
619
+ });
620
+ const removed = yield* UsageService.make;
621
+ const retained = yield* removed.readSummary(WINDOW);
622
+ assert.deepStrictEqual(retained.buckets, rewritten.buckets);
623
+ assert.strictEqual(
624
+ retained.sources.find((source) => source.fingerprint.provider === "codex")
625
+ ?.malformedRecords,
626
+ 0,
627
+ );
628
+ yield* removed.awaitPersisted;
629
}).pipe(
630
Effect.scoped,
631
Effect.provide(layerService({ prefix: "usage-compressed-codex", home, settings })),
@@ -2789,7 +2835,7 @@ describe("UsageService", () => {
2835
}).pipe(Effect.scoped),
2836
);
2837
2792
- it.live.each([4, 5, 6, 7, 8, 10])(
2838
+ it.live.each([4, 5, 6, 7, 8, 10, 11, 12, 13])(
2839
"upgrades a v%s cache: reparses live Codex usage, keeps deleted rollouts, removes the old file",
2840
(version) =>
2841
Effect.gen(function* () {
@@ -2890,7 +2936,7 @@ describe("UsageService", () => {
2936
60 + 20 * (version === 4 ? 1 : 2),
2937
);
2938
yield* upgraded.awaitPersisted;
2893
- assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v13.json");
2939
+ assert.strictEqual(SCAN_CACHE_FILE_NAME, "usage-scan-cache-v14.json");
2940
assert.deepStrictEqual(
2941
(yield* Effect.promise(() => NodeFSP.readdir(stateDir)))
2942
.filter((name) => name.startsWith("usage-scan-cache"))
apps/server/src/usage/UsageService.ts
+7
@@ -638,6 +638,13 @@ export const make = Effect.gen(function* () {
638
}
639
return { path, records, malformedRecords };
640
});
641
+ const livePaths = new Set(files.map((file) => file.path));
642
+ for (const file of read) {
643
+ if (file.failed || !file.path.endsWith(".jsonl.zst")) continue;
644
+ const originalPath = file.path.slice(0, -4);
645
+ // A successfully read archive replaces the original's saved records and diagnostics.
646
+ if (!livePaths.has(originalPath) && fileCache.delete(originalPath)) cacheDirty = true;
647
+ }
648
const unread = failedPaths + read.filter((file) => file.failed).length;
649
yield* Effect.annotateCurrentSpan({
650
"usage.files": files.length,
apps/server/src/usage/usageScanCache.test.ts
+11
-7
@@ -168,7 +168,7 @@ describe("scan cache round trip", () => {
168
expect(restored).toEqual(original);
169
});
170
171
- it.each([5, 6, 7, 8, 10])(
171
+ it.each([5, 6, 7, 8, 10, 11, 12, 13])(
172
"retains v%s history and compatible positions but invalidates obsolete state",
173
(version) => {
174
const original = cacheWith([["/gone.jsonl", 100, [record({ speed: "fast" })]]]);
@@ -225,11 +225,15 @@ describe("scan cache round trip", () => {
225
};
226
227
const restored = decodeScanCache(JSON.parse(JSON.stringify(legacy)), TEST_FORMAT_MAP);
228
- expect(restored.get("/gone.jsonl")).toEqual({
229
- ...original.get("/gone.jsonl"),
230
- size: -1,
231
- position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
232
- });
228
+ expect(restored.get("/gone.jsonl")).toEqual(
229
+ version >= 13
230
+ ? original.get("/gone.jsonl")
231
+ : {
232
+ ...original.get("/gone.jsonl"),
233
+ size: -1,
234
+ position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
235
+ },
236
+ );
237
expect(restored.get("/gone-codex.jsonl")).toEqual({
238
...original.get("/gone-codex.jsonl"),
239
size: -1,
@@ -237,7 +241,7 @@ describe("scan cache round trip", () => {
241
});
242
expect(restored.get("/clean-codex.jsonl")).toEqual({
243
...cleanCodex,
240
- size: version >= 8 ? cleanCodex.size : -1,
244
+ size: -1,
245
position: { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
246
});
247
expect(restored.get("/gone-pi.jsonl")).toEqual(
apps/server/src/usage/usageScanCache.ts
+5
-6
@@ -10,7 +10,7 @@ import { CLAUDE_SYNTHETIC_MODEL } from "../provider/Drivers/claudeUsage.ts";
10
import { mergeUsageCopies } from "./usageAggregation.ts";
11
import { GUARD_LENGTH, type TranscriptParsePosition } from "./usageTranscriptReader.ts";
12
13
-const USAGE_SCAN_CACHE_VERSION = 13 as const;
13
+const USAGE_SCAN_CACHE_VERSION = 14 as const;
14
const SPEED_COMPATIBLE_SINCE_VERSION = 4;
15
16
/**
@@ -18,8 +18,9 @@ const SPEED_COMPATIBLE_SINCE_VERSION = 4;
18
* replace it, dropping saved usage for deleted transcripts. Separate files keep
19
* the newer one; older files are removed once it is saved.
20
*/
21
-export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v13.json";
21
+export const SCAN_CACHE_FILE_NAME = "usage-scan-cache-v14.json";
22
export const LEGACY_SCAN_CACHE_FILE_NAMES = [
23
+ "usage-scan-cache-v13.json",
24
"usage-scan-cache-v12.json",
25
"usage-scan-cache-v11.json",
26
"usage-scan-cache-v10.json",
@@ -296,14 +297,12 @@ export function decodeScanCache(
297
continue;
298
}
299
// Keep history for deleted rollouts, but re-parse incompatible reducer state.
299
- // v9 and v11 repair skipped Codex requests; clean v8+ entries stay served while unchanged.
300
+ // v14 uses Codex request ledgers, including compaction spending omitted by context snapshots.
301
// v10 adds Claude advisor calls; before v12 a repeated Claude key kept its first, possibly partial, copy.
302
// v13 adds Claude 1-hour cache writes.
303
const legacy =
304
(entry.p === "claude" && version < 13) ||
304
- (format.state !== undefined &&
305
- (version < 6 ||
306
- (entry.p === "codex" && (version < 8 || (version < 11 && malformedRecords > 0)))));
305
+ (format.state !== undefined && (version < 6 || (entry.p === "codex" && version < 14)));
306
// A corrupt state disqualifies the entry: resuming with it would attach
307
// appended usage to the wrong model or replay fork-copied history.
308
if (!legacy && !isValidState.get(entry.p)?.(entry.cs)) continue;
apps/server/src/vcs/VcsStatusBroadcaster.test.ts
+2
-2
@@ -1555,13 +1555,13 @@ describe("VcsStatusBroadcaster", () => {
1555
yield* Effect.gen(function* () {
1556
const broadcaster = yield* VcsStatusBroadcaster.VcsStatusBroadcaster;
1557
const branches = yield* Stream.toPull(broadcaster.streamBranchStatus({ cwd: "/repo" }));
1558
- assert.deepEqual(yield* branches, [{ refName: "main" }]);
1558
+ assert.deepEqual(yield* branches, [{ refName: "main", isRepo: true }]);
1559
1560
// Every checkout removes HEAD.lock, which leaves the watch running.
1561
state.currentLocalStatus = { ...baseLocalStatus, refName: "other" };
1562
yield* Queue.offer(events, { _tag: "Remove", path: "HEAD.lock" });
1563
yield* Queue.offer(events, { _tag: "Update", path: "HEAD" });
1564
- assert.deepEqual(yield* branches, [{ refName: "other" }]);
1564
+ assert.deepEqual(yield* branches, [{ refName: "other", isRepo: true }]);
1565
1566
// `git worktree remove` deletes the watched directory; Windows keeps reporting it.
1567
gitDirExists = false;