Skip to content
Source
Sign inSign up
pingdotgg/t3code
Open History to see the last commit

UsageService.ts

988 lines37.3 KB

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;
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);
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;
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 unread = failedPaths + read.filter((file) => file.failed).length;
642 yield* Effect.annotateCurrentSpan({
643 "usage.files": files.length,
644 "usage.files_parsed": read.filter((file) => file.update !== undefined).length,
645 });
646 return {
647 provider,
648 dir,
649 volumeId,
650 files: parsedFiles,
651 ...(unread > 0
652 ? {
653 status: "partial",
654 message: `${unread} transcript path(s) could not be read; usage may be incomplete.`,
655 }
656 : {}),
657 } satisfies ScannedDir;
658 });
659​
660 const collectDirs = Effect.fn("UsageService.collectDirs")(function* (
661 windowStartMs: number,
662 settings: ServerSettingsValue,
663 retentionCutoffMs: number,
664 awaitRefresh: boolean,
665 ) {
666 const { dirs, pending } = yield* resolveTranscriptDirs(
667 settings,
668 retentionCutoffMs,
669 awaitRefresh,
670 ).pipe(Effect.provideContext(readerContext));
671​
672 const scans = Effect.forEach(
673 scanReaders,
674 ({ driver, reader }) =>
675 usageInstances(driver, settings).pipe(
676 Effect.flatMap((instances) =>
677 reader.scan({ instances, settings, windowStartMs, retentionCutoffMs, awaitRefresh }),
678 ),
679 Effect.flatMap((sources) =>
680 Effect.forEach(sources, ({ volumeId, ...source }) =>
681 Effect.map(
682 volumeId === undefined
683 ? Effect.promise(() => readDirectoryVolumeId(source.dir))
684 : Effect.succeed(volumeId),
685 (resolved): ScannedDir => ({
686 ...source,
687 files: source.files?.map((file) => ({ ...file, malformedRecords: 0 })) ?? null,
688 provider: reader.provider,
689 volumeId: resolved,
690 }),
691 ),
692 ),
693 ),
694 Effect.provideContext(readerContext),
695 ),
696 { concurrency: "unbounded" },
697 );
698​
699 // Scan independent sources together, directories sequentially to bound open files; keep order, since the first copy decides a duplicate's bucket.
700 const [transcripts, scanDirs] = yield* Effect.all(
701 [Effect.forEach(dirs, (dir) => scanTranscriptDir(dir, windowStartMs)), scans],
702 { concurrency: "unbounded" },
703 );
704 const scanned: readonly ScannedDir[] = [...transcripts, ...pending, ...scanDirs.flat()];
705 return scanned;
706 });
707​
708 const scanSummary = Effect.fn("UsageService.scanSummary")(function* (
709 input: UsageSummaryInput,
710 settings: ServerSettingsValue,
711 ) {
712 if (input.sinceDay > input.untilDay) {
713 return yield* new UsageReadError({
714 reason: "invalidWindow",
715 detail: `sinceDay '${input.sinceDay}' is after untilDay '${input.untilDay}'`,
716 });
717 }
718​
719 let hourlyWindow: { readonly sinceTimeMs: number; readonly untilTimeMs: number } | null = null;
720 if (input.resolution === "hour") {
721 const sinceTime =
722 input.sinceTime === undefined ? Option.none() : DateTime.make(input.sinceTime);
723 const untilTime =
724 input.untilTime === undefined ? Option.none() : DateTime.make(input.untilTime);
725 if (Option.isNone(sinceTime) || Option.isNone(untilTime)) {
726 return yield* new UsageReadError({
727 reason: "invalidWindow",
728 detail: "Hourly usage requires valid sinceTime and untilTime instants",
729 });
730 }
731 const sinceTimeMs = DateTime.toEpochMillis(sinceTime.value);
732 const untilTimeMs = DateTime.toEpochMillis(untilTime.value);
733 const durationMs = untilTimeMs - sinceTimeMs;
734 if (durationMs <= 0 || durationMs > MAX_HOURLY_WINDOW_MS) {
735 return yield* new UsageReadError({
736 reason: "invalidWindow",
737 detail: "Hourly usage window must be greater than zero and at most 24 hours",
738 });
739 }
740 hourlyWindow = { sinceTimeMs, untilTimeMs };
741 }
742​
743 const startedAtMs = yield* Clock.currentTimeMillis;
744 yield* ensureScanCacheLoaded;
745​
746 const windowStart = DateTime.make(`${input.sinceDay}T00:00:00Z`);
747 if (Option.isNone(windowStart)) {
748 return yield* new UsageReadError({
749 reason: "invalidWindow",
750 detail: `sinceDay '${input.sinceDay}' is not a valid date`,
751 });
752 }
753 const windowStartMs =
754 (hourlyWindow?.sinceTimeMs ?? DateTime.toEpochMillis(windowStart.value)) - MTIME_SLACK_MS;
755​
756 const retentionCutoffMs = startedAtMs - CACHE_RETENTION_DAYS * 24 * 60 * 60 * 1000;
757​
758 const [, scannedDirs] = yield* Effect.all(
759 [
760 ensureRates(false),
761 collectDirs(windowStartMs, settings, retentionCutoffMs, input.awaitRefresh === true),
762 ],
763 { concurrency: 2 },
764 );
765​
766 const aggregator = new UsageAggregator({
767 timeZone: input.timeZone,
768 sinceDay: input.sinceDay,
769 untilDay: input.untilDay,
770 resolution: input.resolution ?? "day",
771 ...hourlyWindow,
772 rates,
773 priceOverrides: createOverrideRateTable(settings.usagePriceOverrides),
774 modelAliases: resolveModelAliases(settings.usageModelAliases),
775 ...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
776 });
777​
778 const sources: UsageSource[] = [];
779​
780 // Deleted transcripts' saved usage still aggregates and deduplicates normally.
781 const retainedSinceMs = Math.max(windowStartMs, retentionCutoffMs);
782 const filesByDir = scannedDirs.map(({ provider, dir, files }) => {
783 const retainedFiles = [...(files ?? [])];
784 const livePaths = new Set(retainedFiles.map((file) => file.path));
785 for (const [filePath, entry] of fileCache) {
786 if (
787 entry.provider !== provider ||
788 entry.mtimeMs < retainedSinceMs ||
789 livePaths.has(filePath) ||
790 !isWithinDirectory(filePath, dir)
791 )
792 continue;
793 retainedFiles.push({
794 path: filePath,
795 records: [...entry.records, ...entry.tailRecords],
796 malformedRecords: entry.malformedRecords,
797 });
798 }
799 return retainedFiles;
800 });
801 const windowEndMs =
802 hourlyWindow?.untilTimeMs ??
803 Date.parse(`${input.untilDay}T00:00:00Z`) + 86400000 + MTIME_SLACK_MS;
804 let resolvedAny = false;
805 for (const { reader } of transcriptReaders) {
806 if (reader.resolveServiceTiers === undefined) continue;
807 const pending = new Set<UsageRecord>();
808 for (const [index, files] of filesByDir.entries()) {
809 if (scannedDirs[index]?.provider !== reader.provider) continue;
810 for (const file of files) {
811 for (const raw of file.records) {
812 const record = correctedRecord(raw);
813 if (
814 record.provider === reader.provider &&
815 record.unresolvedServiceTierTurnId !== undefined &&
816 record.timestampMs >= windowStartMs &&
817 record.timestampMs < windowEndMs
818 ) {
819 pending.add(record);
820 }
821 }
822 }
823 }
824 if (pending.size === 0) continue;
825 const resolved = yield* reader
826 .resolveServiceTiers([...pending])
827 .pipe(Effect.provideContext(readerContext));
828 for (const [record, speed] of resolved) {
829 const { unresolvedServiceTierTurnId: _turnId, ...rest } = record;
830 resolvedRecords.set(record, { ...rest, speed });
831 resolvedAny = true;
832 }
833 }
834 if (resolvedAny) {
835 for (const [filePath, entry] of fileCache) {
836 const records = correctedBatch(entry.records);
837 const tailRecords = correctedBatch(entry.tailRecords);
838 if (records === entry.records && tailRecords === entry.tailRecords) continue;
839 // Update the current entry by identity; a slow resolver cannot restore an older file.
840 fileCache.set(filePath, { ...entry, records, tailRecords });
841 cacheDirty = true;
842 }
843 }
844 const crossFileSessions = sharedSessions(filesByDir.flat());
845​
846 for (const [
847 index,
848 { provider, dir, volumeId, files, status, message, refreshing, hostId: sourceHostId },
849 ] of scannedDirs.entries()) {
850 let scannedFiles = 0;
851 let skippedFiles = 0;
852 let malformedRecords = 0;
853 // Distinct per directory. Buckets carry per-cell session counts, but a
854 // session spans days and models, so clients total this figure instead.
855 const sessionIds = new Set<string>();
856​
857 for (const file of filesByDir[index] ?? []) {
858 malformedRecords += file.malformedRecords;
859 if (file.records.length === 0) {
860 skippedFiles += 1;
861 continue;
862 }
863 scannedFiles += 1;
864 const eventOccurrences = new Map<string, number>();
865 for (const rawRecord of file.records) {
866 const record = correctedRecord(rawRecord);
867 let usageRecord = record;
868 if (
869 sharedSessionProviders.has(record.provider) &&
870 crossFileSessions.has(record.sessionId)
871 ) {
872 // Dedupe moved copies but retain repeated equal events within a file, including second-precision timestamps.
873 const key = encodeUsageRecordKey([
874 record.provider,
875 record.sessionId,
876 record.timestampMs,
877 record.model,
878 record.totals,
879 ]);
880 const occurrence = (eventOccurrences.get(key) ?? 0) + 1;
881 eventOccurrences.set(key, occurrence);
882 usageRecord = { ...record, dedupeKey: key + ":" + occurrence };
883 }
884 if (aggregator.add(usageRecord, dir) && record.sessionId.length > 0) {
885 sessionIds.add(record.sessionId);
886 }
887 }
888 }
889​
890 const sourceMessage =
891 message ?? (files === null ? "No transcript directory on this environment." : null);
892 sources.push({
893 fingerprint: { hostId: sourceHostId ?? hostId, provider, resolvedHomePath: dir, volumeId },
894 status:
895 files === null && scannedFiles === 0
896 ? "missing"
897 : malformedRecords > 0
898 ? status === undefined || status === "ok"
899 ? "partial"
900 : status
901 : (status ?? "ok"),
902 scannedFiles,
903 skippedFiles,
904 malformedRecords,
905 distinctSessions: sessionIds.size,
906 message:
907 malformedRecords > 0
908 ? [sourceMessage, formatMalformedUsageWarning(malformedRecords)]
909 .filter(Boolean)
910 .join(" ")
911 : sourceMessage,
912 ...(refreshing ? { refreshing } : {}),
913 });
914 }
915​
916 const pruned = pruneScanCache(fileCache, retentionCutoffMs);
917 if (pruned > 0) cacheDirty = true;
918​
919 const aggregated = aggregator.finish();
920 const readAt = yield* DateTime.now;
921 const finishedAtMs = yield* Clock.currentTimeMillis;
922​
923 return {
924 contractVersion: USAGE_CONTRACT_VERSION,
925 readAt: DateTime.formatIso(readAt),
926 timeZone: input.timeZone,
927 sinceDay: input.sinceDay,
928 untilDay: input.untilDay,
929 buckets: aggregated.buckets,
930 sources,
931 pricing: pricing(),
932 scanDurationMs: Math.max(0, finishedAtMs - startedAtMs),
933 ...(input.modelFilter === undefined ? {} : { modelFilter: input.modelFilter }),
934 } satisfies UsageSummary;
935 });
936​
937 const inflightScans = new Map<string, Deferred.Deferred<UsageSummary, UsageReadError>>();
938​
939 const scanKey = (input: UsageSummaryInput, settings: ServerSettingsValue): string =>
940 JSON.stringify([
941 input.timeZone,
942 input.sinceDay,
943 input.untilDay,
944 input.resolution ?? "day",
945 input.sinceTime ?? null,
946 input.untilTime ?? null,
947 settings,
948 input.awaitRefresh === true,
949 input.modelFilter ?? null,
950 ]);
951​
952 const readSummary = Effect.fn("UsageService.readSummary")(function* (
953 requested: UsageSummaryInput,
954 ) {
955 const { modelFilter: requestedFilter, ...unfiltered } = requested;
956 const modelFilter = canonicalModelFilter(requestedFilter);
957 const input = modelFilter === undefined ? unfiltered : { ...unfiltered, modelFilter };
958 const settings = yield* readSettings;
959 const key = scanKey(input, settings);
960 const deferred = yield* Effect.uninterruptible(
961 Effect.gen(function* () {
962 const existing = inflightScans.get(key);
963 if (existing !== undefined) return existing;
964​
965 // Register and fork atomically so cancellation cannot leave a Deferred without a scan.
966 const created = Deferred.makeUnsafe<UsageSummary, UsageReadError>();
967 inflightScans.set(key, created);
968 // Detach so caller departure cannot cancel shared scans; finished scans warm the cache.
969 // Register writes before releasing waiters, but start writing after delivering their summary.
970 yield* scanSummary(input, settings).pipe(
971 Effect.onExit((exit) =>
972 Effect.sync(() => inflightScans.delete(key)).pipe(
973 Effect.andThen(Exit.isSuccess(exit) ? schedulePersist : Effect.void),
974 Effect.andThen(Deferred.done(created, exit)),
975 ),
976 ),
977 Effect.forkDetach,
978 );
979 return created;
980 }),
981 );
982 return yield* Deferred.await(deferred);
983 });
984​
985 return { readSummary, refreshRates, awaitPersisted } as const;
986});
987​
988export const layer = Layer.effect(UsageService, make);