import {
USAGE_MERGE_COMPATIBLE_SINCE,
type EnvironmentId,
type UsageBucket,
type UsageProviderKind,
type UsageSource,
type UsageSourceFingerprint,
type UsageSummary,
type UsageTokenTotals,
} from "@t3tools/contracts";
export interface EnvironmentUsage {
readonly environmentId: EnvironmentId;
readonly label: string;
readonly summary: UsageSummary;
}
export interface ProviderTotals {
readonly provider: UsageProviderKind;
readonly costUsd: number;
readonly totalTokens: number;
readonly records: number;
readonly sessions: number;
readonly costShare: number;
readonly tokenShare: number;
}
export interface ModelTotals {
readonly model: string;
readonly provider: UsageProviderKind;
readonly costUsd: number;
readonly totalTokens: number;
readonly tokens: UsageTokenTotals;
readonly records: number;
readonly unpricedRecords: number;
readonly unpricedTokens: number;
readonly costShare: number;
readonly tokenShare: number;
}
/** When every record lacks rates, costUsd is unknown and must not be displayed as a dollar figure. */
export function isModelCostUnknown(model: ModelTotals): boolean {
return model.records > 0 && model.unpricedRecords >= model.records;
}
export interface DailyTotals {
readonly day: string;
readonly costUsd: number;
readonly totalTokens: number;
readonly byProvider: ReadonlyMap<UsageProviderKind, { costUsd: number; totalTokens: number }>;
}
export interface HourlyTotals {
readonly day: string;
readonly hourStart: string;
readonly costUsd: number;
readonly totalTokens: number;
readonly byProvider: ReadonlyMap<UsageProviderKind, { costUsd: number; totalTokens: number }>;
}
export interface CostQuality {
readonly providerReportedShare: number;
readonly modelPricedShare: number;
readonly unpricedShare: number;
readonly cacheSavingsUsd: number;
}
export interface CategoryCost {
readonly input: number;
readonly cacheRead: number;
readonly cacheWrite: number;
readonly output: number;
readonly unsplit: number;
}
export interface SpeedCost {
readonly standard: number;
readonly fast: number;
readonly ultrafast: number;
readonly premium: number;
}
export interface UsageContractMismatch {
readonly environmentId: EnvironmentId;
readonly direction: "serverBehind" | "clientBehind";
readonly contractVersion: number;
}
export interface MergedUsage {
readonly costUsd: number;
readonly uncachedInputTokens: number;
readonly cachedInputTokens: number;
readonly cacheCreationTokens: number;
readonly outputTokens: number;
readonly reasoningTokens: number;
readonly totalTokens: number;
readonly records: number;
readonly sessions: number;
readonly providers: readonly ProviderTotals[];
readonly models: readonly ModelTotals[];
readonly daily: readonly DailyTotals[];
readonly hourly: readonly HourlyTotals[];
readonly costQuality: CostQuality;
readonly categoryCost: CategoryCost;
readonly speedCost: SpeedCost;
readonly duplicateSources: readonly string[];
readonly contributingEnvironments: readonly EnvironmentId[];
readonly contractMismatches: readonly UsageContractMismatch[];
}
// volumeId distinguishes machines sharing a hostname and home path.
function fingerprintKey(fingerprint: UsageSourceFingerprint): string {
return [
fingerprint.hostId,
fingerprint.provider,
fingerprint.resolvedHomePath,
fingerprint.volumeId,
].join(" ");
}
function bucketsForSource(summary: UsageSummary, source: UsageSource): readonly UsageBucket[] {
const providerSources = summary.sources.filter(
(entry) => entry.fingerprint.provider === source.fingerprint.provider,
);
return summary.buckets.filter(
(bucket) =>
bucket.provider === source.fingerprint.provider &&
(bucket.sourcePath === source.fingerprint.resolvedHomePath ||
(bucket.sourcePath === undefined && providerSources.length === 1)),
);
}
function bucketKey(bucket: UsageBucket): string {
return JSON.stringify([bucket.day, bucket.hourStart ?? null, bucket.provider, bucket.model]);
}
function claimSources(environments: readonly EnvironmentUsage[]): {
readonly ownerByFingerprint: ReadonlyMap<string, EnvironmentId>;
readonly supplementalBucketsByEnvironment: ReadonlyMap<EnvironmentId, ReadonlySet<UsageBucket>>;
readonly sessionsByFingerprint: ReadonlyMap<string, number>;
readonly duplicates: readonly string[];
} {
const ownerByFingerprint = new Map<string, EnvironmentId>();
const ownerScanByFingerprint = new Map<
string,
{ environment: EnvironmentUsage; source: UsageSource }
>();
const seenBucketKeysByFingerprint = new Map<string, Set<string>>();
const supplementalBucketsByEnvironment = new Map<EnvironmentId, Set<UsageBucket>>();
const sessionsByFingerprint = new Map<string, number>();
const duplicates: string[] = [];
const ordered = [...environments].sort(
(a, b) =>
(Date.parse(b.summary.readAt) || 0) - (Date.parse(a.summary.readAt) || 0) ||
a.environmentId.localeCompare(b.environmentId),
);
for (const status of ["ok", "partial", "failed"] as const) {
for (const environment of ordered) {
for (const source of environment.summary.sources) {
if (source.status !== status) continue;
const key = fingerprintKey(source.fingerprint);
if (ownerByFingerprint.has(key)) {
duplicates.push(`${environment.label}: ${source.fingerprint.resolvedHomePath}`);
continue;
}
ownerByFingerprint.set(key, environment.environmentId);
ownerScanByFingerprint.set(key, { environment, source });
sessionsByFingerprint.set(key, source.distinctSessions);
}
}
}
// Keep cells unique to newer partial scans; aggregates cannot reconcile overlapping records without double-counting.
for (const environment of ordered) {
for (const source of environment.summary.sources) {
if (source.status !== "partial") continue;
const key = fingerprintKey(source.fingerprint);
const owner = ownerScanByFingerprint.get(key);
// A scan under another model filter counts different records, so its cells are not missing ones.
if (
owner?.source.status !== "ok" ||
Date.parse(environment.summary.readAt) <= Date.parse(owner.environment.summary.readAt) ||
JSON.stringify(environment.summary.modelFilter) !==
JSON.stringify(owner.environment.summary.modelFilter)
) {
continue;
}
let seen = seenBucketKeysByFingerprint.get(key);
if (seen === undefined) {
seen = new Set(bucketsForSource(owner.environment.summary, owner.source).map(bucketKey));
seenBucketKeysByFingerprint.set(key, seen);
}
const supplemental =
supplementalBucketsByEnvironment.get(environment.environmentId) ?? new Set<UsageBucket>();
let added = false;
for (const bucket of bucketsForSource(environment.summary, source)) {
const cell = bucketKey(bucket);
if (seen.has(cell)) continue;
seen.add(cell);
supplemental.add(bucket);
added = true;
}
if (!added) continue;
supplementalBucketsByEnvironment.set(environment.environmentId, supplemental);
sessionsByFingerprint.set(
key,
Math.max(sessionsByFingerprint.get(key) ?? 0, source.distinctSessions),
);
}
}
return {
ownerByFingerprint,
supplementalBucketsByEnvironment,
sessionsByFingerprint,
duplicates,
};
}
function ownedContribution(
environment: EnvironmentUsage,
ownerByFingerprint: ReadonlyMap<string, EnvironmentId>,
supplementalBuckets: ReadonlySet<UsageBucket>,
sessionsByFingerprint: ReadonlyMap<string, number>,
): {
readonly buckets: readonly UsageBucket[];
readonly sessionsByProvider: ReadonlyMap<UsageProviderKind, number>;
} {
const ownedProviders = new Set<UsageProviderKind>();
const ownedSources = new Set<string>();
const sessionsByProvider = new Map<UsageProviderKind, number>();
for (const source of environment.summary.sources) {
if (source.status === "missing") continue;
const key = fingerprintKey(source.fingerprint);
if (ownerByFingerprint.get(key) === environment.environmentId) {
const provider = source.fingerprint.provider;
ownedProviders.add(provider);
ownedSources.add(`${provider}\u0000${source.fingerprint.resolvedHomePath}`);
// Count distinct sessions per directory; bucket sums overcount sessions spanning days/models.
sessionsByProvider.set(
provider,
(sessionsByProvider.get(provider) ?? 0) +
(sessionsByFingerprint.get(key) ?? source.distinctSessions),
);
}
}
return {
buckets: environment.summary.buckets.filter(
(bucket) =>
supplementalBuckets.has(bucket) ||
(bucket.sourcePath === undefined
? ownedProviders.has(bucket.provider)
: ownedSources.has(`${bucket.provider}\u0000${bucket.sourcePath}`)),
),
sessionsByProvider,
};
}
function bucketTokens(bucket: UsageBucket): number {
// reasoningTokens is a subset of outputTokens and must not be added again.
return (
bucket.totals.uncachedInputTokens +
bucket.totals.cachedInputTokens +
bucket.totals.cacheCreationTokens +
bucket.totals.outputTokens
);
}
export function isCompatibleUsageContractVersion(version: number, expected: number): boolean {
return version >= USAGE_MERGE_COMPATIBLE_SINCE && version <= expected;
}
const EMPTY_MERGED: MergedUsage = {
costUsd: 0,
uncachedInputTokens: 0,
cachedInputTokens: 0,
cacheCreationTokens: 0,
outputTokens: 0,
reasoningTokens: 0,
totalTokens: 0,
records: 0,
sessions: 0,
providers: [],
models: [],
daily: [],
hourly: [],
costQuality: {
providerReportedShare: 0,
modelPricedShare: 0,
unpricedShare: 0,
cacheSavingsUsd: 0,
},
categoryCost: { input: 0, cacheRead: 0, cacheWrite: 0, output: 0, unsplit: 0 },
speedCost: { standard: 0, fast: 0, ultrafast: 0, premium: 0 },
duplicateSources: [],
contributingEnvironments: [],
contractMismatches: [],
};
export function mergeUsage(
environments: readonly EnvironmentUsage[],
expectedContractVersion: number,
): MergedUsage {
if (environments.length === 0) return EMPTY_MERGED;
const current: EnvironmentUsage[] = [];
const contractMismatches: UsageContractMismatch[] = [];
for (const environment of environments) {
if (
isCompatibleUsageContractVersion(environment.summary.contractVersion, expectedContractVersion)
) {
current.push(environment);
} else {
contractMismatches.push({
environmentId: environment.environmentId,
direction:
environment.summary.contractVersion < expectedContractVersion
? "serverBehind"
: "clientBehind",
contractVersion: environment.summary.contractVersion,
});
}
}
const {
ownerByFingerprint,
supplementalBucketsByEnvironment,
sessionsByFingerprint,
duplicates,
} = claimSources(current);
let costUsd = 0;
let uncachedInputTokens = 0;
let cachedInputTokens = 0;
let cacheCreationTokens = 0;
let outputTokens = 0;
let reasoningTokens = 0;
let records = 0;
let sessions = 0;
let cacheSavingsUsd = 0;
let providerReportedRecords = 0;
let unpricedRecords = 0;
const categoryCost = { input: 0, cacheRead: 0, cacheWrite: 0, output: 0 };
const speedCost = { fast: 0, ultrafast: 0, premium: 0 };
const providerAccumulator = new Map<
UsageProviderKind,
{ costUsd: number; totalTokens: number; records: number; sessions: number }
>();
const modelAccumulator = new Map<
string,
{
provider: UsageProviderKind;
costUsd: number;
totalTokens: number;
tokens: UsageTokenTotals;
records: number;
unpricedRecords: number;
unpricedTokens: number;
}
>();
const dailyAccumulator = new Map<
string,
{
costUsd: number;
totalTokens: number;
byProvider: Map<UsageProviderKind, { costUsd: number; totalTokens: number }>;
}
>();
const hourlyAccumulator = new Map<
string,
{
day: string;
hourStart: string;
costUsd: number;
totalTokens: number;
byProvider: Map<UsageProviderKind, { costUsd: number; totalTokens: number }>;
}
>();
const contributingEnvironments: EnvironmentId[] = [];
for (const environment of current) {
const { buckets, sessionsByProvider } = ownedContribution(
environment,
ownerByFingerprint,
supplementalBucketsByEnvironment.get(environment.environmentId) ?? new Set(),
sessionsByFingerprint,
);
if (buckets.length > 0) contributingEnvironments.push(environment.environmentId);
for (const [providerKind, providerSessions] of sessionsByProvider) {
sessions += providerSessions;
if (providerSessions === 0) continue;
const provider = providerAccumulator.get(providerKind) ?? {
costUsd: 0,
totalTokens: 0,
records: 0,
sessions: 0,
};
provider.sessions += providerSessions;
providerAccumulator.set(providerKind, provider);
}
for (const bucket of buckets) {
const tokens = bucketTokens(bucket);
costUsd += bucket.costUsd;
cacheSavingsUsd += bucket.cacheSavingsUsd;
uncachedInputTokens += bucket.totals.uncachedInputTokens;
cachedInputTokens += bucket.totals.cachedInputTokens;
cacheCreationTokens += bucket.totals.cacheCreationTokens;
outputTokens += bucket.totals.outputTokens;
reasoningTokens += bucket.totals.reasoningTokens;
records += bucket.records;
unpricedRecords += bucket.unpricedRecords;
if (bucket.costSource === "providerReported") providerReportedRecords += bucket.records;
if (bucket.categoryCostUsd !== undefined) {
categoryCost.input += bucket.categoryCostUsd.input;
categoryCost.cacheRead += bucket.categoryCostUsd.cacheRead;
categoryCost.cacheWrite += bucket.categoryCostUsd.cacheWrite;
categoryCost.output += bucket.categoryCostUsd.output;
}
speedCost.fast += bucket.fastCostUsd ?? 0;
speedCost.ultrafast += bucket.ultrafastCostUsd ?? 0;
speedCost.premium += bucket.speedPremiumUsd ?? 0;
const provider = providerAccumulator.get(bucket.provider) ?? {
costUsd: 0,
totalTokens: 0,
records: 0,
sessions: 0,
};
provider.costUsd += bucket.costUsd;
provider.totalTokens += tokens;
provider.records += bucket.records;
providerAccumulator.set(bucket.provider, provider);
const modelKey = `${bucket.provider} ${bucket.model}`;
const model = modelAccumulator.get(modelKey) ?? {
provider: bucket.provider,
costUsd: 0,
totalTokens: 0,
tokens: {
uncachedInputTokens: 0,
cachedInputTokens: 0,
cacheCreationTokens: 0,
outputTokens: 0,
reasoningTokens: 0,
},
records: 0,
unpricedRecords: 0,
unpricedTokens: 0,
};
model.costUsd += bucket.costUsd;
model.totalTokens += tokens;
model.tokens = {
uncachedInputTokens: model.tokens.uncachedInputTokens + bucket.totals.uncachedInputTokens,
cachedInputTokens: model.tokens.cachedInputTokens + bucket.totals.cachedInputTokens,
cacheCreationTokens: model.tokens.cacheCreationTokens + bucket.totals.cacheCreationTokens,
outputTokens: model.tokens.outputTokens + bucket.totals.outputTokens,
reasoningTokens: model.tokens.reasoningTokens + bucket.totals.reasoningTokens,
};
model.records += bucket.records;
model.unpricedRecords += bucket.unpricedRecords;
if (bucket.records > 0) {
model.unpricedTokens += (tokens * bucket.unpricedRecords) / bucket.records;
}
modelAccumulator.set(modelKey, model);
const day = dailyAccumulator.get(bucket.day) ?? {
costUsd: 0,
totalTokens: 0,
byProvider: new Map<UsageProviderKind, { costUsd: number; totalTokens: number }>(),
};
day.costUsd += bucket.costUsd;
day.totalTokens += tokens;
const dayProvider = day.byProvider.get(bucket.provider) ?? { costUsd: 0, totalTokens: 0 };
dayProvider.costUsd += bucket.costUsd;
dayProvider.totalTokens += tokens;
day.byProvider.set(bucket.provider, dayProvider);
dailyAccumulator.set(bucket.day, day);
if (bucket.hourStart !== undefined) {
const hour = hourlyAccumulator.get(bucket.hourStart) ?? {
day: bucket.day,
hourStart: bucket.hourStart,
costUsd: 0,
totalTokens: 0,
byProvider: new Map<UsageProviderKind, { costUsd: number; totalTokens: number }>(),
};
hour.costUsd += bucket.costUsd;
hour.totalTokens += tokens;
const hourProvider = hour.byProvider.get(bucket.provider) ?? {
costUsd: 0,
totalTokens: 0,
};
hourProvider.costUsd += bucket.costUsd;
hourProvider.totalTokens += tokens;
hour.byProvider.set(bucket.provider, hourProvider);
hourlyAccumulator.set(bucket.hourStart, hour);
}
}
}
const totalTokens = uncachedInputTokens + cachedInputTokens + cacheCreationTokens + outputTokens;
const providers: ProviderTotals[] = [...providerAccumulator.entries()]
.map(([provider, totals]) => ({
provider,
costUsd: totals.costUsd,
totalTokens: totals.totalTokens,
records: totals.records,
sessions: totals.sessions,
costShare: costUsd === 0 ? 0 : totals.costUsd / costUsd,
tokenShare: totalTokens === 0 ? 0 : totals.totalTokens / totalTokens,
}))
.sort((a, b) => b.costUsd - a.costUsd);
const models: ModelTotals[] = [...modelAccumulator.entries()]
.map(([key, totals]) => ({
model: key.slice(key.indexOf(" ") + 1),
provider: totals.provider,
costUsd: totals.costUsd,
totalTokens: totals.totalTokens,
tokens: totals.tokens,
records: totals.records,
unpricedRecords: totals.unpricedRecords,
unpricedTokens: totals.unpricedTokens,
costShare: costUsd === 0 ? 0 : totals.costUsd / costUsd,
tokenShare: totalTokens === 0 ? 0 : totals.totalTokens / totalTokens,
}))
.sort((a, b) => b.costUsd - a.costUsd || b.totalTokens - a.totalTokens);
const daily: DailyTotals[] = [...dailyAccumulator.entries()]
.map(([day, totals]) => ({
day,
costUsd: totals.costUsd,
totalTokens: totals.totalTokens,
byProvider: totals.byProvider,
}))
.sort((a, b) => a.day.localeCompare(b.day));
const hourly: HourlyTotals[] = [...hourlyAccumulator.values()].sort((a, b) =>
a.hourStart.localeCompare(b.hourStart),
);
return {
costUsd,
uncachedInputTokens,
cachedInputTokens,
cacheCreationTokens,
outputTokens,
reasoningTokens,
totalTokens,
records,
sessions,
providers,
models,
daily,
hourly,
costQuality: {
providerReportedShare: records === 0 ? 0 : providerReportedRecords / records,
unpricedShare: records === 0 ? 0 : unpricedRecords / records,
modelPricedShare:
records === 0 ? 0 : (records - providerReportedRecords - unpricedRecords) / records,
cacheSavingsUsd,
},
categoryCost: {
...categoryCost,
unsplit: Math.max(
0,
costUsd -
categoryCost.input -
categoryCost.cacheRead -
categoryCost.cacheWrite -
categoryCost.output,
),
},
speedCost: {
...speedCost,
standard: Math.max(0, costUsd - speedCost.fast - speedCost.ultrafast),
},
duplicateSources: duplicates,
contributingEnvironments,
contractMismatches,
};
}