Skip to content
Source
Sign inSign up
pingdotgg/t3code
Open History to see the last commit

codexUsage.ts

525 lines20.1 KB

1import type { CodexSettings } from "@t3tools/contracts";
2import * as Effect from "effect/Effect";
3import * as Path from "effect/Path";
4import * as Schema from "effect/Schema";
5​
6import {
7 parseTimestampMs,
8 type ProviderUsageReader,
9 type TranscriptUsageFormat,
10 type UsageRecord,
11 type UsageSpeed,
12} from "@t3tools/provider-core/server/usage";
13import type { UsageTokenTotals } from "@t3tools/contracts";
14​
15import * as CodexUsageHistory from "../../usage/CodexUsageHistory.ts";
16import { resolveCodexHomeLayout } from "./CodexHomeLayout.ts";
17​
18const TokenCount = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
19const CodexTokenUsage = Schema.Struct({
20 input_tokens: TokenCount,
21 cached_input_tokens: TokenCount,
22 cache_write_input_tokens: TokenCount,
23 output_tokens: TokenCount,
24 reasoning_output_tokens: TokenCount,
25 total_tokens: TokenCount,
26}).check(
27 Schema.makeFilter(
28 (usage) =>
29 usage.cached_input_tokens + usage.cache_write_input_tokens <= usage.input_tokens &&
30 usage.reasoning_output_tokens <= usage.output_tokens &&
31 usage.total_tokens >= usage.input_tokens + usage.output_tokens,
32 ),
33);
34type CodexTokenUsage = typeof CodexTokenUsage.Type;
35const isCodexTokenUsage = Schema.is(CodexTokenUsage);
36const CODEX_USAGE_FIELDS = Object.keys(CodexTokenUsage.fields) as (keyof CodexTokenUsage)[];
37​
38function readCodexTokenUsage(value: unknown): CodexTokenUsage | null {
39 if (typeof value !== "object" || value === null || Array.isArray(value)) return null;
40 const raw = value as Record<string, unknown>;
41 const input = raw["input_tokens"];
42 const output = raw["output_tokens"];
43 if (typeof input !== "number" || typeof output !== "number") return null;
44 const usage = {
45 input_tokens: input,
46 cached_input_tokens: raw["cached_input_tokens"] === undefined ? 0 : raw["cached_input_tokens"],
47 cache_write_input_tokens:
48 raw["cache_write_input_tokens"] === undefined ? 0 : raw["cache_write_input_tokens"],
49 output_tokens: output,
50 reasoning_output_tokens:
51 raw["reasoning_output_tokens"] === undefined ? 0 : raw["reasoning_output_tokens"],
52 total_tokens: raw["total_tokens"] === undefined ? input + output : raw["total_tokens"],
53 };
54 return isCodexTokenUsage(usage) ? usage : null;
56​
57// A zeroed baseline rebases the counters, so the sequence start measured against it is forgotten.
58function rebaseCodexUsage(state: CodexScanState, cumulative: CodexTokenUsage, timestampMs: number) {
59 state.lastCumulativeUsage = cumulative;
60 state.latestCumulativeAtMs = Math.max(state.latestCumulativeAtMs ?? timestampMs, timestampMs);
61 delete state.unreportedRequests;
62 if (cumulative.input_tokens + cumulative.output_tokens === 0) delete state.sequenceStartSignature;
64​
65function advanceCodexUsage(previous: CodexTokenUsage | null, last: CodexTokenUsage) {
66 return readCodexTokenUsage(
67 Object.fromEntries(CODEX_USAGE_FIELDS.map((key) => [key, (previous?.[key] ?? 0) + last[key]])),
68 );
70​
71const CodexSpeed = Schema.Literals(["standard", "fast", "ultrafast"]);
72​
73// What a request is billed as is fixed when it is read, not when a later snapshot reconciles it.
74const CodexUnreportedRequest = Schema.Struct({
75 timestampMs: Schema.Finite,
76 model: Schema.String,
77 turnId: Schema.String,
78 speed: CodexSpeed,
79 sawThreadSettings: Schema.Boolean,
80 usage: CodexTokenUsage,
81});
82type CodexUnreportedRequest = typeof CodexUnreportedRequest.Type;
83type CodexRequestAttribution = Omit<CodexUnreportedRequest, "usage">;
84​
85// An interrupted turn can end before a snapshot reports its last request. Bill those requests only
86// when the `token_usage_record`s since the previous snapshot explain the whole gap; `last` is the
87// final one.
88function unreportedRequests(
89 previous: CodexTokenUsage | null,
90 cumulative: CodexTokenUsage,
91 last: CodexTokenUsage,
92 pending: readonly CodexUnreportedRequest[] | undefined,
93) {
94 if (
95 previous === null ||
96 pending === undefined ||
97 CODEX_USAGE_FIELDS.some(
98 (key) =>
99 cumulative[key] - previous[key] !==
100 pending.reduce((sum, request) => sum + request.usage[key], 0),
101 )
102 ) {
103 return null;
104 }
105 const final = pending.at(-1)!;
106 const remainder = readCodexTokenUsage(
107 Object.fromEntries(CODEX_USAGE_FIELDS.map((key) => [key, final.usage[key] - last[key]])),
108 );
109 if (remainder === null) return null;
110 return [...pending.slice(0, -1), { ...final, usage: remainder }].filter(
111 (request) => request.usage.input_tokens + request.usage.output_tokens > 0,
112 );
114​
115/**
116 * Codex `token_count` events carry no model or service tier, so both are carried forward: the model
117 * from the most recent `turn_context`, the tier from the most recent `thread_settings_applied`.
118 */
119export const CodexScanState = Schema.Struct({
120 model: Schema.mutableKey(Schema.String),
121 speed: Schema.mutableKey(CodexSpeed),
122 sessionId: Schema.mutableKey(Schema.String),
123 lastUsageSignature: Schema.mutableKey(Schema.NullOr(Schema.String)),
124 lastCumulativeUsage: Schema.mutableKey(Schema.NullOr(CodexTokenUsage)),
125 // Optional so scan states cached before these fields existed stay valid.
126 sequenceStartSignature: Schema.mutableKey(Schema.optionalKey(Schema.String)),
127 latestCumulativeAtMs: Schema.mutableKey(Schema.optionalKey(Schema.Finite)),
128 // `token_usage_record` usage since the last cumulative snapshot, one entry per record.
129 unreportedRequests: Schema.mutableKey(
130 Schema.optionalKey(Schema.mutable(Schema.Array(CodexUnreportedRequest))),
131 ),
132 requestLedgerActive: Schema.mutableKey(Schema.optionalKey(Schema.Boolean)),
133 malformedRecords: Schema.mutableKey(TokenCount),
134 sawSessionMeta: Schema.mutableKey(Schema.Boolean),
135 modelProvider: Schema.mutableKey(Schema.String),
136 turnId: Schema.mutableKey(Schema.String),
137 sawThreadSettings: Schema.mutableKey(Schema.Boolean),
138 suppressingForkCopies: Schema.mutableKey(Schema.Boolean),
139 forkCopyAnchorMs: Schema.mutableKey(Schema.Finite),
140});
141export type CodexScanState = typeof CodexScanState.Type;
142​
143export function initialCodexScanState(): CodexScanState {
144 return {
145 model: "",
146 speed: "standard",
147 sessionId: "",
148 lastUsageSignature: null,
149 lastCumulativeUsage: null,
150 malformedRecords: 0,
151 sawSessionMeta: false,
152 modelProvider: "",
153 turnId: "",
154 sawThreadSettings: false,
155 suppressingForkCopies: false,
156 forkCopyAnchorMs: 0,
157 };
159​
160/** Forks copy and restamp parent history in a burst (0-40ms gaps); genuine child usage follows a model turn (5s+ observed). */
161const FORK_COPY_MAX_GAP_MS = 1000;
162​
163function isForkedSessionMeta(payload: Record<string, unknown>): boolean {
164 if (typeof payload["forked_from_id"] === "string") return true;
165 const source = payload["source"];
166 if (typeof source !== "object" || source === null) return false;
167 const subagent = (source as Record<string, unknown>)["subagent"];
168 if (typeof subagent !== "object" || subagent === null) return false;
169 const spawn = (subagent as Record<string, unknown>)["thread_spawn"];
170 if (typeof spawn !== "object" || spawn === null) return false;
171 return typeof (spawn as Record<string, unknown>)["parent_thread_id"] === "string";
173​
174// The first usage line past the copied burst ends suppression for the rest of the rollout.
175function isForkCopy(state: CodexScanState, timestampMs: number): boolean {
176 if (!state.suppressingForkCopies) return false;
177 if (timestampMs - state.forkCopyAnchorMs < FORK_COPY_MAX_GAP_MS) {
178 state.forkCopyAnchorMs = timestampMs;
179 return true;
180 }
181 state.suppressingForkCopies = false;
182 state.lastUsageSignature = null;
183 return false;
185​
186/**
187 * Identified request-ledger entries report spending independently of context snapshots.
188 * Legacy snapshots validate request deltas against cumulative counters.
189 */
190export function parseCodexLine(line: string, state: CodexScanState): readonly UsageRecord[] {
191 let parsed: unknown;
192 try {
193 parsed = JSON.parse(line);
194 } catch {
195 return [];
196 }
197 return parseCodexRecord(parsed, state);
199​
200function parseCodexRecord(parsed: unknown, state: CodexScanState): readonly UsageRecord[] {
201 if (typeof parsed !== "object" || parsed === null) return [];
202​
203 const record = parsed as Record<string, unknown>;
204 const payload = record["payload"];
205 if (typeof payload !== "object" || payload === null) return [];
206 const payloadRecord = payload as Record<string, unknown>;
207 const payloadType = payloadRecord["type"];
208​
209 if (record["type"] === "session_meta") {
210 // Only the first meta identifies this session; copied ancestor metas would misattribute later records.
211 if (state.sawSessionMeta) return [];
212 state.sawSessionMeta = true;
213 const id = payloadRecord["id"] ?? payloadRecord["session_id"];
214 if (typeof id === "string") state.sessionId = id;
215 if (typeof payloadRecord["model_provider"] === "string") {
216 state.modelProvider = payloadRecord["model_provider"];
217 }
218 const metaTimestampMs = parseTimestampMs(record["timestamp"]);
219 if (metaTimestampMs !== null && isForkedSessionMeta(payloadRecord)) {
220 state.suppressingForkCopies = true;
221 state.forkCopyAnchorMs = metaTimestampMs;
222 }
223 return [];
224 }
225​
226 if (record["type"] === "turn_context") {
227 state.requestLedgerActive = false;
228 if (typeof payloadRecord["model"] === "string") state.model = payloadRecord["model"];
229 // Model carry is useful for usage, but history recovery needs this context's own identity.
230 state.turnId =
231 typeof payloadRecord["turn_id"] === "string" &&
232 typeof payloadRecord["model"] === "string" &&
233 payloadRecord["model"].length > 0
234 ? payloadRecord["turn_id"]
235 : "";
236 return [];
237 }
238​
239 // Request ledgers include spending that context snapshots can omit.
240 if (record["type"] === "token_usage_record") {
241 const timestampMs = parseTimestampMs(record["timestamp"]);
242 const usage = readCodexTokenUsage(payloadRecord["usage"]);
243 if (timestampMs === null || usage === null || state.model.length === 0) return [];
244 // Copied history is already billed in the parent.
245 if (isForkCopy(state, timestampMs)) return [];
246 const responseId = payloadRecord["response_id"];
247 if (typeof responseId === "string" && responseId.length > 0) {
248 const pending = state.unreportedRequests ?? [];
249 state.requestLedgerActive = true;
250 for (const request of pending) {
251 state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, request.usage);
252 }
253 state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, usage);
254 delete state.unreportedRequests;
255 return [
256 ...pending.map((request) => codexRequestRecord(state, request.usage, request)),
257 {
258 ...codexRequestRecord(state, usage, codexAttribution(state, timestampMs)),
259 dedupeKey: JSON.stringify(["codex", state.sessionId, responseId]),
260 },
261 ];
262 }
263 state.requestLedgerActive = false;
264 (state.unreportedRequests ??= []).push({ ...codexAttribution(state, timestampMs), usage });
265 return [];
266 }
267​
268 if (payloadType === "thread_settings_applied") {
269 state.sawThreadSettings = true;
270 const settings = payloadRecord["thread_settings"];
271 if (typeof settings === "object" && settings !== null) {
272 state.speed = codexSpeed((settings as Record<string, unknown>)["service_tier"]);
273 }
274 return [];
275 }
276​
277 if (payloadType !== "token_count") return [];
278​
279 const info = payloadRecord["info"];
280 if (typeof info !== "object" || info === null) return [];
281 const infoRecord = info as Record<string, unknown>;
282​
283 // Codex may re-emit these counters after the model or timestamp becomes available.
284 const timestampMs = parseTimestampMs(record["timestamp"]);
285 if (timestampMs === null || state.model.length === 0) return [];
286​
287 const last = readCodexTokenUsage(infoRecord["last_token_usage"]);
288 const rawCumulative = infoRecord["total_token_usage"];
289 const hasCumulative = rawCumulative !== undefined && rawCumulative !== null;
290 const cumulative = hasCumulative ? readCodexTokenUsage(rawCumulative) : null;
291​
292 if (isForkCopy(state, timestampMs)) {
293 // Copied history is already billed in the parent, but establishes the child's baseline.
294 const signature = last === null ? null : JSON.stringify(last);
295 if (cumulative !== null) rebaseCodexUsage(state, cumulative, timestampMs);
296 else if (!hasCumulative && last !== null && signature !== state.lastUsageSignature) {
297 state.lastCumulativeUsage = advanceCodexUsage(state.lastCumulativeUsage, last);
298 }
299 state.lastUsageSignature = signature;
300 return [];
301 }
302​
303 // Context snapshots can rewind on resume and omit compaction spending; identified requests are authoritative.
304 if (state.requestLedgerActive) {
305 if (cumulative !== null) rebaseCodexUsage(state, cumulative, timestampMs);
306 return [];
307 }
308​
309 const previous = state.lastCumulativeUsage;
310 const latestCumulativeAtMs = state.latestCumulativeAtMs;
311 const pending = state.unreportedRequests;
312 // A valid snapshot remains the next baseline even when its paired request is malformed.
313 if (cumulative !== null) rebaseCodexUsage(state, cumulative, timestampMs);
314 if (last === null || (hasCumulative && cumulative === null)) {
315 state.malformedRecords += 1;
316 return [];
317 }
318​
319 // Zero-component counters report context size, not a request: fill_to_context_window, or the
320 // post-compaction marker whose total is the new context size (its cumulative may reset to zero).
321 if (last.input_tokens + last.output_tokens === 0) {
322 state.lastUsageSignature = null;
323 return [];
324 }
325​
326 if (
327 cumulative !== null &&
328 previous !== null &&
329 CODEX_USAGE_FIELDS.every((key) => cumulative[key] === previous[key])
330 ) {
331 return [];
332 }
333​
334 if (last.total_tokens !== last.input_tokens + last.output_tokens) {
335 state.malformedRecords += 1;
336 return [];
337 }
338​
339 const signature = JSON.stringify(last);
340 let unreported: readonly CodexUnreportedRequest[] = [];
341 if (cumulative !== null) {
342 // A session resumed in a new Codex process restarts its cumulative counters at this request.
343 const restarted = CODEX_USAGE_FIELDS.every((key) => cumulative[key] === last[key]);
344 const sequenceStart = JSON.stringify([timestampMs, last]);
345 // Only the same event is a replay; a later request can restart with identical counters.
346 if (restarted && sequenceStart === state.sequenceStartSignature) {
347 state.lastCumulativeUsage = previous;
348 return [];
349 }
350 // Forks and paginated continuations can inherit totals without copying a counter snapshot, and
351 // a later request can continue from an earlier snapshot; a re-emitted old snapshot is not later.
352 // Only bill the latest request, and require the unseen prefix to be valid usage too.
353 const rewound =
354 previous !== null &&
355 (latestCumulativeAtMs === undefined || timestampMs > latestCumulativeAtMs) &&
356 CODEX_USAGE_FIELDS.some((key) => cumulative[key] < previous[key]);
357 const reconciled =
358 previous === null || rewound
359 ? readCodexTokenUsage(
360 Object.fromEntries(CODEX_USAGE_FIELDS.map((key) => [key, cumulative[key] - last[key]])),
361 ) !== null
362 : CODEX_USAGE_FIELDS.every((key) => cumulative[key] - previous[key] === last[key]);
363 if (!restarted && !reconciled) {
364 const bridged = unreportedRequests(previous, cumulative, last, pending);
365 if (bridged === null) {
366 state.malformedRecords += 1;
367 return [];
368 }
369 unreported = bridged;
370 }
371 if (restarted) state.sequenceStartSignature = sequenceStart;
372 } else {
373 if (signature === state.lastUsageSignature) return [];
374 // Advance expected totals for billed legacy requests so a cumulative re-emission is stale.
375 const advanced = advanceCodexUsage(previous, last);
376 if (advanced === null) {
377 state.malformedRecords += 1;
378 return [];
379 }
380 state.lastCumulativeUsage = advanced;
381 }
382 state.lastUsageSignature = signature;
383​
384 return [
385 ...unreported.map((request) => codexRequestRecord(state, request.usage, request)),
386 codexRequestRecord(state, last, codexAttribution(state, timestampMs)),
387 ];
389​
390function codexAttribution(state: CodexScanState, timestampMs: number): CodexRequestAttribution {
391 return {
392 timestampMs,
393 model: state.model,
394 turnId: state.turnId,
395 speed: state.speed,
396 sawThreadSettings: state.sawThreadSettings,
397 };
399​
400function codexRequestRecord(
401 state: CodexScanState,
402 usage: CodexTokenUsage,
403 { timestampMs, model, turnId, speed, sawThreadSettings }: CodexRequestAttribution,
404): UsageRecord {
405 const inputTokens = usage.input_tokens;
406 const cachedInputTokens = usage.cached_input_tokens;
407 const cacheCreationTokens = usage.cache_write_input_tokens;
408 const outputTokens = usage.output_tokens;
409​
410 const totals: UsageTokenTotals = {
411 // Codex reports `input_tokens` inclusive of the cached portion.
412 uncachedInputTokens: inputTokens - cachedInputTokens - cacheCreationTokens,
413 cachedInputTokens,
414 cacheCreationTokens,
415 outputTokens,
416 // Reported inside output_tokens, surfaced separately for the token mix.
417 reasoningTokens: usage.reasoning_output_tokens,
418 };
419​
420 return {
421 provider: "codex",
422 timestampMs,
423 model,
424 sessionId: state.sessionId,
425 totals,
426 reportedCostUsd: null,
427 speed,
428 ...(!sawThreadSettings &&
429 state.modelProvider === "openai" &&
430 state.sessionId.length > 0 &&
431 turnId.length > 0
432 ? { unresolvedServiceTierTurnId: turnId }
433 : {}),
434 dedupeKey: null,
435 };
437​
438/** Missing, default and standard tiers bill as standard; fast aliases priority. */
439function codexSpeed(serviceTier: unknown): UsageSpeed {
440 if (serviceTier === "priority" || serviceTier === "fast") return "fast";
441 if (serviceTier === "ultrafast") return "ultrafast";
442 return "standard";
444​
445export const codexUsageFormat: TranscriptUsageFormat<CodexScanState> = {
446 selectFields: {
447 type: true,
448 timestamp: true,
449 payload: {
450 type: true,
451 id: true,
452 session_id: true,
453 model_provider: true,
454 turn_id: true,
455 response_id: true,
456 model: true,
457 thread_settings: { service_tier: true },
458 forked_from_id: true,
459 source: { subagent: { thread_spawn: { parent_thread_id: true } } },
460 info: { last_token_usage: true, total_token_usage: true },
461 usage: true,
462 },
463 },
464 // Metadata lines carry model, tier and session even without usage.
465 usageMarkers: [
466 '"token_count"',
467 '"token_usage_record"',
468 '"turn_context"',
469 '"thread_settings_applied"',
470 '"session_meta"',
471 ],
472 parseLine: parseCodexLine,
473 parseProjected: parseCodexRecord,
474 state: { initial: initialCodexScanState, schema: CodexScanState },
475 readMalformedRecords: (state) => state.malformedRecords,
476 // A rollout that moved after it was read leaves a copy in both places.
477 sharedSessionsAcrossFiles: true,
478};
479​
480export const codexUsageReader: ProviderUsageReader<
481 CodexSettings,
482 Path.Path | CodexUsageHistory.CodexUsageHistory
483> = {
484 kind: "transcripts",
485 provider: "codex",
486 format: codexUsageFormat,
487 resolveServiceTiers: Effect.fn("codexUsageReader.resolveServiceTiers")(function* (records) {
488 const history = yield* CodexUsageHistory.CodexUsageHistory;
489 const requests = new Map<CodexUsageHistory.CodexUsageHistoryRequest, UsageRecord>();
490 for (const record of records) {
491 if (record.unresolvedServiceTierTurnId === undefined) continue;
492 requests.set(
493 {
494 sessionId: record.sessionId,
495 nativeTurnId: record.unresolvedServiceTierTurnId,
496 model: record.model,
497 },
498 record,
499 );
500 }
501 const resolved = yield* history.resolve([...requests.keys()]).pipe(
502 Effect.catchTags({
503 CodexUsageHistoryReadError: () =>
504 Effect.succeed(new Map<CodexUsageHistory.CodexUsageHistoryRequest, UsageSpeed>()),
505 }),
506 );
507 const speeds = new Map<UsageRecord, UsageSpeed>();
508 for (const [request, speed] of resolved) {
509 const record = requests.get(request);
510 if (record !== undefined) speeds.set(record, speed);
511 }
512 return speeds;
513 }),
514 directories: Effect.fn("codexUsageReader.directories")(function* ({ config, environment }) {
515 if (config === undefined) return [];
516 const path = yield* Path.Path;
517 const environmentHome = environment.CODEX_HOME?.trim();
518 const layout = yield* resolveCodexHomeLayout(
519 config.setupMode !== "managed" && !config.homePath.trim() && environmentHome
520 ? { ...config, homePath: environmentHome }
521 : config,
522 );
523 return [{ dir: path.resolve(layout.sharedHomePath, "sessions") }];
524 }),
525};