pi-antigravity-rotator 1.14.0 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## [Unreleased]
 
+### Added
+- **Hybrid Routing Policy**: Added optional `routingPolicy: "hybrid"` with weighted selection across timer priority, quota, tier, health, local token bucket state, and distance.
+- **Routing Inspector**: Added a dashboard modal that explains the currently selected route, candidate scores, and why each account was excluded for a model.
+- **Rate Limit Parser Module**: Extracted robust retry parsing into `src/rate-limit-parser.ts` with support for `Retry-After`, `x-ratelimit-reset`, `quotaResetDelay`, `quotaResetTimeStamp`, `retryDelay`, and duration strings.
+
+### Changed
+- **Token Bucket Guardrail**: Added optional per-account token buckets to slow repeated reuse of the same account without changing the default v2.0 routing behavior.
+- **Attention Needed Coverage**: The dashboard now surfaces unroutable models and token-bucket exhaustion alongside existing security, cooldown, disabled, flagged, and error alerts.
+- **Compat Hardening**: Added coverage for `cache_control` stripping, schema forwarding, missing-signature tool history, and empty SSE parsing.
+
+## [2.0.0] - 2026-05-20
+
+### Added
+- **Admin Config APIs**: Added `GET /api/config`, `PUT /api/config`, `GET /api/config/export`, and `POST /api/config/import` for validated runtime config management.
+- **Dashboard Config Editor**: Added an embedded JSON editor with load/save/import/export controls and hosted login access.
+- **Docker Deployment**: Added `Dockerfile`, `docker-compose.yml`, and `.dockerignore` for headless deployments with persistent `/data`.
+- **Doctor Command**: Added `pi-antigravity-rotator doctor` to validate config, inspect backups, and report missing admin auth.
+- **Gemini-Compatible Discovery**: Added `/v1beta/models` and a minimal Gemini-style `generateContent` route family.
+
+### Changed
+- **Version 2.0**: Bumped package version to `2.0.0` on branch `v2.0`.
+- **Persistence Hardening**: Config, state, and token usage now write atomically with timestamped backups.
+- **Routing Metadata**: Added optional account `tier` plus runtime `healthScore` as timer-first tie-breakers.
+- **Security Visibility**: Startup logs, `/api/status`, and the dashboard now warn when `PI_ROTATOR_ADMIN_TOKEN` is missing.
+
+### Migration
+- Existing `accounts.json` stays compatible. New defaults are `bindHost: "0.0.0.0"`, `routingPolicy: "timer-first"`, and `accounts[].tier: "unknown"`.
+
 ## [1.14.0] - 2026-05-19
 
 ### Added

package/README.md

@@ -1,7 +1,40 @@
+![Pi Antigravity Rotator logo](./pi-antigravity-rotator_logo.png)
+
 # Pi Antigravity Rotator
 
 Multi-account rotation proxy for Google Antigravity. Distributes API usage across multiple Google accounts with per-model routing, real-time quota tracking, automatic token management, and infringement detection.
 
+> **⚠️ WARNING:** Using this proxy may put connected Google accounts at risk of Terms of Service enforcement, including restriction, suspension, or permanent bans. Use at your own risk.
+
+<details>
+<summary><strong>⚠️ Terms of Service Warning — Read Before Installing</strong></summary>
+
+> [!CAUTION]
+> This is an unofficial tool and is not endorsed by Google. Routing traffic through this proxy may violate Google's Terms of Service or trigger automated abuse or policy enforcement systems.
+>
+> **By using this proxy, you acknowledge:**
+> - Your account may be restricted, suspended, shadow-banned, or permanently banned
+> - Multi-account rotation and proxying can increase account risk compared to normal interactive usage
+> - You assume all responsibility for the accounts and traffic routed through this tool
+>
+> **Recommendation:** Do not use your primary Google account. Prefer disposable or lower-risk accounts, and keep account exposure conservative.
+
+</details>
+
+## Support Me
+
+If this tool has helped you optimize your API usage and save costs, consider supporting its development!
+
+<a href="https://ko-fi.com/tuxevil" target="_blank"><img src="https://storage.ko-fi.com/cdn/kofi2.png?v=3" height="36" alt="Buy Me a Coffee at ko-fi.com" /></a>
+
+## v2.0 Highlights
+
+- Full dashboard config editor with import/export.
+- Official Docker and compose deployment.
+- `pi-antigravity-rotator doctor` for config/state validation.
+- Optional account `tier` metadata and runtime `healthScore`.
+- Strong security warnings when admin routes are open without `PI_ROTATOR_ADMIN_TOKEN`.
+
 ## Features
 
 - **Per-model routing** -- Each model (Gemini Pro, Flash, Claude) routes to its own active account independently. Multiple agents using different models won't interfere with each other.
@@ -49,6 +82,14 @@ npm run login
 npm start
 ```
 
+### Option C: Docker
+
+```bash
+docker compose up -d
+```
+
+The included compose file persists runtime data under `./docker-data` and sets `PI_ROTATOR_DIR=/data`.
+
 ## Adding Accounts
 
 Run `npm run login` once per Google account:
@@ -89,6 +130,8 @@ If login fails at project discovery:
 
 After starting the proxy, open `http://localhost:51200/dashboard` or `http://<your-server-ip>:51200/dashboard` from any machine on the same network (the proxy binds to `0.0.0.0`).
 
+If `PI_ROTATOR_ADMIN_TOKEN` is unset, dashboard and `/api/*` access remains open for backwards compatibility. v2.0 now surfaces loud warnings about that state in startup logs, `/api/status`, and the dashboard itself.
+
 The dashboard shows:
 
 - **Top Status & Controls** -- Real-time routing state, uptime, requests, and PII masking toggle.
@@ -98,7 +141,8 @@ The dashboard shows:
 - **Quota Forecast** -- Predictive modeling showing when each model's quota will run out based on the current requests/hour burn rate.
 - **Searchable Request Log** -- Live feed of the last 200 requests with exact timestamps, models, masked accounts, status codes, and latency.
 - **Account Cards** -- Sorted by total quota. Shows status (`active`, `ready`, `cooldown`, `flagged`, `disabled`), quota bars with timers, and precise error messages.
-- **Operator Panels** -- "Attention Needed" summaries for quarantined accounts and a real-time event feed of rotator actions.
+- **Operator Panels** -- "Attention Needed" summaries for quarantined accounts, unroutable models, token-bucket pressure, and a real-time event feed of rotator actions.
+- **Routing Inspector** -- On-demand modal showing the active routing policy, candidate scores, local token bucket state, and rejection reasons per model.
 
 ![Dashboard](dashboard.png)
 
@@ -220,6 +264,8 @@ export PI_ROTATOR_DIR=/path/to/config
 export PI_ROTATOR_QUOTA_USER_AGENT="antigravity/1.107.0 darwin/arm64"
 # Optional: require this token for dashboard/API access. If unset, legacy open access is preserved.
 export PI_ROTATOR_ADMIN_TOKEN="change-me"
+# Optional: bind the proxy to a safer local-only interface.
+export PI_ROTATOR_BIND_HOST="127.0.0.1"
 # Optional: max accepted proxy request body size in bytes. Default: 26214400 (25 MiB).
 export PI_ROTATOR_MAX_BODY_BYTES=26214400
 # Optional: log verbosity. One of debug, info, warn, error, silent. Default: info.
@@ -231,6 +277,24 @@ export PI_AI_ANTIGRAVITY_VERSION=1.107.0
 pi-antigravity-rotator start --config-dir /path/to/config
 ```
 
+New v2.0 config fields:
+
+- `bindHost`: interface to bind on. Default: `0.0.0.0`.
+- `routingPolicy`: current default is `timer-first`. Optional values now include `tier-first`, `quota-first`, and `hybrid`.
+- `tokenBucketEnabled`: enables the local per-account request bucket used by `hybrid`. Default: `false`.
+- `tokenBucketMaxTokens`: bucket capacity when enabled. Default: `50`.
+- `tokenBucketRefillPerMinute`: refill speed when enabled. Default: `6`.
+- `tokenBucketInitialTokens`: startup fill level when enabled. Default: `50`.
+- `accounts[].tier`: optional `ultra`, `pro`, `free`, or `unknown`.
+
+## Doctor
+
+```bash
+pi-antigravity-rotator doctor
+```
+
+This validates `accounts.json`, checks local state files, lists backups, and warns when admin auth is not configured.
+
 `accounts.json` is created automatically by the login command.
 Login now fails if Google does not return a project ID. No shared fallback.
 
@@ -463,9 +527,3 @@ 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!
-
-<a href="https://ko-fi.com/tuxevil" target="_blank"><img src="https://storage.ko-fi.com/cdn/kofi2.png?v=3" height="36" alt="Buy Me a Coffee at ko-fi.com" /></a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-antigravity-rotator",
-  "version": "1.14.0",
+  "version": "2.0.0",
   "description": "Multi-account rotation proxy for Google Antigravity with per-model routing, real-time quota tracking, and infringement detection",
   "license": "MIT",
   "type": "module",

package/src/account-store.ts

@@ -1,24 +1,59 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { getAccountsPath } from "./paths.js";
 import type { AccountConfig, Config } from "./types.js";
+import { backupFile, readJsonFile, writeJsonFileAtomic } from "./storage.js";
+import { formatValidationErrors, validateConfig } from "./validators.js";
 
 const ACCOUNTS_FILE = getAccountsPath();
 const PI_DIR = join(homedir(), ".pi", "agent");
 const PI_MODELS_FILE = join(PI_DIR, "models.json");
 const PI_AUTH_FILE = join(PI_DIR, "auth.json");
+const TOKEN_USAGE_FILE = join(join(ACCOUNTS_FILE, ".."), "token-usage.json");
 
-export function loadOrCreateAccountsConfig(): Config {
-	if (existsSync(ACCOUNTS_FILE)) {
-		try {
-			return JSON.parse(readFileSync(ACCOUNTS_FILE, "utf-8")) as Config;
-		} catch {
-			// Corrupted, start fresh
-		}
-	}
+export function getTokenUsagePath(): string {
+	return TOKEN_USAGE_FILE;
+}
+
+export function applyConfigDefaults(config: Config): Config {
 	return {
+		proxyPort: config.proxyPort || 51200,
+		bindHost: config.bindHost || process.env.PI_ROTATOR_BIND_HOST || "0.0.0.0",
+		routingPolicy: config.routingPolicy || "timer-first",
+		requestsPerRotation: config.requestsPerRotation || 5,
+		rotateOnQuotaDrop: config.rotateOnQuotaDrop ?? 20,
+		quotaPollIntervalMs: config.quotaPollIntervalMs || 300000,
+		maxConcurrentRequestsPerAccount: config.maxConcurrentRequestsPerAccount ?? 1,
+		maxConcurrentRequestsPerProjectModel: config.maxConcurrentRequestsPerProjectModel ?? 1,
+		projectCircuitBreaker429Threshold: config.projectCircuitBreaker429Threshold ?? 3,
+		projectCircuitBreakerWindowMs: config.projectCircuitBreakerWindowMs ?? 10 * 60 * 1000,
+		projectCircuitBreakerCooldownMs: config.projectCircuitBreakerCooldownMs ?? 60 * 60 * 1000,
+		modelCircuitBreaker429Threshold: config.modelCircuitBreaker429Threshold ?? 3,
+		modelCircuitBreakerCooldownMs: config.modelCircuitBreakerCooldownMs ?? 6 * 60 * 60 * 1000,
+		dailyAccountSlowRequests: config.dailyAccountSlowRequests ?? 250,
+		dailyAccountStopRequests: config.dailyAccountStopRequests ?? 350,
+		dailyProjectSlowRequests: config.dailyProjectSlowRequests ?? 900,
+		dailyProjectStopRequests: config.dailyProjectStopRequests ?? 1200,
+		slowModeJitterMinMs: config.slowModeJitterMinMs ?? 8_000,
+		slowModeJitterMaxMs: config.slowModeJitterMaxMs ?? 25_000,
+		protectivePauseMs: config.protectivePauseMs ?? 21600000,
+		useRequestCountRotationWhenQuotaUnknownOnly: config.useRequestCountRotationWhenQuotaUnknownOnly ?? true,
+		tokenBucketEnabled: config.tokenBucketEnabled ?? false,
+		tokenBucketMaxTokens: config.tokenBucketMaxTokens ?? 50,
+		tokenBucketRefillPerMinute: config.tokenBucketRefillPerMinute ?? 6,
+		tokenBucketInitialTokens: config.tokenBucketInitialTokens ?? (config.tokenBucketMaxTokens ?? 50),
+		accounts: config.accounts.map((account) => ({
+			...account,
+			tier: account.tier || "unknown",
+		})),
+	};
+}
+
+export function getDefaultConfig(): Config {
+	return applyConfigDefaults({
 		proxyPort: 51200,
+		accounts: [],
 		requestsPerRotation: 5,
 		rotateOnQuotaDrop: 20,
 		quotaPollIntervalMs: 300000,
@@ -37,12 +72,34 @@ export function loadOrCreateAccountsConfig(): Config {
 		slowModeJitterMaxMs: 25_000,
 		protectivePauseMs: 21600000,
 		useRequestCountRotationWhenQuotaUnknownOnly: true,
-		accounts: [],
-	};
+		tokenBucketEnabled: false,
+		tokenBucketMaxTokens: 50,
+		tokenBucketRefillPerMinute: 6,
+		tokenBucketInitialTokens: 50,
+	});
+}
+
+export function loadConfigFromDisk(): Config {
+	const parsed = readJsonFile<unknown>(ACCOUNTS_FILE);
+	if (parsed === null) return getDefaultConfig();
+	const validation = validateConfig(parsed);
+	if (!validation.ok || !validation.value) {
+		throw new Error(formatValidationErrors(validation.errors));
+	}
+	return applyConfigDefaults(validation.value);
+}
+
+export function loadOrCreateAccountsConfig(): Config {
+	try {
+		return loadConfigFromDisk();
+	} catch {
+		return getDefaultConfig();
+	}
 }
 
 export function saveAccountsConfig(config: Config): void {
-	writeFileSync(ACCOUNTS_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
+	backupFile(ACCOUNTS_FILE, "accounts");
+	writeJsonFileAtomic(ACCOUNTS_FILE, applyConfigDefaults(config));
 }
 
 export function addAccountToConfig(entry: AccountConfig): { isNew: boolean } {
@@ -83,7 +140,7 @@ export function ensurePiModelsConfig(): void {
 	providers["google-antigravity"] = antigravity;
 	models.providers = providers;
 
-	writeFileSync(PI_MODELS_FILE, JSON.stringify(models, null, 2) + "\n", "utf-8");
+	writeJsonFileAtomic(PI_MODELS_FILE, models);
 	console.log(`  Updated ${PI_MODELS_FILE}`);
 }
 
@@ -112,6 +169,6 @@ export function ensurePiAuthConfig(): void {
 		projectId: "proxy-managed",
 	};
 
-	writeFileSync(PI_AUTH_FILE, JSON.stringify(auth, null, 2) + "\n", "utf-8");
+	writeJsonFileAtomic(PI_AUTH_FILE, auth);
 	console.log(`  Updated ${PI_AUTH_FILE}`);
 }

package/src/cli.ts

@@ -38,6 +38,13 @@ switch (command) {
 		}
 		break;
 	}
+	case "doctor": {
+		const { printDoctorReport, runDoctor } = await import("./doctor.js");
+		const result = runDoctor();
+		printDoctorReport(result);
+		process.exit(result.ok ? 0 : 1);
+		break;
+	}
 	default:
 		console.log("Pi Antigravity Rotator");
 		console.log();
@@ -45,6 +52,7 @@ switch (command) {
 		console.log("  pi-antigravity-rotator start     Start the proxy (default)");
 		console.log("  pi-antigravity-rotator login     Add a new Google account");
 		console.log("  pi-antigravity-rotator status    Show account status (JSON)");
+		console.log("  pi-antigravity-rotator doctor    Validate config and local state");
 		console.log();
 		console.log("Options:");
 		console.log("  --config-dir <path>    Config directory (default: ~/.pi-antigravity-rotator/)");

package/src/compat.ts

@@ -1190,20 +1190,21 @@ async function completeViaRotator(
 }
 
 
+const MODEL_CATALOG = [
+	{ id: "gemini-3.5-flash-low", family: "gemini-3.5-flash", ctx: 1048576, quotaPool: "gemini-3.5-flash", multimodal: true, tools: true },
+	{ id: "gemini-3.5-flash-high", family: "gemini-3.5-flash", ctx: 1048576, quotaPool: "gemini-3.5-flash", multimodal: true, tools: true },
+	{ id: "gemini-3-flash", family: "gemini-3.5-flash", ctx: 1048576, quotaPool: "gemini-3.5-flash", multimodal: true, tools: true },
+	{ id: "gemini-3.1-pro-low", family: "gemini-3.1-pro", ctx: 1048576, quotaPool: "gemini-3.1-pro", multimodal: true, tools: true },
+	{ id: "gemini-3.1-pro-high", family: "gemini-3.1-pro", ctx: 1048576, quotaPool: "gemini-3.1-pro", multimodal: true, tools: true },
+	{ id: "claude-sonnet-4-6", family: "claude", ctx: 500000, quotaPool: "claude-opus-4-6-thinking", multimodal: true, tools: true },
+	{ id: "claude-opus-4-6-thinking", family: "claude", ctx: 500000, quotaPool: "claude-opus-4-6-thinking", multimodal: true, tools: true },
+	{ id: "gpt-oss-120b-medium", family: "gpt-oss", ctx: 131072, quotaPool: "claude-opus-4-6-thinking", multimodal: false, tools: true },
+] as const;
+
 export function serveOpenAIModels(res: ServerResponse): void {
-	const models = [
-		{ id: "gemini-3.5-flash-low", ctx: 1048576 },
-		{ id: "gemini-3.5-flash-high", ctx: 1048576 },
-		{ id: "gemini-3-flash", ctx: 1048576 },
-		{ id: "gemini-3.1-pro-low", ctx: 1048576 },
-		{ id: "gemini-3.1-pro-high", ctx: 1048576 },
-		{ id: "claude-sonnet-4-6", ctx: 500000 },
-		{ id: "claude-opus-4-6-thinking", ctx: 500000 },
-		{ id: "gpt-oss-120b-medium", ctx: 131072 },
-	];
 	writeJson(res, 200, {
 		object: "list",
-		data: models.map(({ id, ctx }) => ({
+		data: MODEL_CATALOG.map(({ id, ctx, family, quotaPool, multimodal, tools }) => ({
 			id,
 			object: "model",
 			created: 0,
@@ -1212,11 +1213,81 @@ export function serveOpenAIModels(res: ServerResponse): void {
 			max_model_len: ctx,
 			meta: {
 				context_length: ctx,
+				family,
+				quota_pool: quotaPool,
+				multimodal,
+				tool_calling: tools,
 			}
 		})),
 	});
 }
 
+export function serveGeminiModels(res: ServerResponse): void {
+	writeJson(res, 200, {
+		models: MODEL_CATALOG.map(({ id, ctx, family, quotaPool, multimodal, tools }) => ({
+			name: `models/${id}`,
+			baseModelId: family,
+			version: "v2.0",
+			displayName: id,
+			description: `Pi Antigravity Rotator Gemini-compatible model entry for ${id}`,
+			inputTokenLimit: ctx,
+			outputTokenLimit: ctx,
+			supportedGenerationMethods: ["generateContent", "streamGenerateContent"],
+			capabilities: {
+				tools,
+				multimodal,
+				quotaPool,
+			},
+		})),
+	});
+}
+
+export async function handleGeminiGenerateContent(req: IncomingMessage, res: ServerResponse, rotator: AccountRotator): Promise<void> {
+	let parsed: unknown;
+	try {
+		parsed = await readJsonBody(req);
+	} catch (err) {
+		if (err instanceof PayloadTooLargeError) return writeJson(res, 413, { error: { message: "Payload too large", status: "INVALID_ARGUMENT" } });
+		return writeJson(res, 400, { error: { message: "Invalid JSON body", status: "INVALID_ARGUMENT" } });
+	}
+	if (!isRecord(parsed)) return writeJson(res, 400, { error: { message: "Body must be an object", status: "INVALID_ARGUMENT" } });
+
+	const pathname = new URL(req.url || "/", "http://localhost").pathname;
+	const modelToken = pathname.match(/\/v1beta\/models\/(.+):(generateContent|streamGenerateContent)$/)?.[1];
+	const model = modelToken ? decodeURIComponent(modelToken).replace(/^models\//, "") : null;
+	if (!model) return writeJson(res, 400, { error: { message: "Model path is required", status: "INVALID_ARGUMENT" } });
+
+	const body: RequestBody = {
+		model,
+		project: "",
+		request: {
+			contents: Array.isArray(parsed.contents) ? parsed.contents : [],
+			systemInstruction: parsed.systemInstruction,
+			generationConfig: parsed.generationConfig,
+			tools: parsed.tools,
+		},
+	};
+	const result = await completeViaRotator(req, res, rotator, body, "none");
+	if (result.status !== 200) {
+		return writeJson(res, result.status, { error: { message: result.errorText || "Upstream error", status: "UPSTREAM_ERROR" } });
+	}
+	if (result.streamed) return;
+	writeJson(res, 200, {
+		candidates: [{
+			content: {
+				role: "model",
+				parts: [{ text: result.completion.text }],
+			},
+			finishReason: "STOP",
+		}],
+		usageMetadata: {
+			promptTokenCount: result.completion.inputTokens,
+			candidatesTokenCount: result.completion.outputTokens,
+			totalTokenCount: result.completion.inputTokens + result.completion.outputTokens,
+		},
+	});
+}
+
 export async function handleOpenAIChatCompletions(req: IncomingMessage, res: ServerResponse, rotator: AccountRotator): Promise<void> {
 	let parsed: unknown;
 	try {