pi-antigravity-rotator 1.7.0 → 1.8.3

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [1.8.2] - 2026-04-29
+
+### Fixed
+- **Token Usage Overcounting**: `getTokenUsage()` was summing `minutes + hours + days + months` buckets, which are hierarchical rollups of the same data — causing every token to be counted ~4×. Now reads only the raw `minutes` buckets (source of truth). Telemetry payload corrected accordingly. Historical JSONL data on the receiver was inflated; divide by ~4 for real estimates.
+- **Telemetry Dashboard Filters**: Added server-side filtering to `/v1/stats` by `installId`, `version`, `os`, `model`, `from`, `to` query params.
+- **Telemetry Web Dashboard**: Added interactive filter bar with auto-populated dropdowns for all filter dimensions. Active filter indicator shows current scope. Auto-refresh respects active filters.
+- **Telemetry Endpoint**: Updated to `http://telemetry.dragont.ec:3800/v1/events` (port explicit until reverse proxy is configured).
+
+## [1.8.0] - 2026-04-29
+
+### Added
+- **Anonymous Telemetry**: Opt-out telemetry to help understand real-world usage and, crucially, to improve the anti-flag algorithm that protects your accounts. Collects pool metrics, error patterns, and flag triggers without capturing any PII or emails.
+- **Telemetry Receiver**: Included a standalone Node.js server (`tools/telemetry-receiver/`) for deploying your own instance to collect telemetry securely via JSONL files.
+- **Server-Side Savings Calculation**: The receiver now computes estimated USD savings directly from raw per-model token usage reports, ensuring pricing updates don't require client updates.
+- **Star Reminder**: A one-time, non-intrusive terminal prompt shown after 24 hours of successful use, encouraging a GitHub star.
 
 ## [1.7.0] - 2026-04-29
 

package/README.md

@@ -320,6 +320,58 @@ The proxy now returns `503` and waits for cooldown or manual recovery. It does n
 **Multiple agents on different models**
 This is fully supported. Each model routes independently. Agent 1 using Gemini Pro and Agent 2 using Claude will each have their own active account and won't interfere with each other's rotation.
 
+## Telemetry
+
+pi-antigravity-rotator collects **anonymous usage telemetry** to help understand how the tool is used and — most importantly — to improve the anti-flag algorithm that protects your accounts.
+
+### What is collected
+
+**Heartbeat** (at boot, every 6h, at shutdown):
+- Random install ID (UUID — not tied to any account or person)
+- Rotator version, Node.js version, OS, architecture
+- Account count, models in use, total request count, uptime
+- Routing health state (healthy/paused/stopped)
+- Flagged/disabled/pro/free account counts
+- Per-model token usage (input/output tokens + request count per model)
+- Feature usage flags (dashboard opened, login used, etc. — booleans only)
+
+**Flag events** (sent immediately when Google flags an account):
+- HTTP status that triggered the flag (401 or 403)
+- Which known patterns matched (e.g. `infring`, `abus`, `suspend` — from a fixed allowlist)
+- Model being requested, quota timer type, quota percentage
+- Account request velocity (requests/hour), concurrent requests, lifetime requests
+- Pool state: size, healthy count, whether protective pause triggered
+- Time since previous flag
+
+Flag data is the most valuable signal. It lets us study what behavior patterns lead to flags and improve the rotation algorithm to avoid them — benefiting everyone.
+
+### What is NEVER collected
+
+- ❌ Email addresses
+- ❌ OAuth tokens or API keys
+- ❌ IP addresses
+- ❌ Google project IDs
+- ❌ Request/response bodies
+- ❌ Error message text (only which known keywords matched)
+
+### Endpoint
+
+Telemetry posts to:
+
+```bash
+http://telemetry.dragont.ec:3800/v1/events
+```
+
+### Opt out
+
+Set the environment variable before starting:
+
+```bash
+export PI_ROTATOR_TELEMETRY=off
+```
+
+Or use any of: `PI_ROTATOR_TELEMETRY=false`, `PI_ROTATOR_TELEMETRY=0`.
+
 ## Support Me
 
 If this tool has helped you optimize your API usage and save costs, consider supporting its development!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-antigravity-rotator",
-  "version": "1.7.0",
+  "version": "1.8.3",
   "description": "Multi-account rotation proxy for Google Antigravity with per-model routing, real-time quota tracking, and infringement detection",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,7 @@
   "files": [
     "bin/",
     "src/",
+    "tools/telemetry-receiver/",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"

package/src/index.ts

@@ -1,11 +1,13 @@
 // Entry point - loads config and starts the proxy
 
-import { readFileSync, existsSync } from "node:fs";
+import { readFileSync, existsSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import type { Config } from "./types.js";
 import { AccountRotator } from "./rotator.js";
 import { startProxy } from "./proxy.js";
-import { getAccountsPath } from "./paths.js";
+import { getAccountsPath, getConfigDir } from "./paths.js";
 import { formatValidationErrors, validateConfig } from "./validators.js";
+import { TelemetryReporter, setActiveReporter } from "./telemetry.js";
 
 function loadConfig(): Config {
 	const configPath = getAccountsPath();
@@ -47,6 +49,46 @@ function loadConfig(): Config {
 	}
 }
 
+const TWENTY_FOUR_HOURS_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Show a one-time, non-intrusive star reminder after 24h since first install.
+ * Creates .first-boot on first run, shows prompt once after 24h,
+ * then writes .star-prompted so it never appears again.
+ */
+function maybeShowStarNudge(): void {
+	const dir = getConfigDir();
+	const promptedPath = join(dir, ".star-prompted");
+	if (existsSync(promptedPath)) return; // already shown, done forever
+
+	const firstBootPath = join(dir, ".first-boot");
+	let firstBootMs: number;
+
+	if (existsSync(firstBootPath)) {
+		try {
+			firstBootMs = parseInt(readFileSync(firstBootPath, "utf-8").trim(), 10);
+			if (Number.isNaN(firstBootMs)) return;
+		} catch { return; }
+	} else {
+		// First ever boot — record timestamp
+		firstBootMs = Date.now();
+		try { writeFileSync(firstBootPath, String(firstBootMs), "utf-8"); } catch { /* best effort */ }
+		return; // too early, come back after 24h
+	}
+
+	if (Date.now() - firstBootMs < TWENTY_FOUR_HOURS_MS) return; // not yet
+
+	// Show it once
+	console.log("  ╭──────────────────────────────────────────────────────────╮");
+	console.log("  │  ⭐ Enjoying pi-antigravity-rotator?                     │");
+	console.log("  │  github.com/tuxevil/pi-antigravity-rotator              │");
+	console.log("  │  A star helps others find it. Thanks!                   │");
+	console.log("  ╰──────────────────────────────────────────────────────────╯");
+	console.log();
+
+	try { writeFileSync(promptedPath, String(Date.now()), "utf-8"); } catch { /* best effort */ }
+}
+
 export function main(): void {
 	console.log("=== Pi Antigravity Rotator ===");
 	console.log();
@@ -64,7 +106,52 @@ export function main(): void {
 	}
 	console.log();
 
+	maybeShowStarNudge();
+
 	const rotator = new AccountRotator(config);
+
+	// ── Telemetry (anonymous, opt-out via PI_ROTATOR_TELEMETRY=off) ──
+	const telemetry = new TelemetryReporter(() => {
+		const status = rotator.getStatus();
+
+		// Use getTokenUsage() which correctly reads only the raw minutes buckets
+		const tu = rotator.getTokenUsage();
+		const tokensByModel: Record<string, { input: number; output: number; requests: number }> = {};
+		for (const b of tu.minutes) {
+			for (const [model, data] of Object.entries(b.byModel)) {
+				if (!tokensByModel[model]) tokensByModel[model] = { input: 0, output: 0, requests: 0 };
+				tokensByModel[model].input += data.inputTokens;
+				tokensByModel[model].output += data.outputTokens;
+				tokensByModel[model].requests += data.requests;
+			}
+		}
+
+		return {
+			accountCount: status.accounts.length,
+			modelsUsed: Object.keys(status.activeAccounts),
+			totalRequests: status.totalRequestsAllAccounts,
+			uptimeSeconds: Math.round(status.uptime / 1000),
+			routingHealthState: status.routingHealth.state,
+			flaggedCount: status.routingHealth.flaggedCount,
+			disabledCount: status.routingHealth.disabledCount,
+			proCount: status.accounts.filter(a => a.proDetected).length,
+			freeCount: status.accounts.filter(a => !a.proDetected).length,
+			tokensByModel,
+		};
+	});
+	setActiveReporter(telemetry);
+	void telemetry.start();
+
+	// ── Graceful shutdown ──
+	const shutdown = async (): Promise<void> => {
+		console.log("\nShutting down...");
+		await telemetry.shutdown();
+		rotator.stopQuotaPolling();
+		process.exit(0);
+	};
+	process.on("SIGINT", () => void shutdown());
+	process.on("SIGTERM", () => void shutdown());
+
 	startProxy(rotator, config.proxyPort);
 }
 

package/src/proxy.ts

@@ -18,6 +18,8 @@ import { requireAdmin } from "./admin-auth.js";
 import { PayloadTooLargeError, readLimitedBody } from "./body-limit.js";
 import { validateProxyRequestBody } from "./validators.js";
 import { logger } from "./logger.js";
+import { trackFeature, reportFlagEvent, FLAG_PATTERNS, type FlagPattern } from "./telemetry.js";
+import type { FlagEventData } from "./telemetry.js";
 
 const proxyLogger = logger.child("proxy");
 
@@ -415,6 +417,28 @@ async function handleProxyRequest(
 				if (response.status === 401) {
 					const errorText = await response.text().catch(() => "");
 					proxyLog(`[${label}] BLOCKED (401): ${errorText.slice(0, 200)}`, "error");
+
+					// Telemetry: report flag event BEFORE markFlagged (which may trigger protective pause)
+					const lower401 = errorText.toLowerCase();
+					const matched401 = FLAG_PATTERNS.filter(p => lower401.includes(p));
+					const ctx401 = rotator.getFlagContext(account, modelKey);
+					reportFlagEvent({
+						flagHttpStatus: 401,
+						flagPatternsMatched: matched401.length > 0 ? matched401 : ["blocked_401" as FlagPattern],
+						model: modelKey,
+						timerType: ctx401.timerType as FlagEventData["timerType"],
+						accountQuotaPercent: ctx401.accountQuotaPercent,
+						wasProAccount: ctx401.wasProAccount,
+						accountTotalRequests: account.totalRequests,
+						accountRequestsLastHour: ctx401.accountRequestsLastHour,
+						accountConcurrentAtFlag: account.inFlightRequests,
+						poolSize: ctx401.poolSize,
+						poolHealthyCount: ctx401.poolHealthyCount,
+						protectivePauseTriggered: false, // not yet — markFlagged decides
+						uptimeSeconds: ctx401.uptimeSeconds,
+						timeSinceLastFlagSeconds: -1, // filled by reporter
+					});
+
 					rotator.markFlagged(account, `Account blocked (401): ${errorText.slice(0, 300)}`);
 					logRequestEnd(401);
 				const nextAccount = await rotateAndRelease();
@@ -428,13 +452,34 @@ async function handleProxyRequest(
 			if (response.status === 403) {
 				const errorText = await response.text().catch(() => "");
 				const lower = errorText.toLowerCase();
-				const flagPatterns = ["infring", "suspend", "abus", "terminat", "violat", "banned", "policy", "forbidden", "verif"];
-					const isFlagged = flagPatterns.some((p) => lower.includes(p));
+				const flagPatternsLocal = ["infring", "suspend", "abus", "terminat", "violat", "banned", "policy", "forbidden", "verif"];
+					const isFlagged = flagPatternsLocal.some((p) => lower.includes(p));
 
 					if (isFlagged) {
 						proxyLog(`[${label}] FLAGGED: ${errorText.slice(0, 200)}`, "error");
 						recordOutcome(403);
 						logRequestEnd(403);
+
+						// Telemetry: report flag event with full anonymous context
+						const matchedPatterns = FLAG_PATTERNS.filter(p => lower.includes(p));
+						const ctx403 = rotator.getFlagContext(account, modelKey);
+						reportFlagEvent({
+							flagHttpStatus: 403,
+							flagPatternsMatched: matchedPatterns,
+							model: modelKey,
+							timerType: ctx403.timerType as FlagEventData["timerType"],
+							accountQuotaPercent: ctx403.accountQuotaPercent,
+							wasProAccount: ctx403.wasProAccount,
+							accountTotalRequests: account.totalRequests,
+							accountRequestsLastHour: ctx403.accountRequestsLastHour,
+							accountConcurrentAtFlag: account.inFlightRequests,
+							poolSize: ctx403.poolSize,
+							poolHealthyCount: ctx403.poolHealthyCount,
+							protectivePauseTriggered: false, // not yet
+							uptimeSeconds: ctx403.uptimeSeconds,
+							timeSinceLastFlagSeconds: -1, // filled by reporter
+						});
+
 						rotator.markFlagged(account, errorText.slice(0, 300));
 					const nextAccount = await rotateAndRelease();
 					if (!nextAccount) {
@@ -586,12 +631,14 @@ export function startProxy(rotator: AccountRotator, port: number): void {
 
 		if (method === "GET" && (pathname === "/" || pathname === "/dashboard")) {
 			if (!requireAdmin(req, res)) return;
+			trackFeature("dashboard");
 			serveDashboard(res);
 			return;
 		}
 
 		if (method === "GET" && pathname === "/login") {
 			if (!requireAdmin(req, res)) return;
+			trackFeature("hostedLogin");
 			serveLoginLanding(res);
 			return;
 		}
@@ -674,6 +721,7 @@ export function startProxy(rotator: AccountRotator, port: number): void {
 
 		if (method === "POST" && (url === "/api/settings/fresh-window-starts/on" || url === "/api/settings/fresh-window-starts/off")) {
 			if (!requireAdmin(req, res)) return;
+			trackFeature("freshWindowToggle");
 			serveFreshWindowStartsApi(res, rotator, url.endsWith("/on"));
 			return;
 		}

package/src/rotator.ts

@@ -924,7 +924,10 @@ export class AccountRotator {
 	}
 
 	getTokenUsage(): TokenUsageData {
-		const all = [...this.tokenBuckets.minutes, ...this.tokenBuckets.hours, ...this.tokenBuckets.days, ...this.tokenBuckets.months];
+		// Use only the raw minutes buckets — they are the source of truth.
+		// Hours/days/months are consolidated rollups of the same data and
+		// must NOT be summed together with minutes (that would 4x every count).
+		const all = this.tokenBuckets.minutes;
 		let totalInputTokens = 0;
 		let totalOutputTokens = 0;
 		let totalRequests = 0;
@@ -1244,6 +1247,46 @@ export class AccountRotator {
 		return this.accounts.length;
 	}
 
+	/**
+	 * Get contextual data for telemetry flag reporting.
+	 * Returns anonymous pool state — no emails or PII.
+	 */
+	getFlagContext(account: AccountRuntime, modelKey: string): {
+		wasProAccount: boolean;
+		accountQuotaPercent: number;
+		timerType: string;
+		poolSize: number;
+		poolHealthyCount: number;
+		protectivePauseTriggered: boolean;
+		accountRequestsLastHour: number;
+		uptimeSeconds: number;
+	} {
+		const now = Date.now();
+		const quota = this.getModelQuota(account, modelKey);
+		const timerType = this.getModelTimerType(account, modelKey);
+		const healthyCount = this.accounts.filter(a =>
+			!a.disabled && !a.flagged && this.isAvailable(a, now),
+		).length;
+
+		// Count requests in the last hour from request log
+		const oneHourAgo = now - 3600_000;
+		const label = account.config.label || account.config.email;
+		const requestsLastHour = this.requestLog.filter(e =>
+			e.timestamp >= oneHourAgo && e.account === label,
+		).length;
+
+		return {
+			wasProAccount: this.isProAccount(account),
+			accountQuotaPercent: quota,
+			timerType,
+			poolSize: this.accounts.length,
+			poolHealthyCount: healthyCount,
+			protectivePauseTriggered: this.protectivePauseUntil > now,
+			accountRequestsLastHour: requestsLastHour,
+			uptimeSeconds: Math.round((now - this.startTime) / 1000),
+		};
+	}
+
 	addOrUpdateAccount(accountConfig: AccountConfig): void {
 		const existingIndex = this.accounts.findIndex((account) => account.config.email === accountConfig.email);
 		if (existingIndex >= 0) {