@albinocrabs/o-switcher 0.1.0 → 0.2.0

package/README.md

@@ -1,52 +1,77 @@
 # O-Switcher
 
-[English](#english) | [Русский](#русский)
+[![npm version](https://img.shields.io/npm/v/@albinocrabs/o-switcher)](https://www.npmjs.com/package/@albinocrabs/o-switcher)
+[![CI](https://github.com/apolenkov/o-switcher/actions/workflows/ci.yml/badge.svg)](https://github.com/apolenkov/o-switcher/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
----
+Seamless OpenRouter profile rotation for [OpenCode](https://opencode.ai). Buy multiple cheap subscriptions — when one hits its quota or rate limit, O-Switcher silently switches to the next profile. No manual intervention needed.
 
-## English
+## Why?
 
-### What is it?
+- OpenRouter profiles have quota limits and rate limits
+- Without O-Switcher: quota runs out, you manually re-auth with another profile, lose context
+- With O-Switcher: automatic rotation across profiles, work continues uninterrupted
+- Buy 5 cheap subscriptions → use them as one seamless pool
 
-An [OpenCode](https://opencode.ai) plugin that automatically switches between LLM providers when one goes down. If Anthropic returns errors — your request silently goes to OpenAI. No manual intervention needed.
-
-### Why?
-
-- Provider APIs go down, hit rate limits, or return errors
-- Without O-Switcher: you wait, manually switch providers, lose context
-- With O-Switcher: automatic retry, failover to backup provider, work continues
-
-### Install
+## Quick Start
 
 Add to your `opencode.json`:
 
 ```json
 {
-  "plugin": [
-    "@apolenkov/o-switcher@latest"
-  ]
+  "plugin": ["@albinocrabs/o-switcher@latest"]
 }
 ```
 
-Or for local development:
+That's it. O-Switcher auto-discovers all your configured OpenCode providers.
 
-```json
-{
-  "plugin": [
-    "/path/to/o-switcher"
-  ]
-}
+## How It Works
+
+```mermaid
+flowchart LR
+    subgraph pool["Subscription Pool"]
+        A["Profile A<br/>$5/mo"] 
+        B["Profile B<br/>$5/mo"]
+        C["Profile C<br/>$5/mo"]
+    end
+
+    R([LLM Request]) --> SW{O-Switcher}
+    SW -->|healthy| A
+    A -.->|"quota hit ❌"| SW
+    SW -->|rotate| B
+    B -.->|"quota hit ❌"| SW
+    SW -->|rotate| C
+    C -->|"✅ success"| RES([Response])
+
+    style pool fill:#f0f9ff,stroke:#0284c7
+    style SW fill:#4a9eff,color:#fff
+    style RES fill:#6f6,color:#000
 ```
 
-### Configure
+1. **Install the plugin** — add `@albinocrabs/o-switcher@latest` to your `opencode.json`
+2. **Auto-discovers your profiles** — O-Switcher reads all configured OpenRouter profiles at startup
+3. **Re-authenticate to add more** — run `opencode auth login openrouter` with another key, O-Switcher saves both profiles
+4. **Switcher rotates** — when one profile hits quota or rate limit, requests automatically route to the next
+
+When a request fails, O-Switcher classifies the error and acts:
+
+| Error | Action |
+|-------|--------|
+| Rate limited (429) | Waits and retries with backoff (up to 3 times) |
+| Server error (5xx) | Retries with exponential backoff |
+| Model unavailable | Immediately tries next target |
+| Auth error (401) | Stops, marks target for re-authentication |
+| All retries exhausted | Fails over to backup target (up to 2 failovers) |
+
+All routing decisions are logged as structured NDJSON for debugging.
 
-That's it. O-Switcher auto-discovers all configured providers from your OpenCode config. No target configuration needed.
+## Configuration
 
-Want to customize retry and timeout?
+Optional — O-Switcher works with zero config. Customize retry and timeout if needed:
 
 ```json
 {
-  "plugin": ["@apolenkov/o-switcher@latest"],
+  "plugin": ["@albinocrabs/o-switcher@latest"],
   "switcher": {
     "retry": 3,
     "timeout": 30000
@@ -54,308 +79,83 @@ Want to customize retry and timeout?
 }
 ```
 
-Both fields are optional with sensible defaults.
+| Option | Default | Description |
+|--------|---------|-------------|
+| `retry` | `3` | Max retry attempts per request |
+| `timeout` | `30000` | Request timeout in milliseconds |
 
-### Examples
+## Examples
 
 **Zero config — just add the plugin:**
 
 ```json
 {
-  "plugin": ["@apolenkov/o-switcher@latest"]
+  "plugin": ["@albinocrabs/o-switcher@latest"]
 }
 ```
 
-O-Switcher reads your configured providers (anthropic, openai, etc.) and creates targets automatically. You get: automatic retry on errors, circuit breaker protection, health monitoring.
-
-**Multiple API keys for one provider (rate limit distribution):**
+**Multiple OpenRouter profiles (quota pool rotation):**
 
 ```json
 {
   "provider": {
-    "openai-work":     { "api": "openai", "apiKey": "sk-work-key-111" },
-    "openai-personal": { "api": "openai", "apiKey": "sk-personal-222" },
-    "openai-backup":   { "api": "openai", "apiKey": "sk-backup-333" }
+    "openrouter-main":   { "api": "openrouter", "apiKey": "sk-or-v1-aaa..." },
+    "openrouter-backup": { "api": "openrouter", "apiKey": "sk-or-v1-bbb..." },
+    "openrouter-spare":  { "api": "openrouter", "apiKey": "sk-or-v1-ccc..." }
   },
-  "plugin": ["@apolenkov/o-switcher@latest"]
-}
-```
-
-O-Switcher sees 3 separate targets (all OpenAI). When `work` key hits rate limit — switches to `personal`, then `backup`. Same model, different keys.
-
-**Custom retry and timeout:**
-
-```json
-{
-  "switcher": {
-    "retry": 5,
-    "timeout": 60000
-  }
-}
-```
-
-### Advanced: Manual Targets
-
-For full control, you can specify targets explicitly. When `targets` is present, auto-discovery is disabled.
-
-**Two providers — primary + backup:**
-
-```json
-{
-  "switcher": {
-    "targets": [
-      {
-        "target_id": "claude",
-        "provider_id": "anthropic",
-        "capabilities": ["chat"],
-        "enabled": true,
-        "operator_priority": 2,
-        "policy_tags": []
-      },
-      {
-        "target_id": "gpt",
-        "provider_id": "openai",
-        "capabilities": ["chat"],
-        "enabled": true,
-        "operator_priority": 1,
-        "policy_tags": []
-      }
-    ]
-  }
+  "plugin": ["@albinocrabs/o-switcher@latest"]
 }
 ```
 
-Claude is primary (priority 2). If Claude fails 3 times — switches to GPT.
+O-Switcher sees 3 profiles (all OpenRouter). When `main` hits quota — switches to `backup`, then `spare`. Same models, different subscriptions.
 
-**Custom retry and failover limits:**
+## Operator Commands
 
-```json
-{
-  "switcher": {
-    "targets": [/* ... */],
-    "retry_budget": 5,
-    "failover_budget": 3,
-    "backoff": {
-      "base_ms": 500,
-      "max_ms": 15000
-    }
-  }
-}
-```
+Control targets at runtime without code changes:
 
-### How it works
+| Command | Description |
+|---------|-------------|
+| `list` | Show all targets with health score, circuit breaker state, cooldown status |
+| `pause <target>` | Temporarily stop routing to a target |
+| `resume <target>` | Resume routing to a paused target |
+| `drain <target>` | Stop new requests, let in-flight complete |
+| `disable <target>` | Fully disable a target |
+| `inspect <request_id>` | Show full request trace (attempts, failovers, segments) |
 
-1. You send a request in OpenCode
-2. O-Switcher picks the healthiest target
-3. If the request fails:
-   - **Rate limited** → waits and retries (up to 3 times)
-   - **Server error** → retries with backoff
-   - **Model unavailable** → immediately tries next target
-   - **Auth error** → stops, marks target for re-authentication
-4. If all retries fail → switches to backup target (up to 2 failovers)
-5. All decisions are logged for debugging
-
-### Docs
+## Documentation
 
 - [Getting Started](docs/getting-started.md) — installation, configuration, troubleshooting
 - [API Reference](docs/api-reference.md) — all config options, operator tools, error classes, log format
 - [Examples](docs/examples.md) — multi-key, multi-provider, log analysis, circuit breaker tuning
 - [Architecture](docs/architecture.md) — C4 diagrams, sequence flows, internals
 
-### Development
+## Development
 
 ```bash
 git clone https://github.com/apolenkov/o-switcher.git
 cd o-switcher
 npm install
-npm test             # 396 tests
+npm test             # 455 tests
 npm run typecheck    # TypeScript strict
 npm run build        # ESM + CJS
 ```
 
-### License
-
-[MIT](LICENSE)
-
----
-
-## Русский
-
-### Что это?
-
-Плагин для [OpenCode](https://opencode.ai), который автоматически переключается между LLM-провайдерами, когда один падает. Если Anthropic возвращает ошибки — запрос тихо уходит в OpenAI. Никакого ручного вмешательства.
-
-### Зачем?
-
-- API провайдеров падают, упираются в rate limit, возвращают ошибки
-- Без O-Switcher: ждёшь, вручную переключаешь провайдера, теряешь контекст
-- С O-Switcher: автоматический retry, failover на резервного провайдера, работа продолжается
-
-### Установка
-
-Добавь в `opencode.json`:
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide.
 
-```json
-{
-  "plugin": [
-    "@apolenkov/o-switcher@latest"
-  ]
-}
-```
+## Contributing
 
-Или для локальной разработки:
-
-```json
-{
-  "plugin": [
-    "/путь/до/o-switcher"
-  ]
-}
-```
+O-Switcher is open source and we welcome contributions! Whether it's bug reports, feature ideas, documentation improvements, or code — every contribution matters.
 
-### Настройка
+Check out our [Contributing Guide](CONTRIBUTING.md) to get started. Look for issues labeled [`good first issue`](https://github.com/apolenkov/o-switcher/labels/good%20first%20issue) — these are curated for new contributors.
 
-Все. O-Switcher автоматически находит все настроенные провайдеры из конфига OpenCode. Настраивать таргеты не нужно.
+## Roadmap
 
-Хочешь задать свои retry и timeout?
+O-Switcher started as a plugin, but the goal is to contribute this as a core feature to [OpenCode](https://github.com/opencode-ai/opencode) itself — so that any provider (not just OpenRouter) can have multiple profiles that automatically substitute each other when problems occur on any of them.
 
-```json
-{
-  "plugin": ["@apolenkov/o-switcher@latest"],
-  "switcher": {
-    "retry": 3,
-    "timeout": 30000
-  }
-}
-```
-
-Оба поля опциональны и имеют разумные дефолты.
-
-### Примеры
-
-**Нулевой конфиг — просто добавь плагин:**
-
-```json
-{
-  "plugin": ["@apolenkov/o-switcher@latest"]
-}
-```
-
-O-Switcher читает настроенных провайдеров (anthropic, openai и т.д.) и создает таргеты автоматически. Получаешь: автоматический retry, circuit breaker, мониторинг здоровья.
-
-**Несколько API ключей для одного провайдера (распределение rate limit):**
-
-```json
-{
-  "provider": {
-    "openai-work":     { "api": "openai", "apiKey": "sk-work-key-111" },
-    "openai-personal": { "api": "openai", "apiKey": "sk-personal-222" },
-    "openai-backup":   { "api": "openai", "apiKey": "sk-backup-333" }
-  },
-  "plugin": ["@apolenkov/o-switcher@latest"]
-}
-```
-
-O-Switcher видит 3 отдельных таргета (все OpenAI). Когда ключ `work` упирается в rate limit — переключается на `personal`, потом `backup`. Та же модель, разные ключи.
-
-Посмотреть настроенные провайдеры и ключи:
-
-```bash
-opencode providers list    # все провайдеры и авторизации
-opencode providers login   # добавить новый ключ
-opencode providers logout  # удалить ключ
-```
-
-**Свои retry и timeout:**
-
-```json
-{
-  "switcher": {
-    "retry": 5,
-    "timeout": 60000
-  }
-}
-```
-
-### Продвинутое: Ручная настройка таргетов
-
-Для полного контроля можно указать таргеты явно. Когда `targets` присутствует, автообнаружение отключается.
-
-**Два провайдера — основной + резервный:**
-
-```json
-{
-  "switcher": {
-    "targets": [
-      {
-        "target_id": "claude",
-        "provider_id": "anthropic",
-        "capabilities": ["chat"],
-        "enabled": true,
-        "operator_priority": 2,
-        "policy_tags": []
-      },
-      {
-        "target_id": "gpt",
-        "provider_id": "openai",
-        "capabilities": ["chat"],
-        "enabled": true,
-        "operator_priority": 1,
-        "policy_tags": []
-      }
-    ]
-  }
-}
-```
-
-Claude основной (приоритет 2). Если Claude упал 3 раза — переключается на GPT.
-
-**Свои лимиты retry и failover:**
-
-```json
-{
-  "switcher": {
-    "targets": [/* ... */],
-    "retry_budget": 5,
-    "failover_budget": 3,
-    "backoff": {
-      "base_ms": 500,
-      "max_ms": 15000
-    }
-  }
-}
-```
-
-### Как это работает
-
-1. Отправляешь запрос в OpenCode
-2. O-Switcher выбирает самый здоровый таргет
-3. Если запрос упал:
-   - **Rate limit** → ждёт и повторяет (до 3 раз)
-   - **Ошибка сервера** → повтор с backoff
-   - **Модель недоступна** → сразу пробует следующий таргет
-   - **Ошибка авторизации** → останавливается, помечает таргет
-4. Если все retry исчерпаны → переключение на резервный таргет (до 2 failover)
-5. Все решения логируются для отладки
-
-### Документация
-
-- [Getting Started](docs/getting-started.md) — установка, настройка, траблшутинг
-- [API Reference](docs/api-reference.md) — все опции конфига, операторские команды, классы ошибок, формат логов
-- [Примеры](docs/examples.md) — мульти-ключи, мульти-провайдеры, анализ логов, тюнинг circuit breaker
-- [Архитектура](docs/architecture.md) — C4 диаграммы, sequence-диаграммы, внутреннее устройство
-
-### Разработка
-
-```bash
-git clone https://github.com/apolenkov/o-switcher.git
-cd o-switcher
-npm install
-npm test             # 359 тестов
-npm run typecheck    # TypeScript strict
-npm run build        # ESM + CJS
-```
+- **Now:** Plugin for OpenCode — works with OpenRouter profiles
+- **Next:** PR to OpenCode — built-in multi-profile rotation for every provider
+- **Vision:** Each provider in OpenCode config can have N profiles, auto-failover between them is transparent and zero-config
 
-### Лицензия
+## License
 
-[MIT](LICENSE)
+[Apache-2.0](LICENSE)