@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 468 lines 16.5 KB
Raw
1 // @effect-diagnostics globalDate:off
2 import type {
3 UsageBucket,
4 UsageCategoryCost,
5 UsageDay,
6 UsageModelFilter,
7 UsageModelSelector,
8 UsageResolution,
9 UsageTokenTotals,
10 } from "@t3tools/contracts";
11
12 import { EMPTY_TOTALS, type UsageRecord } from "@t3tools/provider-core/server/usage";
13 import { cacheSavingsUsd, lookupRate, priceUsage, type RateTable } from "./usagePricing.ts";
14
15 // en-CA gives ISO-ordered parts in the requested zone; Date getters are host-local.
16 function makeDayFormatter(timeZone: string): (timestampMs: number) => string {
17 let format: Intl.DateTimeFormat;
18 try {
19 format = new Intl.DateTimeFormat("en-CA", {
20 timeZone,
21 year: "numeric",
22 month: "2-digit",
23 day: "2-digit",
24 });
25 } catch {
26 format = new Intl.DateTimeFormat("en-CA", {
27 timeZone: "UTC",
28 year: "numeric",
29 month: "2-digit",
30 day: "2-digit",
31 });
32 }
33 // Cache quarter-hour slots to avoid per-record Intl calls; fixed-offset midnight can split slots and needs exact formatting.
34 const days = new Map<number, string | null>();
35 return (timestampMs) => {
36 const slot = Math.floor(timestampMs / QUARTER_HOUR_MS);
37 let day = days.get(slot);
38 if (day === undefined) {
39 const first = format.format(new Date(slot * QUARTER_HOUR_MS));
40 const last = format.format(new Date((slot + 1) * QUARTER_HOUR_MS - 1));
41 day = first === last ? first : null;
42 days.set(slot, day);
43 }
44 return day ?? format.format(new Date(timestampMs));
45 };
46 }
47
48 const QUARTER_HOUR_MS = 15 * 60 * 1000;
49 const HOUR_MS = 60 * 60 * 1000;
50
51 interface MutableBucket {
52 totals: { -readonly [K in keyof UsageTokenTotals]: number };
53 costUsd: number;
54 cacheSavingsUsd: number;
55 categoryCostUsd: UsageCategoryCost | null;
56 fastCostUsd: number;
57 ultrafastCostUsd: number;
58 speedPremiumUsd: number;
59 records: number;
60 unpricedRecords: number;
61 unpricedTokens: number;
62 providerReportedRecords: number;
63 sessions: Set<string>;
64 }
65
66 export interface AggregateOptions {
67 readonly timeZone: string;
68 readonly sinceDay: string;
69 readonly untilDay: string;
70 readonly rates: RateTable;
71 readonly priceOverrides?: RateTable;
72 readonly modelAliases?: ReadonlyMap<string, string>;
73 readonly rateModel?: (provider: UsageRecord["provider"], model: string) => string | undefined;
74 readonly modelFilter?: UsageModelFilter;
75 readonly resolution?: UsageResolution;
76 readonly sinceTimeMs?: number;
77 readonly untilTimeMs?: number;
78 }
79
80 export function resolveModelAliases(
81 aliases: Readonly<Record<string, string>>,
82 ): ReadonlyMap<string, string> {
83 const models = Object.keys(aliases);
84 const memo = new Map<string, string | null>();
85 for (const model of models) {
86 if (memo.has(model)) continue;
87 const path: string[] = [];
88 let target = model;
89 while (Object.hasOwn(aliases, target) && !memo.has(target)) {
90 path.push(target);
91 // Null marks both the active walk and paths that end in a cycle.
92 memo.set(target, null);
93 target = aliases[target]!;
94 }
95 const terminal = Object.hasOwn(aliases, target) ? (memo.get(target) ?? null) : target;
96 for (const alias of path) memo.set(alias, terminal);
97 }
98
99 const resolved = new Map<string, string>();
100 for (const model of models) {
101 const target = memo.get(model);
102 if (target !== null && target !== undefined) resolved.set(model, target);
103 }
104 return resolved;
105 }
106
107 /** Matches original IDs, so an alias cannot pull excluded usage into a kept model. */
108 function keepsUsageRecord(filter: UsageModelFilter | undefined, record: UsageRecord): boolean {
109 if (filter === undefined) return true;
110 const model = record.model.trim();
111 const matches = (selector: UsageModelSelector) =>
112 selector.model === model &&
113 (selector.provider === undefined || selector.provider === record.provider);
114 return (filter.include?.some(matches) ?? true) && !(filter.exclude?.some(matches) ?? false);
115 }
116
117 const selectorKey = (selector: UsageModelSelector) =>
118 JSON.stringify([selector.provider ?? null, selector.model]);
119
120 const canonicalSelectors = (selectors: readonly UsageModelSelector[]) =>
121 [...new Map(selectors.map((selector) => [selectorKey(selector), selector]))]
122 // Code-unit order, so servers in different locales echo the same form.
123 .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
124 .map(([, selector]) => selector);
125
126 /** Equal filters get one form, so they share scans and clients can compare echoed filters. */
127 export function canonicalModelFilter(
128 filter: UsageModelFilter | undefined,
129 ): UsageModelFilter | undefined {
130 if (filter === undefined) return undefined;
131 const exclude = filter.exclude?.length ? canonicalSelectors(filter.exclude) : undefined;
132 if (filter.include === undefined && exclude === undefined) return undefined;
133 return {
134 ...(filter.include === undefined ? {} : { include: canonicalSelectors(filter.include) }),
135 ...(exclude === undefined ? {} : { exclude }),
136 };
137 }
138
139 export interface AggregateResult {
140 readonly buckets: readonly UsageBucket[];
141 readonly duplicatesDropped: number;
142 readonly outOfWindow: number;
143 }
144
145 /**
146 * Partial copies share a billed message's key: keep each token channel's maximum and the larger
147 * reported cost, and the first copy's time, model, session and speed so it stays in its bucket.
148 */
149 export function mergeUsageCopies(held: UsageRecord, copy: UsageRecord): UsageRecord {
150 const a = held.totals;
151 const b = copy.totals;
152 const reportedCostUsd =
153 held.reportedCostUsd === null || copy.reportedCostUsd === null
154 ? (held.reportedCostUsd ?? copy.reportedCostUsd)
155 : Math.max(held.reportedCostUsd, copy.reportedCostUsd);
156 if (
157 b.uncachedInputTokens <= a.uncachedInputTokens &&
158 b.cachedInputTokens <= a.cachedInputTokens &&
159 b.cacheCreationTokens <= a.cacheCreationTokens &&
160 b.outputTokens <= a.outputTokens &&
161 b.reasoningTokens <= a.reasoningTokens &&
162 (copy.cacheCreation1hTokens ?? 0) <= (held.cacheCreation1hTokens ?? 0) &&
163 reportedCostUsd === held.reportedCostUsd
164 ) {
165 return held;
166 }
167 const cacheCreation1hTokens = Math.max(
168 held.cacheCreation1hTokens ?? 0,
169 copy.cacheCreation1hTokens ?? 0,
170 );
171 return {
172 ...held,
173 ...(cacheCreation1hTokens > 0 ? { cacheCreation1hTokens } : {}),
174 totals: {
175 uncachedInputTokens: Math.max(a.uncachedInputTokens, b.uncachedInputTokens),
176 cachedInputTokens: Math.max(a.cachedInputTokens, b.cachedInputTokens),
177 cacheCreationTokens: Math.max(a.cacheCreationTokens, b.cacheCreationTokens),
178 outputTokens: Math.max(a.outputTokens, b.outputTokens),
179 reasoningTokens: Math.max(a.reasoningTokens, b.reasoningTokens),
180 },
181 reportedCostUsd,
182 };
183 }
184
185 /**
186 * Grok reports each turn once, complete, so real copies are equal. A larger one is a deleted
187 * transcript's pre-v17 maximum over turns that shared a prompt id, whichever source it came from.
188 */
189 function smallestGrokCopy(held: UsageRecord, copy: UsageRecord): UsageRecord {
190 const a = held.totals;
191 const b = copy.totals;
192 const reportedCostUsd =
193 held.reportedCostUsd === null || copy.reportedCostUsd === null
194 ? (held.reportedCostUsd ?? copy.reportedCostUsd)
195 : Math.min(held.reportedCostUsd, copy.reportedCostUsd);
196 return {
197 ...held,
198 totals: {
199 uncachedInputTokens: Math.min(a.uncachedInputTokens, b.uncachedInputTokens),
200 cachedInputTokens: Math.min(a.cachedInputTokens, b.cachedInputTokens),
201 cacheCreationTokens: Math.min(a.cacheCreationTokens, b.cacheCreationTokens),
202 outputTokens: Math.min(a.outputTokens, b.outputTokens),
203 reasoningTokens: Math.min(a.reasoningTokens, b.reasoningTokens),
204 },
205 reportedCostUsd,
206 };
207 }
208
209 interface Contribution {
210 record: UsageRecord;
211 /** Null when the first copy fell outside the window. */
212 readonly bucket: MutableBucket | null;
213 }
214
215 /** Deduplicates across the whole scan; Claude copies records into resumed/forked transcripts. */
216 export class UsageAggregator {
217 readonly #buckets = new Map<string, MutableBucket>();
218 readonly #seen = new Map<string, Contribution>();
219 readonly #toDay: (timestampMs: number) => string;
220 readonly #hourlyWindow: { readonly sinceTimeMs: number; readonly untilTimeMs: number } | null;
221 readonly #options: AggregateOptions;
222 #lastBucket: {
223 readonly day: string;
224 readonly hourIndex: number;
225 readonly provider: string;
226 readonly model: string;
227 readonly source: string;
228 readonly bucket: MutableBucket;
229 } | null = null;
230 #duplicatesDropped = 0;
231 #outOfWindow = 0;
232
233 constructor(options: AggregateOptions) {
234 this.#options = options;
235 this.#toDay = makeDayFormatter(options.timeZone);
236 if (options.resolution === "hour") {
237 if (options.sinceTimeMs === undefined || options.untilTimeMs === undefined) {
238 throw new Error("Hourly usage aggregation requires exact time bounds");
239 }
240 this.#hourlyWindow = {
241 sinceTimeMs: options.sinceTimeMs,
242 untilTimeMs: options.untilTimeMs,
243 };
244 } else {
245 this.#hourlyWindow = null;
246 }
247 }
248
249 add(input: UsageRecord, sourcePath?: string): boolean {
250 if (!keepsUsageRecord(this.#options.modelFilter, input)) return false;
251 const record = this.#mapModel(input);
252 if (record.dedupeKey !== null) {
253 const held = this.#seen.get(record.dedupeKey);
254 if (held !== undefined) {
255 this.#duplicatesDropped += 1;
256 if (held.bucket !== null) {
257 held.record =
258 record.provider === "grok"
259 ? smallestGrokCopy(held.record, record)
260 : mergeUsageCopies(held.record, record);
261 }
262 return false;
263 }
264 }
265
266 const bucket = this.#placeInWindow(record, sourcePath ?? "");
267 if (record.dedupeKey !== null) this.#seen.set(record.dedupeKey, { record, bucket });
268 if (bucket === null) {
269 this.#outOfWindow += 1;
270 return false;
271 }
272 // Keyed usage is counted in finish(), once all its copies are merged.
273 if (record.dedupeKey === null) this.#accumulate(bucket, record);
274 if (record.sessionId.length > 0) bucket.sessions.add(record.sessionId);
275 return true;
276 }
277
278 #placeInWindow(record: UsageRecord, source: string): MutableBucket | null {
279 if (
280 this.#hourlyWindow !== null &&
281 (record.timestampMs < this.#hourlyWindow.sinceTimeMs ||
282 record.timestampMs >= this.#hourlyWindow.untilTimeMs)
283 ) {
284 return null;
285 }
286
287 const day = this.#toDay(record.timestampMs);
288 if (
289 this.#hourlyWindow === null &&
290 (day < this.#options.sinceDay || day > this.#options.untilDay)
291 ) {
292 return null;
293 }
294
295 const hourIndex =
296 this.#hourlyWindow === null
297 ? -1
298 : Math.floor((record.timestampMs - this.#hourlyWindow.sinceTimeMs) / HOUR_MS);
299 return this.#bucketFor(day, hourIndex, record.provider, record.model, source);
300 }
301
302 #accumulate(bucket: MutableBucket, record: UsageRecord): void {
303 const priced = priceUsage(this.#options.rates, record, this.#options.priceOverrides);
304
305 const totals = bucket.totals;
306 totals.uncachedInputTokens += record.totals.uncachedInputTokens;
307 totals.cachedInputTokens += record.totals.cachedInputTokens;
308 totals.cacheCreationTokens += record.totals.cacheCreationTokens;
309 totals.outputTokens += record.totals.outputTokens;
310 totals.reasoningTokens += record.totals.reasoningTokens;
311 bucket.costUsd += priced.costUsd;
312 if (priced.categoryCostUsd !== null) {
313 const sum = bucket.categoryCostUsd;
314 const add = priced.categoryCostUsd;
315 bucket.categoryCostUsd =
316 sum === null
317 ? add
318 : {
319 input: sum.input + add.input,
320 cacheRead: sum.cacheRead + add.cacheRead,
321 cacheWrite: sum.cacheWrite + add.cacheWrite,
322 output: sum.output + add.output,
323 };
324 }
325 if (record.speed === "fast") bucket.fastCostUsd += priced.costUsd;
326 if (record.speed === "ultrafast") bucket.ultrafastCostUsd += priced.costUsd;
327 bucket.speedPremiumUsd += priced.speedPremiumUsd;
328 bucket.cacheSavingsUsd += cacheSavingsUsd(
329 this.#options.rates,
330 record,
331 this.#options.priceOverrides,
332 );
333 bucket.records += 1;
334 if (priced.costSource === "unpriced") {
335 bucket.unpricedRecords += 1;
336 bucket.unpricedTokens +=
337 record.totals.uncachedInputTokens +
338 record.totals.cachedInputTokens +
339 record.totals.cacheCreationTokens +
340 record.totals.outputTokens;
341 }
342 if (priced.costSource === "providerReported") bucket.providerReportedRecords += 1;
343 }
344
345 // Aliases use the target's rate. Only an unpriced target goes through the provider's own rate naming.
346 #mapModel(record: UsageRecord): UsageRecord {
347 const model = this.#options.modelAliases?.get(record.model);
348 if (model === undefined) return record;
349 const { rateModel: _rateModel, ...rest } = record;
350 const rateModel =
351 lookupRate(this.#options.rates, model) === null
352 ? this.#options.rateModel?.(record.provider, model)
353 : undefined;
354 return rateModel === undefined ? { ...rest, model } : { ...rest, model, rateModel };
355 }
356
357 // Time-ordered records usually reuse the previous bucket; avoid rebuilding its key.
358 #bucketFor(
359 day: string,
360 hourIndex: number,
361 provider: string,
362 model: string,
363 source: string,
364 ): MutableBucket {
365 const last = this.#lastBucket;
366 if (
367 last !== null &&
368 last.day === day &&
369 last.hourIndex === hourIndex &&
370 last.provider === provider &&
371 last.model === model &&
372 last.source === source
373 ) {
374 return last.bucket;
375 }
376 const window = this.#hourlyWindow;
377 const hourStart =
378 window === null ? "" : new Date(window.sinceTimeMs + hourIndex * HOUR_MS).toISOString();
379 const key = `${day}\u0000${hourStart}\u0000${provider}\u0000${model}\u0000${source}`;
380 let bucket = this.#buckets.get(key);
381 if (bucket === undefined) {
382 bucket = {
383 totals: { ...EMPTY_TOTALS },
384 costUsd: 0,
385 cacheSavingsUsd: 0,
386 categoryCostUsd: null,
387 fastCostUsd: 0,
388 ultrafastCostUsd: 0,
389 speedPremiumUsd: 0,
390 records: 0,
391 unpricedRecords: 0,
392 unpricedTokens: 0,
393 providerReportedRecords: 0,
394 sessions: new Set<string>(),
395 };
396 this.#buckets.set(key, bucket);
397 }
398 this.#lastBucket = { day, hourIndex, provider, model, source, bucket };
399 return bucket;
400 }
401
402 finish(): AggregateResult {
403 for (const { record, bucket } of this.#seen.values()) {
404 if (bucket !== null) this.#accumulate(bucket, record);
405 }
406 this.#seen.clear();
407 const buckets: UsageBucket[] = [];
408 for (const [key, bucket] of this.#buckets) {
409 const [day = "", hourStart = "", provider = "", model = "", sourcePath = ""] =
410 key.split("\u0000");
411 const category = bucket.categoryCostUsd;
412 const fastCostUsd = roundUsd(bucket.fastCostUsd);
413 const ultrafastCostUsd = roundUsd(bucket.ultrafastCostUsd);
414 const speedPremiumUsd = roundUsd(bucket.speedPremiumUsd);
415 buckets.push({
416 day: day as UsageDay,
417 ...(hourStart === "" ? {} : { hourStart }),
418 provider: provider as UsageBucket["provider"],
419 model,
420 ...(sourcePath === "" ? {} : { sourcePath }),
421 totals: { ...bucket.totals },
422 costUsd: bucket.costUsd,
423 cacheSavingsUsd: bucket.cacheSavingsUsd,
424 ...(category === null
425 ? {}
426 : {
427 categoryCostUsd: {
428 input: roundUsd(category.input),
429 cacheRead: roundUsd(category.cacheRead),
430 cacheWrite: roundUsd(category.cacheWrite),
431 output: roundUsd(category.output),
432 },
433 }),
434 ...(fastCostUsd === 0 ? {} : { fastCostUsd }),
435 ...(ultrafastCostUsd === 0 ? {} : { ultrafastCostUsd }),
436 ...(speedPremiumUsd === 0 ? {} : { speedPremiumUsd }),
437 costSource: resolveCostSource(bucket),
438 records: bucket.records,
439 unpricedRecords: bucket.unpricedRecords,
440 unpricedTokens: bucket.unpricedTokens,
441 sessions: bucket.sessions.size,
442 });
443 }
444 buckets.sort(
445 (a, b) =>
446 a.day.localeCompare(b.day) ||
447 (a.hourStart ?? "").localeCompare(b.hourStart ?? "") ||
448 a.provider.localeCompare(b.provider) ||
449 a.model.localeCompare(b.model),
450 );
451
452 return {
453 buckets,
454 duplicatesDropped: this.#duplicatesDropped,
455 outOfWindow: this.#outOfWindow,
456 };
457 }
458 }
459
460 function roundUsd(value: number): number {
461 return Math.round(value * 1e6) / 1e6;
462 }
463
464 function resolveCostSource(bucket: MutableBucket): UsageBucket["costSource"] {
465 if (bucket.unpricedRecords === bucket.records) return "unpriced";
466 if (bucket.providerReportedRecords === bucket.records) return "providerReported";
467 return "modelPriced";
468 }