@oh-my-pi/omp-stats 17.3.8 → 17.4.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [17.4.0] - 2026-08-20
+
+### Changed
+
+- Window token estimates now incorporate broker-reported fleet token burn when an auth broker is configured, accurately tracking fleet-wide usage instead of undercounting with local-only statistics.
+
+### Fixed
+
+- Fixed an issue in subscription-window insights where distinct limits sharing a duration label (such as Anthropic overall vs. model-scoped 7-day windows) were incorrectly merged, which inflated window-equivalents and skewed tokens-per-window estimates. Windows are now grouped by provider limit ID.
+
 ## [17.3.6] - 2026-08-17
 
 ### Fixed

package/dist/types/aggregator.d.ts

@@ -96,6 +96,10 @@ export declare function getToolDashboardStats(range?: string | null): Promise<To
  * Get the providers dashboard payload: per-provider totals, peak-burn-hours
  * histogram, provider token time series, and subscription-window analytics
  * (utilization series + insights) derived from recorded usage-limit snapshots.
+ *
+ * Window token estimates use broker-held fleet token burn when a broker is
+ * configured — the window fractions cover every install sharing the broker's
+ * credentials, so dividing them into local-only tokens would undercount.
  */
 export declare function getProviderDashboardStats(range?: string | null): Promise<ProviderDashboardStats>;
 export {};

package/dist/types/shared-types.d.ts

@@ -359,8 +359,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[];
 }
@@ -371,7 +372,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/dist/types/usage-windows.d.ts

@@ -1,3 +1,4 @@
+import type { ClientUsageClientSummary } from "@oh-my-pi/pi-ai/usage";
 import type { ProviderWindowInsight, UsageWindowSeries } from "./shared-types.js";
 /** Subset of a `usage_history` row consumed by the window analytics. */
 export interface UsageSnapshotRow {
@@ -20,26 +21,52 @@ export interface UsageWindowStats {
     usageSeries: UsageWindowSeries[];
     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;
+}
 /**
  * Read usage-limit snapshots recorded at or after `sinceMs`, oldest first.
  * Opens the agent DB read-only; returns `[]` when the DB or table is absent.
  */
 export declare function readUsageSnapshots(sinceMs: number, dbPath?: string): UsageSnapshotRow[];
 /**
- * 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 declare function fetchUsageData(sinceMs: number): Promise<UsageDataSnapshot>;
+/**
+ * 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 declare function fetchUsageSnapshots(sinceMs: number): Promise<UsageSnapshotRow[]>;
+export declare function sumFleetTokens(clients: ClientUsageClientSummary[]): Map<string, number> | null;
 /**
  * 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 declare function computeUsageWindowStats(rows: UsageSnapshotRow[], tokensByProvider: ReadonlyMap<string, number>): UsageWindowStats;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/omp-stats",
-	"version": "17.3.8",
+	"version": "17.4.0",
 	"description": "Local observability dashboard for pi AI usage statistics",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -39,9 +39,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-ai": "17.3.8",
-		"@oh-my-pi/pi-catalog": "17.3.8",
-		"@oh-my-pi/pi-utils": "17.3.8",
+		"@oh-my-pi/pi-ai": "17.4.0",
+		"@oh-my-pi/pi-catalog": "17.4.0",
+		"@oh-my-pi/pi-utils": "17.4.0",
 		"@tailwindcss/node": "^4.3.2",
 		"chart.js": "^4.5.1",
 		"lucide-react": "^1.24.0",

package/src/aggregator.ts

@@ -48,7 +48,7 @@ import type {
 	RequestDetails,
 	ToolDashboardStats,
 } from "./types";
-import { computeUsageWindowStats, fetchUsageSnapshots } from "./usage-windows";
+import { computeUsageWindowStats, fetchUsageData } from "./usage-windows";
 
 const STATS_SYNC_LOCK_RETRY_MS = 25;
 const STATS_SYNC_LOCK_WAIT_MS = 60 * 60 * 1000;
@@ -544,14 +544,18 @@ export async function getToolDashboardStats(range?: string | null): Promise<Tool
  * Get the providers dashboard payload: per-provider totals, peak-burn-hours
  * histogram, provider token time series, and subscription-window analytics
  * (utilization series + insights) derived from recorded usage-limit snapshots.
+ *
+ * Window token estimates use broker-held fleet token burn when a broker is
+ * configured — the window fractions cover every install sharing the broker's
+ * credentials, so dividing them into local-only tokens would undercount.
  */
 export async function getProviderDashboardStats(range?: string | null): Promise<ProviderDashboardStats> {
 	await initDb();
 	const { modelSeriesDays, modelSeriesBucketMs, cutoff } = getTimeRangeConfig(range);
 	const providers = getStatsByProvider(cutoff ?? undefined);
-	const tokensByProvider = new Map(providers.map(p => [p.provider, p.totalTokens]));
-	const snapshots = await fetchUsageSnapshots(cutoff ?? 0);
-	const { usageSeries, windowInsights } = computeUsageWindowStats(snapshots, tokensByProvider);
+	const usage = await fetchUsageData(cutoff ?? 0);
+	const tokensByProvider = usage.fleetTokensByProvider ?? new Map(providers.map(p => [p.provider, p.totalTokens]));
+	const { usageSeries, windowInsights } = computeUsageWindowStats(usage.rows, tokensByProvider);
 	return {
 		providers,
 		hourly: getProviderHourlyBurn(cutoff ?? undefined),

package/src/shared-types.ts

@@ -386,8 +386,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 +400,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 "@oh-my-pi/pi-ai/auth-broker";
+import type { ClientUsageClientSummary } from "@oh-my-pi/pi-ai/usage";
 import { getAgentDbPath, logger } from "@oh-my-pi/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: [] };