@devries-cameron20 / t3code Mirror · read-only
Fork 0

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, 04:45 UTC

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