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, 18:30 UTC
perf(usage): the Usage page shows cost and tokens at once instead of after a full scan (#33993)
Co-authored-by: Julius Marminge <julius0216@outlook.com>
Bilal Bakr committed
Nov 12, 2026 at 23:50 UTC
7fab4ef97838e3e0f1b7e0e2af58d778fda059d8
7 files changed
+450
-85
apps/server/src/usage/UsageService.test.ts
+138
-2
@@ -249,6 +249,7 @@ const layerService = (input: {
249
);
250
251
const BEFORE_NARROW_WINDOW = Date.parse("2026-08-01T10:00:00Z") / 1000;
252
+const NARROW_WINDOW_MTIME = Date.parse("2026-09-01T10:00:00Z") / 1000;
253
const NARROW_WINDOW: UsageSummaryInput = {
254
timeZone: "UTC",
255
sinceDay: UsageDay.make("2026-09-01"),
@@ -2449,6 +2450,75 @@ describe("UsageService", () => {
2450
}).pipe(Effect.scoped),
2451
);
2452
2453
+ it.live(
2454
+ "answers a provisional read from the last scan, then the exact read adds what changed",
2455
+ () =>
2456
+ Effect.gen(function* () {
2457
+ const { transcript, settings, home } = yield* setup;
2458
+ yield* Effect.promise(() => NodeFSP.writeFile(transcript, claudeLine(1, 5)));
2459
+ const provisional = { ...WINDOW, provisional: true };
2460
+ const claude = (summary: UsageSummary) =>
2461
+ summary.sources.find((source) => source.fingerprint.provider === "claude");
2462
+ yield* Effect.gen(function* () {
2463
+ // With nothing persisted, the first answer is a full scan.
2464
+ const service = yield* UsageService.make;
2465
+ const loop = NodePath.join(NodePath.dirname(transcript), "loop.jsonl");
2466
+ yield* Effect.promise(() => NodeFSP.symlink(loop, loop, "junction"));
2467
+ assert.strictEqual(claude(yield* service.readSummary(provisional))?.status, "partial");
2468
+ yield* Effect.promise(() => NodeFSP.rm(loop));
2469
+ // A scan that missed a path covers nothing, so this is a full scan too.
2470
+ assert.isUndefined(claude(yield* service.readSummary(provisional))?.refreshing);
2471
+ yield* service.awaitPersisted;
2472
+
2473
+ yield* Effect.promise(() => NodeFSP.appendFile(transcript, claudeLine(2, 7)));
2474
+ const restarted = yield* UsageService.make;
2475
+ const saved = yield* restarted.readSummary(provisional);
2476
+ assert.strictEqual(totalOutputTokens(saved), 5);
2477
+ assert.isTrue(claude(saved)?.refreshing);
2478
+ // A window that starts before the saved scan could only show part of its usage.
2479
+ const wider = yield* restarted.readSummary({
2480
+ ...provisional,
2481
+ sinceDay: UsageDay.make("2026-07-01"),
2482
+ });
2483
+ assert.strictEqual(totalOutputTokens(wider), 12);
2484
+ assert.isUndefined(claude(wider)?.refreshing);
2485
+ const refreshed = yield* restarted.readSummary({ ...WINDOW, awaitRefresh: true });
2486
+ assert.strictEqual(totalOutputTokens(refreshed), 12);
2487
+ assert.isUndefined(claude(refreshed)?.refreshing);
2488
+ // Saved usage with nothing to show marks nothing refreshing, so it must not be the answer.
2489
+ yield* Effect.promise(() =>
2490
+ NodeFSP.appendFile(transcript, claudeLine(3, 11, "claude-other")),
2491
+ );
2492
+ const unseen = yield* restarted.readSummary({
2493
+ ...provisional,
2494
+ modelFilter: { include: [{ model: "claude-other" }] },
2495
+ });
2496
+ assert.strictEqual(totalOutputTokens(unseen), 11);
2497
+ yield* restarted.awaitPersisted;
2498
+
2499
+ // A saved scan with an entry this server cannot read covers nothing.
2500
+ const { stateDir } = yield* ServerConfig.ServerConfig;
2501
+ const cachePath = NodePath.join(stateDir, SCAN_CACHE_FILE_NAME);
2502
+ yield* Effect.promise(async () => {
2503
+ const document = decodeUnknownJsonString(await NodeFSP.readFile(cachePath, "utf8")) as {
2504
+ files: Record<string, Record<string, unknown>>;
2505
+ };
2506
+ const [entry] = Object.values(document.files);
2507
+ document.files[NodePath.join(NodePath.dirname(transcript), "broken.jsonl")] = {
2508
+ ...entry,
2509
+ r: "broken",
2510
+ };
2511
+ await NodeFSP.writeFile(cachePath, JSON.stringify(document));
2512
+ });
2513
+ const reloaded = yield* UsageService.make;
2514
+ assert.isUndefined(claude(yield* reloaded.readSummary(provisional))?.refreshing);
2515
+ }).pipe(
2516
+ Effect.scoped,
2517
+ Effect.provide(layerService({ prefix: "usage-service-provisional", home, settings })),
2518
+ );
2519
+ }).pipe(Effect.scoped),
2520
+ );
2521
+
2522
it.live("filters original model IDs before aliases, pricing, buckets and session counts", () =>
2523
Effect.gen(function* () {
2524
const { transcript, settings, home } = yield* setup;
@@ -3204,6 +3274,64 @@ describe("UsageService", () => {
3274
}).pipe(Effect.scoped),
3275
);
3276
3277
+ it.live("credits the same copy of a duplicate from the last scan as an exact read does", () =>
3278
+ Effect.gen(function* () {
3279
+ yield* TestClock.setTime(Date.parse("2026-08-15T00:00:00Z"));
3280
+ const { transcript, settings, home } = yield* setup;
3281
+ const dir = NodePath.dirname(transcript);
3282
+ const [first = "", second = ""] = yield* Effect.promise(async () => {
3283
+ await NodeFSP.writeFile(NodePath.join(dir, "a.jsonl"), "");
3284
+ await NodeFSP.writeFile(NodePath.join(dir, "b.jsonl"), "");
3285
+ return (await NodeFSP.readdir(dir)).map((name) => NodePath.join(dir, name));
3286
+ });
3287
+ const forked = (line: string) => line.replace('"session-1"', '"session-2"');
3288
+ yield* Effect.promise(async () => {
3289
+ await NodeFSP.writeFile(first, claudeLine(1, 5));
3290
+ await NodeFSP.utimes(first, BEFORE_NARROW_WINDOW, BEFORE_NARROW_WINDOW);
3291
+ await NodeFSP.writeFile(second, forked(claudeLine(1, 5)) + forked(claudeLine(2, 7)));
3292
+ });
3293
+ yield* Effect.gen(function* () {
3294
+ const service = yield* UsageService.make;
3295
+ // The narrow window saves the second copy before the wide one reads the first.
3296
+ yield* service.readSummary(NARROW_WINDOW);
3297
+ const exact = yield* service.readSummary(WINDOW);
3298
+ yield* service.awaitPersisted;
3299
+ const restarted = yield* UsageService.make;
3300
+ const saved = yield* restarted.readSummary({ ...WINDOW, provisional: true });
3301
+ assert.isTrue(saved.sources.some((source) => source.refreshing === true));
3302
+ assert.deepStrictEqual(saved.buckets, exact.buckets);
3303
+ }).pipe(
3304
+ Effect.provide(layerService({ prefix: "usage-service-saved-order-test", home, settings })),
3305
+ );
3306
+
3307
+ // A narrow scan that first saves the earlier copy still puts it before a later file it skipped.
3308
+ yield* Effect.promise(async () => {
3309
+ await NodeFSP.writeFile(first, forked(claudeLine(1, 5)) + forked(claudeLine(2, 7)));
3310
+ await NodeFSP.utimes(
3311
+ first,
3312
+ Date.parse("2026-07-01T00:00:00Z") / 1000,
3313
+ Date.parse("2026-07-01T00:00:00Z") / 1000,
3314
+ );
3315
+ await NodeFSP.writeFile(second, claudeLine(1, 5));
3316
+ await NodeFSP.utimes(second, BEFORE_NARROW_WINDOW, BEFORE_NARROW_WINDOW);
3317
+ });
3318
+ yield* Effect.gen(function* () {
3319
+ const service = yield* UsageService.make;
3320
+ yield* service.readSummary(WINDOW);
3321
+ yield* Effect.promise(() =>
3322
+ NodeFSP.utimes(first, NARROW_WINDOW_MTIME, NARROW_WINDOW_MTIME),
3323
+ );
3324
+ yield* service.readSummary(NARROW_WINDOW);
3325
+ const saved = yield* service.readSummary({ ...WINDOW, provisional: true });
3326
+ assert.isTrue(saved.sources.some((source) => source.refreshing === true));
3327
+ const exact = yield* service.readSummary(WINDOW);
3328
+ assert.deepStrictEqual(saved.buckets, exact.buckets);
3329
+ }).pipe(
3330
+ Effect.provide(layerService({ prefix: "usage-service-narrow-order-test", home, settings })),
3331
+ );
3332
+ }).pipe(Effect.scoped, Effect.provide(TestClock.layer())),
3333
+ );
3334
+
3335
it.live.skipIf(HostProcess.Platform.defaultValue() === "win32")(
3336
"keeps a newer cached read when a slower scan of another window finishes later",
3337
() =>
@@ -3345,7 +3473,14 @@ describe("UsageService", () => {
3473
HttpClient.HttpClient,
3474
HttpClient.make((request) =>
3475
Deferred.await(releaseRates).pipe(
3348
- Effect.as(HttpClientResponse.fromWeb(request, Response.json({}))),
3476
+ Effect.as(
3477
+ HttpClientResponse.fromWeb(
3478
+ request,
3479
+ Response.json({
3480
+ "example-model": { input_cost_per_token: 1e-6, output_cost_per_token: 1e-5 },
3481
+ }),
3482
+ ),
3483
+ ),
3484
),
3485
),
3486
),
@@ -3364,7 +3499,8 @@ describe("UsageService", () => {
3499
3500
const original = yield* Fiber.join(first);
3501
const updated = yield* Fiber.join(second);
3367
- assert.strictEqual(original.buckets[0]?.costUsd, 0);
3502
+ // Fetched rates price the first read, so scans must start while the fetch is pending.
3503
+ assert.isAbove(original.buckets[0]?.costUsd ?? 0, 0);
3504
assert.closeTo(updated.buckets[0]?.costUsd ?? -1, 0.00006, 1e-12);
3505
}).pipe(
3506
Effect.provide(layerService({ prefix: "usage-service-price-race-test", home, settings })),
apps/server/src/usage/UsageService.ts
+175
-47
@@ -137,7 +137,10 @@ function sharedSessions(
137
return shared;
138
}
139
const decodeCachedSources = Schema.decodeUnknownOption(
140
- Schema.Struct({ sources: Schema.Record(Schema.String, CachedSource) }),
140
+ Schema.Struct({
141
+ sources: Schema.Record(Schema.String, CachedSource),
142
+ coveredSince: Schema.optional(Schema.Record(Schema.String, Schema.Number)),
143
+ }),
144
);
145
146
export class UsageService extends Context.Service<
@@ -165,7 +168,15 @@ export const make = Effect.gen(function* () {
168
const correctedBatch = (records: readonly UsageRecord[]) =>
169
records.some((record) => resolvedRecords.has(record)) ? records.map(correctedRecord) : records;
170
const sourceCache = new Map<string, typeof CachedSource.Type>();
171
+ // Earliest window start a complete scan read each transcript directory from.
172
+ const coveredSince = new Map<string, number>();
173
+ const coverageKey = (source: TranscriptSource) => `${source.provider}\0${source.dir}`;
174
let cacheDirty = false;
175
+ const cover = (source: TranscriptSource, windowStartMs: number) => {
176
+ if ((coveredSince.get(coverageKey(source)) ?? Infinity) <= windowStartMs) return;
177
+ coveredSince.set(coverageKey(source), windowStartMs);
178
+ cacheDirty = true;
179
+ };
180
const isWithinDirectory = (filePath: string, dir: string) => {
181
const relative = path.relative(dir, filePath);
182
return relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
@@ -235,27 +246,26 @@ export const make = Effect.gen(function* () {
246
Effect.catchCause(() => Effect.succeed(null)),
247
);
248
249
+ // Outside ratesLock, which a slow fetch holds: a provisional answer prices with these.
250
+ const loadSavedRates = yield* Effect.cached(
251
+ fileSystem.readFileString(ratesCachePath).pipe(
252
+ Effect.flatMap((raw) => decodeRatesCache(raw)),
253
+ Effect.map((saved) => {
254
+ const parsed = parseRateTable(saved.document);
255
+ if (parsed.size === 0) return;
256
+ rates = parsed;
257
+ ratesFetchedAtMs = saved.fetchedAtMs;
258
+ ratesStatus = "cached";
259
+ }),
260
+ Effect.ignoreCause,
261
+ ),
262
+ );
263
+
264
const loadRates = Effect.fn("UsageService.loadRates")(function* (force: boolean) {
265
const now = yield* Clock.currentTimeMillis;
266
const maxAgeMs = force ? RATES_REFRESH_FLOOR_MS : RATES_TTL_MS;
267
+ yield* loadSavedRates;
268
if (ratesFetchedAtMs !== null && now - ratesFetchedAtMs < maxAgeMs) return;
242
-
243
- if (ratesFetchedAtMs === null) {
244
- const fromDisk = yield* fileSystem.readFileString(ratesCachePath).pipe(
245
- Effect.flatMap((raw) => decodeRatesCache(raw)),
246
- Effect.catchCause(() => Effect.succeed(null)),
247
- );
248
- if (fromDisk !== null) {
249
- const parsed = parseRateTable(fromDisk.document);
250
- if (parsed.size > 0) {
251
- rates = parsed;
252
- ratesFetchedAtMs = fromDisk.fetchedAtMs;
253
- ratesStatus = "cached";
254
- if (now - fromDisk.fetchedAtMs < maxAgeMs) return;
255
- }
256
- }
257
- }
258
-
269
if (ratesLastFailedAtMs !== null && now - ratesLastFailedAtMs < RATES_REFRESH_FLOOR_MS) return;
270
271
let fetched = yield* fetchRates(LITELLM_RATES_URL);
@@ -396,19 +406,27 @@ export const make = Effect.gen(function* () {
406
Effect.catchCause(() => Effect.succeed(null)),
407
);
408
let document = yield* readDocument(scanCachePath);
409
+ const current = document !== null;
410
for (const fileName of LEGACY_SCAN_CACHE_FILE_NAMES) {
411
if (document !== null) break;
412
document = yield* readDocument(path.join(config.stateDir, fileName));
413
cacheDirty = document !== null;
414
}
415
if (document === null) return;
405
- for (const [path, entry] of decodeScanCache(document, transcriptFormats)) {
406
- fileCache.set(path, entry);
407
- }
416
+ const decoded = decodeScanCache(document, transcriptFormats);
417
+ for (const [path, entry] of decoded) fileCache.set(path, entry);
418
+ const saved = (document as { readonly files?: unknown }).files;
419
+ const complete =
420
+ typeof saved === "object" && saved !== null && Object.keys(saved).length === decoded.size;
421
const sources = decodeCachedSources(document);
422
if (Option.isSome(sources)) {
423
for (const [key, source] of Object.entries(sources.value.sources))
424
sourceCache.set(key, source);
425
+ // Coverage describes the saved files, so it needs every one, in this version's format.
426
+ if (current && complete && fileCache.size > 0) {
427
+ for (const [key, since] of Object.entries(sources.value.coveredSince ?? {}))
428
+ coveredSince.set(key, since);
429
+ }
430
}
431
}),
432
);
@@ -448,7 +466,10 @@ export const make = Effect.gen(function* () {
466
if (cacheDirty) {
467
cacheDirty = false;
468
yield* Effect.sync(() =>
451
- writeScanCache(fileCache, { sources: Object.fromEntries(sourceCache) }),
469
+ writeScanCache(fileCache, {
470
+ sources: Object.fromEntries(sourceCache),
471
+ coveredSince: Object.fromEntries(coveredSince),
472
+ }),
473
).pipe(
474
Effect.flatMap((contents) => writeCacheFile(scanCachePath, contents)),
475
Effect.andThen(
@@ -595,19 +616,27 @@ export const make = Effect.gen(function* () {
616
readonly malformedRecords: number;
617
}[]
618
| null;
619
+ /** Every transcript path the walk listed, in walk order, whatever its mtime. */
620
+ readonly walked?: readonly string[];
621
readonly refreshing?: true;
622
}
623
624
const scanTranscriptDir = Effect.fn("UsageService.scanTranscriptDir")(function* (
625
source: TranscriptSource,
626
windowStartMs: number,
627
+ fromMemory: boolean,
628
) {
629
const { provider, format, dir, volumeId, fileName } = source;
630
const exists = yield* fileSystem
631
.exists(dir)
632
.pipe(Effect.catchCause(() => Effect.succeed(false)));
609
- if (!exists) return { provider, dir, volumeId, files: null } satisfies ScannedDir;
610
- const { files, failedPaths } = yield* Effect.promise(() =>
633
+ if (!exists) {
634
+ cover(source, windowStartMs);
635
+ return { provider, dir, volumeId, files: null } satisfies ScannedDir;
636
+ }
637
+ // scanSummary aggregates the saved files, as it does for a deleted directory.
638
+ if (fromMemory) return { provider, dir, volumeId, files: [] } satisfies ScannedDir;
639
+ const { files, walked, failedPaths } = yield* Effect.promise(() =>
640
listTranscriptFiles(dir, windowStartMs, fileName === undefined ? undefined : { fileName }),
641
);
642
const read = yield* Effect.forEach(
@@ -646,6 +675,7 @@ export const make = Effect.gen(function* () {
675
if (!livePaths.has(originalPath) && fileCache.delete(originalPath)) cacheDirty = true;
676
}
677
const unread = failedPaths + read.filter((file) => file.failed).length;
678
+ if (unread === 0) cover(source, windowStartMs);
679
yield* Effect.annotateCurrentSpan({
680
"usage.files": files.length,
681
"usage.files_parsed": read.filter((file) => file.update !== undefined).length,
@@ -655,6 +685,7 @@ export const make = Effect.gen(function* () {
685
dir,
686
volumeId,
687
files: parsedFiles,
688
+ walked,
689
...(unread > 0
690
? {
691
status: "partial",
@@ -665,17 +696,13 @@ export const make = Effect.gen(function* () {
696
});
697
698
const collectDirs = Effect.fn("UsageService.collectDirs")(function* (
699
+ { dirs, pending }: Effect.Success<ReturnType<typeof resolveTranscriptDirs>>,
700
windowStartMs: number,
701
settings: ServerSettingsValue,
702
retentionCutoffMs: number,
703
awaitRefresh: boolean,
704
+ fromMemory: boolean,
705
) {
673
- const { dirs, pending } = yield* resolveTranscriptDirs(
674
- settings,
675
- retentionCutoffMs,
676
- awaitRefresh,
677
- ).pipe(Effect.provideContext(readerContext));
678
-
706
const scans = Effect.forEach(
707
scanReaders,
708
({ driver, reader }) =>
@@ -705,7 +732,7 @@ export const make = Effect.gen(function* () {
732
733
// Scan independent sources together, directories sequentially to bound open files; keep order, since the first copy decides a duplicate's bucket.
734
const [transcripts, scanDirs] = yield* Effect.all(
708
- [Effect.forEach(dirs, (dir) => scanTranscriptDir(dir, windowStartMs)), scans],
735
+ [Effect.forEach(dirs, (dir) => scanTranscriptDir(dir, windowStartMs, fromMemory)), scans],
736
{ concurrency: "unbounded" },
737
);
738
const scanned: readonly ScannedDir[] = [...transcripts, ...pending, ...scanDirs.flat()];
@@ -715,6 +742,7 @@ export const make = Effect.gen(function* () {
742
const scanSummary = Effect.fn("UsageService.scanSummary")(function* (
743
input: UsageSummaryInput,
744
settings: ServerSettingsValue,
745
+ provisional: boolean,
746
) {
747
if (input.sinceDay > input.untilDay) {
748
return yield* new UsageReadError({
@@ -762,11 +790,38 @@ export const make = Effect.gen(function* () {
790
791
const retentionCutoffMs = startedAtMs - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000;
792
765
- const [, scannedDirs] = yield* Effect.all(
766
- [
767
- ensureRates(false),
768
- collectDirs(windowStartMs, settings, retentionCutoffMs, input.awaitRefresh === true),
769
- ],
793
+ const awaitRefresh = input.awaitRefresh === true;
794
+ const collect = Effect.gen(function* () {
795
+ const resolved = yield* resolveTranscriptDirs(settings, retentionCutoffMs, awaitRefresh).pipe(
796
+ Effect.provideContext(readerContext),
797
+ );
798
+ // A window no complete scan has read would show partial totals, so every directory must cover it.
799
+ // Saved files are keyed by path, so two providers reading one directory keep only one parse.
800
+ const fromMemory =
801
+ provisional &&
802
+ resolved.dirs.length > 0 &&
803
+ new Set(resolved.dirs.map((source) => source.dir)).size === resolved.dirs.length &&
804
+ resolved.dirs.every(
805
+ (source) => (coveredSince.get(coverageKey(source)) ?? Infinity) <= windowStartMs,
806
+ );
807
+ const [, scanned] = yield* Effect.all(
808
+ [
809
+ fromMemory ? loadSavedRates : provisional ? ensureRates(false) : Effect.void,
810
+ collectDirs(
811
+ resolved,
812
+ windowStartMs,
813
+ settings,
814
+ retentionCutoffMs,
815
+ awaitRefresh,
816
+ fromMemory,
817
+ ),
818
+ ],
819
+ { concurrency: 2 },
820
+ );
821
+ return { scannedDirs: scanned, fromMemory };
822
+ });
823
+ const [{ scannedDirs, fromMemory }] = yield* Effect.all(
824
+ [collect, provisional ? Effect.void : ensureRates(false)],
825
{ concurrency: 2 },
826
);
827
@@ -786,31 +841,73 @@ export const make = Effect.gen(function* () {
841
842
// Deleted transcripts' saved usage still aggregates and deduplicates normally.
843
const retainedSinceMs = Math.max(windowStartMs, retentionCutoffMs);
844
+ // Saved paths are files below a scanned root, so their folder decides; folders repeat thousands of times.
845
+ const withinDir = (dir: string) => {
846
+ const foldersWithin = new Map<string, boolean>();
847
+ return (filePath: string) => {
848
+ const folder = path.dirname(filePath);
849
+ let within = foldersWithin.get(folder);
850
+ if (within === undefined) {
851
+ within = isWithinDirectory(folder, dir);
852
+ foldersWithin.set(folder, within);
853
+ }
854
+ return within;
855
+ };
856
+ };
857
const filesByDir = scannedDirs.map(({ provider, dir, files }) => {
858
const retainedFiles = [...(files ?? [])];
859
const livePaths = new Set(retainedFiles.map((file) => file.path));
860
+ const isRetained = withinDir(dir);
861
for (const [filePath, entry] of fileCache) {
862
if (
863
entry.provider !== provider ||
864
entry.mtimeMs < retainedSinceMs ||
865
livePaths.has(filePath) ||
797
- !isWithinDirectory(filePath, dir)
866
+ !isRetained(filePath)
867
)
868
continue;
869
retainedFiles.push({
870
path: filePath,
802
- records: [...entry.records, ...entry.tailRecords],
871
+ records:
872
+ entry.tailRecords.length === 0
873
+ ? entry.records
874
+ : [...entry.records, ...entry.tailRecords],
875
malformedRecords: entry.malformedRecords,
876
});
877
}
878
return retainedFiles;
879
});
880
+ // Usage two transcripts share counts in the first one, so saved files take the order an exact
881
+ // scan reads them in: walked files in walk order, then the directory's deleted files.
882
+ for (const { provider, dir, walked } of fromMemory ? [] : scannedDirs) {
883
+ if (walked === undefined) continue;
884
+ const within = withinDir(dir);
885
+ const saved = [...fileCache.keys()];
886
+ const members = new Set(
887
+ saved.filter(
888
+ (filePath) => fileCache.get(filePath)!.provider === provider && within(filePath),
889
+ ),
890
+ );
891
+ if (members.size < 2) continue;
892
+ const listed = new Set(walked);
893
+ const target = [
894
+ ...walked.filter((filePath) => members.has(filePath)),
895
+ ...saved.filter((filePath) => members.has(filePath) && !listed.has(filePath)),
896
+ ];
897
+ let next = 0;
898
+ const ordered = saved.map((filePath) => (members.has(filePath) ? target[next++]! : filePath));
899
+ if (ordered.every((filePath, index) => filePath === saved[index])) continue;
900
+ const entries = new Map(fileCache);
901
+ fileCache.clear();
902
+ for (const filePath of ordered) fileCache.set(filePath, entries.get(filePath)!);
903
+ cacheDirty = true;
904
+ }
905
const windowEndMs =
906
hourlyWindow?.untilTimeMs ??
907
Date.parse(`${input.untilDay}T00:00:00Z`) + 86400000 + MTIME_SLACK_MS;
908
let resolvedAny = false;
909
for (const { reader } of transcriptReaders) {
813
- if (reader.resolveServiceTiers === undefined) continue;
910
+ if (reader.resolveServiceTiers === undefined || fromMemory) continue;
911
const pending = new Set<UsageRecord>();
912
for (const [index, files] of filesByDir.entries()) {
913
if (scannedDirs[index]?.provider !== reader.provider) continue;
@@ -860,6 +957,7 @@ export const make = Effect.gen(function* () {
957
// Distinct per directory. Buckets carry per-cell session counts, but a
958
// session spans days and models, so clients total this figure instead.
959
const sessionIds = new Set<string>();
960
+ let counted = false;
961
962
for (const file of filesByDir[index] ?? []) {
963
malformedRecords += file.malformedRecords;
@@ -888,8 +986,9 @@ export const make = Effect.gen(function* () {
986
eventOccurrences.set(key, occurrence);
987
usageRecord = { ...record, dedupeKey: key + ":" + occurrence };
988
}
891
- if (aggregator.add(usageRecord, dir) && record.sessionId.length > 0) {
892
- sessionIds.add(record.sessionId);
989
+ if (aggregator.add(usageRecord, dir)) {
990
+ counted = true;
991
+ if (record.sessionId.length > 0) sessionIds.add(record.sessionId);
992
}
993
}
994
}
@@ -916,18 +1015,28 @@ export const make = Effect.gen(function* () {
1015
.filter(Boolean)
1016
.join(" ")
1017
: sourceMessage,
919
- ...(refreshing ? { refreshing } : {}),
1018
+ // A saved answer misses what changed since its scan, so the client must ask again. An
1019
+ // empty source stays unmarked: it would only flash a loading row.
1020
+ ...(refreshing || (fromMemory && counted && transcriptFormats.has(provider))
1021
+ ? { refreshing: true }
1022
+ : {}),
1023
});
1024
}
1025
1026
const pruned = pruneScanCache(fileCache, retentionCutoffMs);
924
- if (pruned > 0) cacheDirty = true;
1027
+ if (pruned > 0) {
1028
+ cacheDirty = true;
1029
+ // Pruned files are no longer saved, so nothing before the cutoff stays covered.
1030
+ for (const [key, since] of coveredSince) {
1031
+ if (since < retentionCutoffMs) coveredSince.set(key, retentionCutoffMs);
1032
+ }
1033
+ }
1034
1035
const aggregated = aggregator.finish();
1036
const readAt = yield* DateTime.now;
1037
const finishedAtMs = yield* Clock.currentTimeMillis;
1038
930
- return {
1039
+ const summary = {
1040
contractVersion: USAGE_CONTRACT_VERSION,
1041
readAt: DateTime.formatIso(readAt),
1042
timeZone: input.timeZone,
@@ -939,11 +1048,28 @@ export const make = Effect.gen(function* () {
1048
scanDurationMs: Math.max(0, finishedAtMs - startedAtMs),
1049
...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
1050
} satisfies UsageSummary;
1051
+ return { summary, fromMemory };
1052
+ });
1053
+
1054
+ const readWindow = Effect.fn("UsageService.readWindow")(function* (
1055
+ input: UsageSummaryInput,
1056
+ settings: ServerSettingsValue,
1057
+ provisional: boolean,
1058
+ ) {
1059
+ const { summary, fromMemory } = yield* scanSummary(input, settings, provisional);
1060
+ // With nothing marked refreshing the client would keep a saved answer as final.
1061
+ return fromMemory && !summary.sources.some((source) => source.refreshing === true)
1062
+ ? (yield* scanSummary(input, settings, false)).summary
1063
+ : summary;
1064
});
1065
1066
const inflightScans = new Map<string, Deferred.Deferred<UsageSummary, UsageReadError>>();
1067
946
- const scanKey = (input: UsageSummaryInput, settings: ServerSettingsValue): string =>
1068
+ const scanKey = (
1069
+ input: UsageSummaryInput,
1070
+ settings: ServerSettingsValue,
1071
+ provisional: boolean,
1072
+ ): string =>
1073
JSON.stringify([
1074
input.timeZone,
1075
input.sinceDay,
@@ -953,6 +1079,7 @@ export const make = Effect.gen(function* () {
1079
input.untilTime ?? null,
1080
settings,
1081
input.awaitRefresh === true,
1082
+ provisional,
1083
input.modelFilter ?? null,
1084
]);
1085
@@ -963,7 +1090,8 @@ export const make = Effect.gen(function* () {
1090
const modelFilter = canonicalModelFilter(requestedFilter);
1091
const input = modelFilter === undefined ? unfiltered : { ...unfiltered, modelFilter };
1092
const settings = yield* readSettings;
966
- const key = scanKey(input, settings);
1093
+ const provisional = input.provisional === true && input.awaitRefresh !== true;
1094
+ const key = scanKey(input, settings, provisional);
1095
const deferred = yield* Effect.uninterruptible(
1096
Effect.gen(function* () {
1097
const existing = inflightScans.get(key);
@@ -974,7 +1102,7 @@ export const make = Effect.gen(function* () {
1102
inflightScans.set(key, created);
1103
// Detach so caller departure cannot cancel shared scans; finished scans warm the cache.
1104
// Register writes before releasing waiters, but start writing after delivering their summary.
977
- yield* scanSummary(input, settings).pipe(
1105
+ yield* readWindow(input, settings, provisional).pipe(
1106
Effect.onExit((exit) =>
1107
Effect.sync(() => inflightScans.delete(key)).pipe(
1108
Effect.andThen(Exit.isSuccess(exit) ? schedulePersist : Effect.void),
apps/server/src/usage/usageTranscriptReader.test.ts
+24
@@ -99,6 +99,30 @@ describe("compressed transcripts", () => {
99
assert.isAbove(listed.files.find((file) => file.path === compressed)?.size ?? 0, 0);
100
});
101
102
+ it("lists files in directory order when more directories wait than it reads at once", async () => {
103
+ for (let index = 0; index < 40; index += 1) {
104
+ const nested = NodePath.join(dir, `project-${index}`, "sessions");
105
+ await NodeFSP.mkdir(nested, { recursive: true });
106
+ await NodeFSP.writeFile(NodePath.join(nested, "a.jsonl"), "");
107
+ await NodeFSP.writeFile(NodePath.join(nested, "..", "b.jsonl"), "");
108
+ }
109
+ // Usage that two transcripts share counts in the first one listed, so the order is part of the result.
110
+ const inOrder = async (folder: string): Promise<string[]> => {
111
+ const paths: string[] = [];
112
+ for (const entry of await NodeFSP.readdir(folder, { withFileTypes: true })) {
113
+ const child = NodePath.join(folder, entry.name);
114
+ if (entry.isDirectory()) paths.push(...(await inOrder(child)));
115
+ else paths.push(child);
116
+ }
117
+ return paths;
118
+ };
119
+ const listed = await listTranscriptFiles(dir, 0);
120
+ assert.deepStrictEqual(
121
+ listed.files.map((file) => file.path),
122
+ await inOrder(dir),
123
+ );
124
+ });
125
+
126
it.each([
127
{ parser: "native", streamingThresholdBytes: undefined },
128
{ parser: "projected", streamingThresholdBytes: 1024 },
apps/server/src/usage/usageTranscriptReader.ts
+39
-18
@@ -1,8 +1,10 @@
1
// @effect-diagnostics nodeBuiltinImport:off
2
// Cold windows span ~1.4 GB/1,500 files; node:fs buffer streaming is ~10x cheaper than materializing files.
3
+import * as NodeFS from "node:fs";
4
import * as NodeFSP from "node:fs/promises";
5
import * as NodePath from "node:path";
6
import * as NodeStringDecoder from "node:string_decoder";
7
+import * as NodeUtil from "node:util";
8
import * as NodeZlib from "node:zlib";
9
10
import type {
@@ -43,6 +45,9 @@ export const GUARD_LENGTH = 64;
45
const STREAMING_THRESHOLD_BYTES = 8 * 1024 * 1024;
46
const NEWLINE = 0x0a;
47
const STAT_CONCURRENCY = 32;
48
+const WALK_CONCURRENCY = 16;
49
+// Measured about 3x faster than the promise API's stat across 20,000 transcripts.
50
+const statFile = NodeUtil.promisify(NodeFS.stat);
51
const CARRIAGE_RETURN = 0x0d;
52
53
function selectUsageFields(fields: SelectedFields) {
@@ -71,38 +76,54 @@ export async function listTranscriptFiles(
76
root: string,
77
sinceMs: number,
78
options?: { readonly fileName?: string },
74
-): Promise<{ readonly files: readonly TranscriptFile[]; readonly failedPaths: number }> {
79
+): Promise<{
80
+ readonly files: readonly TranscriptFile[];
81
+ readonly walked: readonly string[];
82
+ readonly failedPaths: number;
83
+}> {
84
const fileName = options?.fileName;
76
- const candidates: string[] = [];
85
let failedPaths = 0;
78
- const walk = async (dir: string): Promise<void> => {
86
+ let reading = 0;
87
+ const waiting: Array<() => void> = [];
88
+ // Sibling directories read together; each returns its own list so the result keeps readdir order.
89
+ const walk = async (dir: string): Promise<readonly string[]> => {
90
+ if (reading < WALK_CONCURRENCY) reading += 1;
91
+ else await new Promise<void>((resume) => waiting.push(resume));
92
let entries;
93
try {
94
entries = await NodeFSP.readdir(dir, { withFileTypes: true });
95
} catch {
96
failedPaths += 1;
84
- return;
85
- }
86
- for (const entry of entries) {
87
- const child = NodePath.join(dir, entry.name);
88
- if (entry.isDirectory()) await walk(child);
89
- else if (
90
- fileName !== undefined
91
- ? entry.name === fileName
92
- : entry.name.endsWith(".jsonl") || entry.name.endsWith(".jsonl.zst")
93
- ) {
94
- candidates.push(child);
95
- }
97
+ return [];
98
+ } finally {
99
+ // A waiting directory takes over this slot, so the count only drops when none waits.
100
+ const next = waiting.shift();
101
+ if (next === undefined) reading -= 1;
102
+ else next();
103
}
104
+ const found = await Promise.all(
105
+ entries.map((entry) => {
106
+ const child = NodePath.join(dir, entry.name);
107
+ if (entry.isDirectory()) return walk(child);
108
+ return (
109
+ fileName !== undefined
110
+ ? entry.name === fileName
111
+ : entry.name.endsWith(".jsonl") || entry.name.endsWith(".jsonl.zst")
112
+ )
113
+ ? [child]
114
+ : [];
115
+ }),
116
+ );
117
+ return found.flat();
118
};
98
- await walk(root);
119
+ const candidates = await walk(root);
120
121
const found: Array<TranscriptFile | undefined> = Array.from({ length: candidates.length });
122
const queue = candidates.entries();
123
const statQueued = async (): Promise<void> => {
124
for (const [index, path] of queue) {
125
try {
105
- const stats = await NodeFSP.stat(path);
126
+ const stats = await statFile(path);
127
if (stats.mtimeMs >= sinceMs) {
128
found[index] = { path, size: stats.size, mtimeMs: stats.mtimeMs };
129
}
@@ -116,7 +137,7 @@ export async function listTranscriptFiles(
137
await Promise.all(
138
Array.from({ length: Math.min(STAT_CONCURRENCY, candidates.length) }, statQueued),
139
);
119
- return { files: found.filter((file) => file !== undefined), failedPaths };
140
+ return { files: found.filter((file) => file !== undefined), walked: candidates, failedPaths };
141
}
142
143
export async function readDirectoryVolumeId(path: string): Promise<string> {
packages/client-runtime/src/state/server.ts
+29
-16
@@ -9,6 +9,7 @@ import {
9
type ServerSelfUpdateProgressEvent,
10
type ServerSelfUpdateResult,
11
shouldRecommendDatabaseCompaction,
12
+ type UsageSummary,
13
WS_METHODS,
14
} from "@t3tools/contracts";
15
import * as Cause from "effect/Cause";
@@ -1497,30 +1498,42 @@ export function createServerEnvironmentAtoms<R, E>(
1498
tag: WS_METHODS.scheduledTasksSubscribe,
1499
}),
1500
// A cold transcript scan is measured in seconds, so keep the result around
1500
- // long enough that switching windows or re-rendering does not rescan.
1501
+ // long enough that switching windows or re-rendering does not rescan. With
1502
+ // nothing to show yet, the server's last scan answers first, then a plain
1503
+ // read, then a read that waits for slow sources.
1504
usageSummary: createEnvironmentRpcQueryAtomFamily(runtime, {
1505
label: "environment-data:server:usage-summary",
1506
tag: WS_METHODS.serverGetUsageSummary,
1507
staleTimeMs: 60_000,
1508
refreshTrigger: ({ environmentId }) => usageScanSettingsAtom(environmentId),
1506
- execute: (input, emit) =>
1507
- request(WS_METHODS.serverGetUsageSummary, input).pipe(
1508
- Effect.filterOrElse(
1509
- (summary) => !summary.sources.some((source) => source.refreshing === true),
1510
- (summary) =>
1511
- emit(summary).pipe(
1512
- Effect.andThen(
1513
- request(WS_METHODS.serverGetUsageSummary, { ...input, awaitRefresh: true }),
1514
- ),
1515
- Effect.catch((error) =>
1516
- Effect.logWarning("Could not refresh slow usage sources.").pipe(
1517
- Effect.annotateLogs({ ...safeErrorLogAttributes(error) }),
1518
- Effect.as(summary),
1519
- ),
1509
+ execute: (input, emit, previous) => {
1510
+ const settled = (summary: UsageSummary) =>
1511
+ !summary.sources.some((source) => source.refreshing === true);
1512
+ const read = request(WS_METHODS.serverGetUsageSummary, input).pipe(
1513
+ Effect.filterOrElse(settled, (summary) =>
1514
+ emit(summary).pipe(
1515
+ Effect.andThen(
1516
+ request(WS_METHODS.serverGetUsageSummary, { ...input, awaitRefresh: true }),
1517
+ ),
1518
+ Effect.catch((error) =>
1519
+ Effect.logWarning("Could not refresh slow usage sources.").pipe(
1520
+ Effect.annotateLogs({ ...safeErrorLogAttributes(error) }),
1521
+ Effect.as(summary),
1522
),
1523
),
1524
+ ),
1525
),
1523
- ),
1526
+ );
1527
+ if (Option.isSome(previous)) return read;
1528
+ return request(WS_METHODS.serverGetUsageSummary, { ...input, provisional: true }).pipe(
1529
+ Effect.matchEffect({
1530
+ // The saved answer only speeds things up; without it the plain read still answers.
1531
+ onFailure: () => read,
1532
+ onSuccess: (saved) =>
1533
+ settled(saved) ? Effect.succeed(saved) : emit(saved).pipe(Effect.andThen(read)),
1534
+ }),
1535
+ );
1536
+ },
1537
}),
1538
resourceTelemetry: createEnvironmentRpcSubscriptionAtomFamily(runtime, {
1539
label: "environment-data:server:resource-telemetry",
packages/client-runtime/src/state/serverUsage.test.ts
+43
-2
@@ -232,7 +232,13 @@ const makeRefreshingHarness = Effect.fn("ServerUsageTest.makeRefreshingHarness")
232
input.awaitRefresh === true
233
? Deferred.succeed(followUpStarted, undefined).pipe(Effect.andThen(followUp))
234
: Effect.void,
235
- (input) => [cursorSource(input.awaitRefresh !== true)],
235
+ // The saved answer differs from the plain one, so a test can tell which was kept.
236
+ (input) => [
237
+ {
238
+ ...cursorSource(input.awaitRefresh !== true),
239
+ ...(input.provisional === true ? { scannedFiles: 0 } : {}),
240
+ },
241
+ ],
242
);
243
return { ...harness, followUpStarted };
244
});
@@ -295,7 +301,42 @@ it.effect("keeps the cached usage summary when the awaited refresh fails", () =>
301
cursorSource(true),
302
]);
303
expect(AsyncResult.isSuccess(harness.registry.get(summary))).toBe(true);
298
- expect(harness.requests()).toBe(2);
304
+ // The saved answer is followed by a plain read before the one that waits for Cursor.
305
+ expect(
306
+ harness.inputs().map(({ provisional, awaitRefresh }) => ({ provisional, awaitRefresh })),
307
+ ).toEqual([
308
+ { provisional: true, awaitRefresh: undefined },
309
+ { provisional: undefined, awaitRefresh: undefined },
310
+ { provisional: undefined, awaitRefresh: true },
311
+ ]);
312
+ // With figures on screen, a refresh reads them exactly instead of asking for saved ones.
313
+ yield* harness.updateSettings({
314
+ ...DEFAULT_SERVER_SETTINGS,
315
+ usagePriceOverrides: {
316
+ "custom-model": { inputCostPerMillionTokens: 5, outputCostPerMillionTokens: 10 },
317
+ },
318
+ });
319
+ yield* waitForCost(harness.registry, summary, 5);
320
+ expect(harness.inputs()[3]?.provisional).toBeUndefined();
321
+ unmount();
322
+ }),
323
+ ),
324
+);
325
+
326
+it.effect("reads usage in full when the saved answer cannot be read", () =>
327
+ Effect.scoped(
328
+ Effect.gen(function* () {
329
+ const harness = yield* makeHarness((_request, input) =>
330
+ input.provisional === true
331
+ ? Effect.fail(
332
+ new UsageReadError({ reason: "scanFailed", detail: "saved scan unreadable" }),
333
+ )
334
+ : Effect.void,
335
+ );
336
+ const summary = harness.summary();
337
+ const unmount = harness.registry.mount(summary);
338
+ yield* settledSummary(harness.registry, summary);
339
+ expect(harness.inputs().map(({ provisional }) => provisional)).toEqual([true, undefined]);
340
unmount();
341
}),
342
),
packages/contracts/src/usage.ts
+2
@@ -135,6 +135,8 @@ export const UsageSummaryInput = Schema.Struct({
135
sinceTime: Schema.optional(TrimmedNonEmptyString),
136
untilTime: Schema.optional(TrimmedNonEmptyString),
137
awaitRefresh: Schema.optional(Schema.Boolean),
138
+ /** Accept an immediate answer from the last scan; its sources are marked refreshing. */
139
+ provisional: Schema.optional(Schema.Boolean),
140
modelFilter: Schema.optional(UsageModelFilter),
141
});
142
export type UsageSummaryInput = typeof UsageSummaryInput.Type;