The best way to control Claude Code, Codex and more from any computer or phone

main
ts 396 lines 14 KB
Raw
1 import type { UsageProviderKind } from "@t3tools/contracts";
2 import type {
3 TranscriptUsageFormat,
4 UsageRecord,
5 UsageSpeed,
6 } from "@t3tools/provider-core/server/usage";
7 import * as Schema from "effect/Schema";
8
9 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 = 17 as const;
14 const SPEED_COMPATIBLE_SINCE_VERSION = 4;
15
16 /**
17 * An older server sharing that directory cannot read a newer cache and would
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-v17.json";
22 export const LEGACY_SCAN_CACHE_FILE_NAMES = [
23 "usage-scan-cache-v16.json",
24 "usage-scan-cache-v15.json",
25 "usage-scan-cache-v14.json",
26 "usage-scan-cache-v13.json",
27 "usage-scan-cache-v12.json",
28 "usage-scan-cache-v11.json",
29 "usage-scan-cache-v10.json",
30 "usage-scan-cache-v9.json",
31 "usage-scan-cache-v8.json",
32 "usage-scan-cache-v7.json",
33 "usage-scan-cache-v6.json",
34 "usage-scan-cache-v5.json",
35 "usage-scan-cache.json",
36 ] as const;
37
38 const SPEEDS: readonly UsageSpeed[] = ["standard", "fast", "ultrafast"];
39
40 export interface CachedFile {
41 readonly size: number;
42 readonly mtimeMs: number;
43 readonly provider: UsageProviderKind;
44 readonly records: readonly UsageRecord[];
45 /** Unterminated tail records stay separate because incremental parsing rereads them. */
46 readonly tailRecords: readonly UsageRecord[];
47 /** Whole-file count, including diagnostics from the tentative tail. */
48 readonly malformedRecords: number;
49 readonly position: TranscriptParsePosition;
50 }
51
52 export type ScanCache = Map<string, CachedFile>;
53
54 type SerializedRecord = readonly [
55 timestampMs: number,
56 modelIndex: number,
57 sessionIndex: number,
58 uncachedInputTokens: number,
59 cachedInputTokens: number,
60 cacheCreationTokens: number,
61 outputTokens: number,
62 reasoningTokens: number,
63 dedupeKey: string | null,
64 reportedCostUsd: number | null,
65 speed: number,
66 rateModelIndex?: number | null,
67 unresolvedServiceTierTurnId?: string | null,
68 cacheCreation1hTokens?: number,
69 ];
70
71 interface SerializedFile {
72 readonly s: number;
73 readonly m: number;
74 readonly p: UsageProviderKind;
75 readonly r: readonly SerializedRecord[];
76 readonly t: readonly SerializedRecord[];
77 readonly mr: number;
78 readonly o: number;
79 readonly gl: number;
80 readonly gh: number;
81 readonly cs: unknown;
82 }
83
84 interface SerializedCache {
85 readonly version: number;
86 readonly models: readonly string[];
87 readonly sessions: readonly string[];
88 readonly files: Readonly<Record<string, SerializedFile>>;
89 }
90
91 interface InternTables {
92 readonly models: string[];
93 readonly sessions: string[];
94 readonly modelIndex: Map<string, number>;
95 readonly sessionIndex: Map<string, number>;
96 }
97
98 function makeInternTables(): InternTables {
99 return { models: [], sessions: [], modelIndex: new Map(), sessionIndex: new Map() };
100 }
101
102 function intern(table: string[], index: Map<string, number>, value: string): number {
103 const existing = index.get(value);
104 if (existing !== undefined) return existing;
105 const next = table.length;
106 table.push(value);
107 index.set(value, next);
108 return next;
109 }
110
111 function serializeFile(entry: CachedFile, tables: InternTables): SerializedFile {
112 const serializeRecord = (record: UsageRecord): SerializedRecord => [
113 record.timestampMs,
114 intern(tables.models, tables.modelIndex, record.model),
115 intern(tables.sessions, tables.sessionIndex, record.sessionId),
116 record.totals.uncachedInputTokens,
117 record.totals.cachedInputTokens,
118 record.totals.cacheCreationTokens,
119 record.totals.outputTokens,
120 record.totals.reasoningTokens,
121 record.dedupeKey,
122 record.reportedCostUsd,
123 SPEEDS.indexOf(record.speed),
124 record.rateModel === undefined
125 ? null
126 : intern(tables.models, tables.modelIndex, record.rateModel),
127 ...(record.cacheCreation1hTokens !== undefined
128 ? ([record.unresolvedServiceTierTurnId ?? null, record.cacheCreation1hTokens] as const)
129 : record.unresolvedServiceTierTurnId !== undefined
130 ? ([record.unresolvedServiceTierTurnId] as const)
131 : ([] as const)),
132 ];
133 return {
134 s: entry.size,
135 m: entry.mtimeMs,
136 p: entry.provider,
137 r: entry.records.map(serializeRecord),
138 t: entry.tailRecords.map(serializeRecord),
139 mr: entry.malformedRecords,
140 o: entry.position.resumeOffset,
141 gl: entry.position.guardLength,
142 gh: entry.position.guardHash,
143 cs: entry.position.state,
144 };
145 }
146
147 /** Yields the document in pieces so large caches never become one string; growing intern tables preserve indexes, retaining unused strings until restart. */
148 export function makeScanCacheWriter(): (
149 cache: ScanCache,
150 extra: Readonly<Record<string, unknown>>,
151 ) => Iterable<string> {
152 const tables = makeInternTables();
153 function* encode(entries: readonly (readonly [string, CachedFile])[], extra: object) {
154 yield '{"files":{';
155 for (const [index, [path, entry]] of entries.entries()) {
156 yield `${index === 0 ? "" : ","}${JSON.stringify(path)}:${JSON.stringify(serializeFile(entry, tables))}`;
157 }
158 // Encoded after the files, which may have added to the intern tables.
159 const tail = JSON.stringify({
160 ...extra,
161 version: USAGE_SCAN_CACHE_VERSION,
162 models: tables.models,
163 sessions: tables.sessions,
164 });
165 yield `},${tail.slice(1)}`;
166 }
167 // Snapshot now: the encoding runs later, while the file is written.
168 return (cache, extra) => encode([...cache], extra);
169 }
170
171 function isRecordArray(value: unknown): value is readonly unknown[] {
172 return Array.isArray(value);
173 }
174
175 export function decodeScanCache(
176 document: unknown,
177 formats: ReadonlyMap<UsageProviderKind, TranscriptUsageFormat<unknown>>,
178 ): ScanCache {
179 const cache: ScanCache = new Map();
180 const isValidState = makeStateValidators(formats);
181 if (typeof document !== "object" || document === null) return cache;
182
183 const root = document as Partial<SerializedCache>;
184 const version = root.version;
185 if (
186 typeof version !== "number" ||
187 version < SPEED_COMPATIBLE_SINCE_VERSION ||
188 version > USAGE_SCAN_CACHE_VERSION
189 ) {
190 return cache;
191 }
192 if (!isRecordArray(root.models) || !isRecordArray(root.sessions)) return cache;
193 if (typeof root.files !== "object" || root.files === null) return cache;
194
195 if (!root.models.every((value) => typeof value === "string")) return cache;
196 if (!root.sessions.every((value) => typeof value === "string")) return cache;
197 const models = root.models as readonly string[];
198 const sessions = root.sessions as readonly string[];
199
200 // Reject entire corrupt entries; partial survivors would appear warm and hide usage until the file changes.
201 const decodeRecords = (
202 rows: readonly unknown[],
203 provider: UsageProviderKind,
204 ): UsageRecord[] | null => {
205 const records: UsageRecord[] = [];
206 for (const row of rows) {
207 if (!isRecordArray(row) || row.length < 11) return null;
208 const [
209 timestampMs,
210 modelIndex,
211 sessionIndex,
212 uncached,
213 cached,
214 cacheCreation,
215 output,
216 reasoning,
217 dedupeKey,
218 reportedCostUsd,
219 speedIndex,
220 rateModelIndex,
221 unresolvedServiceTierTurnId,
222 cacheCreation1h = 0,
223 ] = row as SerializedRecord;
224 const speed = typeof speedIndex === "number" ? SPEEDS[speedIndex] : undefined;
225
226 const model = typeof modelIndex === "number" ? models[modelIndex] : undefined;
227 const rateModel = typeof rateModelIndex === "number" ? models[rateModelIndex] : undefined;
228 if (
229 typeof timestampMs !== "number" ||
230 !Number.isFinite(timestampMs) ||
231 model === undefined ||
232 (unresolvedServiceTierTurnId != null && typeof unresolvedServiceTierTurnId !== "string") ||
233 !Number.isFinite(cacheCreation1h) ||
234 (rateModelIndex != null && rateModel === undefined) ||
235 !Number.isFinite(uncached) ||
236 !Number.isFinite(cached) ||
237 !Number.isFinite(cacheCreation) ||
238 !Number.isFinite(output) ||
239 !Number.isFinite(reasoning) ||
240 speed === undefined
241 ) {
242 return null;
243 }
244
245 // Unchanged and deleted transcripts may only exist in the cache, so the
246 // parser cannot remove their previously saved local placeholders.
247 if (provider === "claude" && model === CLAUDE_SYNTHETIC_MODEL) continue;
248
249 records.push({
250 provider,
251 timestampMs,
252 model,
253 ...(rateModel === undefined ? {} : { rateModel }),
254 sessionId: (typeof sessionIndex === "number" ? sessions[sessionIndex] : undefined) ?? "",
255 totals: {
256 uncachedInputTokens: uncached,
257 cachedInputTokens: cached,
258 cacheCreationTokens: cacheCreation,
259 outputTokens: output,
260 reasoningTokens: reasoning,
261 },
262 ...(cacheCreation1h > 0 ? { cacheCreation1hTokens: cacheCreation1h } : {}),
263 reportedCostUsd: typeof reportedCostUsd === "number" ? reportedCostUsd : null,
264 speed,
265 ...(version >= 7 && unresolvedServiceTierTurnId != null
266 ? { unresolvedServiceTierTurnId }
267 : {}),
268 dedupeKey:
269 typeof dedupeKey !== "string"
270 ? null
271 : // Saved copies of moved transcripts must still match the re-parsed v17 key.
272 provider === "grok" &&
273 version < 17 &&
274 dedupeKey.endsWith(`:${model}`) &&
275 !dedupeKey.endsWith(`:${timestampMs}:${model}`)
276 ? `${dedupeKey.slice(0, -model.length)}${timestampMs}:${model}`
277 : dedupeKey,
278 });
279 }
280 return records;
281 };
282
283 for (const [path, raw] of Object.entries(root.files)) {
284 if (typeof raw !== "object" || raw === null) continue;
285 const entry = raw as Partial<SerializedFile>;
286 if (typeof entry.s !== "number" || typeof entry.m !== "number") continue;
287 if (entry.p === undefined) continue;
288 const format = formats.get(entry.p);
289 if (format === undefined) continue;
290 if (!isRecordArray(entry.r) || !isRecordArray(entry.t)) continue;
291 const malformedRecords = entry.mr === undefined ? 0 : entry.mr;
292 if (!Number.isSafeInteger(malformedRecords) || malformedRecords < 0) continue;
293 // Position fields feed byte offsets and a Buffer allocation in the reader,
294 // so anything outside their real ranges must reject the entry: a bogus
295 // guard length would otherwise fail every parse of the file, silently
296 // dropping its usage instead of costing the documented cold re-parse.
297 if (
298 typeof entry.o !== "number" ||
299 !Number.isSafeInteger(entry.o) ||
300 entry.o < 0 ||
301 typeof entry.gl !== "number" ||
302 !Number.isSafeInteger(entry.gl) ||
303 entry.gl < 0 ||
304 entry.gl > GUARD_LENGTH ||
305 entry.gl > entry.o ||
306 typeof entry.gh !== "number" ||
307 !Number.isFinite(entry.gh)
308 ) {
309 continue;
310 }
311 // Keep history for deleted rollouts, but re-parse incompatible reducer state.
312 // v13 adds Claude 1-hour cache writes; v14 uses Codex request ledgers.
313 // v15 repairs skipped Codex requests whose counters rewound; clean v14 entries stay served.
314 // v17 keys Grok turns by time, restoring turns previously dropped as repeats.
315 const legacy =
316 (entry.p === "claude" && version < 13) ||
317 (entry.p === "grok" && version < 17) ||
318 (format.state !== undefined &&
319 (version < 6 ||
320 (entry.p === "codex" && (version < 14 || (version < 15 && malformedRecords > 0)))));
321 // A corrupt state disqualifies the entry: resuming with it would attach
322 // appended usage to the wrong model or replay fork-copied history.
323 if (!legacy && !isValidState.get(entry.p)?.(entry.cs)) continue;
324 // Before v16 a Codex baseline can lack the time of its latest move, or carry an older one,
325 // and that time keeps a re-emitted older snapshot from billing twice. A grown file re-parses
326 // whole instead of resuming.
327 const resumable = !legacy && !(entry.p === "codex" && version < 16);
328
329 const provider = entry.p;
330 const records = decodeRecords(entry.r, provider);
331 const tailRecords = decodeRecords(entry.t, provider);
332 if (records === null || tailRecords === null) continue;
333
334 cache.set(path, {
335 size: legacy ? -1 : entry.s,
336 mtimeMs: entry.m,
337 provider,
338 records,
339 tailRecords,
340 malformedRecords,
341 position: resumable
342 ? {
343 resumeOffset: entry.o,
344 guardLength: entry.gl,
345 guardHash: entry.gh,
346 state: entry.cs,
347 }
348 : { resumeOffset: 0, guardLength: 0, guardHash: 0, state: null },
349 });
350 }
351
352 return cache;
353 }
354
355 function makeStateValidators(
356 formats: ReadonlyMap<UsageProviderKind, TranscriptUsageFormat<unknown>>,
357 ): ReadonlyMap<UsageProviderKind, (value: unknown) => boolean> {
358 return new Map(
359 [...formats].map(([provider, format]) => {
360 const isState = format.state === undefined ? undefined : Schema.is(format.state.schema);
361 return [
362 provider,
363 (value: unknown) => value === null || (isState !== undefined && isState(value)),
364 ] as const;
365 }),
366 );
367 }
368
369 export function pruneScanCache(cache: ScanCache, retentionCutoffMs: number): number {
370 let removed = 0;
371 for (const [path, entry] of cache) {
372 if (entry.mtimeMs < retentionCutoffMs) {
373 cache.delete(path);
374 removed += 1;
375 }
376 }
377 return removed;
378 }
379
380 /** Pass only newline-terminated records: an unterminated tail can still change, so the aggregator merges it per scan. */
381 export function dedupeWithinFile(records: readonly UsageRecord[]): readonly UsageRecord[] {
382 const kept: UsageRecord[] = [];
383 const firstIndex = new Map<string, number>();
384 for (const record of records) {
385 if (record.dedupeKey !== null) {
386 const index = firstIndex.get(record.dedupeKey);
387 if (index !== undefined) {
388 kept[index] = mergeUsageCopies(kept[index]!, record);
389 continue;
390 }
391 firstIndex.set(record.dedupeKey, kept.length);
392 }
393 kept.push(record);
394 }
395 return kept;
396 }