// Native snapshots, not tokenizers, pricing estimates, or accumulated deltas. const count = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? (value === 0 ? 0 : value) : null; const amount = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? (value === 0 ? 0 : value) : null; export function normalizeChatUsage(usage) { if (!usage || typeof usage !== "object" || Array.isArray(usage)) return null; const window = count(usage.context_window); const result = { scope: ["session", "turn"].includes(usage.scope) ? usage.scope : "", total_tokens: count(usage.total_tokens), context_tokens: count(usage.context_tokens), context_window: window > 0 ? window : null, cost_usd: amount(usage.cost_usd), output_tokens_per_second: amount(usage.output_tokens_per_second), rate_basis: ["generation", "turn"].includes(usage.rate_basis) ? usage.rate_basis : "", }; // Legacy input/output counters do not prove a total that includes cache and // reasoning; legacy zero-valued costs cannot distinguish unknown from free. return result.scope || Object.entries(result).some(([key, value]) => key !== "scope" && key !== "rate_basis" && value !== null) ? result : null; } export function chatUsageMetrics(value, locale) { const usage = normalizeChatUsage(value); const integer = new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }); const decimal = new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }); const dollars = new Intl.NumberFormat(locale, { style: "currency", currency: "USD", minimumFractionDigits: 4, maximumFractionDigits: 6 }); const metric = (key, label, number, format, title) => ({ key, label, available: number !== null && number !== undefined, value: number === null || number === undefined ? "Unavailable" : format(number), title }); const rateTitle = usage?.rate_basis === "turn" ? "Average output tokens per second over the measured turn, including tools and waiting." : usage?.rate_basis === "generation" ? "Non-reasoning output tokens per second over the latest native request-to-stream-completion interval, including request latency but excluding tool execution." : "Native output-token rate when reported; never estimated from text length."; const used = usage?.context_tokens ?? null; const limit = usage?.context_window ?? null; const context = used !== null && limit !== null ? `${integer.format(used)} / ${integer.format(limit)}` : limit !== null ? `${integer.format(limit)} limit` : used !== null ? `${integer.format(used)} used` : "Unavailable"; return [ metric("rate", usage?.rate_basis === "turn" ? "Avg output rate" : "Output rate", usage?.output_tokens_per_second, (number) => `${number > 0 && number < 0.1 ? "<" + decimal.format(0.1) : decimal.format(number)} tok/s`, rateTitle), metric("tokens", usage?.scope === "turn" ? "Turn tokens" : "Total tokens", usage?.total_tokens, (number) => integer.format(number), usage?.scope === "turn" ? "Reported token total for the measured turn. Snapshots are not added together." : "Reported token total across the conversation's model calls, not the current context size. Snapshots are not added together."), { key: "context", label: "Context", available: used !== null || limit !== null, value: context, title: "Latest reported prompt/context usage / model context-window limit. Harness accounting may differ; cumulative processed tokens are not context usage." }, metric("cost", "Reported cost", usage?.cost_usd, (number) => number > 0 && number < 0.000001 ? "<" + dollars.format(0.000001) : dollars.format(number), "USD cost reported by the harness, not a subscription invoice. We do not estimate unreported costs or infer subscription billing."), ]; }