pi-antigravity-rotator 1.13.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [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
+- **Gemini 3.5 Flash Support**: Added routing and dashboard support for the new `gemini-3.5-flash` model family (including `gemini-3.5-flash-low` / `gemini-3.5-flash-medium` and `gemini-3-flash-agent` / `gemini-3.5-flash-high`).
+- **GPT-OSS 120B Support**: Added complete support (pricing, styling, and dashboard visualization) for the `gpt-oss-120b-medium` model, mapping its quota tracking to the shared Claude pool (`claude-opus-4-6-thinking`).
+- **Model Role Support**: Added support for the `"model"` role in compatibility layer chat completions, validating and mapping it to native Gemini model turns.
+- **Request Normalization**: Added normalization helpers (`normalizeOpenAIChatCompletionRequest` / `normalizeAnthropicMessagesRequest`) to automatically format loose inputs, Responses-style inputs (e.g., `input`, `prompt`), and raw native Antigravity request payloads into standard OpenAI/Anthropic messages format.
+
 ## [1.13.0] - 2026-05-19
 
 ### Removed

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:
@@ -74,7 +115,7 @@ This package is not exclusive to Pi. It can be consumed by **any** agent or fron
 2. Add a new generic/OpenAI-compatible provider
 3. Set the API Base URL to: `http://127.0.0.1:51200/v1/`
 4. Set the API Key to: `antigravity` (or any string, the proxy doesn't validate it)
-5. You can now use any of the models (e.g. `gemini-3-flash`, `gemini-3.1-pro-low`, `claude-sonnet-4-6`, `claude-opus-4-6-thinking`) directly in your agent.
+5. You can now use any of the models (e.g. `gemini-3.5-flash-low`, `gemini-3.5-flash-high`, `gemini-3.1-pro-low`, `claude-sonnet-4-6`, `claude-opus-4-6-thinking`, `gpt-oss-120b-medium`) directly in your agent.
 
 ### Activation rule
 
@@ -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.
 
@@ -353,7 +417,9 @@ curl http://localhost:51200/v1/messages \
 Current adapter scope:
 
 - Text chat/messages.
-- **Native Reasoning visibility**: Models with thinking capabilities (Gemini 3 Pro, Gemini 3 Flash, Claude Sonnet 4.6 Thinking) automatically expose their interleaved thinking blocks in real-time as OpenAI `reasoning_content` or Anthropic `thinking_delta` chunks.
+- **Model Role Support**: Fully supports the `"model"` role in chat message histories (e.g., from Pi or Hermes agents), validating and routing it identically to the `"assistant"` role.
+- **Request Normalization**: Automatically normalizes loose inputs (non-array messages), legacy prompt/input fields (e.g. `prompt` strings/arrays or `input` structures), and raw native Antigravity requests (`request.contents`) into standard OpenAI/Anthropic format.
+- **Native Reasoning visibility**: Models with thinking capabilities (Gemini 3 Pro, Gemini 3.5 Flash, Claude Sonnet 4.6 Thinking) automatically expose their interleaved thinking blocks in real-time as OpenAI `reasoning_content` or Anthropic `thinking_delta` chunks.
 - Streaming mode is supported as compatibility SSE. The adapter buffers the upstream Antigravity stream, then emits one OpenAI/Anthropic-compatible final delta. Native token-by-token pass-through is not implemented yet.
 - Image input is supported when sent as base64 data URL (`OpenAI image_url.url = data:image/...;base64,...`) or Anthropic base64 source (`type=image`, `source.type=base64`).
 - **Tool/function calling is fully supported** (OpenAI `tools`/`tool_choice` format and Anthropic `tool_use`/`tool_result` via standard translation to Gemini `functionDeclarations`).
@@ -461,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.13.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/)");