pi-antigravity-rotator 1.14.0 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-05-21
+
+### Added
+- **Codex Agent Integration Support**: Out-of-the-box support for connecting agentic frameworks like Codex (executing in VS Code or CLI) by routing OpenAI Responses API payloads and enabling native reasoning streaming, function-calling translation, and strict contract validation.
+- **OpenAI Responses API Compatibility**: Full compatibility with the OpenAI Responses endpoint family (`POST /v1/responses`, `GET /v1/responses/<id>`, `DELETE /v1/responses/<id>`, `POST /v1/responses/<id>/cancel`, and `GET /v1/responses/<id>/input_items`). Includes full support for structured inputs, in-memory conversation/responses storage, and native tool-calling/reasoning visibility, tailored for advanced agentic frameworks.
+- **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,9 +1,43 @@
+![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
 
+- **Compatibility Adapters** -- Includes standard OpenAI-compatible `/v1/chat/completions` and Anthropic-compatible `/v1/messages` APIs. Features comprehensive **OpenAI Responses API compatibility** (`/v1/responses`), enabling seamless integration with advanced agentic systems like Codex.
 - **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 classification (`fresh`/`7d`/`5h`) is evaluated per model using each model's actual `resetTime` from the quota API, not a per-account estimate
@@ -49,6 +83,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 +131,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 +142,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 +265,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 +278,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.
 
@@ -315,6 +380,11 @@ Login now fails if Google does not return a project ID. No shared fallback.
 | `POST` | `/api/self-update` | Trigger npm self-update to latest version (admin-only) |
 | `POST` | `/v1internal:streamGenerateContent` | Native Antigravity proxy endpoint (used by pi) |
 | `GET` | `/v1/models` | OpenAI-compatible model list |
+| `POST` | `/v1/responses` | OpenAI Responses-compatible create endpoint |
+| `GET` | `/v1/responses/<id>` | Retrieve stored Responses result |
+| `DELETE` | `/v1/responses/<id>` | Delete stored Responses result |
+| `POST` | `/v1/responses/<id>/cancel` | Cancel an in-progress stored Responses result |
+| `GET` | `/v1/responses/<id>/input_items` | List stored input items for a Responses result |
 | `POST` | `/v1/chat/completions` | OpenAI-compatible non-streaming chat adapter |
 | `POST` | `/v1/messages` | Anthropic-compatible non-streaming messages adapter |
 
@@ -336,6 +406,18 @@ curl http://localhost:51200/v1/chat/completions \
   }'
 ```
 
+**OpenAI Responses-compatible example:**
+
+```bash
+curl http://localhost:51200/v1/responses \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "gemini-3-flash",
+    "input": [{"role": "user", "content": [{"type": "input_text", "text": "Say pong"}]}],
+    "stream": false
+  }'
+```
+
 **Anthropic-compatible example:**
 
 ```bash
@@ -353,13 +435,56 @@ curl http://localhost:51200/v1/messages \
 Current adapter scope:
 
 - Text chat/messages.
+- **Responses API compatibility**: Supports `POST /v1/responses` plus basic in-memory retrieve/delete/cancel/input-items endpoints for Codex-style agents.
 - **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`).
+- Responses-compatible tool support is currently limited to `type: "function"` tools. Built-in tools like `web_search`, `file_search`, `computer`, or `code_interpreter` are rejected explicitly.
+
+
+## Connecting Codex / VS Code Agents
+
+`pi-antigravity-rotator` can act as the multi-account rotation backend for agentic frameworks, including **Codex** executing in VS Code or in the terminal.
+
+Since Codex uses the standard **OpenAI Responses API**, it can seamlessly route its developer-agent workflows through the rotator.
 
+### Configuration for Codex
+
+To connect Codex to your local rotator:
+
+1. **Configure the API Base URL**:
+   In Codex settings (e.g. in your `.codex` config or VS Code configuration), set the OpenAI API base URL to point to your rotator's compatibility adapter:
+   ```json
+   "codex.openai.apiBase": "http://localhost:51200/v1"
+   ```
+   *(Or set the environment variable `OPENAI_BASE_URL=http://localhost:51200/v1` in the workspace shell).*
+
+2. **Set the API Key / Admin Token**:
+   If you have set a `PI_ROTATOR_ADMIN_TOKEN` for your rotator, configure that token as the API key. Otherwise, any non-empty placeholder string (e.g., `sk-antigravity`) works:
+   ```json
+   "codex.openai.apiKey": "your-rotator-admin-token-here"
+   ```
+   *(Or set the environment variable `OPENAI_API_KEY=...` in the shell).*
+
+3. **Select a Supported Model**:
+   Configure Codex to target one of the following models supported by the rotator (which will be mapped to the best available Google Antigravity account/model under the hood):
+   - `gemini-3.5-flash` or `gemini-3.5-flash-high` / `gemini-3.5-flash-low` (Recommended for fast general reasoning)
+   - `gemini-3-pro` or `gemini-pro-agent` (For deep reasoning)
+   - `claude-sonnet-4-6` or `claude-3-5-sonnet` (Alternative routing fallback)
+
+   Example Codex configuration entry:
+   ```json
+   "codex.model": "gemini-3.5-flash-high"
+   ```
+
+### Features Enabled for Codex Agents
+
+- **Native Reasoning Visibility**: If using models with thinking enabled (e.g., `gemini-3.5-flash-high`), interleaved reasoning/thinking blocks are streamed back in real-time as OpenAI `reasoning_content` chunks. This lets Codex inspect the model's inner thoughts before it acts.
+- **Function / Tool Routing**: Function calls emitted by Codex are fully translated to Gemini `functionCalls` and returned back to Codex safely, enabling full agentic capabilities.
+- **Strict Validation**: The rotator strictly validates the Responses input contract and rejects unsupported tools (e.g., `web_search`) proactively to ensure Codex doesn't hit unexpected runtime exceptions.
 
 ## Development Checks
 
@@ -463,9 +588,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.1.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/)");