@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,710 lines • 68.5 kB
text/typescript
import { baseProviderLabel } from "../providers/label";
import { canonicalAntigravityUsageModel } from "../providers/antigravity-models";
import { usageDisplayTotalTokens } from "./totals";
import type { UsageTimeWindow } from "./time-range";
import { isUnresolvedRequestedModel, usageModelPriceOptions } from "./model-identity";
import {
classifyCacheTelemetryProvenance,
isCodexUsageAccountLogLabel,
type CacheTelemetryProvenance,
type PersistedUsageEntry,
type UsageStatus,
} from "./log";
import { type AttemptCostEstimate, type CostEstimate, estimateAttemptCost, estimateRequestCost, serviceTierContext, type ServiceTierContext } from "./cost";
/**
* Canonical range members. The warm-up loop in the management usage route
* iterates this constant rather than its own literal: the two used to be
* written separately, and a subset literal type-checks perfectly happily, so a
* range added to the union but forgotten in the loop was never warmed and
* never invalidated alongside its siblings.
*/
export const USAGE_RANGES = ["today", "7d", "30d", "all"] as const;
export type UsageRange = typeof USAGE_RANGES[number];
export const USAGE_SURFACES = ["all", "codex", "claude", "grok"] as const;
export type UsageSurface = typeof USAGE_SURFACES[number];
/** Maximum number of calendar buckets returned by the all-history chart. */
export const MAX_USAGE_DAY_BUCKETS = 366;
export interface UsageSummaryTotals {
requests: number;
attemptCount: number;
measuredRequests: number;
reportedRequests: number;
unreportedRequests: number;
unsupportedRequests: number;
estimatedRequests: number;
inputTokens: number;
outputTokens: number;
cachedInputTokens: number;
cacheReadInputTokens: number;
cacheCreationInputTokens: number;
reasoningOutputTokens: number;
totalTokens: number;
coverageRatio: number;
/** Display-time estimated cost in USD for the filtered window (WP6, devlog 004).
* Sums per-request estimateRequestCost / per-attempt combo costs; requests whose
* price is unmatched are excluded from the sum and counted separately. */
estimatedCostUsd: number;
pricedRequests: number;
/** Requests with usage but no matched price anywhere (excluded from the sum). */
unpricedRequests: number;
/** Requests whose usage itself is missing/unsupported, so no cost can be computed. */
unmeteredRequests: number;
/**
* Physical upstream sends aggregated per logical request (#4546, devlog 040 slice D): attempts
* and combo children summed on the row, then summed over rows. `attemptCount` answers how many
* attempts were recorded, which is a smaller number — retry layers re-send inside one attempt.
*
* These are optional because the management read-failure fallback emits a zeroed summary of its
* own; absence means "not computed", never zero.
*/
sends?: number;
/** Sends whose attempt reached a terminal status. */
settledSends?: number;
/** Sends charged with no terminal outcome behind them. Never folded into `settledSends`. */
unresolvedSends?: number;
/** Rows that carried a spend record, i.e. logical requests with send accounting. */
spendRequests?: number;
/** Input tokens whose row carried OBSERVED cache detail; the only honest hit-rate denominator. */
cacheObservedInputTokens?: number;
cacheObservedRequests?: number;
/** Rows whose cache detail is a wire-compatibility zero: present, and proof of nothing. */
cacheSynthesizedRequests?: number;
/** Rows with no cache detail at all. Not a miss, and not a zero. */
cacheUnknownRequests?: number;
}
export interface UsageDay {
date: string;
requests: number;
measuredRequests: number;
reportedRequests: number;
totalTokens: number;
/** Display-time estimated cost for this local day, summed from its model rows. */
estimatedCostUsd: number;
models: UsageDayModel[];
}
export interface UsageDayModel {
model: string;
provider: string;
/** Includes trace-proven unresolved requested selectors; absence is not confirmation. */
hasUnresolvedRequestedModel?: true;
requests: number;
attemptCount: number;
totalTokens: number;
inputTokens?: number;
outputTokens?: number;
cacheReadInputTokens?: number;
cacheCreationInputTokens?: number;
cacheHitRate?: number | null;
/** Denominator behind `cacheHitRate`: input tokens whose cache detail was observed. */
cacheObservedInputTokens?: number;
estimatedCostUsd?: number;
}
export interface UsageModel {
provider: string;
model: string;
/** Includes trace-proven unresolved requested selectors; absence is not confirmation. */
hasUnresolvedRequestedModel?: true;
resolvedModel?: string;
requests: number;
attemptCount: number;
measuredRequests: number;
reportedRequests: number;
estimatedRequests: number;
totalTokens: number;
inputTokens: number;
outputTokens: number;
cachedInputTokens?: number;
cacheReadInputTokens?: number;
cacheCreationInputTokens?: number;
cacheHitRate?: number | null;
/** Denominator behind `cacheHitRate`; below `inputTokens` whenever some rows never measured cache. */
cacheObservedInputTokens?: number;
priceCoverageRatio?: number;
pricedRequests?: number;
unpricedRequests?: number;
shareRatio: number;
estimatedCostUsd?: number;
}
export interface UsageProvider {
provider: string;
requests: number;
attemptCount: number;
measuredRequests: number;
reportedRequests: number;
estimatedRequests: number;
totalTokens: number;
inputTokens?: number;
outputTokens?: number;
cachedInputTokens?: number;
cacheReadInputTokens?: number;
cacheCreationInputTokens?: number;
cacheHitRate?: number | null;
/** Denominator behind `cacheHitRate`; below `inputTokens` whenever some rows never measured cache. */
cacheObservedInputTokens?: number;
priceCoverageRatio?: number;
pricedRequests?: number;
unpricedRequests?: number;
shareRatio: number;
estimatedCostUsd?: number;
}
export interface UsageAccount {
accountLogLabel: string;
ambiguous: boolean;
requests: number;
attemptCount: number;
measuredAttempts: number;
reportedAttempts: number;
estimatedAttempts: number;
unmeteredAttempts: number;
inputTokens: number;
outputTokens: number;
cacheReadInputTokens: number;
cacheCreationInputTokens: number;
reasoningOutputTokens: number;
totalTokens: number;
usageCoverageRatio: number;
estimatedCostUsd?: number;
pricedAttempts: number;
unpricedAttempts: number;
priceCoverageRatio: number;
}
export interface UsageSummary {
range: UsageRange;
surface: UsageSurface;
since: number | null;
customWindow?: true;
until?: number;
generatedAt: number;
summary: UsageSummaryTotals;
days: UsageDay[];
models: UsageModel[];
providers: UsageProvider[];
accounts: UsageAccount[];
}
/**
* Echo of an applied API-key/provider/model projection.
*
* Present only on a filtered response so a consumer can distinguish "no rows
* matched" from "no traffic in this window", and can tell that the totals it
* is reading are a projection rather than the whole window.
*/
export interface UsageFilterEcho {
provider: string | null;
model: string | null;
apiKeyId: string | null;
matched: boolean;
/**
* True when a retained row came from a combo attribution. Cost partitions
* cleanly across attempts, but a combo request is counted once per
* participating model, so a filtered REQUEST count can exceed the number of
* distinct requests. Cost is unaffected.
*/
comboOverlap: boolean;
}
export interface EntryCostInfo {
tier: ServiceTierContext;
estimate: CostEstimate | null;
attemptEstimates?: (AttemptCostEstimate | null)[];
costTotal: number;
isPriced: boolean;
}
export function cacheTokensFromUsage(usage?: PersistedUsageEntry["usage"]): {
read: number | undefined;
creation: number | undefined;
hasCacheTelemetry: boolean;
} {
if (!usage) return { read: undefined, creation: undefined, hasCacheTelemetry: false };
const creation = usage.cacheCreationInputTokens;
const read = typeof usage.cacheReadInputTokens === "number"
? usage.cacheReadInputTokens
: typeof usage.cachedInputTokens === "number" && typeof creation === "number"
? Math.max(0, usage.cachedInputTokens - creation)
: usage.cachedInputTokens;
const hasCacheTelemetry = typeof usage.cachedInputTokens === "number"
|| typeof usage.cacheReadInputTokens === "number"
|| typeof usage.cacheCreationInputTokens === "number";
return { read, creation, hasCacheTelemetry };
}
/**
* Cache tokens plus the provenance that says whether they may be averaged.
*
* A persisted `cacheProvenance` wins; a row written before the field existed is reconstructed
* from its own shape, which reproduces the previous reading exactly (telemetry present is
* observed, absent is unknown) so historical rows do not change meaning. Only `observed` reaches
* a hit-rate denominator: a synthesized zero was emitted for wire compatibility and an unknown
* was never measured, and averaging either as a zero is how a cold pool reports a warm cache.
*/
export function cacheObservationFromUsage(
usage: PersistedUsageEntry["usage"],
provenance: CacheTelemetryProvenance | undefined,
): { read: number | undefined; creation: number | undefined; provenance: CacheTelemetryProvenance } {
const { read, creation, hasCacheTelemetry } = cacheTokensFromUsage(usage);
// A row cannot have observed what it does not carry, so a stored label never opens the
// denominator for a record with no cache fields in it.
if (!usage || !hasCacheTelemetry) return { read, creation, provenance: "unknown" };
return { read, creation, provenance: provenance ?? classifyCacheTelemetryProvenance(usage) };
}
export function calculateCacheHitRate(
cacheObserved: boolean,
/** Observed input tokens only. Passing the row's whole input total averages unknowns as zeros. */
observedInputTokens: number,
cacheReadTokens: number,
): number | null {
if (!cacheObserved || observedInputTokens <= 0) return null;
return Math.max(0, Math.min(1, cacheReadTokens / observedInputTokens));
}
export function computeEntryCost(entry: PersistedUsageEntry): EntryCostInfo {
const tier = serviceTierContext(entry);
if (entry.attempts?.length) {
const attemptEstimates = entry.attempts.map(attempt =>
estimateAttemptCost({ ...attempt, ...usageModelPriceOptions(entry, attempt) }, undefined, tier)
);
let costTotal = 0;
let isPriced = false;
for (const est of attemptEstimates) {
if (est) {
costTotal += est.cost.total;
isPriced = true;
}
}
return { tier, estimate: null, attemptEstimates, costTotal, isPriced };
}
const estimate = estimateRequestCost({
...usageModelPriceOptions(entry, entry),
provider: entry.provider,
model: entry.model,
usage: entry.usage,
usageStatus: entry.usageStatus,
serviceTier: tier,
});
return {
tier,
estimate,
costTotal: estimate ? estimate.cost.total : 0,
isPriced: estimate !== null,
};
}
const DAY_MS = 86_400_000;
export const MAX_USAGE_MODEL_BREAKDOWN_ROWS = 256;
export function parseRange(input: string | null | undefined): UsageRange {
// `1d` normalises here rather than becoming a second union member: a second
// member would need its own cache slot, its own grid arm and its own test
// matrix for no user-visible gain.
if (input === "today" || input === "1d") return "today";
if (input === "7d" || input === "30d" || input === "all") return input;
return "30d";
}
export function parseUsageSurface(input: string | null | undefined): UsageSurface {
if (input === "codex" || input === "claude" || input === "grok") return input;
return "all";
}
function startOfLocalDay(ts: number): number {
const d = new Date(ts);
d.setHours(0, 0, 0, 0);
return d.getTime();
}
export function rangeWindow(range: UsageRange, now: number): { since: number | null; days: number } {
// Handled before the others because the fallthrough below is the `all`
// window: a range that reaches it is silently reported as all-time history,
// which for a cost surface is a plausible-looking wrong answer rather than a
// visible failure.
if (range === "today") return { since: startOfLocalDay(now), days: 1 };
if (range === "7d") {
const start = new Date(startOfLocalDay(now));
start.setDate(start.getDate() - 6);
return { since: start.getTime(), days: 7 };
}
if (range === "30d") {
const start = new Date(startOfLocalDay(now));
start.setDate(start.getDate() - 29);
return { since: start.getTime(), days: 30 };
}
return { since: null, days: 0 };
}
function localDateKey(ts: number): string {
const d = new Date(ts);
const y = String(d.getFullYear()).padStart(4, "0");
const m = String(d.getMonth() + 1).padStart(2, "0");
const day = String(d.getDate()).padStart(2, "0");
return `${y}-${m}-${day}`;
}
function dayCountForAllRange(oldest: number | null, now: number): number {
if (oldest === null) return 1;
const days = Math.ceil((now - oldest) / DAY_MS) + 1;
return Math.min(MAX_USAGE_DAY_BUCKETS, Math.max(1, days));
}
function customWindowDates(window: UsageTimeWindow): string[] {
const start = startOfLocalDay(window.since);
const date = new Date(startOfLocalDay(window.until));
const dates: string[] = [];
while (date.getTime() >= start && dates.length < MAX_USAGE_DAY_BUCKETS) {
dates.push(localDateKey(date.getTime()));
const previous = date.getTime();
date.setDate(date.getDate() - 1);
date.setHours(0, 0, 0, 0);
// A skipped civil day can normalize back to this same midnight (Apia, 2011).
// Move through the preceding instant to find the prior existing local day.
if (date.getTime() >= previous) {
date.setTime(previous - 1);
date.setHours(0, 0, 0, 0);
}
}
return dates.reverse();
}
function blankTotals(): UsageSummaryTotals {
return {
requests: 0,
attemptCount: 0,
measuredRequests: 0,
reportedRequests: 0,
unreportedRequests: 0,
unsupportedRequests: 0,
estimatedRequests: 0,
inputTokens: 0,
outputTokens: 0,
cachedInputTokens: 0,
cacheReadInputTokens: 0,
cacheCreationInputTokens: 0,
reasoningOutputTokens: 0,
totalTokens: 0,
coverageRatio: 0,
estimatedCostUsd: 0,
pricedRequests: 0,
unpricedRequests: 0,
unmeteredRequests: 0,
sends: 0,
settledSends: 0,
unresolvedSends: 0,
spendRequests: 0,
cacheObservedInputTokens: 0,
cacheObservedRequests: 0,
cacheSynthesizedRequests: 0,
cacheUnknownRequests: 0,
};
}
function isMeasuredStatus(status: UsageStatus): boolean {
return status === "reported" || status === "estimated";
}
export interface UsageAttribution {
requestId: string;
provider: string;
model: string;
resolvedModel?: string;
hasUnresolvedRequestedModel?: true;
accountLogLabel?: string;
usageStatus: UsageStatus;
usage?: PersistedUsageEntry["usage"];
totalTokens?: number;
/** Attempt provenance when the row has one, else the entry's; never assumed observed. */
cacheProvenance?: CacheTelemetryProvenance;
}
/**
* Usage row identity for model breakdowns.
* Google Antigravity collapses wire/compat/suffix ids to picker/call base models so
* historical effort-variant logs merge with current base-model invocations.
*/
function usageModelIdentity(
provider: string,
model: string,
resolvedModel?: string,
): { model: string; resolvedModel?: string } {
if (baseProviderLabel(provider) !== "google-antigravity") {
return resolvedModel ? { model, resolvedModel } : { model };
}
const fromModel = canonicalAntigravityUsageModel(model);
const fromResolved = resolvedModel
? canonicalAntigravityUsageModel(resolvedModel)
: undefined;
// Prefer an explicit base mapping from model; if model is unknown but resolved maps
// to a known base, use that (covers base call + upstream wire resolvedModel pairs).
const canonical = fromModel !== model
? fromModel
: (fromResolved && fromResolved !== resolvedModel ? fromResolved : fromModel);
return { model: canonical };
}
function usageModelKey(providerKey: string, model: string): string {
return `${providerKey}\0${model}`;
}
export function usageAttributions(entry: PersistedUsageEntry): UsageAttribution[] {
if (!entry.attempts?.length) {
return [{
requestId: entry.requestId,
provider: entry.provider,
...usageModelIdentity(entry.provider, entry.model, entry.resolvedModel),
...(isUnresolvedRequestedModel(entry, entry) ? { hasUnresolvedRequestedModel: true as const } : {}),
...(entry.accountLogLabel ? { accountLogLabel: entry.accountLogLabel } : {}),
usageStatus: entry.usageStatus,
...(entry.usage ? { usage: entry.usage } : {}),
...(entry.totalTokens !== undefined ? { totalTokens: entry.totalTokens } : {}),
...(entry.cacheProvenance ? { cacheProvenance: entry.cacheProvenance } : {}),
}];
}
return entry.attempts.map(attempt => {
// An attempt's own provenance wins; the row's is the fallback for a child written before
// attempt-level provenance existed. A child carrying no cache fields still resolves to
// unknown in cacheObservationFromUsage, so it cannot inherit a sibling's observation.
const cacheProvenance = attempt.cacheProvenance ?? entry.cacheProvenance;
return {
requestId: entry.requestId,
provider: attempt.provider,
...usageModelIdentity(attempt.provider, attempt.model),
...(isUnresolvedRequestedModel(entry, attempt) ? { hasUnresolvedRequestedModel: true as const } : {}),
...(attempt.accountLogLabel ? { accountLogLabel: attempt.accountLogLabel } : {}),
usageStatus: attempt.usageStatus,
...(attempt.usage ? { usage: attempt.usage } : {}),
...(attempt.totalTokens !== undefined ? { totalTokens: attempt.totalTokens } : {}),
...(cacheProvenance ? { cacheProvenance } : {}),
};
});
}
function projectedComboUsage(
attempts: readonly NonNullable<PersistedUsageEntry["attempts"]>[number][],
): { usage?: PersistedUsageEntry["usage"]; totalTokens?: number } {
let inputTokens = 0;
let outputTokens = 0;
let cachedInputTokens = 0;
let cacheReadInputTokens = 0;
let cacheCreationInputTokens = 0;
let reasoningOutputTokens = 0;
let hasUsage = false;
let hasCacheTelemetry = false;
let hasReasoningTelemetry = false;
let totalTokens = 0;
let hasTotalTokens = false;
let estimated = false;
for (const attempt of attempts) {
if (attempt.usage) {
hasUsage = true;
inputTokens += attempt.usage.inputTokens;
outputTokens += attempt.usage.outputTokens;
const cache = cacheTokensFromUsage(attempt.usage);
if (cache.hasCacheTelemetry) hasCacheTelemetry = true;
if (typeof cache.read === "number") {
cachedInputTokens += cache.read;
cacheReadInputTokens += cache.read;
}
if (typeof cache.creation === "number") cacheCreationInputTokens += cache.creation;
if (typeof attempt.usage.reasoningOutputTokens === "number") {
hasReasoningTelemetry = true;
reasoningOutputTokens += attempt.usage.reasoningOutputTokens;
}
if (attempt.usage.estimated === true) estimated = true;
}
const attemptTotal = usageDisplayTotalTokens(attempt.usage, attempt.totalTokens);
if (attemptTotal !== undefined) {
hasTotalTokens = true;
totalTokens += attemptTotal;
}
}
if (!hasUsage && !hasTotalTokens) return {};
const usage = hasUsage
? {
inputTokens,
outputTokens,
...(hasCacheTelemetry ? { cachedInputTokens, cacheReadInputTokens, cacheCreationInputTokens } : {}),
...(hasReasoningTelemetry ? { reasoningOutputTokens } : {}),
...(estimated ? { estimated: true } : {}),
}
: undefined;
return {
...(usage ? { usage } : {}),
...(hasTotalTokens ? { totalTokens } : {}),
};
}
function bumpStatus(totals: UsageSummaryTotals, status: UsageStatus): void {
totals.requests += 1;
if (isMeasuredStatus(status)) totals.measuredRequests += 1;
if (status === "reported") totals.reportedRequests += 1;
else if (status === "unreported") totals.unreportedRequests += 1;
else if (status === "unsupported") totals.unsupportedRequests += 1;
else if (status === "estimated") totals.estimatedRequests += 1;
}
function addTokens(
totals: UsageSummaryTotals,
entry: Pick<PersistedUsageEntry, "usage" | "totalTokens">,
): void {
if (!entry.usage) return;
totals.inputTokens += entry.usage.inputTokens;
totals.outputTokens += entry.usage.outputTokens;
const { read, creation } = cacheTokensFromUsage(entry.usage);
if (typeof read === "number") {
totals.cachedInputTokens += read;
totals.cacheReadInputTokens += read;
}
if (typeof creation === "number") totals.cacheCreationInputTokens += creation;
if (typeof entry.usage.reasoningOutputTokens === "number") totals.reasoningOutputTokens += entry.usage.reasoningOutputTokens;
totals.totalTokens += usageDisplayTotalTokens(entry.usage, entry.totalTokens) ?? 0;
}
/**
* Fold one row's send accounting into the window totals.
*
* The row already aggregated its attempts and combo children, so this is a sum over logical
* requests. Rows written before the spend record existed contribute nothing rather than a zero:
* a request whose sends were never counted is not a request that sent nothing.
*/
function addSpendTotals(
totals: UsageSummaryTotals,
entry: Pick<PersistedUsageEntry, "spend">,
): void {
const spend = entry.spend;
if (!spend) return;
totals.sends = (totals.sends ?? 0) + spend.sends;
totals.settledSends = (totals.settledSends ?? 0) + spend.settled;
totals.unresolvedSends = (totals.unresolvedSends ?? 0) + spend.unresolved;
totals.spendRequests = (totals.spendRequests ?? 0) + 1;
}
/** Keep the three cache provenances countable, and let only observed input tokens be averaged. */
function addCacheProvenanceTotals(
totals: UsageSummaryTotals,
entry: Pick<PersistedUsageEntry, "usage" | "cacheProvenance">,
): void {
const { provenance } = cacheObservationFromUsage(entry.usage, entry.cacheProvenance);
if (provenance === "observed") {
totals.cacheObservedRequests = (totals.cacheObservedRequests ?? 0) + 1;
totals.cacheObservedInputTokens = (totals.cacheObservedInputTokens ?? 0) + (entry.usage?.inputTokens ?? 0);
return;
}
if (provenance === "synthesized") {
totals.cacheSynthesizedRequests = (totals.cacheSynthesizedRequests ?? 0) + 1;
return;
}
totals.cacheUnknownRequests = (totals.cacheUnknownRequests ?? 0) + 1;
}
function finalizeCoverage(totals: UsageSummaryTotals): void {
totals.coverageRatio = totals.requests === 0 ? 0 : totals.measuredRequests / totals.requests;
}
function addEstimatedCost(
totals: UsageSummaryTotals,
entry: Pick<PersistedUsageEntry, "usageStatus" | "usage" | "attempts">,
costInfo: EntryCostInfo,
): void {
if (entry.usageStatus === "unreported" || entry.usageStatus === "unsupported"
|| (!entry.usage && !entry.attempts?.length)) {
totals.unmeteredRequests += 1;
return;
}
if (!costInfo.isPriced) {
totals.unpricedRequests += 1;
return;
}
totals.pricedRequests += 1;
totals.estimatedCostUsd += costInfo.costTotal;
}
const REQUEST_REPORTED = 1 << 0;
const REQUEST_ESTIMATED = 1 << 1;
const REQUEST_UNREPORTED = 1 << 2;
const REQUEST_UNSUPPORTED = 1 << 3;
const REQUEST_PRICED = 1 << 4;
const REQUEST_UNPRICED = 1 << 5;
const REQUEST_STATUS_MASK = REQUEST_REPORTED | REQUEST_ESTIMATED | REQUEST_UNREPORTED | REQUEST_UNSUPPORTED;
type UsagePartitionSurface = Exclude<UsageSurface, "all"> | "other";
export type UsageAccumulatorMode = "exact" | "row-unique";
interface UsageRequestCounts {
requests: number;
measuredRequests: number;
reportedRequests: number;
estimatedRequests: number;
pricedRequests: number;
unpricedRequests: number;
}
interface UsageModelOverlap {
models: ReadonlyArray<readonly [modelKey: string, requestFacts: number]>;
count: number;
}
interface UsageModelAccumulator {
provider: string;
model: string;
resolvedModel?: string;
hasUnresolvedRequestedModel?: true;
firstSeen: number;
attemptCount: number;
dayTotalTokens: number;
summaryTotalTokens: number;
inputTokens: number;
outputTokens: number;
cacheReadInputTokens: number;
cacheCreationInputTokens: number;
cacheObserved: boolean;
/** Input tokens from attributions with OBSERVED cache detail; the hit-rate denominator. */
cacheObservedInputTokens: number;
estimatedCostUsd?: number;
requestCounts: UsageRequestCounts;
requestFacts?: Map<number, number>;
}
interface UsageAccountAccumulator {
accountLogLabel: string;
ambiguous: boolean;
firstSeen: number;
requests: number;
requestIds?: Set<number>;
attemptCount: number;
measuredAttempts: number;
reportedAttempts: number;
estimatedAttempts: number;
unmeteredAttempts: number;
inputTokens: number;
outputTokens: number;
cacheReadInputTokens: number;
cacheCreationInputTokens: number;
reasoningOutputTokens: number;
totalTokens: number;
estimatedCostUsd?: number;
pricedAttempts: number;
unpricedAttempts: number;
}
interface UsagePartition {
date: string;
dayStart: number;
surface: UsagePartitionSurface;
oldestTimestamp: number | null;
totals: UsageSummaryTotals;
models: Map<string, UsageModelAccumulator>;
providers?: Map<string, UsageModelAccumulator>;
accounts: Map<string, UsageAccountAccumulator>;
modelOverlaps: Map<string, UsageModelOverlap>;
}
interface UsageDayAccumulator {
totals: UsageSummaryTotals;
models: Map<string, UsageModelAccumulator>;
modelOverlaps: UsageModelOverlap[];
}
interface NormalizedUsageFilter {
provider: string | null;
model: string | null;
apiKeyId: string | null;
}
export interface UsageSummaryAccumulator {
add(entry: PersistedUsageEntry): void;
/** Return a mutation-independent snapshot that may continue accepting rows. */
clone(): UsageSummaryAccumulator;
summarize(
range: UsageRange,
now: number,
surface?: UsageSurface,
): UsageSummary & { filter?: UsageFilterEcho };
readonly snapshotWindow: { start: number | null; end: number | null };
/** Conservative O(1) retained-state estimate; excludes scan and summarize temporaries. */
readonly estimatedBytes: number;
}
function requestStatusFact(status: UsageStatus): number {
if (status === "reported") return REQUEST_REPORTED;
if (status === "estimated") return REQUEST_ESTIMATED;
if (status === "unsupported") return REQUEST_UNSUPPORTED;
return REQUEST_UNREPORTED;
}
function statusFromRequestFacts(facts: number): UsageStatus {
const statuses = facts & REQUEST_STATUS_MASK;
if (statuses === REQUEST_UNSUPPORTED) return "unsupported";
if ((statuses & (REQUEST_UNREPORTED | REQUEST_UNSUPPORTED)) !== 0) return "unreported";
if ((statuses & REQUEST_ESTIMATED) !== 0) return "estimated";
return (statuses & REQUEST_REPORTED) !== 0 ? "reported" : "unreported";
}
function blankRequestCounts(): UsageRequestCounts {
return {
requests: 0,
measuredRequests: 0,
reportedRequests: 0,
estimatedRequests: 0,
pricedRequests: 0,
unpricedRequests: 0,
};
}
function bumpRequestCounts(counts: UsageRequestCounts, facts: number, amount = 1): void {
counts.requests += amount;
const status = statusFromRequestFacts(facts);
if (isMeasuredStatus(status)) counts.measuredRequests += amount;
if (status === "reported") counts.reportedRequests += amount;
else if (status === "estimated") counts.estimatedRequests += amount;
if ((facts & REQUEST_PRICED) !== 0) counts.pricedRequests += amount;
if ((facts & REQUEST_UNPRICED) !== 0) counts.unpricedRequests += amount;
}
function mergeRequestCounts(target: UsageRequestCounts, source: UsageRequestCounts): void {
target.requests += source.requests;
target.measuredRequests += source.measuredRequests;
target.reportedRequests += source.reportedRequests;
target.estimatedRequests += source.estimatedRequests;
target.pricedRequests += source.pricedRequests;
target.unpricedRequests += source.unpricedRequests;
}
function mergeRequestFacts(target: Map<number, number>, source: Map<number, number>): void {
for (const [requestId, facts] of source) {
target.set(requestId, (target.get(requestId) ?? 0) | facts);
}
}
function requestCountsFor(model: UsageModelAccumulator): UsageRequestCounts {
if (!model.requestFacts) return model.requestCounts;
const counts = blankRequestCounts();
for (const facts of model.requestFacts.values()) bumpRequestCounts(counts, facts);
return counts;
}
function mergeTotals(target: UsageSummaryTotals, source: UsageSummaryTotals): void {
target.requests += source.requests;
target.attemptCount += source.attemptCount;
target.measuredRequests += source.measuredRequests;
target.reportedRequests += source.reportedRequests;
target.unreportedRequests += source.unreportedRequests;
target.unsupportedRequests += source.unsupportedRequests;
target.estimatedRequests += source.estimatedRequests;
target.inputTokens += source.inputTokens;
target.outputTokens += source.outputTokens;
target.cachedInputTokens += source.cachedInputTokens;
target.cacheReadInputTokens += source.cacheReadInputTokens;
target.cacheCreationInputTokens += source.cacheCreationInputTokens;
target.reasoningOutputTokens += source.reasoningOutputTokens;
target.totalTokens += source.totalTokens;
target.estimatedCostUsd += source.estimatedCostUsd;
target.pricedRequests += source.pricedRequests;
target.unpricedRequests += source.unpricedRequests;
target.unmeteredRequests += source.unmeteredRequests;
target.sends = mergeOptionalTotal(target.sends, source.sends);
target.settledSends = mergeOptionalTotal(target.settledSends, source.settledSends);
target.unresolvedSends = mergeOptionalTotal(target.unresolvedSends, source.unresolvedSends);
target.spendRequests = mergeOptionalTotal(target.spendRequests, source.spendRequests);
target.cacheObservedInputTokens = mergeOptionalTotal(target.cacheObservedInputTokens, source.cacheObservedInputTokens);
target.cacheObservedRequests = mergeOptionalTotal(target.cacheObservedRequests, source.cacheObservedRequests);
target.cacheSynthesizedRequests = mergeOptionalTotal(target.cacheSynthesizedRequests, source.cacheSynthesizedRequests);
target.cacheUnknownRequests = mergeOptionalTotal(target.cacheUnknownRequests, source.cacheUnknownRequests);
}
/** Sum an optional total. Absent on one side means "not computed there", so it contributes nothing. */
function mergeOptionalTotal(target: number | undefined, source: number | undefined): number | undefined {
if (target === undefined && source === undefined) return undefined;
return (target ?? 0) + (source ?? 0);
}
function blankModelAccumulator(
provider: string,
model: string,
resolvedModel: string | undefined,
firstSeen: number,
mode: UsageAccumulatorMode,
): UsageModelAccumulator {
return {
provider,
model,
...(resolvedModel ? { resolvedModel } : {}),
firstSeen,
attemptCount: 0,
dayTotalTokens: 0,
summaryTotalTokens: 0,
inputTokens: 0,
outputTokens: 0,
cacheReadInputTokens: 0,
cacheCreationInputTokens: 0,
cacheObserved: false,
cacheObservedInputTokens: 0,
requestCounts: blankRequestCounts(),
...(mode === "exact" ? { requestFacts: new Map() } : {}),
};
}
function cloneModelAccumulator(source: UsageModelAccumulator): UsageModelAccumulator {
return {
...source,
requestCounts: { ...source.requestCounts },
...(source.requestFacts ? { requestFacts: new Map(source.requestFacts) } : {}),
};
}
function mergeModelAccumulator(target: UsageModelAccumulator, source: UsageModelAccumulator): void {
if (source.hasUnresolvedRequestedModel) target.hasUnresolvedRequestedModel = true;
if (source.firstSeen < target.firstSeen) {
target.firstSeen = source.firstSeen;
target.resolvedModel = source.resolvedModel;
}
target.attemptCount += source.attemptCount;
target.dayTotalTokens += source.dayTotalTokens;
target.summaryTotalTokens += source.summaryTotalTokens;
target.inputTokens += source.inputTokens;
target.outputTokens += source.outputTokens;
target.cacheReadInputTokens += source.cacheReadInputTokens;
target.cacheCreationInputTokens += source.cacheCreationInputTokens;
target.cacheObserved ||= source.cacheObserved;
target.cacheObservedInputTokens += source.cacheObservedInputTokens;
if (source.estimatedCostUsd !== undefined) {
target.estimatedCostUsd = (target.estimatedCostUsd ?? 0) + source.estimatedCostUsd;
}
if (target.requestFacts && source.requestFacts) mergeRequestFacts(target.requestFacts, source.requestFacts);
else mergeRequestCounts(target.requestCounts, source.requestCounts);
}
function mergeModelMaps(
target: Map<string, UsageModelAccumulator>,
source: Map<string, UsageModelAccumulator>,
): void {
for (const [key, model] of source) {
const current = target.get(key);
if (current) mergeModelAccumulator(current, model);
else target.set(key, cloneModelAccumulator(model));
}
}
function cloneAccountAccumulator(source: UsageAccountAccumulator): UsageAccountAccumulator {
return {
...source,
...(source.requestIds ? { requestIds: new Set(source.requestIds) } : {}),
};
}
function mergeAccountAccumulator(target: UsageAccountAccumulator, source: UsageAccountAccumulator): void {
target.firstSeen = Math.min(target.firstSeen, source.firstSeen);
if (target.requestIds && source.requestIds) {
for (const requestId of source.requestIds) target.requestIds.add(requestId);
} else {
target.requests += source.requests;
}
target.attemptCount += source.attemptCount;
target.measuredAttempts += source.measuredAttempts;
target.reportedAttempts += source.reportedAttempts;
target.estimatedAttempts += source.estimatedAttempts;
target.unmeteredAttempts += source.unmeteredAttempts;
target.inputTokens += source.inputTokens;
target.outputTokens += source.outputTokens;
target.cacheReadInputTokens += source.cacheReadInputTokens;
target.cacheCreationInputTokens += source.cacheCreationInputTokens;
target.reasoningOutputTokens += source.reasoningOutputTokens;
target.totalTokens += source.totalTokens;
if (source.estimatedCostUsd !== undefined) {
target.estimatedCostUsd = (target.estimatedCostUsd ?? 0) + source.estimatedCostUsd;
}
target.pricedAttempts += source.pricedAttempts;
target.unpricedAttempts += source.unpricedAttempts;
}
function usagePartitionSurface(entry: PersistedUsageEntry): UsagePartitionSurface {
if (entry.surface === undefined) return "codex";
if (entry.surface === "claude" || entry.surface === "claude-desktop") return "claude";
if (entry.surface === "grok") return "grok";
return "other";
}
function usageSurfaceMatches(partition: UsagePartitionSurface, surface: UsageSurface): boolean {
return surface === "all" || partition === surface;
}
const LEGACY_AMBIGUOUS_ACCOUNT_LABEL = "legacy-ambiguous";
function legacyCodexAccountLabel(provider: string): string | null {
if (baseProviderLabel(provider) !== "openai") return null;
const suffix = provider.match(/-(main|p[a-f0-9]{6})$/)?.[1];
return suffix ?? LEGACY_AMBIGUOUS_ACCOUNT_LABEL;
}
/**
* An explicitly stamped label of EITHER family is authoritative for any provider (#2699).
* The legacy fallback stays openai-only so unrelated unlabeled providers are not guessed.
*/
function accountLabelForAttribution(provider: string, explicit: unknown): string | null {
if (isCodexUsageAccountLogLabel(explicit)) return explicit;
return legacyCodexAccountLabel(provider);
}
function filterMatchesAttribution(
filter: NormalizedUsageFilter,
provider: string,
model: string,
): boolean {
if (filter.provider !== null && baseProviderLabel(provider).toLowerCase() !== filter.provider) return false;
if (filter.model !== null && model.toLowerCase() !== filter.model) return false;
return true;
}
function projectedEntryForFilter(
entry: PersistedUsageEntry,
filter: NormalizedUsageFilter,
): { entry: PersistedUsageEntry; comboOverlap: boolean } | null {
if (filter.apiKeyId !== null && entry.apiKeyId !== filter.apiKeyId) return null;
if (!entry.attempts?.length) {
const identity = usageModelIdentity(entry.provider, entry.model, entry.resolvedModel);
return filterMatchesAttribution(filter, entry.provider, identity.model)
? { entry, comboOverlap: false }
: null;
}
const attempts = entry.attempts.filter(attempt => {
const identity = usageModelIdentity(attempt.provider, attempt.model);
return filterMatchesAttribution(filter, attempt.provider, identity.model);
});
if (attempts.length === 0) return null;
const { usage: _parentUsage, totalTokens: _parentTotalTokens, spend: parentSpend, ...withoutParentUsage } = entry;
return {
entry: {
...withoutParentUsage,
// The spend record counts the whole logical request. A projection that dropped a combo
// child no longer describes it, so the record is dropped with the child rather than
// reporting a full-request send count against a partial row.
...(parentSpend && attempts.length === entry.attempts.length ? { spend: parentSpend } : {}),
attempts,
...projectedComboUsage(attempts),
},
comboOverlap: entry.attempts.length > 1,
};
}
function overflowModelAccumulator(
models: UsageModelAccumulator[],
overlaps: readonly UsageModelOverlap[],
): UsageModelAccumulator {
const mode: UsageAccumulatorMode = models[0]?.requestFacts ? "exact" : "row-unique";
const other = blankModelAccumulator("other", "other", undefined, models[0]?.firstSeen ?? 0, mode);
for (const model of models) mergeModelAccumulator(other, model);
if (mode === "row-unique" && overlaps.length > 0) {
const overflowKeys = new Set(models.map(model => usageModelKey(model.provider, model.model)));
for (const overlap of overlaps) {
const retained = overlap.models.filter(([modelKey]) => overflowKeys.has(modelKey));
if (retained.length < 2) continue;
let combinedFacts = 0;
for (const [, facts] of retained) {
bumpRequestCounts(other.requestCounts, facts, -overlap.count);
combinedFacts |= facts;
}
bumpRequestCounts(other.requestCounts, combinedFacts, overlap.count);
}
}
other.provider = "other";
other.model = "other";
delete other.resolvedModel;
return other;
}
function retainedModelAccumulators(
models: UsageModelAccumulator[],
overlaps: readonly UsageModelOverlap[],
): UsageModelAccumulator[] {
if (models.length <= MAX_USAGE_MODEL_BREAKDOWN_ROWS) return models;
return [
...models.slice(0, MAX_USAGE_MODEL_BREAKDOWN_ROWS - 1),
overflowModelAccumulator(models.slice(MAX_USAGE_MODEL_BREAKDOWN_ROWS - 1), overlaps),
];
}
function buildDayModels(
models: Map<string, UsageModelAccumulator>,
overlaps: readonly UsageModelOverlap[],
): UsageDayModel[] {
const sorted = [...models.values()].sort((a, b) =>
requestCountsFor(b).requests - requestCountsFor(a).requests || a.firstSeen - b.firstSeen
);
return retainedModelAccumulators(sorted, overlaps).map(model => ({
model: model.model,
provider: model.provider,
...(model.hasUnresolvedRequestedModel ? { hasUnresolvedRequestedModel: true as const } : {}),
requests: requestCountsFor(model).requests,
attemptCount: model.attemptCount,
totalTokens: model.dayTotalTokens,
inputTokens: model.inputTokens,
outputTokens: model.outputTokens,
cacheReadInputTokens: model.cacheReadInputTokens,
cacheCreationInputTokens: model.cacheCreationInputTokens,
cacheHitRate: calculateCacheHitRate(model.cacheObserved, model.cacheObservedInputTokens, model.cacheReadInputTokens),
cacheObservedInputTokens: model.cacheObservedInputTokens,
...(model.estimatedCostUsd !== undefined ? { estimatedCostUsd: model.estimatedCostUsd } : {}),
}));
}
function buildUsageModels(
models: Map<string, UsageModelAccumulator>,
totalTokens: number,
overlaps: readonly UsageModelOverlap[],
): UsageModel[] {
const sorted = [...models.values()].sort((a, b) =>
requestCountsFor(b).requests - requestCountsFor(a).requests || a.firstSeen - b.firstSeen
);
return retainedModelAccumulators(sorted, overlaps).map(model => {
const counts = requestCountsFor(model);
const requests = counts.requests;
return {
provider: model.provider,
model: model.model,
...(model.hasUnresolvedRequestedModel ? { hasUnresolvedRequestedModel: true as const } : {}),
...(model.resolvedModel ? { resolvedModel: model.resolvedModel } : {}),
requests,
attemptCount: model.attemptCount,
measuredRequests: counts.measuredRequests,
reportedRequests: counts.reportedRequests,
estimatedRequests: counts.estimatedRequests,
totalTokens: model.summaryTotalTokens,
inputTokens: model.inputTokens,
outputTokens: model.outputTokens,
cachedInputTokens: model.cacheReadInputTokens,
cacheReadInputTokens: model.cacheReadInputTokens,
cacheCreationInputTokens: model.cacheCreationInputTokens,
cacheHitRate: calculateCacheHitRate(model.cacheObserved, model.cacheObservedInputTokens, model.cacheReadInputTokens),
cacheObservedInputTokens: model.cacheObservedInputTokens,
priceCoverageRatio: requests > 0 ? counts.pricedRequests / requests : 0,
pricedRequests: counts.pricedRequests,
unpricedRequests: counts.unpricedRequests,
shareRatio: totalTokens === 0 ? 0 : model.summaryTotalTokens / totalTokens,
...(model.estimatedCostUsd !== undefined ? { estimatedCostUsd: model.estimatedCostUsd } : {}),
};
});
}
function buildUsageProviders(
models: Map<string, UsageModelAccumulator>,
totalTokens: number,
): UsageProvider[] {
const providers = new Map<string, UsageModelAccumulator>();
for (const model of models.values()) {
const current = providers.get(model.provider);
if (current) mergeModelAccumulator(current, model);
else providers.set(model.provider, cloneModelAccumulator(model));
}
return [...providers.values()]
.sort((a, b) => requestCountsFor(b).requests - requestCountsFor(a).requests || a.firstSeen - b.firstSeen)
.map(provider => {
const counts = requestCountsFor(provider);
const requests = counts.requests;
return {
provider: provider.provider,
requests,
attemptCount: provider.attemptCount,
measuredRequests: counts.measuredRequests,
reportedRequests: counts.reportedRequests,
estimatedRequests: counts.estimatedRequests,
totalTokens: provider.summaryTotalTokens,
inputTokens: provider.inputTokens,
outputTokens: provider.outputTokens,
cachedInputTokens: provider.cacheReadInputTokens,
cacheReadInputTokens: provider.cacheReadInputTokens,
cacheCreationInputTokens: provider.cacheCreationInputTokens,
cacheHitRate: calculateCacheHitRate(provider.cacheObserved, provider.cacheObservedInputTokens, provider.cacheReadInputTokens),
cacheObservedInputTokens: provider.cacheObservedInputTokens,
priceCoverageRatio: requests > 0 ? counts.pricedRequests / requests : 0,
pricedRequests: counts.pricedRequests,
unpricedRequests: counts.unpricedRequests,
shareRatio: totalTokens === 0 ? 0 : provider.summaryTotalTokens / totalTokens,
...(provider.estimatedCostUsd !== undefined ? { estimatedCostUsd: provider.estimatedCostUsd } : {}),
};
});
}
function buildUsageAccounts(accounts: Map<string, UsageAccountAccumulator>): UsageAccount[] {
return [...accounts.values()]
.sort((a, b) => b.totalTokens - a.totalTokens || a.firstSeen - b.firstSeen)
.map(account => ({
accountLogLabel: account.accountLogLabel,
ambiguous: account.ambiguous,
requests: account.requestIds?.size ?? account.requests,
attemptCount: account.attemptCount,
measuredAttempts: account.measuredAttempts,
reportedAttempts: account.reportedAttempts,
estimatedAttempts: account.estimatedAttempts,
unmeteredAttempts: account.unmeteredAttempts,
inputTokens: account.inputTokens,
outputTokens: account.outputTokens,
cacheReadInputTokens: account.cacheReadInputTokens,
cacheCreationInputTokens: account.cacheCreationInputTokens,
reasoningOutputTokens: account.reasoningOutputTokens,
totalTokens: account.totalTokens,
usageCoverageRatio: account.attemptCount === 0 ? 0 : account.measuredAttempts / account.attemptCount,
...(account.estimatedCostUsd !== undefined ? { estimatedCostUsd: account.estimatedCostUsd } : {}),
pricedAttempts: account.pricedAttempts,
unpricedAttempts: account.unpricedAttempts,
priceCoverageRatio: account.measuredAttempts === 0 ? 0 : account.pricedAttempts / account.measuredAttempts,
}));
}
// Retained-size estimates intentionally favor over-counting. They are updated only when
// retained structures grow, so memory-budget checks stay O(1) even on very large ledgers.
const ESTIMATED_ACCUMULATOR_BASE_BYTES = 2_048;
const ESTIMATED_PARTITION_BYTES = 1_024;
const ESTIMATED_BREAKDOWN_BYTES = 1_024;
const ESTIMATED_EXACT_REQUEST_ID_BYTES = 1_024;
const ESTIMATED_REQUEST_FACT_BYTES = 512;
const ESTIMATED_ACCOUNT_REQUEST_BYTES = 256;
const ESTIMATED_OVERLAP_BYTES = 128;
const ESTIMATED_OVERLAP_MODEL_BYTES = 256;
class StreamingUsageSummaryAccumulator implements UsageSummaryAccumulator {
private readonly partitions = new Map<string, UsagePartition>();
private readonly requestIds: Map<string, number> | null;
private readonly filter: NormalizedUsageFilter | null;
private readonly mode: UsageAccumulatorMode;
private readonly window: UsageTimeWindow | undefined;
private nextRequestId = 0;
private nextOrdinal = 0;
private snapshotStart: number | null = null;
private snapshotEnd: number | null = null;
private comboOverlap = false;
private estimatedRetainedBytes = ESTIMATED_ACCUMULATOR_BASE_BYTES;
constructor(options?: {
filter?: { provider?: string | null; model?: string | null; apiKeyId?: string | null };
mode?: UsageAccumulatorMode;
window?: UsageTimeWindow;
}) {
const provider = normalizeFilterValue(options?.filter?.provider);
const model = normalizeFilterValue(options?.filter?.model);
const apiKeyId = normalizeExactFilterValue(options?.filter?.apiKeyId);
this.filter = provider === null && model === null && apiKeyId === null
? null
: { provider, model, apiKeyId };
this.mode = options?.mode ?? "exact";
this.window = options?.window ? Object.freeze({ ...options.window }) : undefined;
this.requestIds = this.mode === "exact" ? new Map() : null;
}
get snapshotWindow(): { start: number | null; end: number | null } {
return { start: this.snapshotStart, end: this.snapshotEnd };
}
get estimatedBytes(): number {
return this.estimatedRetainedBytes;
}
clone(): UsageSummaryAccumulator {
const cloned = new StreamingUsageSummaryAccumulator({
...(this.filter ? { filter: this.filter } : {}),
mode: this.mode,
window: this.window,
});
cloned.nextRequestId = this.nextRequestId;
cloned.nextOrdinal = this.nextOrdinal;
cloned.snapshotStart = this.snapshotStart;
cloned.snapshotEnd = this.snapshotEnd;
cloned.comboOverlap = this.comboOverlap;
cloned.estimatedRetainedBytes = this.estimatedRetainedBytes;
if (this.requestIds && cloned.requestIds) {
for (const [requestId, key] of this.requestIds) cloned.requestIds.set(requestId, key);
}
for (const [key, partition] of this.partitions) {
const models = new Map<string, UsageModelAccumulator>();
for (const [modelKey, model] of partition.models) {
models.set(modelKey, cloneModelAccumulator(model));
}
const providers = partition.providers
? new Map([...partition.providers].map(([providerKey, provider]) => [providerKey, cloneModelAccumulator(provider)]))
: undefined;
const accounts = new Map<string, UsageAccountAccumulator>();
for (const [label, account] of partition.accounts) {
accounts.set(label, cloneAccountAccumulator(account));
}
cloned.partitions.set(key, {
...partition,
totals: { ...partition.totals },
models,
...(providers ? { providers } : {}),
accounts,
modelOverlaps: new Map(
[...partition.modelOverlaps].map(([signature, overlap]) => [signature, { ...overlap }]),
),
});
}
return cloned;
}
private requestKey(requestId: string): number {
if (!this.requestIds) throw new Error("row-unique accumulators do not retain request ids");
const existing = this.requestIds.get(requestId);
if (existing !== undefined) return existing;
const key = this.nextRequestId++;
this.requestIds.set(requestId, key);
this.estimatedRetainedBytes += ESTIMATED_EXACT_REQUEST_ID_BYTES + requestId.length * 2;
return key;
}
private partitionFor(entry: PersistedUsageEntry): UsagePartition {
const date = localDateKey(entry.timestamp);
const dayStart = startOfLocalDay(entry.timestamp);
const surface = usagePartitionSurface(entry);
const key = `${date}\0${surface}`;
let partition = this.partitions.get(key);
if (!partition) {
partition = {
date,
dayStart,
surface,
oldestTimestamp: null,
totals: blankTotals(),
models: new Map(),
...(this.mode === "row-unique" ? { providers: new Map() } : {}),
accounts: new Map(),
modelOverlaps: new Map(),
};
this.partitions.set(key, partition);
this.estimatedRetainedBytes += ESTIMATED_PARTITION_BYTES;
}
if (Number.isFinite(entry.timestamp)) {
partition.oldestTimestamp = partition.oldestTimestamp === null
? entry.timestamp
: Math.min(partition.oldestTimestamp, entry.timestamp);
}
return partition;
}
private addAttributionMetrics(
breakdown: UsageModelAccumulator,
attribution: UsageAttribution,
estimate: AttemptCostEstimate | CostEstimate | null,
): void {
if (attribution.hasUnresolvedRequestedModel) breakdown.hasUnresolvedRequestedModel = true;
breakdown.attemptCount += 1;
if (attribution.usage) {
breakdown.inputTokens += attribution.usage.inputTokens;
breakdown.outputTokens += attribution.usage.outputTokens;
const { read, creation, provenance } = cacheObservationFromUsage(
attribution.usage,
attribution.cacheProvenance,
);
// Only an observation opens the denominator. A synthesized zero and an unreported detail
// both contribute their tokens to inputTokens and nothing to the cache average, which is
// the difference between "no cache reads measured" and "no cache reads happened".
if (provenance === "observed") {
breakdown.cacheObserved = true;
breakdown.cacheObservedInputTokens += attribution.usage.inputTokens;
}
if (typeof read === "number") breakdown.cacheReadInputTokens += read;
if (typeof creation === "number") breakdown.cacheCreationInputTokens += creation;
breakdown.summaryTotalTokens += usageDisplayTotalTokens(attribution.usage, attribution.totalTokens) ?? 0;
}
breakdown.dayTotalTokens += usageDisplayTotalTokens(attribution.usage, attribution.totalTokens) ?? 0;
if (estimate) breakdown.estimatedCostUsd = (breakdown.estimatedCostUsd ?? 0) + estimate.cost.total;
}
private addModelAttribution(
partition: UsagePartition,
attribution: UsageAttribution,
estimate: AttemptCostEstimate | CostEstimate | null,
ordinal: number,
): string {
const provider = baseProviderLabel(attribution.provider);
const key = usageModelKey(provider, attribution.model);
let model = partition.models.get(key);
if (!model) {
model = blankModelAccumulator(provider, attribution.model, attribution.resolvedModel, ordinal, this.mode);
partition.models.set(key, model);
this.estimatedRetainedBytes += ESTIMATED_BREAKDOWN_BYTES + key.length * 2;
}
this.addAttributionMetrics(model, attribution, estimate);
return key;
}
private addProviderAttribution(
partition: UsagePartition,
attribution: UsageAttribution,
estimate: AttemptCostEstimate | CostEstimate | null,
ordinal: number,
): string {
const providerKey = baseProviderLabel(attribution.provider);
const providers = partition.providers;
if (!providers) return providerKey;
let provider = providers.get(providerKey);
if (!provider) {
provider = blankModelAccumulator(providerKey, "", undefined, ordinal, "row-unique");
providers.set(providerKey, provider);
this.estimatedRetainedBytes += ESTIMATED_BREAKDOWN_BYTES + providerKey.length * 2;
}
this.addAttributionMetrics(provider, attribution, estimate);
return providerKey;
}
private addBreakdownRequest(
breakdown: UsageModelAccumulator,
facts: number,
requestKey: number | null,
): void {
if (breakdown.requestFacts) {
if (requestKey === null) throw new Error("exact accumulators require request identity");
const previous = breakdown.requestFacts.get(requestKey);
breakdown.requestFacts.set(requestKey, (previous ?? 0) | facts);
if (previous === undefined) this.estimatedRetainedBytes += ESTIMATED_REQUEST_FACT_BYTES;
return;
}
bumpRequestCounts(breakdown.requestCounts, facts);
}
private addAccountRequest(account: UsageAccountAccumulator, requestKey: number | null): void {
if (account.requestIds) {
if (requestKey === null) throw new Error("exact accumulators require request identity");
const previousSize = account.requestIds.size;
account.requestIds.add(requestKey);
if (account.requestIds.size !== previousSize) {
this.estimatedRetainedBytes += ESTIMATED_ACCOUNT_REQUEST_BYTES;
}
return;
}
account.requests += 1;
}
private addAccountAttribution(
partition: UsagePartition,
attribution: UsageAttribution,
estimate: AttemptCostEstimate | CostEstimate | null,
ordinal: number,
): string | null {
const label = accountLabelForAttribution(attribution.provider, attribution.accountLogLabel);
if (!label) return null;
let account = partition.accounts.get(label);
if (!account) {
account = {
accountLogLabel: label,
ambiguous: label === LEGACY_AMBIGUOUS_ACCOUNT_LABEL,
firstSeen: ordinal,
requests: 0,
...(this.mode === "exact" ? { requestIds: new Set() } : {}),
attemptCount: 0,
measuredAttempts: 0,
reportedAttempts: 0,
estimatedAttempts: 0,
unmeteredAttempts: 0,
inputTokens: 0,
outputTokens: 0,
cacheReadInputTokens: 0,
cacheCreationInputTokens: 0,
reasoningOutputTokens: 0,
totalTokens: 0,
pricedAttempts: 0,
unpricedAttempts: 0,
};
partition.accounts.set(label, account);
this.estimatedRetainedBytes += ESTIMATED_BREAKDOWN_BYTES + label.length * 2;
}
account.attemptCount += 1;
if (!attribution.usage || !isMeasuredStatus(attribution.usageStatus)) {
account.unmeteredAttempts += 1;
return label;
}
account.measuredAttempts += 1;
if (attribution.usageStatus === "reported") account.reportedAttempts += 1;
else if (attribution.usageStatus === "estimated") account.estimatedAttempts += 1;
account.inputTokens += attribution.usage.inputTokens;
account.outputTokens += attribution.usage.outputTokens;
const { read, creation } = cacheTokensFromUsage(attribution.usage);
if (typeof read === "number") account.cacheReadInputTokens += read;
if (typeof creation === "number") account.cacheCreationInputTokens += creation;
if (typeof attribution.usage.reasoningOutputTokens === "number") {
account.reasoningOutputTokens += attribution.usage.reasoningOutputTokens;
}
account.totalTokens += usageDisplayTotalTokens(attribution.usage, attribution.totalTokens) ?? 0;
if (estimate) {
account.pricedAttempts += 1;
account.estimatedCostUsd = (account.estimatedCostUsd ?? 0) + estimate.cost.total;
} else {
account.unpricedAttempts += 1;
}
return label;
}
add(sourceEntry: PersistedUsageEntry): void {
if (Number.isFinite(sourceEntry.timestamp)) {
this.snapshotStart = this.snapshotStart === null
? sourceEntry.timestamp
: Math.min(this.snapshotStart, sourceEntry.timestamp);
this.snapshotEnd = this.snapshotEnd === null
? sourceEntry.timestamp
: Math.max(this.snapshotEnd, sourceEntry.timestamp);
}
if (this.window && (!Number.isFinite(sourceEntry.timestamp)
|| sourceEntry.timestamp < this.window.since || sourceEntry.timestamp > this.window.until)) return;
const projected = this.filter ? projectedEntryForFilter(sourceEntry, this.filter) : { entry: sourceEntry, comboOverlap: false };
if (!projected) return;
this.comboOverlap ||= projected.comboOverlap;
const entry = projected.entry;
const partition = this.partitionFor(entry);
const costInfo = computeEntryCost(entry);
bumpStatus(partition.totals, entry.usageStatus);
partition.totals.attemptCount += entry.attempts?.length ?? 1;
addTokens(partition.totals, entry);
addSpendTotals(partition.totals, entry);
addCacheProvenanceTotals(partition.totals, entry);
addEstimatedCost(partition.totals, entry, costInfo);
const requestKey = this.mode === "exact" ? this.requestKey(entry.requestId) : null;
const attributions = usageAttributions(entry);
const modelFacts = new Map<string, number>();
const providerFacts = new Map<string, number>();
const accountLabels = new Set<string>();
for (let index = 0; index < attributions.length; index++) {
const attribution = attributions[index]!;
const estimate = entry.attempts?.length
? costInfo.attemptEstimates?.[index] ?? null
: costInfo.estimate;
const ordinal = this.nextOrdinal++;
const facts = requestStatusFact(attribution.usageStatus)
| (estimate ? REQUEST_PRICED : REQUEST_UNPRICED);
const modelKey = this.addModelAttribution(partition, attribution, estimate, ordinal);
modelFacts.set(modelKey, (modelFacts.get(modelKey) ?? 0) | facts);
if (this.mode === "row-unique") {
const providerKey = this.addProviderAttribution(partition, attribution, estimate, ordinal);
providerFacts.set(providerKey, (providerFacts.get(providerKey) ?? 0) | facts);
}
const accountLabel = this.addAccountAttribution(partition, attribution, estimate, ordinal);
if (accountLabel) accountLabels.add(accountLabel);
}
for (const [modelKey, facts] of modelFacts) {
this.addBreakdownRequest(partition.models.get(modelKey)!, facts, requestKey);
}
if (partition.providers) {
for (const [providerKey, facts] of providerFacts) {
this.addBreakdownRequest(partition.providers.get(providerKey)!, facts, null);
}
}
for (const label of accountLabels) {
this.addAccountRequest(partition.accounts.get(label)!, requestKey);
}
if (this.mode === "row-unique" && modelFacts.size > 1) {
const models = [...modelFacts].sort(([a], [b]) => a.localeCompare(b));
const signature = JSON.stringify(models);
const overlap = partition.modelOverlaps.get(signature);
if (overlap) {
overlap.count += 1;
} else {
partition.modelOverlaps.set(signature, { models, count: 1 });
this.estimatedRetainedBytes += ESTIMATED_OVERLAP_BYTES
+ models.length * ESTIMATED_OVERLAP_MODEL_BYTES
+ signature.length * 2;
}
}
}
summarize(
range: UsageRange,
now: number,
surface: UsageSurface = "all",
): UsageSummary & { filter?: UsageFilterEcho } {
const preset = rangeWindow(range, now);
const since = this.window?.since ?? preset.since;
const fixedDays = preset.days;
const totals = blankTotals();
const models = new Map<string, UsageModelAccumulator>();
const providers = new Map<string, UsageModelAccumulator>();
const accounts = new Map<string, UsageAccountAccumulator>();
const dayAccumulators = new Map<string, UsageDayAccumulator>();
const modelOverlaps: UsageModelOverlap[] = [];
let oldestTimestamp: number | null = null;
for (const partition of this.partitions.values()) {
if (!usageSurfaceMatches(partition.surface, surface)) continue;
if (!this.window && since !== null && partition.dayStart < since) continue;
mergeTotals(totals, partition.totals);
mergeModelMaps(models, partition.models);
if (partition.providers) mergeModelMaps(providers, partition.providers);
modelOverlaps.push(...partition.modelOverlaps.values());
for (const [label, account] of partition.accounts) {
const current = accounts.get(label);
if (current) mergeAccountAccumulator(current, account);
else accounts.set(label, cloneAccountAccumulator(account));
}
if (partition.oldestTimestamp !== null) {
oldestTimestamp = oldestTimestamp === null
? partition.oldestTimestamp
: Math.min(oldestTimestamp, partition.oldestTimestamp);
}
let day = dayAccumulators.get(partition.date);
if (!day) {
day = { totals: blankTotals(), models: new Map(), modelOverlaps: [] };
dayAccumulators.set(partition.date, day);
}
mergeTotals(day.totals, partition.totals);
mergeModelMaps(day.models, partition.models);
day.modelOverlaps.push(...partition.modelOverlaps.values());
}
finalizeCoverage(totals);
const customDates = this.window ? new Set(customWindowDates(this.window)) : null;
const dayCount = customDates?.size ?? (range === "all" ? dayCountForAllRange(oldestTimestamp, now) : fixedDays);
const startOfToday = startOfLocalDay(this.window?.until ?? now);
const firstVisibleDay = new Date(startOfToday);
firstVisibleDay.setDate(firstVisibleDay.getDate() - dayCount + 1);
const firstVisibleDate = localDateKey(firstVisibleDay.getTime());
const lastVisibleDate = localDateKey(startOfToday);
const visibleDates = customDates ?? new Set<string>();
for (let offset = dayCount - 1; !customDates && offset >= 0; offset--) {
const date = new Date(startOfToday);
date.setDate(date.getDate() - offset);
visibleDates.add(localDateKey(date.getTime()));
}
for (const key of visibleDates) {
if (!dayAccumulators.has(key)) {
dayAccumulators.set(key, { totals: blankTotals(), models: new Map(), modelOverlaps: [] });
}
}
const visibleDays = customDates
? [...customDates].map(date => [date, dayAccumulators.get(date)!] as const)
: [...dayAccumulators]
// All-history totals, models, providers, and accounts still cover every
// retained row. Only the chart buckets are bounded so one malformed or
// ancient timestamp cannot synthesize an enormous JSON response.
.filter(([date]) => range !== "all"
|| (date >= firstVisibleDate && date <= lastVisibleDate))
.sort(([a], [b]) => a.localeCompare(b));
const days = visibleDays
.map(([date, day]): UsageDay => ({
date,
requests: day.totals.requests,
measuredRequests: day.totals.measuredRequests,
reportedRequests: day.totals.reportedRequests,
totalTokens: day.totals.totalTokens,
estimatedCostUsd: day.totals.estimatedCostUsd,
models: buildDayModels(day.models, day.modelOverlaps),
}));
const summary: UsageSummary = {
range,
surface,
since,
...(this.window ? { customWindow: true as const, until: this.window.until } : {}),
generatedAt: now,
summary: totals,
days,
models: buildUsageModels(models, totals.totalTokens, modelOverlaps),
providers: buildUsageProviders(this.mode === "row-unique" ? providers : models, totals.totalTokens),
accounts: buildUsageAccounts(accounts),
};
if (!this.filter) return summary;
const matches = (provider: string, model: string): boolean =>
filterMatchesAttribution(this.filter!, provider, model);
const retainedModels = summary.models.filter(row => matches(row.provider, row.model));
const retainedProviders = new Set(retainedModels.map(row => row.provider));
return {
...summary,
days: summary.days.map(day => ({
...day,
models: day.models.filter(row => matches(row.provider, row.model)),
})),
models: retainedModels,
providers: summary.providers.filter(row => retainedProviders.has(row.provider)),
accounts: this.filter.provider === null && this.filter.model === null
? summary.accounts
: [],
filter: {
provider: this.filter.provider,
model: this.filter.model,
apiKeyId: this.filter.apiKeyId,
matched: summary.summary.requests > 0,
comboOverlap: this.comboOverlap,
},
};
}
}
export function createUsageSummaryAccumulator(options?: {
filter?: { provider?: string | null; model?: string | null; apiKeyId?: string | null };
mode?: UsageAccumulatorMode;
window?: UsageTimeWindow;
}): UsageSummaryAccumulator {
return new StreamingUsageSummaryAccumulator(options);
}
export function summarizeUsage(
entries: PersistedUsageEntry[],
range: UsageRange,
now: number,
surface: UsageSurface = "all",
): UsageSummary {
const accumulator = createUsageSummaryAccumulator();
for (const entry of entries) accumulator.add(entry);
return accumulator.summarize(range, now, surface);
}
function normalizeFilterValue(input: string | null | undefined): string | null {
const trimmed = typeof input === "string" ? input.trim() : "";
return trimmed === "" ? null : trimmed.toLowerCase();
}
function normalizeExactFilterValue(input: string | null | undefined): string | null {
const trimmed = typeof input === "string" ? input.trim() : "";
return trimmed === "" ? null : trimmed;
}
/**
* Narrow an already-summarised window to one provider and/or model.
*
* The compatibility wrapper feeds source rows through a filter-bound streaming
* accumulator. The management route can use the same accumulator directly and
* still keep filtered results outside its unfiltered `range:surface` cache.
*
* Totals are recomputed from the retained rows. For combo traffic a request is
* counted once per participating model, so a filtered request count can exceed
* the number of distinct requests; `comboOverlap` reports when that is
* possible. Cost is unaffected — combo cost is attributed per attempt, so it
* partitions across models rather than repeating.
*
* `accounts` is emptied whenever a filter is active: account rows are not
* provider-partitioned in a way this projection could honestly re-derive, and
* unfiltered account totals sitting beside filtered model totals would invite
* exactly the wrong reading.
*/
export function projectUsageSummary<T extends UsageSummary>(
summary: T,
filter: { provider?: string | null; model?: string | null; apiKeyId?: string | null },
entries?: PersistedUsageEntry[],
): T & { filter?: UsageFilterEcho } {
const provider = normalizeFilterValue(filter.provider);
const model = normalizeFilterValue(filter.model);
const apiKeyId = normalizeExactFilterValue(filter.apiKeyId);
if (provider === null && model === null && apiKeyId === null) return summary;
const accumulator = createUsageSummaryAccumulator({
filter: { provider, model, apiKeyId },
...(summary.customWindow && summary.since !== null && summary.until !== undefined
? { window: { since: summary.since, until: summary.until } } : {}),
});
for (const entry of entries ?? []) accumulator.add(entry);
const projected = accumulator.summarize(summary.range, summary.generatedAt, summary.surface);
return {
...summary,
summary: projected.summary,
days: projected.days,
models: projected.models,
providers: projected.providers,
accounts: projected.accounts,
filter: projected.filter,
};
}