Skip to content

Commit 4633bce

Browse files
t3dotggclaude
andcommitted
fix(usage): address review-bot findings across scan, cache, and page
Server: settings failures now surface as UsageReadError instead of reading as zero usage; a Codex token_count arriving before its turn_context no longer poisons the duplicate signature; failed file reads are no longer memoised as empty; the scan-cache load is raced-safe via Effect.cached; the dirty flag only clears after a successful persist; pruning is scoped to walked roots so a missing provider directory cannot purge warm entries; decode validates numeric fields; stale rate tables stop reporting fresh. Contract: UsageDay validates its YYYY-MM-DD shape, sources report distinct session counts, version bumped to 3. Web: session totals come from per-directory distinct counts instead of per-bucket sums; the refresh button refreshes each environment query rather than the derived atom; partial coverage distinguishes still-reporting from failed and surfaces stale-version environments; the window start uses calendar arithmetic so DST cannot shift it; the daily average is labelled per active day; adjacent chart bands share one smoothed curve per stack boundary so edges cannot gap or overlap. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
1 parent f6082c3 commit 4633bce

14 files changed

Lines changed: 353 additions & 104 deletions

File tree

‎apps/server/src/server.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -826,7 +826,7 @@ const buildAppUnderTest = (options?: {
826826

827827
const appLayer = servedRoutesLayer.pipe(
828828
Layer.provide(resourceTelemetryLayer),
829-
Layer.provide(UsageService.UsageService.layerTest),
829+
Layer.provide(UsageService.layerTest),
830830
Layer.provide(
831831
Layer.mock(BrowserTraceCollector.BrowserTraceCollector)({
832832
record: () => Effect.void,

‎apps/server/src/usage/UsageService.ts‎

Lines changed: 79 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -89,41 +89,40 @@ export class UsageService extends Context.Service<
8989
{
9090
readonly readSummary: (input: UsageSummaryInput) => Effect.Effect<UsageSummary, UsageReadError>;
9191
}
92-
>()("t3/usage/UsageService") {
93-
/** Empty summary, for suites that only need the RPC surface to resolve. */
94-
static readonly layerTest = Layer.succeed(
95-
UsageService,
96-
UsageService.of({
97-
readSummary: (input) =>
98-
Effect.succeed({
99-
contractVersion: USAGE_CONTRACT_VERSION,
100-
readAt: "1970-01-01T00:00:00.000Z",
101-
timeZone: input.timeZone,
102-
sinceDay: input.sinceDay,
103-
untilDay: input.untilDay,
104-
buckets: [],
105-
sources: [],
106-
pricing: {
107-
status: "unavailable",
108-
source: LITELLM_RATES_URL,
109-
fetchedAt: null,
110-
knownModels: 0,
111-
},
112-
scanDurationMs: 0,
113-
}),
114-
}),
115-
);
116-
}
92+
>()("t3/usage/UsageService") {}
93+
94+
/** Empty summary, for suites that only need the RPC surface to resolve. */
95+
export const layerTest = Layer.succeed(
96+
UsageService,
97+
UsageService.of({
98+
readSummary: (input) =>
99+
Effect.succeed({
100+
contractVersion: USAGE_CONTRACT_VERSION,
101+
readAt: "1970-01-01T00:00:00.000Z",
102+
timeZone: input.timeZone,
103+
sinceDay: input.sinceDay,
104+
untilDay: input.untilDay,
105+
buckets: [],
106+
sources: [],
107+
pricing: {
108+
status: "unavailable",
109+
source: LITELLM_RATES_URL,
110+
fetchedAt: null,
111+
knownModels: 0,
112+
},
113+
scanDurationMs: 0,
114+
}),
115+
}),
116+
);
117117

118-
const make = Effect.gen(function* () {
118+
export const make = Effect.gen(function* () {
119119
const fileSystem = yield* FileSystem.FileSystem;
120120
const path = yield* Path.Path;
121121
const config = yield* ServerConfig;
122122
const settingsService = yield* ServerSettings.ServerSettingsService;
123123
const httpClient = yield* HttpClient.HttpClient;
124124

125125
const fileCache: ScanCache = new Map();
126-
let cacheLoaded = false;
127126
let cacheDirty = false;
128127

129128
const ratesCachePath = path.join(config.stateDir, "usage-model-rates.json");
@@ -163,7 +162,12 @@ const make = Effect.gen(function* () {
163162
Effect.timeout(10_000),
164163
Effect.catchCause(() => Effect.succeed(null)),
165164
);
166-
if (fetched === null) return;
165+
if (fetched === null) {
166+
// The refresh failed; whatever we are serving is now past its TTL and
167+
// must not keep claiming to be fresh.
168+
if (rates.size > 0) ratesStatus = "cached";
169+
return;
170+
}
167171

168172
const parsed = parseRateTable(fetched);
169173
if (parsed.size === 0) return;
@@ -193,12 +197,17 @@ const make = Effect.gen(function* () {
193197

194198
/** Resolves the transcript directory for each provider. */
195199
const resolveTranscriptDirs = Effect.fn("UsageService.resolveTranscriptDirs")(function* () {
200+
// A settings failure must surface as an error: swallowing it here would
201+
// present "zero usage from every provider" as a valid answer.
196202
const settings = yield* settingsService.getSettings.pipe(
197-
Effect.catchCause(() => Effect.succeed(null)),
203+
Effect.catchCause(
204+
(cause) =>
205+
new UsageReadError({
206+
reason: "scanFailed",
207+
detail: `Server settings could not be read: ${String(cause)}`,
208+
}),
209+
),
198210
);
199-
if (settings === null) {
200-
return [] as readonly { provider: UsageProviderKind; dir: string }[];
201-
}
202211

203212
const claudeHome = yield* resolveClaudeHomePath(settings.providers.claudeAgent);
204213
const claudeDir = yield* resolveClaudeTranscriptDir(claudeHome);
@@ -210,25 +219,33 @@ const make = Effect.gen(function* () {
210219
];
211220
});
212221

213-
/** Loads the persisted scan cache once per process. */
214-
const ensureScanCacheLoaded = Effect.fn("UsageService.ensureScanCacheLoaded")(function* () {
215-
if (cacheLoaded) return;
216-
cacheLoaded = true;
217-
218-
const document = yield* fileSystem.readFileString(scanCachePath).pipe(
219-
Effect.flatMap((raw) => decodeScanCacheFile(raw)),
220-
Effect.catchCause(() => Effect.succeed(null)),
221-
);
222-
if (document === null) return;
223-
224-
for (const [path, entry] of decodeScanCache(document)) fileCache.set(path, entry);
225-
});
222+
/**
223+
* Loads the persisted scan cache exactly once per process.
224+
*
225+
* `Effect.cached` makes concurrent first readers await the same load rather
226+
* than each seeing a "loaded" flag set before the read finished and cold
227+
* scanning against an empty cache.
228+
*/
229+
const ensureScanCacheLoaded = yield* Effect.cached(
230+
Effect.gen(function* () {
231+
const document = yield* fileSystem.readFileString(scanCachePath).pipe(
232+
Effect.flatMap((raw) => decodeScanCacheFile(raw)),
233+
Effect.catchCause(() => Effect.succeed(null)),
234+
);
235+
if (document === null) return;
236+
for (const [path, entry] of decodeScanCache(document)) fileCache.set(path, entry);
237+
}),
238+
);
226239

227240
const persistScanCache = Effect.fn("UsageService.persistScanCache")(function* () {
228241
if (!cacheDirty) return;
229-
cacheDirty = false;
242+
// Cleared only after the write lands, so a failed persist is retried on
243+
// the next scan instead of leaving disk permanently stale.
230244
yield* encodeScanCacheFile(encodeScanCache(fileCache)).pipe(
231245
Effect.flatMap((serialized) => fileSystem.writeFileString(scanCachePath, serialized)),
246+
Effect.map(() => {
247+
cacheDirty = false;
248+
}),
232249
// A cache we cannot write is a slower next start, not a failed read.
233250
Effect.catchCause(() => Effect.void),
234251
);
@@ -246,6 +263,9 @@ const make = Effect.gen(function* () {
246263
if (cached && cached.size === size && cached.mtimeMs === mtimeMs) return cached.records;
247264

248265
const parsed = yield* Effect.promise(() => readTranscriptRecords(filePath, provider));
266+
// A read failure is not an empty transcript: caching it under this
267+
// (size, mtime) would silently drop the file's usage until it changes.
268+
if (parsed === null) return [];
249269
// Stored already de-duplicated within the file, which is 99% of all
250270
// duplicates. The aggregator still runs the cross-file dedupe pass.
251271
const records = dedupeWithinFile(parsed);
@@ -265,7 +285,7 @@ const make = Effect.gen(function* () {
265285

266286
const startedAtMs = yield* Clock.currentTimeMillis;
267287
yield* ensureRates();
268-
yield* ensureScanCacheLoaded();
288+
yield* ensureScanCacheLoaded;
269289

270290
const hostId = NodeOS.hostname();
271291
// The home resolvers ask for `Path` themselves; satisfy them from the
@@ -289,6 +309,7 @@ const make = Effect.gen(function* () {
289309

290310
const sources: UsageSource[] = [];
291311
const livePaths = new Set<string>();
312+
const walkedRoots: string[] = [];
292313

293314
for (const { provider, dir } of dirs) {
294315
const volumeId = yield* Effect.promise(() => readDirectoryVolumeId(dir));
@@ -303,14 +324,19 @@ const make = Effect.gen(function* () {
303324
scannedFiles: 0,
304325
skippedFiles: 0,
305326
malformedRecords: 0,
327+
distinctSessions: 0,
306328
message: "No transcript directory on this environment.",
307329
});
308330
continue;
309331
}
310332

333+
walkedRoots.push(dir);
311334
const files = yield* Effect.promise(() => listTranscriptFiles(dir, windowStartMs));
312335
let scannedFiles = 0;
313336
let skippedFiles = 0;
337+
// Distinct per directory. Buckets carry per-cell session counts, but a
338+
// session spans days and models, so clients total this figure instead.
339+
const sessionIds = new Set<string>();
314340

315341
for (const file of files) {
316342
livePaths.add(file.path);
@@ -320,7 +346,10 @@ const make = Effect.gen(function* () {
320346
continue;
321347
}
322348
scannedFiles += 1;
323-
for (const record of records) aggregator.add(record);
349+
for (const record of records) {
350+
aggregator.add(record);
351+
if (record.sessionId.length > 0) sessionIds.add(record.sessionId);
352+
}
324353
}
325354

326355
sources.push({
@@ -329,12 +358,14 @@ const make = Effect.gen(function* () {
329358
scannedFiles,
330359
skippedFiles,
331360
malformedRecords: 0,
361+
distinctSessions: sessionIds.size,
332362
message: null,
333363
});
334364
}
335365

336366
const pruned = pruneScanCache(fileCache, {
337367
livePaths,
368+
walkedRoots,
338369
windowStartMs,
339370
retentionCutoffMs: startedAtMs - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000,
340371
});

‎apps/server/src/usage/usageScanCache.test.ts‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ describe("pruneScanCache", () => {
8686

8787
const removed = pruneScanCache(cache, {
8888
livePaths: new Set(),
89+
walkedRoots: ["/"],
8990
windowStartMs: 400,
9091
retentionCutoffMs,
9192
});
@@ -97,7 +98,12 @@ describe("pruneScanCache", () => {
9798
it("drops in-window entries whose file has disappeared", () => {
9899
const cache = cacheWith([["/gone.jsonl", 5000, [record()]]]);
99100

100-
pruneScanCache(cache, { livePaths: new Set(), windowStartMs: 4000, retentionCutoffMs });
101+
pruneScanCache(cache, {
102+
livePaths: new Set(),
103+
walkedRoots: ["/"],
104+
windowStartMs: 4000,
105+
retentionCutoffMs,
106+
});
101107

102108
expect(cache.size).toBe(0);
103109
});
@@ -109,6 +115,7 @@ describe("pruneScanCache", () => {
109115

110116
const removed = pruneScanCache(cache, {
111117
livePaths: new Set(),
118+
walkedRoots: ["/"],
112119
windowStartMs: 4000,
113120
retentionCutoffMs,
114121
});
@@ -122,6 +129,7 @@ describe("pruneScanCache", () => {
122129

123130
pruneScanCache(cache, {
124131
livePaths: new Set(["/live.jsonl"]),
132+
walkedRoots: ["/"],
125133
windowStartMs: 4000,
126134
retentionCutoffMs,
127135
});
@@ -130,6 +138,43 @@ describe("pruneScanCache", () => {
130138
});
131139
});
132140

141+
describe("pruneScanCache with an unwalked root", () => {
142+
it("keeps in-window entries for a provider whose directory was not walked", () => {
143+
// A missing provider root or failed settings read leaves livePaths without
144+
// that provider's files. Its warm entries must survive the pass.
145+
const cache = cacheWith([["/codex/sessions/a.jsonl", 5000, [record()]]]);
146+
147+
const removed = pruneScanCache(cache, {
148+
livePaths: new Set(),
149+
walkedRoots: ["/claude/projects"],
150+
windowStartMs: 4000,
151+
retentionCutoffMs: 1000,
152+
});
153+
154+
expect(removed).toBe(0);
155+
expect(cache.size).toBe(1);
156+
});
157+
});
158+
159+
describe("decodeScanCache numeric validation", () => {
160+
it("rejects rows whose token fields are not numbers", () => {
161+
const encoded = encodeScanCache(cacheWith([["/a.jsonl", 100, [record()]]]));
162+
const rows = encoded.files["/a.jsonl"]!.r;
163+
const poisoned = {
164+
...encoded,
165+
files: {
166+
"/a.jsonl": {
167+
...encoded.files["/a.jsonl"]!,
168+
r: [[...rows[0]!.slice(0, 3), "not-a-number", ...rows[0]!.slice(4)]],
169+
},
170+
},
171+
};
172+
173+
const restored = decodeScanCache(JSON.parse(JSON.stringify(poisoned)));
174+
expect(restored.get("/a.jsonl")?.records).toHaveLength(0);
175+
});
176+
});
177+
133178
describe("dedupeWithinFile", () => {
134179
it("keeps the first record per dedupe key", () => {
135180
const kept = dedupeWithinFile([

‎apps/server/src/usage/usageScanCache.ts‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -147,14 +147,26 @@ export function decodeScanCache(document: unknown): ScanCache {
147147
reportedCostUsd,
148148
] = row as SerializedRecord;
149149

150-
const model = models[modelIndex];
151-
if (typeof timestampMs !== "number" || model === undefined) continue;
150+
const model = typeof modelIndex === "number" ? models[modelIndex] : undefined;
151+
if (typeof timestampMs !== "number" || !Number.isFinite(timestampMs)) continue;
152+
if (model === undefined) continue;
153+
// Token fields must be real numbers: a corrupt row must cost a cold
154+
// re-parse of its file, never flow into the aggregate as NaN or a string.
155+
if (
156+
!Number.isFinite(uncached) ||
157+
!Number.isFinite(cached) ||
158+
!Number.isFinite(cacheCreation) ||
159+
!Number.isFinite(output) ||
160+
!Number.isFinite(reasoning)
161+
) {
162+
continue;
163+
}
152164

153165
records.push({
154166
provider,
155167
timestampMs,
156168
model,
157-
sessionId: sessions[sessionIndex] ?? "",
169+
sessionId: (typeof sessionIndex === "number" ? sessions[sessionIndex] : undefined) ?? "",
158170
totals: {
159171
uncachedInputTokens: uncached,
160172
cachedInputTokens: cached,
@@ -176,6 +188,12 @@ export function decodeScanCache(document: unknown): ScanCache {
176188
export interface PruneOptions {
177189
/** Files the walk just saw. Only meaningful inside the walked window. */
178190
readonly livePaths: ReadonlySet<string>;
191+
/**
192+
* Roots the walk actually completed. Absence from `livePaths` only proves a
193+
* file is gone when its root was walked: a provider whose directory failed to
194+
* resolve this pass must not have its warm entries purged.
195+
*/
196+
readonly walkedRoots: readonly string[];
179197
/** Start of the walked window; entries older than this were not looked for. */
180198
readonly windowStartMs: number;
181199
/** Entries older than this are dropped regardless. */
@@ -196,7 +214,9 @@ export function pruneScanCache(cache: ScanCache, options: PruneOptions): number
196214
let removed = 0;
197215
for (const [path, entry] of cache) {
198216
const agedOut = entry.mtimeMs < options.retentionCutoffMs;
199-
const deleted = entry.mtimeMs >= options.windowStartMs && !options.livePaths.has(path);
217+
const underWalkedRoot = options.walkedRoots.some((root) => path.startsWith(root));
218+
const deleted =
219+
underWalkedRoot && entry.mtimeMs >= options.windowStartMs && !options.livePaths.has(path);
200220
if (agedOut || deleted) {
201221
cache.delete(path);
202222
removed += 1;

0 commit comments

Comments
 (0)