Open History to see the last commit
1import {
2 type ProviderInstanceConfig,
3 ProviderInstanceId,
4 USAGE_CONTRACT_VERSION,
5 type ServerSettings as ServerSettingsValue,
6 type UsageProviderKind,
7 type UsageSource,
8 type UsagePricing,
9 type UsageSummary,
10 type UsageSummaryInput,
11 UsageReadError,
12} from "@t3tools/contracts";
13import * as HostProcess from "@t3tools/shared/HostProcess";
14import * as Cause from "effect/Cause";
15import * as Clock from "effect/Clock";
16import * as Context from "effect/Context";
17import * as DateTime from "effect/DateTime";
18import * as Deferred from "effect/Deferred";
19import * as Effect from "effect/Effect";
20import * as Exit from "effect/Exit";
21import * as Fiber from "effect/Fiber";
22import * as FileSystem from "effect/FileSystem";
23import * as Layer from "effect/Layer";
24import * as Option from "effect/Option";
25import * as Path from "effect/Path";
26import * as Schema from "effect/Schema";
27import * as Semaphore from "effect/Semaphore";
28import { HttpClient, HttpClientResponse } from "effect/http";
29
30import { writeFileStringAtomically } from "@t3tools/shared/atomicWrite";
31import { formatMalformedUsageWarning } from "@t3tools/shared/usageFormat";
32import * as ServerConfig from "../config.ts";
33import * as ServerSettings from "../serverSettings.ts";
34import { BUILT_IN_USAGE_DRIVERS, type BuiltInUsageReadersEnv } from "../provider/builtInDrivers.ts";
35import type { ProviderDriver } from "@t3tools/provider-core/server/driver";
36import { mergeProviderInstanceEnvironment } from "@t3tools/provider-core/server/instanceEnvironment";
37import type {
38 ProviderUsageInstance,
39 TranscriptUsageFormat,
40 UsageRecord,
41} from "@t3tools/provider-core/server/usage";
42import { canonicalModelFilter, resolveModelAliases, UsageAggregator } from "./usageAggregation.ts";
43import { createOverrideRateTable, parseRateTable, type RateTable } from "./usagePricing.ts";
44import {
45 listTranscriptFiles,
46 readDirectoryVolumeId,
47 readTranscriptRecords,
48} from "./usageTranscriptReader.ts";
49import {
50 decodeScanCache,
51 dedupeWithinFile,
52 LEGACY_SCAN_CACHE_FILE_NAMES,
53 makeScanCacheWriter,
54 pruneScanCache,
55 SCAN_CACHE_FILE_NAME,
56 type CachedFile,
57 type ScanCache,
58} from "./usageScanCache.ts";
59
60const LITELLM_RATES_URL =
61 "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
62const LITELLM_RATES_API_URL =
63 "https://api.github.com/repos/BerriAI/litellm/contents/model_prices_and_context_window.json?ref=main";
64
65const RATES_TTL_MS = 24 * 60 * 60 * 1000;
66
67const RATES_REFRESH_FLOOR_MS = 60 * 1000;
68
69// mtime slack includes writes just before local midnight on the window's first day.
70const MTIME_SLACK_MS = 36 * 60 * 60 * 1000;
71const MAX_HOURLY_WINDOW_MS = 24 * 60 * 60 * 1000;
72
73const CACHE_RETENTION_DAYS = 92;
74const STALE_TEMP_DIRECTORY_MS = 60 * 60 * 1000;
75
76const TRANSCRIPT_READ_CONCURRENCY = 4;
77
78const transcriptReaders = BUILT_IN_USAGE_DRIVERS.flatMap((driver) =>
79 driver.usage?.kind === "transcripts" ? [{ driver, reader: driver.usage }] : [],
80);
81
82const scanReaders = BUILT_IN_USAGE_DRIVERS.flatMap((driver) =>
83 driver.usage?.kind === "scan" ? [{ driver, reader: driver.usage }] : [],
84);
85
86const transcriptFormats = new Map(
87 transcriptReaders.map(({ reader }) => [reader.provider, reader.format] as const),
88);
89
90interface TranscriptSource {
91 readonly provider: UsageProviderKind;
92 readonly format: TranscriptUsageFormat<unknown>;
93 readonly dir: string;
94 readonly volumeId: string;
95 readonly fileName?: string;
96}
97
98const RatesCacheFile = Schema.Struct({
99 fetchedAtMs: Schema.Number,
100 document: Schema.Unknown,
101});
102const decodeRatesCache = Schema.decodeUnknownEffect(Schema.fromJsonString(RatesCacheFile));
103const encodeRatesCache = Schema.encodeEffect(Schema.fromJsonString(RatesCacheFile));
104
105const ScanCacheJson = Schema.fromJsonString(Schema.Unknown);
106const decodeScanCacheFile = Schema.decodeUnknownEffect(ScanCacheJson);
107const encodeUsageRecordKey = Schema.encodeSync(ScanCacheJson);
108const CachedSource = Schema.Struct({ dir: Schema.String, volumeId: Schema.String });
109
110function isLaterRead(a: CachedFile, b: CachedFile): boolean {
111 return a.mtimeMs > b.mtimeMs || (a.mtimeMs === b.mtimeMs && a.size > b.size);
112}
113
114const sharedSessionProviders: ReadonlySet<UsageProviderKind> = new Set(
115 transcriptReaders.flatMap(({ reader }) =>
116 reader.format.sharedSessionsAcrossFiles ? [reader.provider] : [],
117 ),
118);
119
120// Only shared sessions need cross-file dedupe; per-file occurrence counts make other keys unique.
121function sharedSessions(
122 files: readonly { readonly records: readonly UsageRecord[] }[],
123): ReadonlySet<string> {
124 const firstFile = new Map<string, number>();
125 const shared = new Set<string>();
126 for (const [index, file] of files.entries()) {
127 let previous = "";
128 for (const { provider, sessionId } of file.records) {
129 if (!sharedSessionProviders.has(provider) || sessionId === previous || sessionId.length === 0)
130 continue;
131 previous = sessionId;
132 const first = firstFile.get(sessionId);
133 if (first === undefined) firstFile.set(sessionId, index);
134 else if (first !== index) shared.add(sessionId);
135 }
136 }
137 return shared;
138}
139const decodeCachedSources = Schema.decodeUnknownOption(
140 Schema.Struct({ sources: Schema.Record(Schema.String, CachedSource) }),
141);
142
143export class UsageService extends Context.Service<
144 UsageService,
145 {
146 readonly readSummary: (input: UsageSummaryInput) => Effect.Effect<UsageSummary, UsageReadError>;
147 readonly refreshRates: Effect.Effect<UsagePricing>;
148 }
149>()("t3/usage/UsageService") {}
150
151export const make = Effect.gen(function* () {
152 const fileSystem = yield* FileSystem.FileSystem;
153 const path = yield* Path.Path;
154 const config = yield* ServerConfig.ServerConfig;
155 const settingsService = yield* ServerSettings.ServerSettingsService;
156 const httpClient = yield* HttpClient.HttpClient;
157 const hostEnvironment = yield* HostProcess.Environment;
158 const hostname = yield* HostProcess.Hostname;
159 const readerContext = yield* Effect.context<BuiltInUsageReadersEnv>();
160
161 const fileCache: ScanCache = new Map();
162 // Reads from concurrent windows can still hold the original record after it is corrected.
163 const resolvedRecords = new WeakMap<UsageRecord, UsageRecord>();
164 const correctedRecord = (record: UsageRecord) => resolvedRecords.get(record) ?? record;
165 const correctedBatch = (records: readonly UsageRecord[]) =>
166 records.some((record) => resolvedRecords.has(record)) ? records.map(correctedRecord) : records;
167 const sourceCache = new Map<string, typeof CachedSource.Type>();
168 let cacheDirty = false;
169 const isWithinDirectory = (filePath: string, dir: string) => {
170 const relative = path.relative(dir, filePath);
171 return relative !== ".." && !relative.startsWith(".." + path.sep) && !path.isAbsolute(relative);
172 };
173
174 const ratesCachePath = path.join(config.stateDir, "usage-model-rates.json");
175 const scanCachePath = path.join(config.stateDir, SCAN_CACHE_FILE_NAME);
176 const writeCacheFile = (filePath: string, contents: string | Iterable<string>) =>
177 writeFileStringAtomically({ filePath, contents }).pipe(
178 Effect.provideService(FileSystem.FileSystem, fileSystem),
179 Effect.provideService(Path.Path, path),
180 );
181 const hostIdPath = path.join(config.baseDir, "usage-host-id");
182 const explicitHostId = hostEnvironment["T3CODE_HOST_ID"]?.trim();
183 const hostId =
184 explicitHostId ||
185 (yield* fileSystem.readFileString(hostIdPath).pipe(
186 Effect.catchIf(
187 (error) => error.reason._tag === "NotFound",
188 () =>
189 Effect.scoped(
190 Effect.gen(function* () {
191 yield* fileSystem.makeDirectory(config.baseDir, { recursive: true });
192 const tempDirectory = yield* fileSystem.makeTempDirectoryScoped({
193 directory: config.baseDir,
194 prefix: "usage-host-id.",
195 });
196 const tempFile = path.join(tempDirectory, "identity");
197 yield* fileSystem.writeFileString(tempFile, `${hostname}\n`);
198 // Publish complete contents without replacing another initializer's identity.
199 yield* fileSystem.link(tempFile, hostIdPath).pipe(
200 Effect.catchIf(
201 (error) => error.reason._tag === "AlreadyExists",
202 () => Effect.void,
203 ),
204 );
205 return yield* fileSystem.readFileString(hostIdPath);
206 }),
207 ),
208 ),
209 Effect.map((value) => value.trim() || hostname),
210 Effect.orElseSucceed(() => hostname),
211 ));
212 let rates: RateTable = new Map();
213 let ratesFetchedAtMs: number | null = null;
214 let ratesLastFailedAtMs: number | null = null;
215 let ratesStatus: UsagePricing["status"] = "unavailable";
216 const ratesLock = yield* Semaphore.make(1);
217
218 const pricing = (): UsagePricing => ({
219 status: ratesStatus,
220 source: LITELLM_RATES_URL,
221 fetchedAt:
222 ratesFetchedAtMs === null ? null : DateTime.formatIso(DateTime.makeUnsafe(ratesFetchedAtMs)),
223 knownModels: rates.size,
224 });
225
226 const fetchRates = (url: string, accept = "application/json") =>
227 httpClient.get(url, { headers: { accept } }).pipe(
228 Effect.flatMap(HttpClientResponse.filterStatusOk),
229 Effect.flatMap((response) => response.json),
230 Effect.map((document) => {
231 const parsed = parseRateTable(document);
232 return parsed.size > 0 ? { document, parsed } : null;
233 }),
234 Effect.timeout(10_000),
235 Effect.catchCause(() => Effect.succeed(null)),
236 );
237
238 const loadRates = Effect.fn("UsageService.loadRates")(function* (force: boolean) {
239 const now = yield* Clock.currentTimeMillis;
240 const maxAgeMs = force ? RATES_REFRESH_FLOOR_MS : RATES_TTL_MS;
241 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
259 if (ratesLastFailedAtMs !== null && now - ratesLastFailedAtMs < RATES_REFRESH_FLOOR_MS) return;
260
261 let fetched = yield* fetchRates(LITELLM_RATES_URL);
262 if (fetched === null) {
263 fetched = yield* fetchRates(LITELLM_RATES_API_URL, "application/vnd.github.raw+json");
264 }
265 if (fetched === null) {
266 ratesLastFailedAtMs = yield* Clock.currentTimeMillis;
267 if (rates.size > 0) ratesStatus = "cached";
268 return;
269 }
270
271 rates = fetched.parsed;
272 ratesFetchedAtMs = now;
273 ratesLastFailedAtMs = null;
274 ratesStatus = "fresh";
275
276 yield* encodeRatesCache({ fetchedAtMs: now, document: fetched.document }).pipe(
277 Effect.flatMap((contents) => writeCacheFile(ratesCachePath, contents)),
278 Effect.ignoreCause,
279 );
280 });
281
282 const ensureRates = (force: boolean) => ratesLock.withPermit(loadRates(force));
283
284 const refreshRates = ensureRates(true).pipe(
285 Effect.map(pricing),
286 Effect.withSpan("UsageService.refreshRates"),
287 );
288
289 const readSettings = settingsService.getSettings.pipe(
290 Effect.catchCause(
291 (cause) =>
292 new UsageReadError({
293 reason: "scanFailed",
294 detail: "Server settings could not be read.",
295 cause: Cause.squash(cause),
296 }),
297 ),
298 );
299
300 const usageInstances = Effect.fn("UsageService.usageInstances")(function* <Config>(
301 driver: ProviderDriver<Config, unknown, unknown>,
302 settings: ServerSettingsValue,
303 ) {
304 const entries: Array<
305 readonly [ProviderInstanceId, Pick<ProviderInstanceConfig, "config" | "environment">, boolean]
306 > = Object.entries(settings.providerInstances)
307 .filter(([, instance]) => instance.driver === driver.driverKind)
308 .map(([id, instance]) => [ProviderInstanceId.make(id), instance, true] as const);
309 if (!Object.hasOwn(settings.providerInstances, driver.driverKind)) {
310 entries.push([ProviderInstanceId.make(driver.driverKind), {}, false]);
311 }
312 const decodeConfig = Schema.decodeUnknownOption(driver.configSchema);
313 return yield* Effect.forEach(
314 entries,
315 Effect.fnUntraced(function* ([instanceId, instance, configured]) {
316 const instanceConfig: ProviderUsageInstance<Config> = {
317 instanceId,
318 config: Option.getOrUndefined(decodeConfig(instance.config ?? {})),
319 environment: yield* mergeProviderInstanceEnvironment(
320 instance.environment,
321 hostEnvironment,
322 ),
323 configured,
324 };
325 return instanceConfig;
326 }),
327 );
328 });
329
330 const resolveTranscriptDirs = Effect.fn("UsageService.resolveTranscriptDirs")(function* (
331 settings: ServerSettingsValue,
332 retentionCutoffMs: number,
333 awaitRefresh: boolean,
334 ) {
335 const dirs: Array<TranscriptSource> = [];
336 const pending: Array<ScannedDir> = [];
337 const seen = new Set<string>();
338 for (const { driver, reader } of transcriptReaders) {
339 const { provider, format } = reader;
340 const directories = yield* Effect.forEach(
341 yield* usageInstances(driver, settings),
342 (instance) => reader.directories(instance, { awaitRefresh }),
343 );
344 for (const { dir: directory, fileName, refreshing } of directories.flat()) {
345 if (refreshing) {
346 const key = `${provider}\0${directory}`;
347 if (seen.has(key)) continue;
348 seen.add(key);
349 pending.push({ provider, dir: directory, volumeId: "", files: [], refreshing });
350 continue;
351 }
352 const sourceKey = provider + "\0" + directory;
353 const previous = sourceCache.get(sourceKey);
354 const dir = yield* fileSystem
355 .realPath(directory)
356 .pipe(Effect.orElseSucceed(() => previous?.dir ?? directory));
357 const currentVolumeId = yield* Effect.promise(() => readDirectoryVolumeId(dir));
358 const hasRetainedHistory = fileCache
359 .entries()
360 .some(
361 ([filePath, entry]) =>
362 entry.provider === provider &&
363 entry.mtimeMs >= retentionCutoffMs &&
364 (entry.records.length + entry.tailRecords.length > 0 || entry.malformedRecords > 0) &&
365 isWithinDirectory(filePath, dir),
366 );
367 const volumeId =
368 previous?.dir === dir && (hasRetainedHistory || !currentVolumeId)
369 ? previous.volumeId || currentVolumeId
370 : currentVolumeId;
371 if (previous?.dir !== dir || previous.volumeId !== volumeId) {
372 sourceCache.set(sourceKey, { dir, volumeId });
373 cacheDirty = true;
374 }
375 const key = `${provider}\0${dir}`;
376 if (seen.has(key)) continue;
377 seen.add(key);
378 dirs.push({
379 provider,
380 format,
381 dir,
382 volumeId,
383 ...(fileName === undefined ? {} : { fileName }),
384 });
385 }
386 }
387 return { dirs, pending };
388 });
389
390 // Share first loads so concurrent readers cannot scan against a still-empty cache.
391 const ensureScanCacheLoaded = yield* Effect.cached(
392 Effect.gen(function* () {
393 const readDocument = (filePath: string) =>
394 fileSystem.readFileString(filePath).pipe(
395 Effect.flatMap((raw) => decodeScanCacheFile(raw)),
396 Effect.catchCause(() => Effect.succeed(null)),
397 );
398 let document = yield* readDocument(scanCachePath);
399 for (const fileName of LEGACY_SCAN_CACHE_FILE_NAMES) {
400 if (document !== null) break;
401 document = yield* readDocument(path.join(config.stateDir, fileName));
402 cacheDirty = document !== null;
403 }
404 if (document === null) return;
405 for (const [path, entry] of decodeScanCache(document, transcriptFormats)) {
406 fileCache.set(path, entry);
407 }
408 const sources = decodeCachedSources(document);
409 if (Option.isSome(sources)) {
410 for (const [key, source] of Object.entries(sources.value.sources))
411 sourceCache.set(key, source);
412 }
413 }),
414 );
415
416 const writeScanCache = makeScanCacheWriter();
417 // Serialize writes so concurrently finished window scans cannot overwrite newer snapshots.
418 const persistLock = yield* Semaphore.make(1);
419
420 // The saved cache supersedes older versions. Temp folders an aborted write left behind are
421 // removed once idle for an hour, so a write in progress from another server survives.
422 let supersededFilesRemoved = false;
423 const removeSupersededCacheFiles = Effect.gen(function* () {
424 for (const fileName of LEGACY_SCAN_CACHE_FILE_NAMES) {
425 yield* fileSystem.remove(path.join(config.stateDir, fileName)).pipe(Effect.ignore);
426 }
427 const tempPrefixes = [SCAN_CACHE_FILE_NAME, ...LEGACY_SCAN_CACHE_FILE_NAMES].map(
428 (fileName) => `${fileName}.`,
429 );
430 const staleBeforeMs = (yield* Clock.currentTimeMillis) - STALE_TEMP_DIRECTORY_MS;
431 for (const name of yield* fileSystem.readDirectory(config.stateDir)) {
432 if (!tempPrefixes.some((prefix) => name.startsWith(prefix))) continue;
433 const tempPath = path.join(config.stateDir, name);
434 yield* fileSystem.stat(tempPath).pipe(
435 Effect.flatMap((info) => {
436 const mtimeMs = Option.getOrUndefined(info.mtime)?.getTime();
437 return info.type === "Directory" && mtimeMs !== undefined && mtimeMs <= staleBeforeMs
438 ? fileSystem.remove(tempPath, { recursive: true })
439 : Effect.void;
440 }),
441 Effect.ignore,
442 );
443 }
444 }).pipe(Effect.ignore);
445
446 // Clear dirty before encoding to retain concurrent changes; restore it on failure for retry.
447 const persistCaches = Effect.gen(function* () {
448 if (cacheDirty) {
449 cacheDirty = false;
450 yield* Effect.sync(() =>
451 writeScanCache(fileCache, { sources: Object.fromEntries(sourceCache) }),
452 ).pipe(
453 Effect.flatMap((contents) => writeCacheFile(scanCachePath, contents)),
454 Effect.andThen(
455 Effect.suspend(() => {
456 if (supersededFilesRemoved) return Effect.void;
457 supersededFilesRemoved = true;
458 return removeSupersededCacheFiles;
459 }),
460 ),
461 Effect.catchCause(() =>
462 Effect.sync(() => {
463 cacheDirty = true;
464 }),
465 ),
466 );
467 }
468 }).pipe(persistLock.withPermit, Effect.withSpan("UsageService.persistCaches"));
469
470 const pendingPersists = new Set<Fiber.Fiber<void>>();
471 const schedulePersist = Effect.forkDetach(persistCaches).pipe(
472 Effect.map((fiber) => {
473 pendingPersists.add(fiber);
474 fiber.addObserver(() => pendingPersists.delete(fiber));
475 }),
476 );
477 const awaitPersisted = Effect.suspend(() => Fiber.awaitAll([...pendingPersists])).pipe(
478 Effect.asVoid,
479 );
480 yield* Effect.addFinalizer(() => awaitPersisted);
481
482 /**
483 * Reads run concurrently, and the caller stores updates in walk order rather
484 * than completion order: saved records of deleted transcripts aggregate in
485 * cache order, where the first copy of a duplicate decides its bucket. Untraced: a scan
486 * reads thousands of files, so scanTranscriptDir records the counts instead.
487 */
488 const readFileRecords = Effect.fnUntraced(function* (
489 filePath: string,
490 size: number,
491 mtimeMs: number,
492 provider: UsageProviderKind,
493 format: TranscriptUsageFormat<unknown>,
494 ): Effect.fn.Return<{
495 readonly records: readonly UsageRecord[];
496 readonly malformedRecords: number;
497 readonly failed?: true;
498 readonly update?: { readonly entry: CachedFile; readonly replaces: CachedFile | undefined };
499 }> {
500 const cached = fileCache.get(filePath);
501 // Provider is part of the identity: if both providers were ever pointed
502 // at one directory, a hit parsed by the other parser must not be reused.
503 if (
504 cached &&
505 cached.size === size &&
506 cached.mtimeMs === mtimeMs &&
507 cached.provider === provider
508 ) {
509 return {
510 records:
511 cached.tailRecords.length === 0
512 ? cached.records
513 : [...cached.records, ...cached.tailRecords],
514 malformedRecords: cached.malformedRecords,
515 };
516 }
517
518 // Only a strictly grown file may resume. Same size with a new mtime, or
519 // a shrunken file, means rewritten content; re-parse it whole.
520 const resumeFrom =
521 cached !== undefined && cached.provider === provider && size > cached.size
522 ? cached.position
523 : undefined;
524
525 const parsed = yield* Effect.promise(() => readTranscriptRecords(filePath, format, resumeFrom));
526 // A read failure is not an empty transcript: caching it under this
527 // (size, mtime) would silently drop the file's usage until it changes.
528 if (parsed === null)
529 return {
530 records: cached?.provider === provider ? [...cached.records, ...cached.tailRecords] : [],
531 malformedRecords: cached?.provider === provider ? cached.malformedRecords : 0,
532 failed: true,
533 };
534
535 if (parsed.resumed && cached !== undefined && cached.tailRecords.length > 0) {
536 // Completing a tentative line reparses it. Reuse its saved correction only when the
537 // same usage is emitted again, without putting inferred tiers in the parser state.
538 const reparsed = [...parsed.records, ...parsed.tailRecords];
539 const identity = (record: UsageRecord) =>
540 encodeUsageRecordKey([
541 record.provider,
542 record.sessionId,
543 record.timestampMs,
544 record.model,
545 record.rateModel,
546 record.totals,
547 record.reportedCostUsd,
548 record.dedupeKey,
549 ]);
550 for (const [index, previous] of cached.tailRecords.entries()) {
551 const record = reparsed[index];
552 const corrected = correctedRecord(previous);
553 if (
554 record?.unresolvedServiceTierTurnId !== undefined &&
555 corrected.unresolvedServiceTierTurnId === undefined &&
556 identity(record) === identity(corrected)
557 ) {
558 resolvedRecords.set(record, corrected);
559 }
560 }
561 }
562 const base = parsed.resumed && cached !== undefined ? cached.records : [];
563 const records = dedupeWithinFile([...base, ...parsed.records]);
564 const tailRecords = parsed.tailRecords;
565
566 return {
567 records: tailRecords.length === 0 ? records : [...records, ...tailRecords],
568 malformedRecords: parsed.malformedRecords,
569 update: {
570 entry: {
571 size,
572 mtimeMs,
573 provider,
574 records,
575 tailRecords,
576 malformedRecords: parsed.malformedRecords,
577 position: parsed.position,
578 },
579 replaces: cached,
580 },
581 };
582 });
583
584 interface ScannedDir {
585 readonly provider: UsageProviderKind;
586 readonly dir: string;
587 readonly volumeId: string;
588 readonly hostId?: string;
589 readonly status?: UsageSource["status"];
590 readonly message?: string;
591 readonly files:
592 | readonly {
593 readonly path: string;
594 readonly records: readonly UsageRecord[];
595 readonly malformedRecords: number;
596 }[]
597 | null;
598 readonly refreshing?: true;
599 }
600
601 const scanTranscriptDir = Effect.fn("UsageService.scanTranscriptDir")(function* (
602 source: TranscriptSource,
603 windowStartMs: number,
604 ) {
605 const { provider, format, dir, volumeId, fileName } = source;
606 const exists = yield* fileSystem
607 .exists(dir)
608 .pipe(Effect.catchCause(() => Effect.succeed(false)));
609 if (!exists) return { provider, dir, volumeId, files: null } satisfies ScannedDir;
610 const { files, failedPaths } = yield* Effect.promise(() =>
611 listTranscriptFiles(dir, windowStartMs, fileName === undefined ? undefined : { fileName }),
612 );
613 const read = yield* Effect.forEach(
614 files,
615 (file) =>
616 readFileRecords(file.path, file.size, file.mtimeMs, provider, format).pipe(
617 Effect.map((result) => ({ path: file.path, ...result })),
618 ),
619 { concurrency: TRANSCRIPT_READ_CONCURRENCY },
620 );
621 const parsedFiles = read.map(({ path, records, malformedRecords, update }) => {
622 if (update === undefined) return { path, records, malformedRecords };
623 // A scan of another window may have cached its own read of this file
624 // meanwhile. Then keep whichever read saw the later file, so a slower
625 // scan never replaces newer usage with older.
626 const current = fileCache.get(path);
627 if (
628 current === update.replaces ||
629 current === undefined ||
630 isLaterRead(update.entry, current)
631 ) {
632 fileCache.set(path, {
633 ...update.entry,
634 records: correctedBatch(update.entry.records),
635 tailRecords: correctedBatch(update.entry.tailRecords),
636 });
637 cacheDirty = true;
638 }
639 return { path, records, malformedRecords };
640 });
641 const livePaths = new Set(files.map((file) => file.path));
642 for (const file of read) {
643 if (file.failed || !file.path.endsWith(".jsonl.zst")) continue;
644 const originalPath = file.path.slice(0, -4);
645 // A successfully read archive replaces the original's saved records and diagnostics.
646 if (!livePaths.has(originalPath) && fileCache.delete(originalPath)) cacheDirty = true;
647 }
648 const unread = failedPaths + read.filter((file) => file.failed).length;
649 yield* Effect.annotateCurrentSpan({
650 "usage.files": files.length,
651 "usage.files_parsed": read.filter((file) => file.update !== undefined).length,
652 });
653 return {
654 provider,
655 dir,
656 volumeId,
657 files: parsedFiles,
658 ...(unread > 0
659 ? {
660 status: "partial",
661 message: `${unread} transcript path(s) could not be read; usage may be incomplete.`,
662 }
663 : {}),
664 } satisfies ScannedDir;
665 });
666
667 const collectDirs = Effect.fn("UsageService.collectDirs")(function* (
668 windowStartMs: number,
669 settings: ServerSettingsValue,
670 retentionCutoffMs: number,
671 awaitRefresh: boolean,
672 ) {
673 const { dirs, pending } = yield* resolveTranscriptDirs(
674 settings,
675 retentionCutoffMs,
676 awaitRefresh,
677 ).pipe(Effect.provideContext(readerContext));
678
679 const scans = Effect.forEach(
680 scanReaders,
681 ({ driver, reader }) =>
682 usageInstances(driver, settings).pipe(
683 Effect.flatMap((instances) =>
684 reader.scan({ instances, settings, windowStartMs, retentionCutoffMs, awaitRefresh }),
685 ),
686 Effect.flatMap((sources) =>
687 Effect.forEach(sources, ({ volumeId, ...source }) =>
688 Effect.map(
689 volumeId === undefined
690 ? Effect.promise(() => readDirectoryVolumeId(source.dir))
691 : Effect.succeed(volumeId),
692 (resolved): ScannedDir => ({
693 ...source,
694 files: source.files?.map((file) => ({ ...file, malformedRecords: 0 })) ?? null,
695 provider: reader.provider,
696 volumeId: resolved,
697 }),
698 ),
699 ),
700 ),
701 Effect.provideContext(readerContext),
702 ),
703 { concurrency: "unbounded" },
704 );
705
706 // Scan independent sources together, directories sequentially to bound open files; keep order, since the first copy decides a duplicate's bucket.
707 const [transcripts, scanDirs] = yield* Effect.all(
708 [Effect.forEach(dirs, (dir) => scanTranscriptDir(dir, windowStartMs)), scans],
709 { concurrency: "unbounded" },
710 );
711 const scanned: readonly ScannedDir[] = [...transcripts, ...pending, ...scanDirs.flat()];
712 return scanned;
713 });
714
715 const scanSummary = Effect.fn("UsageService.scanSummary")(function* (
716 input: UsageSummaryInput,
717 settings: ServerSettingsValue,
718 ) {
719 if (input.sinceDay > input.untilDay) {
720 return yield* new UsageReadError({
721 reason: "invalidWindow",
722 detail: `sinceDay '${input.sinceDay}' is after untilDay '${input.untilDay}'`,
723 });
724 }
725
726 let hourlyWindow: { readonly sinceTimeMs: number; readonly untilTimeMs: number } | null = null;
727 if (input.resolution === "hour") {
728 const sinceTime =
729 input.sinceTime === undefined ? Option.none() : DateTime.make(input.sinceTime);
730 const untilTime =
731 input.untilTime === undefined ? Option.none() : DateTime.make(input.untilTime);
732 if (Option.isNone(sinceTime) || Option.isNone(untilTime)) {
733 return yield* new UsageReadError({
734 reason: "invalidWindow",
735 detail: "Hourly usage requires valid sinceTime and untilTime instants",
736 });
737 }
738 const sinceTimeMs = DateTime.toEpochMillis(sinceTime.value);
739 const untilTimeMs = DateTime.toEpochMillis(untilTime.value);
740 const durationMs = untilTimeMs - sinceTimeMs;
741 if (durationMs <= 0 || durationMs > MAX_HOURLY_WINDOW_MS) {
742 return yield* new UsageReadError({
743 reason: "invalidWindow",
744 detail: "Hourly usage window must be greater than zero and at most 24 hours",
745 });
746 }
747 hourlyWindow = { sinceTimeMs, untilTimeMs };
748 }
749
750 const startedAtMs = yield* Clock.currentTimeMillis;
751 yield* ensureScanCacheLoaded;
752
753 const windowStart = DateTime.make(`${input.sinceDay}T00:00:00Z`);
754 if (Option.isNone(windowStart)) {
755 return yield* new UsageReadError({
756 reason: "invalidWindow",
757 detail: `sinceDay '${input.sinceDay}' is not a valid date`,
758 });
759 }
760 const windowStartMs =
761 (hourlyWindow?.sinceTimeMs ?? DateTime.toEpochMillis(windowStart.value)) - MTIME_SLACK_MS;
762
763 const retentionCutoffMs = startedAtMs - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000;
764
765 const [, scannedDirs] = yield* Effect.all(
766 [
767 ensureRates(false),
768 collectDirs(windowStartMs, settings, retentionCutoffMs, input.awaitRefresh === true),
769 ],
770 { concurrency: 2 },
771 );
772
773 const aggregator = new UsageAggregator({
774 timeZone: input.timeZone,
775 sinceDay: input.sinceDay,
776 untilDay: input.untilDay,
777 resolution: input.resolution ?? "day",
778 ...hourlyWindow,
779 rates,
780 priceOverrides: createOverrideRateTable(settings.usagePriceOverrides),
781 modelAliases: resolveModelAliases(settings.usageModelAliases),
782 ...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
783 });
784
785 const sources: UsageSource[] = [];
786
787 // Deleted transcripts' saved usage still aggregates and deduplicates normally.
788 const retainedSinceMs = Math.max(windowStartMs, retentionCutoffMs);
789 const filesByDir = scannedDirs.map(({ provider, dir, files }) => {
790 const retainedFiles = [...(files ?? [])];
791 const livePaths = new Set(retainedFiles.map((file) => file.path));
792 for (const [filePath, entry] of fileCache) {
793 if (
794 entry.provider !== provider ||
795 entry.mtimeMs < retainedSinceMs ||
796 livePaths.has(filePath) ||
797 !isWithinDirectory(filePath, dir)
798 )
799 continue;
800 retainedFiles.push({
801 path: filePath,
802 records: [...entry.records, ...entry.tailRecords],
803 malformedRecords: entry.malformedRecords,
804 });
805 }
806 return retainedFiles;
807 });
808 const windowEndMs =
809 hourlyWindow?.untilTimeMs ??
810 Date.parse(`${input.untilDay}T00:00:00Z`) + 86400000 + MTIME_SLACK_MS;
811 let resolvedAny = false;
812 for (const { reader } of transcriptReaders) {
813 if (reader.resolveServiceTiers === undefined) continue;
814 const pending = new Set<UsageRecord>();
815 for (const [index, files] of filesByDir.entries()) {
816 if (scannedDirs[index]?.provider !== reader.provider) continue;
817 for (const file of files) {
818 for (const raw of file.records) {
819 const record = correctedRecord(raw);
820 if (
821 record.provider === reader.provider &&
822 record.unresolvedServiceTierTurnId !== undefined &&
823 record.timestampMs >= windowStartMs &&
824 record.timestampMs < windowEndMs
825 ) {
826 pending.add(record);
827 }
828 }
829 }
830 }
831 if (pending.size === 0) continue;
832 const resolved = yield* reader
833 .resolveServiceTiers([...pending])
834 .pipe(Effect.provideContext(readerContext));
835 for (const [record, speed] of resolved) {
836 const { unresolvedServiceTierTurnId: _turnId, ...rest } = record;
837 resolvedRecords.set(record, { ...rest, speed });
838 resolvedAny = true;
839 }
840 }
841 if (resolvedAny) {
842 for (const [filePath, entry] of fileCache) {
843 const records = correctedBatch(entry.records);
844 const tailRecords = correctedBatch(entry.tailRecords);
845 if (records === entry.records && tailRecords === entry.tailRecords) continue;
846 // Update the current entry by identity; a slow resolver cannot restore an older file.
847 fileCache.set(filePath, { ...entry, records, tailRecords });
848 cacheDirty = true;
849 }
850 }
851 const crossFileSessions = sharedSessions(filesByDir.flat());
852
853 for (const [
854 index,
855 { provider, dir, volumeId, files, status, message, refreshing, hostId: sourceHostId },
856 ] of scannedDirs.entries()) {
857 let scannedFiles = 0;
858 let skippedFiles = 0;
859 let malformedRecords = 0;
860 // Distinct per directory. Buckets carry per-cell session counts, but a
861 // session spans days and models, so clients total this figure instead.
862 const sessionIds = new Set<string>();
863
864 for (const file of filesByDir[index] ?? []) {
865 malformedRecords += file.malformedRecords;
866 if (file.records.length === 0) {
867 skippedFiles += 1;
868 continue;
869 }
870 scannedFiles += 1;
871 const eventOccurrences = new Map<string, number>();
872 for (const rawRecord of file.records) {
873 const record = correctedRecord(rawRecord);
874 let usageRecord = record;
875 if (
876 sharedSessionProviders.has(record.provider) &&
877 crossFileSessions.has(record.sessionId)
878 ) {
879 // Dedupe moved copies but retain repeated equal events within a file, including second-precision timestamps.
880 const key = encodeUsageRecordKey([
881 record.provider,
882 record.sessionId,
883 record.timestampMs,
884 record.model,
885 record.totals,
886 ]);
887 const occurrence = (eventOccurrences.get(key) ?? 0) + 1;
888 eventOccurrences.set(key, occurrence);
889 usageRecord = { ...record, dedupeKey: key + ":" + occurrence };
890 }
891 if (aggregator.add(usageRecord, dir) && record.sessionId.length > 0) {
892 sessionIds.add(record.sessionId);
893 }
894 }
895 }
896
897 const sourceMessage =
898 message ?? (files === null ? "No transcript directory on this environment." : null);
899 sources.push({
900 fingerprint: { hostId: sourceHostId ?? hostId, provider, resolvedHomePath: dir, volumeId },
901 status:
902 files === null && scannedFiles === 0
903 ? "missing"
904 : malformedRecords > 0
905 ? status === undefined || status === "ok"
906 ? "partial"
907 : status
908 : (status ?? "ok"),
909 scannedFiles,
910 skippedFiles,
911 malformedRecords,
912 distinctSessions: sessionIds.size,
913 message:
914 malformedRecords > 0
915 ? [sourceMessage, formatMalformedUsageWarning(malformedRecords)]
916 .filter(Boolean)
917 .join(" ")
918 : sourceMessage,
919 ...(refreshing ? { refreshing } : {}),
920 });
921 }
922
923 const pruned = pruneScanCache(fileCache, retentionCutoffMs);
924 if (pruned > 0) cacheDirty = true;
925
926 const aggregated = aggregator.finish();
927 const readAt = yield* DateTime.now;
928 const finishedAtMs = yield* Clock.currentTimeMillis;
929
930 return {
931 contractVersion: USAGE_CONTRACT_VERSION,
932 readAt: DateTime.formatIso(readAt),
933 timeZone: input.timeZone,
934 sinceDay: input.sinceDay,
935 untilDay: input.untilDay,
936 buckets: aggregated.buckets,
937 sources,
938 pricing: pricing(),
939 scanDurationMs: Math.max(0, finishedAtMs - startedAtMs),
940 ...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
941 } satisfies UsageSummary;
942 });
943
944 const inflightScans = new Map<string, Deferred.Deferred<UsageSummary, UsageReadError>>();
945
946 const scanKey = (input: UsageSummaryInput, settings: ServerSettingsValue): string =>
947 JSON.stringify([
948 input.timeZone,
949 input.sinceDay,
950 input.untilDay,
951 input.resolution ?? "day",
952 input.sinceTime ?? null,
953 input.untilTime ?? null,
954 settings,
955 input.awaitRefresh === true,
956 input.modelFilter ?? null,
957 ]);
958
959 const readSummary = Effect.fn("UsageService.readSummary")(function* (
960 requested: UsageSummaryInput,
961 ) {
962 const { modelFilter: requestedFilter, ...unfiltered } = requested;
963 const modelFilter = canonicalModelFilter(requestedFilter);
964 const input = modelFilter === undefined ? unfiltered : { ...unfiltered, modelFilter };
965 const settings = yield* readSettings;
966 const key = scanKey(input, settings);
967 const deferred = yield* Effect.uninterruptible(
968 Effect.gen(function* () {
969 const existing = inflightScans.get(key);
970 if (existing !== undefined) return existing;
971
972 // Register and fork atomically so cancellation cannot leave a Deferred without a scan.
973 const created = Deferred.makeUnsafe<UsageSummary, UsageReadError>();
974 inflightScans.set(key, created);
975 // Detach so caller departure cannot cancel shared scans; finished scans warm the cache.
976 // Register writes before releasing waiters, but start writing after delivering their summary.
977 yield* scanSummary(input, settings).pipe(
978 Effect.onExit((exit) =>
979 Effect.sync(() => inflightScans.delete(key)).pipe(
980 Effect.andThen(Exit.isSuccess(exit) ? schedulePersist : Effect.void),
981 Effect.andThen(Deferred.done(created, exit)),
982 ),
983 ),
984 Effect.forkDetach,
985 );
986 return created;
987 }),
988 );
989 return yield* Deferred.await(deferred);
990 });
991
992 return { readSummary, refreshRates, awaitPersisted } as const;
993});
994
995export const layer = Layer.effect(UsageService, make);