opencode-v2-gemini-rotator 0.0.0-stage → 2.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Sabirjanov Abdurahmon
+Copyright (c) 2026 Jianling Zhong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,163 @@
+# Gemini Key Rotator for OpenCode V2
+
+English | [Русский](./README.md)
+
+**Maintained by: Sabirjanov Abdurahmon**
+
+A server-side OpenCode V2 plugin that rotates a pool of Gemini API keys. On HTTP 429, HTTP 503, recognized quota errors, or a recognized invalid key, it updates the key state and uses OpenCode's retry mechanism to select another available key. The implementation adapts the V1 rotator's behavior to the V2 API.
+
+**Tested:** The maintainer confirms real-world testing on OpenCode 2.2.0 with Google API keys from six accounts, including successful key switching after actual HTTP 429 and 503 errors. Compatibility with other V2 versions is not guaranteed.
+
+The automated E2E tests in this repository are separate: they use a **local Gemini API mock and fake keys**, not live accounts.
+
+The implementation is [`index.ts`](./index.ts). It exports `Plugin.define({ id, effect })` and explicitly registers `http.request`, `http.response`, and `retry` through `ctx.session.hook`. It does not patch `globalThis.fetch` or wrap a V1 plugin.
+
+## 1. Installation
+
+The following commands are for Linux, macOS, and other POSIX shells. Extract the archive, then run:
+
+```bash
+cd opencode-gemini-rotator-v2
+CONFIG_ROOT="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
+mkdir -p "$CONFIG_ROOT/plugins/gemini-rotator"
+cp index.ts LICENSE "$CONFIG_ROOT/plugins/gemini-rotator/"
+```
+
+The default location is `~/.config/opencode/plugins/gemini-rotator/index.ts`. OpenCode V2 automatically discovers plugins in this directory. No separate `npm install` or build step is required for normal use: OpenCode loads the single source file. Distribute the accompanying `LICENSE` file with the code to retain the MIT notices.
+
+For a project-local installation, put `index.ts` and `LICENSE` in `.opencode/plugins/gemini-rotator/`. Do not load multiple copies of this plugin. If an older V1 rotator is installed, remove its entry from `plugin`/`plugins` and remove the old automatically discovered files without changing unrelated plugins.
+
+Check your OpenCode version:
+
+```bash
+opencode --version
+```
+
+## 2. Keys and Google provider activation
+
+The rotator needs a key pool, and the **Google provider must also be activated** in OpenCode. Setting `GEMINI_API_KEYS` alone may not activate the provider.
+
+For a standalone run from the current shell:
+
+```bash
+# Replace these placeholders with your own keys; avoid exposing them in shell history.
+export GEMINI_API_KEYS='YOUR_GOOGLE_KEY_1,YOUR_GOOGLE_KEY_2,YOUR_GOOGLE_KEY_3,YOUR_GOOGLE_KEY_4,YOUR_GOOGLE_KEY_5,YOUR_GOOGLE_KEY_6'
+# The provider credential is usually the first key in the pool.
+export GOOGLE_GENERATIVE_AI_API_KEY='YOUR_GOOGLE_KEY_1'
+
+# --standalone starts a private server with this shell's environment.
+opencode run --standalone --model google/gemini-3.7-flash "Say hello"
+```
+
+The six keys above are an example, not a limit. Configure **1 to 256 keys** separated by commas. Empty entries and duplicates are removed. Google applies rate limits per project rather than per API key, so several keys belonging to the same project generally do not increase its quota.
+
+Choose a model available to your account using `opencode models` or `/models`. The example uses `google/gemini-3.7-flash`. **As of October 27, 2026**, Google marks Gemini 3.7 Flash as deprecated and automatically routes its API requests to Gemini 3.8 Flash [1](https://ai.google.dev/gemini-api/docs/models/gemini-3.7-flash). If 3.7 is missing from your OpenCode catalog, select an available model such as `google/gemini-3.8-flash`.
+
+Instead of setting `GOOGLE_GENERATIVE_AI_API_KEY`, you can connect Google through `/connect` and select a model with `/models`. Use the **Gemini API / Google** provider: Vertex and custom gateways are outside this plugin's scope.
+
+### Background service
+
+Exporting a variable in a shell does not update an already running server. For the managed service, set the variables and restart it:
+
+```bash
+# Set the two shell variables shown above first.
+opencode service set env GEMINI_API_KEYS "$GEMINI_API_KEYS"
+opencode service set env GOOGLE_GENERATIVE_AI_API_KEY "$GOOGLE_GENERATIVE_AI_API_KEY"
+opencode service start
+
+opencode run --model google/gemini-3.7-flash "Say hello"
+```
+
+If Google is already connected through `/connect`, setting the provider credential through the service may not be necessary. `service set env` stores a value in service configuration and stops the running service; run `service start` after making all changes. Use `opencode service restart` after changing plugin files. `--standalone` and `opencode serve` use their own process environments and do not automatically inherit managed-service variables.
+
+**Secrets:** Environment values and commands can appear in shell history, service configuration, or process listings. Do not share `opencode service get env` output or commit real keys. Use a secure storage method appropriate to your system. Configuration and keys are read when the plugin loads; restart the relevant server after changing its environment.
+
+## Alternative: configure a plugin directory with options
+
+Use this approach **instead of**, not in addition to, automatic discovery. Place the source outside `plugins/`:
+
+```bash
+CONFIG_ROOT="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
+mkdir -p "$CONFIG_ROOT/custom/gemini-rotator"
+cp index.ts LICENSE "$CONFIG_ROOT/custom/gemini-rotator/"
+```
+
+Add an entry to the `plugins` array in your existing `$CONFIG_ROOT/opencode.json` without overwriting other settings:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "./custom/gemini-rotator",
+      "options": {
+        "keys": [
+          "YOUR_GOOGLE_KEY_1", "YOUR_GOOGLE_KEY_2", "YOUR_GOOGLE_KEY_3",
+          "YOUR_GOOGLE_KEY_4", "YOUR_GOOGLE_KEY_5", "YOUR_GOOGLE_KEY_6"
+        ],
+        "logFile": "/tmp/gemini-rotator-custom.log"
+      }
+    }
+  ]
+}
+```
+
+`package` points to a **directory**, not directly to `index.ts`. Relative paths are resolved from the configuration file. `keys` can also be a comma-separated string. An explicitly supplied `options.keys`, even an empty array, takes precedence over `GEMINI_API_KEYS`. `logFile` is optional. Anyone who can read the JSON file can read keys stored there: restrict file permissions and keep secrets out of version control. Google provider activation is still required.
+
+## How it works
+
+1. For requests to the exact origin `https://generativelanguage.googleapis.com`, the first available configured key is selected. A single incoming `x-goog-api-key`, `?key=`, or Bearer credential is appended if not already present. As in V1, a comma-separated incoming credential specifies its own request pool. Empty entries and duplicates are removed; there is a limit of 256 candidates.
+2. API keys are sent in `x-goog-api-key`; `ya29.*` and `Bearer ...` credentials use `Authorization`. The `?key=` query parameter is removed. Configured credentials are not inserted for other origins.
+3. HTTP **429**, any HTTP **503**, and recognized quota errors in **400/403** place a key on cooldown. The plugin considers `retry-after-ms`, `Retry-After`, Google `RetryInfo.retryDelay`, and suitable hints in the error message. The default is 60 seconds for 429 and 10 seconds for other eligible errors, bounded to 250 ms–24 hours.
+4. An `API_KEY_INVALID` reason or `API key not valid` message in a 400/403 response invalidates the key until the plugin instance reloads. Unrelated 400/403 errors and other status codes are not classified as rotation triggers.
+5. If every valid key is cooling down, the earliest available time is selected. The wait before a new request uses interruptible `Effect.sleep`. If all keys are invalid, a retry is not forced, and a new request fails. Key state is kept in memory and is cleared when the plugin instance reloads.
+6. The plugin does not send an extra HTTP request itself: it adjusts OpenCode's native retry decision and substitutes a key on the next attempt.
+
+## Important limitations
+
+- **Retries are finite.** In OpenCode 2.2.0, the main flow allows up to 10 retries after the first attempt; some errors, such as timeouts, have a lower limit. A request can still fail after the retry budget is exhausted or after output has started. Long waits can also exceed a surrounding timeout. This differs from V1's internal infinite retry loop.
+- V2's `retry` event does not carry the original HTTP request ID. The plugin correlates failures on a best-effort basis using session, agent, model, status, and an expiry time. Concurrent requests in the same session can be correlated incorrectly. `title` and `generate` use a separate retry path: their 429/503 responses affect the key pool, but forced retries for 400/403 are not available in every path.
+- Only the exact HTTPS Gemini API origin is supported. Custom `baseURL` values, Vertex AI, and third-party gateways are intentionally excluded to avoid sending configured keys to another host. A standard HTTPS CONNECT proxy that preserves the original URL is supported.
+- Google [rate limits are per project](https://ai.google.dev/gemini-api/docs/rate-limits), not per API key. Check the limits and terms of the projects you use.
+- The V1 TUI sidebar, toast notifications, and status JSON are **not included**. Use the optional debug log to observe rotations.
+- Wait interruption is covered by an Effect unit test; end-to-end cancellation from the real OpenCode UI has not been tested separately.
+
+## Debugging
+
+For a standalone run:
+
+```bash
+export OPENCODE_GEMINI_DEBUG=1
+opencode run --standalone --model google/gemini-3.7-flash "Say hello"
+tail -f "${TMPDIR:-/tmp}/gemini-rotator-debug.log"
+```
+
+The log is written to the server process's `os.tmpdir()`, which may be different on your system. For the managed service, set `OPENCODE_GEMINI_DEBUG` using `opencode service set env`, then run `opencode service start`. Alternatively, specify an absolute `options.logFile` path. The log includes a key's position in the pool and HTTP status, but not key values, URLs, request or response bodies, or exception text. A new file is created with mode `0600`; existing permissions are not changed. Logging failures do not abort requests.
+
+If rotation does not appear, check that OpenCode V2 is in use, the plugin is not loaded twice, Google is activated, the **server** has the environment variables, and the endpoint has not been redirected to another host. A healthy first key will not rotate until a qualifying error occurs.
+
+## Testing and development
+
+No test files or `npm install` are required for ordinary use. For development, install Node.js (22.19+ recommended for dependencies) and npm:
+
+```bash
+npm ci
+npm test
+npm run typecheck
+```
+
+The optional black-box test starts a real OpenCode binary, creates a temporary certificate using `openssl`, and runs a local TLS CONNECT proxy. It simulates Gemini responses without real API keys. It requires OpenSSL with `-addext` support and OpenCode 2.2.0 in PATH:
+
+```bash
+npm run test:e2e
+# Or specify the CLI path:
+npm run test:e2e -- /absolute/path/to/opencode
+# More diagnostics:
+E2E_DEBUG=1 npm run test:e2e
+```
+
+E2E scenarios cover 429/503, quota-related 403, invalid-key 400, all keys on cooldown, all keys invalid, and automatic discovery of `index.ts`. Unit tests additionally cover a six-key `GEMINI_API_KEYS` pool and the 256-key limit.
+
+## Documentation and license
+
+- OpenCode documentation: [V1-to-V2 migration](https://opencode.ai/v2/docs/build/plugins/migrate-v1/), [server hooks](https://opencode.ai/v2/docs/build/plugins/server/), [plugin loading](https://opencode.ai/v2/docs/plugins/), and [service environment](https://opencode.ai/v2/docs/network/).
+- License: MIT. Keep [`LICENSE`](./LICENSE), including its existing copyright and permission notices, with redistributed copies of the code.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# OpenCode Gemini Rotator V2
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English] | [Русский](README.ru.md)
+
+**Maintained by: Sabirjanov Abdurahmon**
+
+`opencode-v2-gemini-rotator` is a native OpenCode V2 server plugin that provides automatic Google Gemini API key rotation and smart rate-limit fallback. When encountering HTTP 429 (Rate Limit / Quota Exceeded), HTTP 503 (Service Unavailable), quota errors, or invalid keys, it temporarily excludes the active key, selects the next available key from your pool, and triggers OpenCode's native retry pipeline.
+
+Tested and validated on **OpenCode 2.2.0** with a multi-key pool of Google Gemini API keys.
+
+---
+
+## What It Handles
+
+The plugin intercepts responses from `https://generativelanguage.googleapis.com` and automatically classifies error responses to determine rotation policy:
+
+| Status Code / Error | Category / Detection | Plugin Action | Cooldown Period |
+| :--- | :--- | :--- | :--- |
+| **HTTP 429** | Rate Limit / Resource Exhausted | Marks key on cooldown; rotates to next key in pool | Extracted from `Retry-After`, `retry-after-ms`, or Google `RetryInfo` (Default: 60s) |
+| **HTTP 503** | Service Unavailable / Overloaded | Marks key on cooldown; rotates to next key in pool | Extracted from headers/body (Default: 10s) |
+| **HTTP 400 / 403** | Quota Exceeded / Resource Exhausted | Marks key on cooldown; rotates to next key in pool | 10s default or parsed from response delay hints |
+| **HTTP 400 / 403** | `API_KEY_INVALID` / "API key not valid" | Marks key as **permanently invalid** for current process session | Until plugin or server process reload |
+| **Other 4xx / 5xx** | Generic Client/Server Errors | Passed through to OpenCode standard error handling | No key rotation forced |
+
+---
+
+## Who Is This For / Who Is This NOT For
+
+### ✅ Who Is This For
+- **Developers using OpenCode V2** with Google Gemini models (`google/gemini-2.5-flash`, `google/gemini-2.5-pro`, `google/gemini-3.7-flash`, etc.).
+- Users running into **429 Rate Limit / Quota Exceeded** errors on free-tier or pay-as-you-go Gemini API accounts.
+- AI coding agent workflows requiring uninterrupted long-running generation tasks using multiple Google API keys (pool size 1 to 256 keys).
+- Developers who want a clean, single-file plugin without `npm install`, build steps, or monkey-patching `globalThis.fetch`.
+
+### ❌ Who Is This NOT For
+- **OpenCode V1 Users:** This plugin uses OpenCode V2 Server Plugin APIs (`Plugin.define`, `ctx.session.hook`, Effect runtime) and is incompatible with OpenCode V1.
+- **Google Vertex AI / Custom Proxies:** For security and key safety, this plugin exclusively targets the exact origin `https://generativelanguage.googleapis.com`. Custom `baseURL` and Vertex AI endpoints are ignored.
+- **Single Google Cloud Project multi-key pools:** Google applies rate limits at the GCP Project level. Using multiple keys generated from the exact same GCP project will not increase your project quota. Use keys across different GCP projects.
+- **Users expecting TUI status bars / toast UI popups:** OpenCode V2 plugin API handles backend request hooks. Debug logs are accessible via environment variable (`OPENCODE_GEMINI_DEBUG=1`).
+
+---
+
+## Quick Start & Installation
+
+### Option A: Global Single-File Installation (Recommended)
+
+In POSIX shell (Linux / macOS):
+
+```bash
+CONFIG_ROOT="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
+mkdir -p "$CONFIG_ROOT/plugins/gemini-rotator"
+cp index.ts LICENSE "$CONFIG_ROOT/plugins/gemini-rotator/"
+```
+
+OpenCode V2 automatically discovers plugins inside `~/.config/opencode/plugins/gemini-rotator/index.ts`. No `npm install` or compilation step is required.
+
+### Option B: Project-Level Installation
+
+Place `index.ts` and `LICENSE` in `.opencode/plugins/gemini-rotator/` within your project root directory.
+
+---
+
+## Key Configuration
+
+Set your pool of Gemini API keys via the `GEMINI_API_KEYS` environment variable (comma-separated, supporting 1 to 256 keys):
+
+```bash
+export GEMINI_API_KEYS='YOUR_GOOGLE_KEY_1,YOUR_GOOGLE_KEY_2,YOUR_GOOGLE_KEY_3'
+export GOOGLE_GENERATIVE_AI_API_KEY='YOUR_GOOGLE_KEY_1' # Primary provider key
+
+# Run standalone CLI
+opencode run --standalone --model google/gemini-2.5-flash "Write a hello world function"
+```
+
+### Managed Background Service
+
+If using `opencode service`:
+
+```bash
+opencode service set env GEMINI_API_KEYS "$GEMINI_API_KEYS"
+opencode service set env GOOGLE_GENERATIVE_AI_API_KEY "$GOOGLE_GENERATIVE_AI_API_KEY"
+opencode service start
+```
+
+### JSON Options Configuration (`opencode.json`)
+
+Alternative setup placing source in custom location:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "./custom/gemini-rotator",
+      "options": {
+        "keys": [
+          "YOUR_GOOGLE_KEY_1",
+          "YOUR_GOOGLE_KEY_2",
+          "YOUR_GOOGLE_KEY_3"
+        ],
+        "logFile": "/tmp/gemini-rotator-debug.log"
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Debugging
+
+To observe rotation events in real-time, enable debug logging:
+
+```bash
+export OPENCODE_GEMINI_DEBUG=1
+opencode run --standalone --model google/gemini-2.5-flash "Say hello"
+tail -f "${TMPDIR:-/tmp}/gemini-rotator-debug.log"
+```
+
+The log records active key indices, HTTP error status codes, and cooldown durations without logging key secrets, request URLs, or payloads.
+
+---
+
+## Documentation & Machine Readable Specs
+
+- **Full HTML Documentation:** [OpenCode Gemini Rotator V2 Docs](https://sngx762.github.io/opencode-v2-gemini-rotator/)
+- **Machine Readability (LLMs):** [llms.txt](./llms.txt) | [llms-full.txt](./llms-full.txt)
+- **Russian Guide:** [README.ru.md](./README.ru.md)
+
+---
+
+## License
+
+MIT License. See [LICENSE](./LICENSE) for details.

package/README.ru.md

@@ -0,0 +1,163 @@
+# Gemini Key Rotator для OpenCode V2
+
+[English](./README.en.md) | Русский
+
+**Maintained by: Sabirjanov Abdurahmon**
+
+Локальный server-плагин для OpenCode V2 с адаптированной логикой ротации ключей V1. При 429, 503, ошибках квоты и распознанном недействительном ключе он помечает ключ, выбирает следующий и использует механизм повторов OpenCode.
+
+**Tested:** Проверено в реальной работе на OpenCode 2.2.0 с реальными API-ключами Google (пул из 6 аккаунтов). Плагин успешно переживает реальные ошибки 429 (лимиты) и 503 (перегрузка серверов), автоматически переключая ключи. Эту проверку подтвердил сопровождающий проекта. На других версиях V2 совместимость не гарантируется.
+
+Автоматические E2E-тесты из этого репозитория отдельно используют **локальный имитатор Gemini API и тестовые ключи**, а не реальные аккаунты.
+
+Код — в [`index.ts`](./index.ts). Это не V1-обёртка и не патч `globalThis.fetch`: экспортируется `Plugin.define({ id, effect })`, а хуки `http.request`, `http.response` и `retry` явно регистрируются через `ctx.session.hook`. Effect-вариант — штатная альтернатива `setup` в V2.
+
+## 1. Установка
+
+Команды ниже — для Linux/macOS или другой POSIX-оболочки. Распакуйте архив и из каталога проекта выполните:
+
+```bash
+cd opencode-gemini-rotator-v2
+CONFIG_ROOT="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
+mkdir -p "$CONFIG_ROOT/plugins/gemini-rotator"
+cp index.ts LICENSE "$CONFIG_ROOT/plugins/gemini-rotator/"
+```
+
+В обычной конфигурации код окажется в `~/.config/opencode/plugins/gemini-rotator/index.ts`. OpenCode V2 автоматически обнаруживает глобальные плагины в этом каталоге. Для запуска отдельно выполнять `npm install` или сборку **не нужно**: OpenCode загружает один файл кода. Файл `LICENSE` нужно распространять вместе с кодом, чтобы сохранить уведомления MIT.
+
+Для отдельного проекта альтернативный путь — `.opencode/plugins/gemini-rotator/` внутри проекта; разместите там `index.ts` и `LICENSE`. Не включайте одновременно несколько копий этого плагина. Если установлена предыдущая V1-версия ротатора, удалите её запись из `plugin`/`plugins` в соответствующих конфигурациях и уберите старые автоматически обнаруживаемые файлы. Другие плагины и настройки удалять не нужно.
+
+Проверьте версию:
+
+```bash
+opencode --version
+```
+
+## 2. Ключи и подключение Google
+
+Плагину нужен список ключей, а **сам провайдер Google нужно отдельно активировать** в OpenCode. Одной переменной `GEMINI_API_KEYS` для активации провайдера может быть недостаточно.
+
+Вариант для разового запуска в текущем терминале:
+
+```bash
+# Замените значения своими ключами; не оставляйте их в общедоступной истории shell.
+export GEMINI_API_KEYS='YOUR_GOOGLE_KEY_1,YOUR_GOOGLE_KEY_2,YOUR_GOOGLE_KEY_3,YOUR_GOOGLE_KEY_4,YOUR_GOOGLE_KEY_5,YOUR_GOOGLE_KEY_6'
+# Учетные данные провайдера; обычно это первый ключ из списка.
+export GOOGLE_GENERATIVE_AI_API_KEY='YOUR_GOOGLE_KEY_1'
+
+# --standalone запускает отдельный сервер с окружением этого терминала.
+opencode run --standalone --model google/gemini-3.7-flash "Скажи привет"
+```
+
+Шесть ключей выше — только пример: можно указать **от 1 до 256 ключей**, разделённых запятыми. Пустые элементы и дубликаты удаляются. Убедитесь, что ключи относятся к нужным проектам Google: квоты применяются на уровне проекта, а не отдельного ключа.
+
+Выберите доступную вам Google-модель через `opencode models` или `/models` в интерактивном интерфейсе. В примере указан `google/gemini-3.7-flash`. **По состоянию на 27 октября 2026 года** Google помечает Gemini 3.7 Flash устаревшей и автоматически направляет запросы к Gemini 3.8 Flash [1](https://ai.google.dev/gemini-api/docs/models/gemini-3.7-flash). Если 3.7 отсутствует в каталоге OpenCode, выберите доступную модель, например `google/gemini-3.8-flash`.
+
+Вместо `GOOGLE_GENERATIVE_AI_API_KEY` можно подключить Google через `/connect` в интерфейсе OpenCode, после чего выбрать модель через `/models`. Проверяйте именно **Gemini API/Google**; маршруты Vertex и произвольные шлюзы этим плагином не обслуживаются.
+
+### Если используется фоновый сервис
+
+Экспорт в текущем shell не меняет окружение уже запущенного сервера. Для управляемого сервиса задайте переменные и запустите сервис заново:
+
+```bash
+# Сначала задайте обе переменные в текущей оболочке, как показано выше.
+opencode service set env GEMINI_API_KEYS "$GEMINI_API_KEYS"
+opencode service set env GOOGLE_GENERATIVE_AI_API_KEY "$GOOGLE_GENERATIVE_AI_API_KEY"
+opencode service start
+
+opencode run --model google/gemini-3.7-flash "Скажи привет"
+```
+
+Если Google уже подключён через `/connect`, вторая строка `service set env` может не понадобиться. Команда `service set env` сохраняет значение в конфигурации сервиса и останавливает работающий сервис; после всех изменений выполните `service start`. При изменении файлов плагина можно выполнить `opencode service restart`. У `--standalone` и `opencode serve` собственное окружение процесса; они не получают эти значения автоматически из управляемого сервиса.
+
+**Секреты:** значения переменных и команды с ними могут попасть в историю оболочки, конфигурацию сервиса и список процессов. Не отправляйте вывод `opencode service get env` другим людям и не коммитьте ключи в Git. Выбирайте подходящий способ хранения секретов для своей системы. Настройки и ключи читаются при загрузке плагина; после изменения окружения перезапустите соответствующий сервер.
+
+## Альтернатива: явно подключить каталог с options
+
+Используйте **вместо** автозагрузки выше, а не вместе с ней. Например, разместите исходник вне `plugins/`:
+
+```bash
+CONFIG_ROOT="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
+mkdir -p "$CONFIG_ROOT/custom/gemini-rotator"
+cp index.ts LICENSE "$CONFIG_ROOT/custom/gemini-rotator/"
+```
+
+Добавьте элемент в массив `plugins` существующего `$CONFIG_ROOT/opencode.json` (не затирайте остальные настройки):
+
+```json
+{
+  "plugins": [
+    {
+      "package": "./custom/gemini-rotator",
+      "options": {
+        "keys": [
+          "YOUR_GOOGLE_KEY_1", "YOUR_GOOGLE_KEY_2", "YOUR_GOOGLE_KEY_3",
+          "YOUR_GOOGLE_KEY_4", "YOUR_GOOGLE_KEY_5", "YOUR_GOOGLE_KEY_6"
+        ],
+        "logFile": "/tmp/gemini-rotator-custom.log"
+      }
+    }
+  ]
+}
+```
+
+Путь `package` указывает на **каталог**, а не на `index.ts`; относительный путь разрешается относительно файла конфигурации. `keys` также может быть одной строкой с ключами через запятую. Явно заданный `options.keys`, даже пустой массив, имеет приоритет над `GEMINI_API_KEYS`. `logFile` необязателен. Хранение ключей в JSON означает, что к ним получит доступ каждый, кто может прочитать файл; ограничьте права и не включайте файл в репозиторий. Активация провайдера Google по-прежнему нужна.
+
+## Поведение
+
+1. При запросе к точному origin `https://generativelanguage.googleapis.com` выбирается первый доступный ключ из настроенного списка. Одиночный ключ из исходного `x-goog-api-key`, `?key=` или Bearer-заголовка добавляется в конец списка, если его там ещё нет. Список через запятую в самом исходном credential, как и в V1, задаёт отдельный пул для этого запроса. Пустые элементы и дубликаты убираются. Лимит — 256 кандидатов.
+2. API-ключ отправляется в `x-goog-api-key`, а `ya29.*` и `Bearer ...` — в `Authorization`. `?key=` из URL удаляется. На другие origin плагин ключи не подставляет.
+3. При **429** и любом **503**, а также при распознанной ошибке квоты в **400/403**, ключ временно исключается. Учитываются `retry-after-ms`, `Retry-After`, Google `RetryInfo.retryDelay` или подходящая подсказка в сообщении. Без подсказки: 60 секунд для 429 и 10 секунд для остальных; задержка ограничена диапазоном 250 мс — 24 часа.
+4. При `API_KEY_INVALID` или сообщении `API key not valid` в 400/403 ключ считается недействительным до выгрузки/перезагрузки экземпляра плагина. Прочие ошибки 400/403 и остальные статусы плагин не классифицирует как повод для ротации.
+5. Если все действительные ключи на паузе, выбирается ближайший срок освобождения. Задержка перед новым запросом использует прерываемый `Effect.sleep`; если все ключи недействительны, повтор не форсируется, а новый запрос завершается ошибкой. Статусы и cooldown хранятся только в памяти экземпляра плагина; его перезагрузка сбрасывает их.
+6. Плагин не делает собственный дополнительный HTTP-запрос: он задаёт политику штатного повтора V2 и подставляет следующий ключ в следующей попытке.
+
+## Важные ограничения
+
+- **Повторы не бесконечны.** В OpenCode 2.2.0 для основного потока есть встроенный предел: до 10 повторов после первой попытки; для некоторых ошибок, например timeout, предел меньше. После расходования бюджета или после начала выдачи текста запрос всё равно может завершиться ошибкой. Если пауза превышает лимиты окружения или запроса, возможно прерывание по timeout. Это отличается от внутреннего бесконечного цикла V1.
+- В V2 событие `retry` не передаёт ID исходного HTTP-запроса. Связь с ошибкой восстанавливается приблизительно по сессии, агенту, модели и HTTP-статусу с ограниченным временем жизни записи. При конкурентных запросах в одной сессии соответствие не гарантировано. `title` и `generate` используют собственный путь повторов: их 429/503 влияют на выбор ключа при следующих попытках, но принудительный повтор для 400/403 есть не во всех путях.
+- Распознаётся только точный HTTPS origin Google Gemini API. Кастомный `baseURL`, Vertex AI и сторонний шлюз намеренно исключены, чтобы не отправлять туда ключи. Обычный сетевой HTTPS CONNECT-прокси, сохраняющий исходный URL, допустим.
+- Google применяет [rate limits на уровне проекта](https://ai.google.dev/gemini-api/docs/rate-limits), а не каждого ключа. Несколько ключей одного проекта обычно не увеличат его квоту; проверяйте условия и лимиты своих проектов.
+- V1 TUI-сайдбар, toast-уведомления и статусный JSON **не перенесены**. Ротацию можно наблюдать через необязательный отладочный лог.
+- Прерывание ожидания проверено unit-тестом Effect; отдельный end-to-end тест отмены из реального интерфейса OpenCode не проводился.
+
+## Отладка
+
+Для standalone запустите процесс с `OPENCODE_GEMINI_DEBUG=1`:
+
+```bash
+export OPENCODE_GEMINI_DEBUG=1
+opencode run --standalone --model google/gemini-3.7-flash "Скажи привет"
+tail -f "${TMPDIR:-/tmp}/gemini-rotator-debug.log"
+```
+
+Файл пишется в `os.tmpdir()` процесса сервера; в зависимости от системы это может быть другой каталог. Для фонового сервиса установите `OPENCODE_GEMINI_DEBUG` через `opencode service set env`, затем `opencode service start`. Альтернативно задайте `options.logFile` с абсолютным путём. Лог содержит номер ключа в пуле и статус, но не значение ключа, URL, тело запроса, тело ответа или текст ошибки. Новый файл создаётся с режимом `0600`; права существующего файла не меняются. Запись лога необязательна: её ошибка не прерывает запрос.
+
+При поиске неисправности проверьте, что используется OpenCode V2, плагин не загружен дважды, Google-провайдер активен, переменные доступны **серверу**, а endpoint не переопределён на другой host. Если первый ключ работает, переключения в логе не будет до первой подходящей ошибки.
+
+## Проверки и разработка
+
+Для обычного использования файлы тестов и `npm install` не нужны. Для разработки понадобятся Node.js (рекомендуется 22.19+ для зависимостей), npm и исходники архива:
+
+```bash
+npm ci
+npm test                 # unit-тесты
+npm run typecheck        # TypeScript
+```
+
+Дополнительный black-box тест запускает настоящий OpenCode, создаёт временный сертификат с `openssl` и локальный TLS CONNECT proxy. Он не использует реальные API-ключи и моделирует ответы Gemini. Нужны `openssl` с поддержкой `-addext` и OpenCode 2.2.0 в PATH:
+
+```bash
+npm run test:e2e
+# или указать путь к CLI:
+npm run test:e2e -- /absolute/path/to/opencode
+# подробности диагностики:
+E2E_DEBUG=1 npm run test:e2e
+```
+
+E2E-проверки охватывают ротацию при 429/503, quota-403 и invalid-key-400, ожидание при cooldown всех ключей, остановку при всех недействительных ключах, а также автозагрузку `index.ts`. Unit-тесты дополнительно проверяют пул из шести ключей через `GEMINI_API_KEYS` и ограничение в 256 ключей.
+
+## Документация и лицензия
+
+- Документация OpenCode: [миграция плагинов V1 → V2](https://opencode.ai/v2/docs/build/plugins/migrate-v1/), [серверные хуки](https://opencode.ai/v2/docs/build/plugins/server/), [загрузка плагинов](https://opencode.ai/v2/docs/plugins/), [окружение сервиса](https://opencode.ai/v2/docs/network/).
+- Лицензия: MIT. При распространении сохраняйте [`LICENSE`](./LICENSE) вместе с кодом.

package/index.ts

@@ -0,0 +1,354 @@
+/*
+ * Gemini Key Rotator for OpenCode V2.
+ * Maintainer: Sabirjanov Abdurahmon.
+ * SPDX-License-Identifier: MIT
+ * Copyright and license notices: see the accompanying LICENSE file.
+ * Targeted and tested against OpenCode 2.2.0 / @opencode/plugin 2.2.0.
+ */
+import { Plugin } from "@opencode/plugin/effect"
+import type { SessionHttpResponse, SessionRetry } from "@opencode/plugin/effect/session"
+import { Duration, Effect } from "effect"
+import { appendFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+const GEMINI_ORIGIN = "https://generativelanguage.googleapis.com"
+const MAX_CONFIGURED_KEYS = 256
+const MAX_TRACKED_KEYS = 512
+const MAX_ERROR_BYTES = 64 * 1024
+const ERROR_READ_TIMEOUT_MS = 1_500
+const FAILURE_TTL_MS = 2 * 60_000
+const MAX_FAILURES = 512
+const MIN_COOLDOWN_MS = 250
+const MAX_COOLDOWN_MS = 24 * 60 * 60_000
+
+type KeyState = { invalid: boolean; availableAt: number }
+type RequestMeta = { candidates: string[] }
+type Failure = { at: number; candidates: string[] }
+type Classification = { kind: "invalid" } | { kind: "cooldown"; ms: number }
+
+/** Normalize OAuth values so `ya29.x` and `Bearer ya29.x` share one state. */
+function normalizeKey(value: string): string | undefined {
+  let key = value.trim()
+  if (!key) return undefined
+  if (/^bearer\s+/i.test(key)) key = `Bearer ${key.replace(/^bearer\s+/i, "")}`
+  else if (key.startsWith("ya29.")) key = `Bearer ${key}`
+  const secret = key.startsWith("Bearer ") ? key.slice(7) : key
+  // Reject CR/LF, whitespace, non-ASCII and unreasonably large header values.
+  if (!secret || secret.length > 8_192 || !/^[\x21-\x7e]+$/.test(secret)) return undefined
+  return key
+}
+
+function uniqueKeys(values: string[]): string[] {
+  const keys: string[] = []
+  for (const value of values) {
+    const trimmed = value.trim()
+    if (!trimmed) continue
+    const key = normalizeKey(trimmed)
+    if (!key) throw new Error("[gemini-rotator] Invalid key format in plugin configuration")
+    if (!keys.includes(key)) keys.push(key)
+  }
+  if (keys.length > MAX_CONFIGURED_KEYS) {
+    throw new Error(`[gemini-rotator] At most ${MAX_CONFIGURED_KEYS} keys are supported`)
+  }
+  return keys
+}
+
+function configuredKeys(options: Readonly<Record<string, unknown>>): string[] {
+  const raw = options.keys === undefined ? process.env.GEMINI_API_KEYS : options.keys
+  if (raw === undefined) return []
+  if (typeof raw === "string") return uniqueKeys(raw.split(","))
+  if (Array.isArray(raw) && raw.every((entry) => typeof entry === "string")) {
+    return uniqueKeys(raw as string[])
+  }
+  throw new Error("[gemini-rotator] options.keys must be a string or an array of strings")
+}
+
+function logger(options: Readonly<Record<string, unknown>>): (message: string) => void {
+  if (options.logFile !== undefined && typeof options.logFile !== "string") {
+    throw new Error("[gemini-rotator] options.logFile must be a path string")
+  }
+  const path = (options.logFile as string | undefined) ||
+    (process.env.OPENCODE_GEMINI_DEBUG === "1" ? join(tmpdir(), "gemini-rotator-debug.log") : undefined)
+  if (!path) return () => {}
+  return (message) => {
+    // Never write response bodies, URLs, headers, keys, or exception text.
+    void appendFile(path, `[${new Date().toISOString()}] ${message}\n`, { mode: 0o600 }).catch(() => {})
+  }
+}
+
+function geminiURL(request: Request): URL | undefined {
+  try {
+    const url = new URL(request.url)
+    // Do not send Google credentials to proxies, custom gateways, Vertex, or other hosts.
+    return url.origin === GEMINI_ORIGIN ? url : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function providedCredentials(request: Request, url: URL): string[] {
+  const auth = request.headers.get("authorization")
+  const supplied = request.headers.get("x-goog-api-key") || url.searchParams.get("key") ||
+    (auth && /^bearer\s+/i.test(auth) ? auth : "")
+  if (!supplied) return []
+  // The V1 plugin accepted a comma-separated list in an incoming credential.
+  return supplied.split(",").map(normalizeKey).filter((key): key is string => key !== undefined)
+}
+
+class KeyPool {
+  private readonly states = new Map<string, KeyState>()
+  private readonly protectedKeys: Set<string>
+
+  constructor(readonly configured: string[]) {
+    this.protectedKeys = new Set(configured)
+    for (const key of configured) this.state(key)
+  }
+
+  state(key: string): KeyState {
+    const existing = this.states.get(key)
+    if (existing) {
+      // LRU order for bounded tracking of dynamically observed credentials.
+      this.states.delete(key)
+      this.states.set(key, existing)
+      return existing
+    }
+    if (this.states.size >= MAX_TRACKED_KEYS) {
+      const evict = [...this.states.keys()].find((item) => !this.protectedKeys.has(item))
+      if (evict !== undefined) this.states.delete(evict)
+    }
+    const created: KeyState = { invalid: false, availableAt: 0 }
+    this.states.set(key, created)
+    return created
+  }
+
+  knows(key: string): boolean {
+    return this.states.has(key)
+  }
+
+  candidates(request: Request, url: URL): string[] {
+    const supplied = providedCredentials(request, url)
+    // Match V1: an incoming comma-separated credential supplies its own pool.
+    const raw = request.headers.get("x-goog-api-key") || url.searchParams.get("key") ||
+      request.headers.get("authorization") || ""
+    const candidates = raw.includes(",") ? supplied : [...this.configured, ...supplied]
+    return [...new Set(candidates)].slice(0, MAX_CONFIGURED_KEYS)
+  }
+
+  choice(candidates: string[], now = Date.now()): { key: string; wait: number } | undefined {
+    let earliest: { key: string; wait: number } | undefined
+    for (const key of candidates) {
+      const state = this.state(key)
+      if (state.invalid) continue
+      const wait = Math.max(0, state.availableAt - now)
+      if (wait === 0) return { key, wait: 0 }
+      if (!earliest || wait < earliest.wait) earliest = { key, wait }
+    }
+    return earliest
+  }
+}
+
+function sendWithKey(event: { request: Request }, url: URL, key: string): void {
+  // Request URL is immutable. Rebuild only when removing a query-string key;
+  // Request copies method, body, headers, and signal to the new request.
+  if (url.searchParams.has("key")) {
+    url.searchParams.delete("key")
+    event.request = new Request(url.toString(), event.request)
+  }
+  if (key.startsWith("Bearer ")) {
+    event.request.headers.set("authorization", key)
+    event.request.headers.delete("x-goog-api-key")
+  } else {
+    event.request.headers.set("x-goog-api-key", key)
+    event.request.headers.delete("authorization")
+  }
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+/** Read a bounded clone, leaving the response OpenCode will consume untouched. */
+async function readErrorJSON(response: Response, signal: AbortSignal): Promise<unknown> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const cancel = () => { if (reader) void reader.cancel().catch(() => {}) }
+  try {
+    const clone = response.clone()
+    if (!clone.body) return undefined
+    reader = clone.body.getReader()
+    signal.addEventListener("abort", cancel, { once: true })
+    if (signal.aborted) return undefined
+    timer = setTimeout(cancel, ERROR_READ_TIMEOUT_MS)
+    const decoder = new TextDecoder()
+    let text = ""
+    let bytes = 0
+    for (;;) {
+      const part = await reader.read()
+      if (part.done) break
+      bytes += part.value.byteLength
+      if (bytes > MAX_ERROR_BYTES) return undefined
+      text += decoder.decode(part.value, { stream: true })
+    }
+    text += decoder.decode()
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  } finally {
+    if (timer) clearTimeout(timer)
+    signal.removeEventListener("abort", cancel)
+    cancel() // Do not await cancellation of one branch of a tee'd stream.
+  }
+}
+
+function parseDuration(value: string): number | undefined {
+  const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h)$/i)
+  if (!match) return undefined
+  const scale: Record<string, number> = { ms: 1, s: 1_000, m: 60_000, h: 3_600_000 }
+  const ms = Number(match[1]) * scale[match[2].toLowerCase()]
+  return Number.isFinite(ms) ? ms : undefined
+}
+
+function retryAfter(headers: Headers, error: Record<string, unknown> | undefined): number | undefined {
+  const millis = headers.get("retry-after-ms")
+  if (millis && /^\d+(?:\.\d+)?$/.test(millis.trim())) return Number(millis)
+  const header = headers.get("retry-after")?.trim()
+  if (header) {
+    if (/^\d+(?:\.\d+)?$/.test(header)) return Number(header) * 1_000
+    const date = Date.parse(header)
+    if (Number.isFinite(date)) return Math.max(0, date - Date.now())
+  }
+  const details = Array.isArray(error?.details) ? error.details : []
+  for (const detail of details) {
+    const entry = record(detail)
+    if (typeof entry?.retryDelay === "string") {
+      const ms = parseDuration(entry.retryDelay)
+      if (ms !== undefined) return ms
+    }
+  }
+  const message = typeof error?.message === "string" ? error.message : ""
+  const match = message.match(/(?:reset\s+after|retry\s+(?:in|after))\s+(\d+(?:\.\d+)?\s*(?:ms|s|m|h))\b/i)
+  return match ? parseDuration(match[1]) : undefined
+}
+
+function classify(response: Response, data: unknown): Classification | undefined {
+  const status = response.status
+  if (![400, 403, 429, 503].includes(status)) return undefined
+  const error = record(record(data)?.error)
+  const message = typeof error?.message === "string" ? error.message.toLowerCase() : ""
+  const errorStatus = typeof error?.status === "string" ? error.status.toLowerCase() : ""
+  const details = Array.isArray(error?.details) ? error.details : []
+  const reasons = details.map((detail) => record(detail)?.reason)
+    .filter((reason): reason is string => typeof reason === "string")
+    .map((reason) => reason.toLowerCase())
+
+  if ((status === 400 || status === 403) &&
+      (message.includes("api key not valid") || reasons.some((reason) => reason.includes("api_key_invalid")))) {
+    return { kind: "invalid" }
+  }
+  const quota = message.includes("quota") || message.includes("rate limit") ||
+    reasons.some((reason) => reason.includes("rate_limit") || reason.includes("quota_exceeded")) ||
+    errorStatus === "resource_exhausted" || errorStatus === "unavailable"
+  // Unlike V1, every 503 rotates, including a non-JSON UNAVAILABLE response.
+  if (status !== 429 && status !== 503 && !quota) return undefined
+  const suggested = retryAfter(response.headers, error)
+  const fallback = status === 429 ? 60_000 : 10_000
+  const ms = Number.isFinite(suggested) ? suggested! : fallback
+  return { kind: "cooldown", ms: Math.min(MAX_COOLDOWN_MS, Math.max(MIN_COOLDOWN_MS, Math.ceil(ms))) }
+}
+
+function scopeKey(event: Pick<SessionHttpResponse, "sessionID" | "agent" | "model">, status: number): string {
+  return JSON.stringify([event.sessionID, event.agent, event.model.providerID, event.model.id, status])
+}
+
+export default Plugin.define({
+  id: "gemini-key-rotator",
+  effect: (ctx) => Effect.gen(function* () {
+    const options: Readonly<Record<string, unknown>> = ctx.options ?? {}
+    const pool = new KeyPool(configuredKeys(options))
+    const log = logger(options)
+    const requests = new WeakMap<Request, RequestMeta>()
+    const failures = new Map<string, Failure[]>()
+    log(`loaded: ${pool.configured.length} configured key(s)`)
+
+    yield* ctx.session.hook("http.request", (event) => Effect.gen(function* () {
+      const url = geminiURL(event.request)
+      if (!url) return
+      const candidates = pool.candidates(event.request, url)
+      if (candidates.length === 0) return // Let OpenCode handle missing credentials normally.
+
+      // Effect.sleep is interruptible: stopping the session cancels this wait.
+      let selected: { key: string; wait: number } | undefined
+      for (;;) {
+        selected = pool.choice(candidates)
+        if (!selected) {
+          return yield* Effect.die(new Error("[gemini-rotator] All available Gemini keys are invalid"))
+        }
+        if (selected.wait <= 0) break
+        yield* Effect.sleep(Duration.millis(selected.wait))
+        // Re-evaluate after waking: another request may have extended the cooldown.
+      }
+      sendWithKey(event, url, selected.key)
+      requests.set(event.request, { candidates })
+      log(`request: key #${candidates.indexOf(selected.key) + 1}/${candidates.length}`)
+    }))
+
+    yield* ctx.session.hook("http.response", (event) => Effect.gen(function* () {
+      const url = geminiURL(event.request)
+      if (!url || ![400, 403, 429, 503].includes(event.response.status)) return
+      const sent = providedCredentials(event.request, url)[0]
+      if (!sent) return
+      const metadata = requests.get(event.request)
+      // Another plugin can replace Request after our request hook; only act on a key we know.
+      if (!metadata && !pool.knows(sent)) return
+      const candidates = metadata?.candidates ?? [...new Set([...pool.configured, sent])]
+      if (!candidates.includes(sent)) return
+
+      const data = yield* Effect.promise((signal) => readErrorJSON(event.response, signal))
+      const result = classify(event.response, data)
+      if (!result) return
+      const state = pool.state(sent)
+      if (result.kind === "invalid") state.invalid = true
+      else state.availableAt = Math.max(state.availableAt, Date.now() + result.ms)
+      log(`response: HTTP ${event.response.status}; key #${candidates.indexOf(sent) + 1}/${candidates.length}; ` +
+        (result.kind === "invalid" ? "invalid" : `cooldown ${result.ms}ms`))
+
+      // The retry hook has no request ID or kind. Title/generate calls use their
+      // own retry path, so they must not overwrite a primary/compaction failure.
+      if (event.kind !== "primary" && event.kind !== "compaction") return
+      const now = Date.now()
+      for (const [key, values] of failures) {
+        const fresh = values.filter((failure) => now - failure.at < FAILURE_TTL_MS)
+        if (fresh.length === 0) failures.delete(key)
+        else failures.set(key, fresh)
+      }
+      const key = scopeKey(event, event.response.status)
+      const list = failures.get(key) ?? []
+      list.push({ at: now, candidates })
+      failures.delete(key)
+      failures.set(key, list.slice(-4))
+      while (failures.size > MAX_FAILURES) {
+        const first = failures.keys().next().value
+        if (first === undefined) break
+        failures.delete(first)
+      }
+    }))
+
+    yield* ctx.session.hook("retry", (event: SessionRetry) => Effect.sync(() => {
+      const status = event.error.status
+      if (status === undefined) return
+      const key = scopeKey(event, status)
+      const list = failures.get(key)
+      if (!list?.length) return // Do not alter unrelated provider failures.
+      const failure = list.pop()!
+      if (list.length === 0) failures.delete(key)
+      if (Date.now() - failure.at >= FAILURE_TTL_MS) return
+      const next = pool.choice(failure.candidates)
+      // All invalid: expose the original provider error rather than retry forever.
+      event.decision = next ? { retry: true, delay: next.wait } : { retry: false }
+      log(next ? `retry: wait ${Math.ceil(next.wait)}ms` : "retry: all keys invalid")
+    }))
+  }),
+})

package/llms-full.txt

@@ -0,0 +1,63 @@
+# Complete Documentation: OpenCode Gemini Rotator V2
+
+## Project Metadata
+- Project Name: OpenCode Gemini Rotator V2 (`opencode-v2-gemini-rotator`)
+- Repository: https://github.com/sngx762/opencode-v2-gemini-rotator
+- Maintained by: Sabirjanov Abdurahmon
+- License: MIT License
+- Tested Platform: OpenCode 2.2.0
+
+## Problem Statement
+When developers run high-throughput AI coding agent tasks using Google Gemini models (`google/gemini-2.5-flash`, `google/gemini-2.5-pro`, `google/gemini-3.7-flash`) in OpenCode V2, they frequently hit HTTP 429 Too Many Requests, HTTP 503 Service Unavailable, or daily quota limits. Single API keys trigger immediate session halts.
+
+## Core Capabilities
+1. Automatic Key Rotation: Intercepts requests targeting https://generativelanguage.googleapis.com. Upon encountering 429 or 503 errors, puts the current key on temporary cooldown and automatically injects the next available key from the pool.
+2. Smart Cooldown Parsing: Parses Retry-After, retry-after-ms, or Google RetryInfo payloads. Defaults to 60s cooldown for 429 rate limits and 10s for 503 service overload.
+3. Invalid Key Handling: If an API key returns API_KEY_INVALID or "API key not valid", it is permanently marked invalid for the process session.
+4. Single-File Installation: Zero build steps or npm install required for end users. Discovered automatically at ~/.config/opencode/plugins/gemini-rotator/index.ts.
+5. Key Security: Exclusively targets official Google Gemini endpoints. Vertex AI and third-party custom proxy URLs are deliberately excluded to eliminate credential leakage risks.
+
+## Error Handling Table
+| HTTP Status | Category | Cooldown | Action |
+| --- | --- | --- | --- |
+| 429 | Rate Limit / Quota | Extracted from headers/body (Default 60s) | Rotates to next valid key |
+| 503 | Overloaded | Extracted from headers/body (Default 10s) | Rotates to next valid key |
+| 400 / 403 | Quota Limit | 10s default | Rotates to next valid key |
+| 400 / 403 | API_KEY_INVALID | Permanent for process session | Marks key invalid, rotates |
+
+## Installation & Configuration
+
+### Global Single-File Installation
+```bash
+CONFIG_ROOT="${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
+mkdir -p "$CONFIG_ROOT/plugins/gemini-rotator"
+cp index.ts LICENSE "$CONFIG_ROOT/plugins/gemini-rotator/"
+```
+
+### Environment Variables
+```bash
+export GEMINI_API_KEYS='YOUR_KEY_1,YOUR_KEY_2,YOUR_KEY_3'
+export GOOGLE_GENERATIVE_AI_API_KEY='YOUR_KEY_1'
+opencode run --standalone --model google/gemini-2.5-flash "Say hello"
+```
+
+### Managed Service Environment
+```bash
+opencode service set env GEMINI_API_KEYS "$GEMINI_API_KEYS"
+opencode service set env GOOGLE_GENERATIVE_AI_API_KEY "$GOOGLE_GENERATIVE_AI_API_KEY"
+opencode service start
+```
+
+## Debugging
+Enable debug output to inspect key indices and cooldowns without revealing API secrets:
+```bash
+export OPENCODE_GEMINI_DEBUG=1
+opencode run --standalone --model google/gemini-2.5-flash "Say hello"
+tail -f "${TMPDIR:-/tmp}/gemini-rotator-debug.log"
+```
+
+## Non-Goals & Limitations
+- Not compatible with OpenCode V1 (requires OpenCode V2 plugin model).
+- Does not bypass GCP project-level rate limits if all keys belong to the same Google Cloud project. Keys should be created across distinct GCP projects.
+- Does not render TUI status bars or popups in OpenCode terminal UI.
+- Maximum retry budget is constrained by OpenCode V2's native retry engine (up to 10 retries).

package/llms.txt

@@ -0,0 +1,20 @@
+# OpenCode Gemini Rotator V2
+
+> Native OpenCode V2 server plugin for automatic Google Gemini API key rotation on 429 Rate Limits, 503 errors, and quota exhaustion.
+
+OpenCode Gemini Rotator V2 (`opencode-v2-gemini-rotator`) handles HTTP 429 (Rate Limit / Resource Exhausted), HTTP 503 (Service Overloaded), quota limits, and invalid keys during AI coding sessions in OpenCode 2.2.0+. It provides seamless multi-key fallback across a pool of up to 256 Google Gemini API keys without monkey-patching fetch or adding external proxy processes.
+
+## Main Documentation
+
+- [Project Homepage](https://sngx762.github.io/opencode-v2-gemini-rotator/index.html): Overview, problem description, and single-file setup guide.
+- [How Key Rotation Works](https://sngx762.github.io/opencode-v2-gemini-rotator/solution.html): Architecture, Effect.ts session hooks, and error classification details.
+- [Who Is It For](https://sngx762.github.io/opencode-v2-gemini-rotator/who-is-it-for.html): Target developer audience and ideal AI coding workflows.
+- [Who Is It NOT For](https://sngx762.github.io/opencode-v2-gemini-rotator/who-is-it-not-for.html): Transparent list of limitations, non-goals, and unsupported platforms.
+- [Frequently Asked Questions](https://sngx762.github.io/opencode-v2-gemini-rotator/faq.html): FAQ covering 429 rate limit fixes, key pool limits, and security details.
+- [Alternatives Comparison](https://sngx762.github.io/opencode-v2-gemini-rotator/alternatives.html): Feature matrix comparing Rotator V2 against LiteLLM, OpenRouter, V1 Rotator, and native retries.
+- [V1 vs V2 Comparison](https://sngx762.github.io/opencode-v2-gemini-rotator/vs/opencode-gemini-rotator-v1.html): Technical differences and migration steps from legacy V1 plugin.
+- [Real-World Use Cases](https://sngx762.github.io/opencode-v2-gemini-rotator/use-cases.html): Multi-file refactoring and background session use cases.
+
+## Full Plain Text Context
+
+- [Full Plain Text Documentation](https://sngx762.github.io/opencode-v2-gemini-rotator/llms-full.txt): Complete markdown context for LLMs and AI crawlers.

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "opencode-v2-gemini-rotator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Native OpenCode V2 plugin for automatic Google Gemini API key rotation on 429 Rate Limits and 503 errors.",
+  "author": "Sabirjanov Abdurahmon",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "README.ru.md",
+    "LICENSE",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "test:e2e": "node test/e2e.mjs"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.2.0",
+    "effect": "4.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  }
+}