@devries-cameron20 / t3code-1 / commits / 7fab4ef978
Fork 0

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

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;