pi-antigravity-rotator 1.3.2 → 1.3.4

package/README.md

@@ -6,11 +6,12 @@ Multi-account rotation proxy for Google Antigravity. Distributes API usage acros
 
 - **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.
 - **Real-time quota monitoring** -- Polls Google's quota API every 5 minutes to track remaining usage per model per account
-- **Per-model timer tracking** -- Timer priority (fresh/7d/5h) is evaluated per model using each model's actual `resetTime` from the quota API, not a per-account estimate
+- **Per-model timer tracking** -- Timer classification (`fresh`/`7d`/`5h`) is evaluated per model using each model's actual `resetTime` from the quota API, not a per-account estimate
 - **Smart rotation** -- Rotates only the specific model whose quota dropped, leaving other models on their current accounts
 - **Infringement detection** -- On 403 with infringement/abuse/suspension keywords, the account is immediately flagged and excluded from routing
 - **Automatic failover** -- On 429 rate limits, instantly switches the affected model to the next available account
 - **Concurrency guardrails** -- Limits each account to one in-flight request by default to avoid bursty pressure
+- **Operator fresh-window controls** -- You can block new `fresh` window starts globally, then selectively allow specific accounts to override that policy
 - **Protective pause** -- Pauses all routing for several hours after serious ToS/abuse-style flags so the rest of the pool is not burned
 - **Token auto-refresh** -- Tokens are refreshed automatically before expiry; no manual management
 - **Endpoint cascade** -- Tries daily, autopush, and prod API endpoints for resilience
@@ -62,6 +63,31 @@ The tool automatically:
 
 Re-running with the same email updates the existing entry.
 
+## Hosted Login Page
+
+This fork can also host a family-facing login page so people can connect their own account without copying a `localhost` URL by hand.
+
+Public routes:
+
+- `GET /login` -- landing page for account linking
+- `GET /auth/antigravity/start` -- starts the Google OAuth flow
+- `GET /auth/antigravity/callback` -- receives the OAuth callback and adds the account to the running rotator
+
+Required environment variables for hosted mode:
+
+```bash
+export ANTIGRAVITY_CLIENT_ID="your-oauth-client-id"
+export ANTIGRAVITY_CLIENT_SECRET="your-oauth-client-secret"
+export ANTIGRAVITY_REDIRECT_URI="https://your-domain.example.com/auth/antigravity/callback"
+```
+
+Notes:
+
+- The redirect URI must be registered on the OAuth client, or Google will reject the flow.
+- The hosted page does not modify `~/.pi/agent/*`; it only adds the account to the rotator config.
+- If those env vars are not set, `/login` still loads but explains that hosted OAuth is not configured yet.
+- Refresh token handling during normal runtime uses the same configured client ID and secret, so the hosted sign-in and later token refreshes stay aligned.
+
 ## Dashboard
 
 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`).
@@ -72,8 +98,9 @@ The dashboard shows:
 - **Account cards** sorted by total quota (highest first), flagged/disabled last:
   - Status badge: `active`, `ready`, `cooldown`, `flagged`, `disabled`, or `error`
   - Model badges: which models this account is currently serving
-  - Per-model quota bars with timer type (`fresh`/`7d`/`5h`) and reset countdown
+  - Per-model quota bars with timer type (`idle`/`7d`/`5h`) and reset countdown
   - Request counts, last used time, token status
+  - Fresh-window policy status plus a per-account override button
   - Error messages for flagged/errored accounts
   - Re-enable button for disabled accounts
 
@@ -103,11 +130,17 @@ Each model maintains its own active account. When the proxy needs to rotate a mo
 
 | Priority | Badge | Condition | Rationale |
 |----------|-------|-----------|-----------|
-| 1 (first) | `fresh` | No active timer for this model | Start the 7-day clock ASAP so it resets sooner |
-| 2 | `7d` | 7-day timer running for this model | Already ticking, keep using it |
-| 3 (last) | `5h` | 5-hour timer running for this model | Short-lived; wasted if not fully consumed |
+| 1 (first) | `5h` | Short reset window is already active for this model | Drain short-window quota before it recharges |
+| 2 | `7d` | Long reset window is already active for this model | Already ticking, so it is still worth using |
+| 3 (last) | `fresh` | No active reset window is known for this model yet | Save untouched quota for later if other timed pools exist |
 
-Within the same priority tier, the account with the most remaining quota for that model wins.
+Within the same priority tier, the account with the most remaining quota for that model wins. If multiple accounts tie on priority and quota, rotation advances circularly from the current account so equal candidates share traffic instead of always favoring the first configured match.
+
+Timer meanings:
+
+- `fresh` -- no future `resetTime` is currently reported for that model on that account. In practice, this means no active reset window is visible in quota polling yet. The dashboard labels this as `idle` to avoid implying that it is automatically safe to start.
+- `5h` -- `resetTime` is less than 6 hours away.
+- `7d` -- `resetTime` is 6 hours or more away.
 
 ### Rotation Triggers
 
@@ -115,32 +148,56 @@ Three mechanisms trigger rotation, scoped to the specific model:
 
 1. **Quota-based** (primary) -- Polls the Google quota API every 5 minutes. When a model's remaining quota drops by `rotateOnQuotaDrop` percentage points (default: 20%), that model rotates to the next account. Other models stay on their current accounts.
 
-2. **Request-count** (fallback) -- After `requestsPerRotation` requests (default: 5), all models on that account rotate. Safety net for when quota data isn't available yet.
+2. **Request-count** (fallback) -- After `requestsPerRotation` successful requests (default: 5), the rotator asks for a rotation on the model that served that request. By default this fallback is only used when quota data for that model is still unknown.
+
+3. **429 failover** (reactive) -- On rate limit, the account is marked exhausted with a parsed retry cooldown and the affected model immediately switches.
+
+### Fresh Windows
+
+The quota polling API only exposes one visible `quotaInfo` block per model. If a model has no visible `resetTime`, the rotator classifies it as `fresh` internally and the dashboard shows it as `idle`.
+
+Operationally, `idle` means:
+
+- no timer window is currently visible for that model in quota polling
+- starting that account may open a new quota window
+- because the provider does not expose all parallel buckets explicitly, the rotator cannot guarantee ahead of time whether that new visible window will behave like a short `5h` opportunity or a longer `7d` runway
+
+For that reason, the rotator has two operator controls:
+
+- a **global fresh-window toggle** that blocks opening new `idle` windows by default
+- a **per-account override** that allows specific accounts to ignore the global block when you intentionally want them available
+
+When fresh-window starts are blocked:
 
-3. **429 failover** (reactive) -- On rate limit or 5xx, the account is marked exhausted with a cooldown and the affected model immediately switches.
+- visible `5h` timers still have highest priority
+- visible `7d` timers are still used normally
+- `idle` accounts are held back unless you explicitly enable their per-account override
 
 ### Account Protection
 
 The proxy detects blocked/suspended accounts at three levels:
 
-1. **Quota API check** (on startup + every poll) -- If the quota API returns `403 PERMISSION_DENIED` with "violation of Terms of Service", the account is immediately flagged.
+1. **Quota API check** (initial poll + every poll) -- If the quota API returns `401` or `403`, the account is immediately flagged.
 
 2. **API 401** (on request) -- If the prod endpoint rejects the token with `401 UNAUTHENTICATED`, the account is flagged.
 
-3. **API 403** (on request) -- If the response body contains infringement keywords (`infring`, `suspend`, `abus`, `terminat`, `violat`, `banned`, `policy`, `forbidden`), the account is flagged.
+3. **API 403** (on request) -- If the response body contains enforcement keywords such as `infring`, `suspend`, `abus`, `terminat`, `violat`, `banned`, `policy`, `forbidden`, or `verif`, the account is flagged.
 
-Flagged accounts are **immediately excluded** from all model routing. The dashboard shows a red `FLAGGED` badge with the error message and quarantine guidance. Flagged accounts are intentionally kept out of rotation until the provider explicitly restores access.
+Flagged accounts are **immediately excluded** from all model routing. If the reason looks serious enough (for example ToS, abuse, infringement, suspension, or ban language), the rotator also enables a global **protective pause** that stops all routing for `protectivePauseMs` (default: 6 hours). The dashboard shows a red `FLAGGED` badge with the error message and quarantine guidance. Flagged accounts are intentionally kept out of rotation until the provider explicitly restores access.
 
 ### Cooldown Management
 
 - Cooldowns are capped at **30 minutes** max
 - Stale cooldowns from previous sessions are capped on startup
+- When every non-flagged account is cooling down, the routing state becomes `cooldown_wait`
 - The dashboard shows why routing is waiting, how long until the next retry window, and which accounts are cooling down
 - Quota-based rotation only triggers if a healthy account is available; the proxy won't rotate away from a working account if there's no better alternative
 
 ### Error Handling
 
 - **429** (rate limit) -- account is marked exhausted with cooldown, rotates to next
+- **401** -- account is flagged and excluded from routing
+- **403** with enforcement keywords -- account is flagged and may trigger protective pause
 - **503** (no capacity) -- returned directly to the agent when all healthy accounts are cooling down, busy, flagged, or disabled
 - **5xx** (other server errors) -- account error counter incremented, rotates to next
 
@@ -152,6 +209,7 @@ The dashboard is intended to replace day-to-day `journalctl` digging for normal
 - The exact stop or wait reason
 - The next retry window when cooldowns are active
 - Protective pause remaining time and the provider signal that triggered it
+- The global fresh-window policy and a button to block or allow new `idle` window starts
 - Pool counts for available, ready, active, cooldown, busy, flagged, disabled, and error accounts
 - An `Attention Needed` section summarizing flagged, cooling, disabled, and error accounts
 - A recent event feed with the latest rotator/proxy incidents that led to the current state
@@ -176,6 +234,9 @@ pi-antigravity-rotator start --config-dir /path/to/config
   "requestsPerRotation": 5,
   "rotateOnQuotaDrop": 20,
   "quotaPollIntervalMs": 300000,
+  "maxConcurrentRequestsPerAccount": 1,
+  "protectivePauseMs": 21600000,
+  "useRequestCountRotationWhenQuotaUnknownOnly": true,
   "accounts": [
     {
       "email": "user@gmail.com",
@@ -195,6 +256,9 @@ pi-antigravity-rotator start --config-dir /path/to/config
 | `requestsPerRotation` | `5` | Max requests before rotating (fallback trigger) |
 | `rotateOnQuotaDrop` | `20` | Rotate when a model's quota drops this many %. Set to `0` to disable |
 | `quotaPollIntervalMs` | `300000` | Quota poll interval in ms (5 minutes) |
+| `maxConcurrentRequestsPerAccount` | `1` | Max simultaneous requests allowed per account |
+| `protectivePauseMs` | `21600000` | Global routing pause after a serious provider enforcement signal |
+| `useRequestCountRotationWhenQuotaUnknownOnly` | `true` | Use request-count rotation only until quota telemetry exists for the request's model |
 
 ### Account Fields
 
@@ -210,8 +274,13 @@ pi-antigravity-rotator start --config-dir /path/to/config
 | Method | Path | Description |
 |--------|------|-------------|
 | `GET` | `/dashboard` | Web dashboard |
+| `GET` | `/login` | Hosted account-link landing page |
 | `GET` | `/api/status` | JSON status: accounts, quotas, model routing, flags |
 | `POST` | `/api/enable/<email>` | Re-enable a disabled account after its underlying issue is fixed |
+| `POST` | `/api/settings/fresh-window-starts/on` | Allow opening new `idle`/fresh windows globally |
+| `POST` | `/api/settings/fresh-window-starts/off` | Block opening new `idle`/fresh windows globally |
+| `POST` | `/api/account-fresh-window-starts/<email>/on` | Allow one account to override the global fresh-window block |
+| `POST` | `/api/account-fresh-window-starts/<email>/off` | Return one account to the global fresh-window policy |
 | `POST` | `/v1internal:streamGenerateContent` | Proxy endpoint (used by pi) |
 
 ## Running as a Service
@@ -239,7 +308,7 @@ WantedBy=multi-user.target
 ## Troubleshooting
 
 **Account shows `flagged` status**
-Google detected potential abuse. Review the error message on the dashboard. After resolving with Google, click Re-enable or `POST /api/enable/<email>`.
+Google detected potential abuse or enforcement. Review the error message on the dashboard and resolve the provider-side block first. Flagged accounts are quarantined and are not re-enabled through `/api/enable/<email>` until the underlying provider issue is cleared by replacing or restoring the account.
 
 **Account keeps getting disabled after 5 errors**
 Check the error message. Common causes: revoked OAuth consent, expired refresh token (re-run `npm run login`), or Google account suspension.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-antigravity-rotator",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "Multi-account rotation proxy for Google Antigravity with per-model routing, real-time quota tracking, and infringement detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/tuxevil/pi-antigravity-rotator.git"
+    "url": "git+https://github.com/tuxevil/pi-antigravity-rotator.git"
   },
   "author": "Sebastián Real (tuxevil)",
   "dependencies": {

package/src/account-store.ts

@@ -0,0 +1,105 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } 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";
+
+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");
+
+export function loadOrCreateAccountsConfig(): Config {
+	if (existsSync(ACCOUNTS_FILE)) {
+		try {
+			return JSON.parse(readFileSync(ACCOUNTS_FILE, "utf-8")) as Config;
+		} catch {
+			// Corrupted, start fresh
+		}
+	}
+	return {
+		proxyPort: 51200,
+		requestsPerRotation: 5,
+		rotateOnQuotaDrop: 20,
+		quotaPollIntervalMs: 300000,
+		maxConcurrentRequestsPerAccount: 1,
+		protectivePauseMs: 21600000,
+		useRequestCountRotationWhenQuotaUnknownOnly: true,
+		accounts: [],
+	};
+}
+
+export function saveAccountsConfig(config: Config): void {
+	writeFileSync(ACCOUNTS_FILE, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+
+export function addAccountToConfig(entry: AccountConfig): { isNew: boolean } {
+	const config = loadOrCreateAccountsConfig();
+	const existing = config.accounts.findIndex((a) => a.email === entry.email);
+
+	if (existing >= 0) {
+		config.accounts[existing] = { ...config.accounts[existing], ...entry };
+		saveAccountsConfig(config);
+		return { isNew: false };
+	}
+
+	config.accounts.push(entry);
+	saveAccountsConfig(config);
+	return { isNew: true };
+}
+
+export function ensurePiModelsConfig(): void {
+	mkdirSync(PI_DIR, { recursive: true });
+
+	let models: Record<string, unknown> = {};
+	if (existsSync(PI_MODELS_FILE)) {
+		try {
+			models = JSON.parse(readFileSync(PI_MODELS_FILE, "utf-8"));
+		} catch {
+			// Corrupted, will overwrite
+		}
+	}
+
+	const providers = (models.providers || {}) as Record<string, Record<string, unknown>>;
+	const antigravity = providers["google-antigravity"] || {};
+
+	if (antigravity.baseUrl === "http://localhost:51200") {
+		return;
+	}
+
+	antigravity.baseUrl = "http://localhost:51200";
+	providers["google-antigravity"] = antigravity;
+	models.providers = providers;
+
+	writeFileSync(PI_MODELS_FILE, JSON.stringify(models, null, 2) + "\n", "utf-8");
+	console.log(`  Updated ${PI_MODELS_FILE}`);
+}
+
+export function ensurePiAuthConfig(): void {
+	mkdirSync(PI_DIR, { recursive: true });
+
+	let auth: Record<string, unknown> = {};
+	if (existsSync(PI_AUTH_FILE)) {
+		try {
+			auth = JSON.parse(readFileSync(PI_AUTH_FILE, "utf-8"));
+		} catch {
+			// Corrupted, will overwrite
+		}
+	}
+
+	const existing = auth["google-antigravity"] as Record<string, unknown> | undefined;
+	if (existing?.type === "oauth" && existing?.refresh === "proxy-managed") {
+		return;
+	}
+
+	auth["google-antigravity"] = {
+		type: "oauth",
+		refresh: "proxy-managed",
+		access: "proxy-managed",
+		expires: 32503680000000,
+		projectId: "proxy-managed",
+	};
+
+	writeFileSync(PI_AUTH_FILE, JSON.stringify(auth, null, 2) + "\n", "utf-8");
+	console.log(`  Updated ${PI_AUTH_FILE}`);
+}