@albinocrabs/o-switcher 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,72 @@
+# Contributing to O-Switcher
+
+Thank you for your interest in contributing!
+
+## Getting Started
+
+```bash
+git clone https://github.com/<owner>/o-switcher.git
+cd o-switcher
+npm install
+npm test        # 351 tests, all must pass
+npm run typecheck  # zero TypeScript errors
+```
+
+## Development Workflow
+
+1. **Fork** the repository
+2. **Create a branch** from `main`: `git checkout -b feat/my-feature`
+3. **Write tests first** (TDD) — tests live next to source files (`*.test.ts`)
+4. **Implement** — make the tests pass
+5. **Verify** — `npm test && npm run typecheck`
+6. **Commit** — use [conventional commits](https://www.conventionalcommits.org/):
+   `feat(routing):`, `fix(config):`, `test(execution):`, `docs:`
+7. **Open a PR** against `main`
+
+## Project Structure
+
+```
+src/
+├── config/       Config loading, Zod schema validation
+├── registry/     Target registry, health scoring, mode detection
+├── errors/       Error taxonomy (10 classes), dual-mode classifier
+├── retry/        Bounded retry with backoff, jitter, Retry-After
+├── routing/      Policy engine, circuit breaker, admission, failover
+├── execution/    Mode adapters, stream stitcher, audit collector
+├── operator/     Operator commands, config reload, plugin tools
+├── integration/  End-to-end integration tests
+├── audit/        Pino-based structured audit logger
+├── mode/         Deployment mode types and capabilities
+└── spike/        Proof-of-concept explorations
+```
+
+## Code Conventions
+
+- **TypeScript strict mode** — `noUncheckedIndexedAccess`, `verbatimModuleSyntax`
+- **ESM** — `"type": "module"` in package.json
+- **Factory functions** — `createXxx()` returning interfaces (not classes)
+- **Pure functions** — routing/scoring logic has no I/O
+- **No `let`** — use `const` only, restructure if needed
+- **No `!!`** — use `Boolean()` for explicit coercion
+- **Vitest** for testing — co-located `*.test.ts` files
+
+## Testing
+
+```bash
+npm test                           # all tests
+npx vitest run src/routing/        # specific module
+npx vitest run --watch             # watch mode
+```
+
+## Architecture
+
+See [README.md](README.md) for the architecture diagram and module overview.
+
+## Reporting Issues
+
+- Use GitHub Issues
+- Include: steps to reproduce, expected vs actual behavior, Node.js version
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 O-Switcher Contributors
+
+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.md

@@ -0,0 +1,361 @@
+# O-Switcher
+
+[English](#english) | [Русский](#русский)
+
+---
+
+## English
+
+### What is it?
+
+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
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "@apolenkov/o-switcher@latest"
+  ]
+}
+```
+
+Or for local development:
+
+```json
+{
+  "plugin": [
+    "/path/to/o-switcher"
+  ]
+}
+```
+
+### Configure
+
+That's it. O-Switcher auto-discovers all configured providers from your OpenCode config. No target configuration needed.
+
+Want to customize retry and timeout?
+
+```json
+{
+  "plugin": ["@apolenkov/o-switcher@latest"],
+  "switcher": {
+    "retry": 3,
+    "timeout": 30000
+  }
+}
+```
+
+Both fields are optional with sensible defaults.
+
+### Examples
+
+**Zero config — just add the plugin:**
+
+```json
+{
+  "plugin": ["@apolenkov/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):**
+
+```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 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": []
+      }
+    ]
+  }
+}
+```
+
+Claude is primary (priority 2). If Claude fails 3 times — switches to GPT.
+
+**Custom retry and failover limits:**
+
+```json
+{
+  "switcher": {
+    "targets": [/* ... */],
+    "retry_budget": 5,
+    "failover_budget": 3,
+    "backoff": {
+      "base_ms": 500,
+      "max_ms": 15000
+    }
+  }
+}
+```
+
+### How it works
+
+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
+
+- [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
+
+```bash
+git clone https://github.com/apolenkov/o-switcher.git
+cd o-switcher
+npm install
+npm test             # 396 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`:
+
+```json
+{
+  "plugin": [
+    "@apolenkov/o-switcher@latest"
+  ]
+}
+```
+
+Или для локальной разработки:
+
+```json
+{
+  "plugin": [
+    "/путь/до/o-switcher"
+  ]
+}
+```
+
+### Настройка
+
+Все. O-Switcher автоматически находит все настроенные провайдеры из конфига OpenCode. Настраивать таргеты не нужно.
+
+Хочешь задать свои retry и timeout?
+
+```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
+```
+
+### Лицензия
+
+[MIT](LICENSE)