pi-antigravity-rotator 1.3.1 → 1.3.3

package/README.md

@@ -6,10 +6,13 @@ 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
 - **Web dashboard** -- Real-time view of model routing table, per-account quota bars with per-model timers, and flagged account alerts
@@ -60,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`).
@@ -70,10 +98,11 @@ 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 flagged or disabled accounts
+  - Re-enable button for disabled accounts
 
 ![Dashboard](dashboard.png)
 
@@ -101,47 +130,90 @@ 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.
 
+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
 
 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 or 5xx, the account is marked exhausted with a cooldown and the affected model immediately switches.
+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:
+
+- 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. Use the Re-enable button or `POST /api/enable/<email>` to clear the flag.
+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
-- Use `POST /api/reset-cooldowns` to clear all cooldowns at once
+- 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
-- **503** (no capacity) -- returned directly to the agent for its own retry/backoff
+- **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
 
+### Dashboard Visibility
+
+The dashboard is intended to replace day-to-day `journalctl` digging for normal operations. The top status panel shows:
+
+- The current routing state (`healthy`, `cooldown_wait`, `busy`, `paused`, `stopped`)
+- 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
+
 ## Configuration
 
 Config files (`accounts.json`, `state.json`) are stored in `~/.pi-antigravity-rotator/` by default. Override with:
@@ -162,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",
@@ -181,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
 
@@ -196,9 +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>` | Clear flagged/disabled state and re-enable an account |
-| `POST` | `/api/reset-cooldowns` | Clear all cooldowns on all accounts |
+| `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
@@ -226,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.
@@ -235,7 +317,7 @@ Check the error message. Common causes: revoked OAuth consent, expired refresh t
 Quota data appears after the first poll cycle (up to 5 minutes). Ensure accounts have valid tokens.
 
 **All accounts exhausted**
-The proxy uses the account with the shortest remaining cooldown. Add more accounts or increase `requestsPerRotation`.
+The proxy now returns `503` and waits for cooldown or manual recovery. It does not reuse cooling-down accounts.
 
 **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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-antigravity-rotator",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "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}`);
+}