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
| 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 | } |