@linxiraos/pi-stats 1.0.10 → 1.1.1

package/src/index.ts

@@ -39,10 +39,9 @@ export type {
 	ToolUsageStats,
 } from "./types";
 
-/**
- * Format cost in dollars.
- */
-function formatCost(n: number): string {
+/** Format an API-equivalent estimate in dollars, or N/A for unpriced usage. */
+function formatCost(n: number, unpricedRequests = 0): string {
+	if (n === 0 && unpricedRequests > 0) return "N/A";
 	if (n < 0.01) return `$${n.toFixed(4)}`;
 	if (n < 1) return `$${n.toFixed(3)}`;
 	return `$${n.toFixed(2)}`;
@@ -69,7 +68,7 @@ async function printStats(): Promise<void> {
 	console.log(`  Output Tokens: ${formatNumber(overall.totalOutputTokens)}`);
 	console.log(`  Cache Rate: ${formatPercent(overall.cacheRate)}`);
 	console.log(`  Cache Savings: ${formatPercent(overall.cacheSavings)}`);
-	console.log(`  Total Cost: ${formatCost(overall.totalCost)}`);
+	console.log(`  API-equivalent estimate: ${formatCost(overall.totalCost, overall.unpricedRequests)}`);
 	console.log(`  Premium Requests: ${formatNumber(normalizePremiumRequests(overall.totalPremiumRequests ?? 0))}`);
 	console.log(`  Avg Duration: ${overall.avgDuration !== null ? formatDuration(overall.avgDuration) : "-"}`);
 	console.log(`  Avg TTFT: ${overall.avgTtft !== null ? formatDuration(overall.avgTtft) : "-"}`);
@@ -78,18 +77,20 @@ async function printStats(): Promise<void> {
 	}
 
 	if (byModel.length > 0) {
-		console.log("\nBy Model:");
+		console.log("\nBy Model (API-equivalent estimates):");
 		for (const m of byModel.slice(0, 10)) {
 			console.log(
-				`  ${m.model}: ${formatNumber(m.totalRequests)} reqs, ${formatCost(m.totalCost)}, ${formatPercent(m.cacheRate)} cache rate, ${formatPercent(m.cacheSavings)} cache savings`,
+				`  ${m.model}: ${formatNumber(m.totalRequests)} reqs, ${formatCost(m.totalCost, m.unpricedRequests)}, ${formatPercent(m.cacheRate)} cache rate, ${formatPercent(m.cacheSavings)} cache savings`,
 			);
 		}
 	}
 
 	if (byFolder.length > 0) {
-		console.log("\nBy Folder:");
+		console.log("\nBy Folder (API-equivalent estimates):");
 		for (const f of byFolder.slice(0, 10)) {
-			console.log(`  ${f.folder}: ${formatNumber(f.totalRequests)} reqs, ${formatCost(f.totalCost)}`);
+			console.log(
+				`  ${f.folder}: ${formatNumber(f.totalRequests)} reqs, ${formatCost(f.totalCost, f.unpricedRequests)}`,
+			);
 		}
 	}
 

package/src/server.ts

@@ -8,6 +8,7 @@ import {
 	getBehaviorDashboardStats,
 	getCostDashboardStats,
 	getDashboardStats,
+	getFolderStats,
 	getModelDashboardStats,
 	getOverviewStats,
 	getProviderDashboardStats,
@@ -253,8 +254,8 @@ export async function handleApi(req: Request): Promise<Response> {
 	}
 
 	if (path === "/api/stats/folders") {
-		const stats = await getDashboardStats(range);
-		return Response.json(stats.byFolder);
+		const stats = await getFolderStats(range);
+		return Response.json(stats);
 	}
 
 	if (path === "/api/stats/timeseries") {

package/src/shared-types.ts

@@ -34,6 +34,8 @@ export interface AggregatedStats {
 	cacheSavings: number;
 	/** Total cost */
 	totalCost: number;
+	/** Requests with token usage but no public-equivalent subscription price. */
+	unpricedRequests: number;
 	/** Total premium requests */
 	totalPremiumRequests: number;
 	/** Average duration in ms */
@@ -122,6 +124,8 @@ export interface CostTimeSeriesPoint {
 	provider: string;
 	/** Total cost for this bucket */
 	cost: number;
+	/** Requests excluded because no public-equivalent subscription price exists. */
+	unpricedRequests: number;
 	/** Cost breakdown */
 	costInput: number;
 	costOutput: number;
@@ -302,6 +306,8 @@ export interface ToolUsageStats {
 	outputTokensShare: number;
 	/** Cost (USD) of invoking turns, attributed per call share. */
 	costShare: number;
+	/** Share of unpriced subscription requests attributed to this tool. */
+	unpricedRequestsShare: number;
 	/** Unix ms of the most recent call in range. */
 	lastUsed: number;
 }
@@ -343,6 +349,8 @@ export interface ProviderAggregate {
 	/** Uncached input + cache reads + cache writes + output. */
 	totalTokens: number;
 	totalCost: number;
+	/** Requests excluded because no public-equivalent subscription price exists. */
+	unpricedRequests: number;
 	totalPremiumRequests: number;
 	avgTokensPerSecond: number | null;
 }
@@ -366,6 +374,8 @@ export interface ProviderTimeSeriesPoint {
 	provider: string;
 	totalTokens: number;
 	cost: number;
+	/** Requests excluded because no public-equivalent subscription price exists. */
+	unpricedRequests: number;
 	requests: number;
 }
 
@@ -386,8 +396,9 @@ export interface UsageWindowSeries {
 	accountKey: string;
 	/** Email/account id when known, else the stable account key. */
 	accountLabel: string;
-	/** Groups the same limit window across accounts (window label or limit id). */
+	/** Groups the same limit window across accounts (the provider limit id). */
 	windowKey: string;
+	/** Human label of the limit (distinguishes same-duration windows). */
 	windowLabel: string;
 	points: UsageWindowPoint[];
 }
@@ -399,7 +410,9 @@ export interface UsageWindowSeries {
  */
 export interface ProviderWindowInsight {
 	provider: string;
+	/** Groups the same limit window across accounts (the provider limit id). */
 	windowKey: string;
+	/** Human label of the limit (distinguishes same-duration windows). */
 	windowLabel: string;
 	/** Accounts with at least one snapshot for this window in range. */
 	accounts: number;

package/src/usage-windows.ts

@@ -14,6 +14,7 @@
  */
 import { Database } from "bun:sqlite";
 import { AuthBrokerClient, resolveAuthBrokerConfig } from "@linxiraos/pi-ai/auth-broker";
+import type { ClientUsageClientSummary } from "@linxiraos/pi-ai/usage";
 import { getAgentDbPath, logger } from "@linxiraos/pi-utils";
 import type { ProviderWindowInsight, UsageWindowPoint, UsageWindowSeries } from "./shared-types";
 
@@ -40,6 +41,19 @@ export interface UsageWindowStats {
 	windowInsights: ProviderWindowInsight[];
 }
 
+/** Usage snapshots plus, in broker mode, fleet-wide token burn per provider. */
+export interface UsageDataSnapshot {
+	rows: UsageSnapshotRow[];
+	/**
+	 * Total tokens (input + output + cache read/write) per provider summed
+	 * across every install reporting to the auth broker, or `null` when no
+	 * broker is configured or no client reports exist for the range. Matches
+	 * the fleet-wide window fractions in `rows`, unlike local message stats
+	 * which only see this install's burn.
+	 */
+	fleetTokensByProvider: Map<string, number> | null;
+}
+
 /** A used-fraction drop smaller than this is jitter, not a window reset. */
 const RESET_DROP_THRESHOLD = 0.05;
 /** Minimum window-equivalents consumed before extrapolating tokens/window. */
@@ -101,35 +115,74 @@ export function readUsageSnapshots(sinceMs: number, dbPath = getAgentDbPath()):
 }
 
 /**
- * Fetch usage snapshots from wherever they actually accumulate: the auth
- * broker's durable history when a broker is configured (the broker performs
- * every upstream usage fetch in that mode, so the local `usage_history` stays
- * frozen), else the local agent DB. Broker errors fall back to the local read
- * so the dashboard degrades to stale-but-present data instead of failing.
+ * Fetch usage data from wherever it actually accumulates: the auth broker's
+ * durable history plus per-client observed-usage reports when a broker is
+ * configured (the broker performs every upstream usage fetch in that mode, so
+ * the local `usage_history` stays frozen), else the local agent DB. Broker
+ * errors fall back to the local read so the dashboard degrades to
+ * stale-but-present data instead of failing.
  */
-export async function fetchUsageSnapshots(sinceMs: number): Promise<UsageSnapshotRow[]> {
+export async function fetchUsageData(sinceMs: number): Promise<UsageDataSnapshot> {
 	try {
 		const brokerConfig = await resolveAuthBrokerConfig();
 		if (brokerConfig) {
 			const client = new AuthBrokerClient({ url: brokerConfig.url, token: brokerConfig.token });
-			const response = await client.fetchUsageHistory({ sinceMs });
-			return response.entries.map(entry => ({
-				recordedAt: entry.recordedAt,
-				provider: entry.provider,
-				accountKey: entry.accountKey,
-				email: entry.email ?? null,
-				accountId: entry.accountId ?? null,
-				limitId: entry.limitId,
-				label: entry.label,
-				windowLabel: entry.windowLabel ?? null,
-				usedFraction: entry.usedFraction ?? null,
-				status: entry.status ?? null,
-			}));
+			const [response, fleetTokensByProvider] = await Promise.all([
+				client.fetchUsageHistory({ sinceMs }),
+				fetchFleetTokens(client, sinceMs),
+			]);
+			return {
+				rows: response.entries.map(entry => ({
+					recordedAt: entry.recordedAt,
+					provider: entry.provider,
+					accountKey: entry.accountKey,
+					email: entry.email ?? null,
+					accountId: entry.accountId ?? null,
+					limitId: entry.limitId,
+					label: entry.label,
+					windowLabel: entry.windowLabel ?? null,
+					usedFraction: entry.usedFraction ?? null,
+					status: entry.status ?? null,
+				})),
+				fleetTokensByProvider,
+			};
 		}
 	} catch (err) {
 		logger.debug("broker usage history unavailable, falling back to local", { error: String(err) });
 	}
-	return readUsageSnapshots(sinceMs);
+	return { rows: readUsageSnapshots(sinceMs), fleetTokensByProvider: null };
+}
+
+/**
+ * Sum broker-recorded client token burn per provider since `sinceMs`.
+ * Returns `null` on fetch failure or when no client has reported usage, so
+ * callers fall back to local message stats instead of zeroing estimates.
+ */
+async function fetchFleetTokens(client: AuthBrokerClient, sinceMs: number): Promise<Map<string, number> | null> {
+	try {
+		const summary = await client.fetchClientUsageSummary({ sinceMs });
+		return sumFleetTokens(summary.clients);
+	} catch (err) {
+		logger.debug("broker client usage summary unavailable", { error: String(err) });
+		return null;
+	}
+}
+
+/**
+ * Fold per-client provider aggregates into total tokens per provider
+ * (input + output + cache read/write, matching message-stat `totalTokens`).
+ * Returns `null` when no client reported anything, signalling "no data"
+ * rather than "zero burn".
+ */
+export function sumFleetTokens(clients: ClientUsageClientSummary[]): Map<string, number> | null {
+	const tokens = new Map<string, number>();
+	for (const client of clients) {
+		for (const p of client.providers) {
+			const total = p.inputTokens + p.outputTokens + p.cacheReadTokens + p.cacheWriteTokens;
+			tokens.set(p.provider, (tokens.get(p.provider) ?? 0) + total);
+		}
+	}
+	return tokens.size > 0 ? tokens : null;
 }
 
 /** True when a snapshot reports an exhausted window, by status or by fraction. */
@@ -175,14 +228,33 @@ interface WindowGroup {
 	accounts: Map<string, AccountSeries>;
 }
 
+/**
+ * Display label for one limit window: the limit label, plus the window label
+ * when it adds information ("Usage (Google) · Daily"). The limit label alone
+ * distinguishes same-duration windows ("Claude 7 Day" vs "Claude 7 Day
+ * (Fable)"); the window-label suffix distinguishes same-named limits with
+ * different durations (Antigravity's daily vs weekly "Usage (Google)").
+ */
+function windowDisplayLabel(row: UsageSnapshotRow): string {
+	const { label, windowLabel } = row;
+	if (!windowLabel || label.toLowerCase().includes(windowLabel.toLowerCase())) return label;
+	return `${label} · ${windowLabel}`;
+}
+
 /**
  * Derive utilization series and per-window insights from raw snapshots.
  *
+ * Windows are grouped by `(provider, limitId)` — never by display label.
+ * Distinct limits can share a duration label (Anthropic's overall and
+ * model-scoped 7-day windows, Codex's base and Spark weeklies); merging them
+ * interleaves unrelated fractions per account and wildly inflates consumption.
+ *
  * `tokensByProvider` supplies each provider's token burn over the same time
- * range (from the local message stats); it converts consumed window fraction
- * into an estimated token capacity per window. Attribution note: tokens are
- * per provider, not per account, so the estimate treats the account fleet as
- * one pooled subscription — which is exactly how round-robin auth uses it.
+ * range (fleet-wide broker client reports when available, else local message
+ * stats); it converts consumed window fraction into an estimated token
+ * capacity per window. Attribution note: tokens are per provider, not per
+ * account, so the estimate treats the account fleet as one pooled
+ * subscription — which is exactly how round-robin auth uses it.
  */
 export function computeUsageWindowStats(
 	rows: UsageSnapshotRow[],
@@ -190,15 +262,19 @@ export function computeUsageWindowStats(
 ): UsageWindowStats {
 	const groups = new Map<string, WindowGroup>();
 	for (const row of rows) {
-		const windowKey = row.windowLabel ?? row.limitId;
-		const groupKey = `${row.provider}\u0000${windowKey}`;
+		const groupKey = `${row.provider}\u0000${row.limitId}`;
 		let group = groups.get(groupKey);
 		if (!group) {
-			group = { provider: row.provider, windowKey, windowLabel: row.windowLabel ?? row.label, accounts: new Map() };
+			group = {
+				provider: row.provider,
+				windowKey: row.limitId,
+				windowLabel: windowDisplayLabel(row),
+				accounts: new Map(),
+			};
 			groups.set(groupKey, group);
 		}
 		// Labels can change across snapshots (provider renames); latest wins.
-		group.windowLabel = row.windowLabel ?? row.label;
+		group.windowLabel = windowDisplayLabel(row);
 		let account = group.accounts.get(row.accountKey);
 		if (!account) {
 			account = { accountKey: row.accountKey, accountLabel: row.email ?? row.accountId ?? row.accountKey, rows: [] };