@devries-cameron20 / t3code-1 / commits / 84547b988d
Fork 0

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));