o-switcher 0.1.0

package/docs/getting-started.md

@@ -0,0 +1,316 @@
+# Getting Started
+
+## Installation
+
+### As OpenCode Plugin (recommended)
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "@apolenkov/o-switcher@latest"
+  ]
+}
+```
+
+### Local Development
+
+Clone and link locally:
+
+```bash
+git clone https://github.com/apolenkov/o-switcher.git
+cd o-switcher
+npm install
+npm run build
+```
+
+In your project's `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "/path/to/o-switcher"
+  ]
+}
+```
+
+## Configuration
+
+O-Switcher auto-discovers all configured providers from your OpenCode config. No target configuration needed.
+
+### Minimal Config (zero targets)
+
+Just add the plugin. O-Switcher reads your providers and creates targets automatically:
+
+```json
+{
+  "plugin": ["@apolenkov/o-switcher@latest"]
+}
+```
+
+### Auto-Discovery
+
+When O-Switcher starts, it reads the `provider` section of your OpenCode config. Each provider entry becomes a target automatically with these defaults:
+
+- `capabilities`: `["chat"]`
+- `enabled`: `true`
+- `operator_priority`: `0` (all targets start equal)
+- `policy_tags`: `[]`
+
+The routing engine differentiates via health scores over time. If one provider starts returning errors, traffic shifts to healthier providers.
+
+**Optional retry and timeout:**
+
+```json
+{
+  "plugin": ["@apolenkov/o-switcher@latest"],
+  "switcher": {
+    "retry": 3,
+    "timeout": 30000
+  }
+}
+```
+
+- `retry` — max retry attempts per request (default: 3)
+- `timeout` — max expected latency in ms (default: 30000)
+
+### Multiple API Keys for One Provider
+
+Register the same provider multiple times with different API keys in your `opencode.json`. O-Switcher treats each as a separate target and distributes load across them:
+
+```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"]
+}
+```
+
+When one key hits rate limits, O-Switcher automatically switches to the next key — same model, different credentials. This is the primary use case for running multiple targets.
+
+**Managing keys via CLI:**
+
+```bash
+opencode providers list     # see all configured providers and credentials
+opencode providers login    # add a new provider/key
+opencode providers logout   # remove a provider/key
+```
+
+### Manual Target Configuration (Advanced)
+
+For full control, specify targets explicitly. When `targets` is present, auto-discovery is disabled:
+
+```json
+{
+  "plugin": ["@apolenkov/o-switcher@latest"],
+  "switcher": {
+    "targets": [
+      {
+        "target_id": "anthropic-main",
+        "provider_id": "anthropic",
+        "capabilities": ["chat"],
+        "enabled": true,
+        "operator_priority": 1,
+        "policy_tags": []
+      },
+      {
+        "target_id": "openai-backup",
+        "provider_id": "openai",
+        "capabilities": ["chat"],
+        "enabled": true,
+        "operator_priority": 0,
+        "policy_tags": []
+      }
+    ]
+  }
+}
+```
+
+### Full Config (all options with defaults shown)
+
+```json
+{
+  "switcher": {
+    "targets": [
+      {
+        "target_id": "anthropic-main",
+        "provider_id": "anthropic",
+        "capabilities": ["chat"],
+        "enabled": true,
+        "operator_priority": 1,
+        "policy_tags": ["primary"],
+        "concurrency_limit": 5,
+        "circuit_breaker": {
+          "failure_threshold": 5,
+          "failure_rate_threshold": 0.5,
+          "sliding_window_size": 10,
+          "half_open_after_ms": 30000,
+          "half_open_max_probes": 1,
+          "success_threshold": 2
+        }
+      },
+      {
+        "target_id": "openai-backup",
+        "provider_id": "openai",
+        "capabilities": ["chat"],
+        "enabled": true,
+        "operator_priority": 0,
+        "policy_tags": ["backup"]
+      }
+    ],
+    "retry_budget": 3,
+    "failover_budget": 2,
+    "backoff": {
+      "base_ms": 1000,
+      "multiplier": 2,
+      "max_ms": 30000,
+      "jitter": "full"
+    },
+    "routing_weights": {
+      "health": 1.0,
+      "latency": 0.5,
+      "failure": 0.8,
+      "priority": 0.3
+    },
+    "queue_limit": 100,
+    "concurrency_limit": 10,
+    "backpressure_threshold": 50,
+    "circuit_breaker": {
+      "failure_threshold": 5,
+      "failure_rate_threshold": 0.5,
+      "sliding_window_size": 10,
+      "half_open_after_ms": 30000,
+      "half_open_max_probes": 1,
+      "success_threshold": 2
+    },
+    "max_expected_latency_ms": 30000,
+    "deployment_mode_hint": "auto"
+  }
+}
+```
+
+## What Happens When You Start
+
+1. **OpenCode loads the plugin** from `opencode.json`
+2. **Config hook fires** — O-Switcher reads the `switcher` config, validates via Zod
+3. **Registry initialized** — each target gets health score 1.0, circuit breaker Closed
+4. **Hooks active:**
+   - `chat.params` — monitors target health, adjusts params for degraded targets
+   - `event` — watches `session.error` events, updates health scores
+
+## How Routing Works
+
+```
+Request arrives
+  ↓
+Admission Control: is system overloaded?
+  ↓ admitted
+Policy Engine: which target is healthiest?
+  ↓ target selected (score = health - latency - failures + priority)
+Execute request on target
+  ↓
+Success? → done, record health +1
+  ↓ failure
+Classify error:
+  • RateLimited → cooldown + retry (up to 3 times)
+  • TransientServerFailure → retry with backoff
+  • ModelUnavailable → immediately try next target
+  • AuthFailure → abort, mark target as ReauthRequired
+  ↓ retry budget exhausted
+Failover to next target (up to 2 failovers)
+  ↓ all targets exhausted
+Return error to user
+```
+
+## Deployment Modes
+
+O-Switcher detects how it's running and adjusts capabilities:
+
+| Mode | What it means | Failover capability |
+|------|--------------|---------------------|
+| **plugin-only** | Installed as OpenCode plugin | Same-target parameter adjustment only. Cannot switch providers. |
+| **server-companion** | Running as HTTP sidecar server | Full cross-provider failover with direct HTTP status codes |
+| **SDK-control** | Embedded via OpenCode SDK | Full cross-provider failover with direct HTTP status codes |
+
+**Most users will use plugin-only mode.** This is the default when you add O-Switcher to `opencode.json`.
+
+## Operator Commands
+
+Once running, you have 7 operator commands available as OpenCode tools:
+
+| Command | What it does |
+|---------|-------------|
+| `listTargets` | Show all targets with health, state, circuit breaker |
+| `pauseTarget` | Stop routing to a target (can resume later) |
+| `resumeTarget` | Resume a paused target |
+| `drainTarget` | Let in-flight requests finish, reject new ones |
+| `disableTarget` | Fully disable a target |
+| `inspectRequest` | Show full trace for a request by ID |
+| `reloadConfig` | Hot-reload config without restart |
+
+## Error Classes
+
+O-Switcher classifies every provider error into one of 10 classes:
+
+| Error | What it means | What O-Switcher does |
+|-------|--------------|---------------------|
+| **RateLimited** | Provider says "too many requests" | Cooldown with backoff, respect Retry-After |
+| **QuotaExhausted** | Billing/quota limit reached | Disable target, no retry |
+| **AuthFailure** | Invalid credentials (401) | One recovery attempt, then ReauthRequired |
+| **PermissionFailure** | Forbidden (403) | PolicyBlocked, no retry |
+| **PolicyFailure** | Content policy violation | PolicyBlocked, no retry |
+| **RegionRestriction** | Region not supported | PolicyBlocked, no retry |
+| **ModelUnavailable** | Model overloaded/not found | Immediately failover to next target |
+| **TransientServerFailure** | Server error (500/502/503) | Retry with backoff |
+| **TransportFailure** | Network error, timeout | Retry with backoff |
+| **InterruptedExecution** | Stream cut mid-output | Save confirmed chunks, resume on next target |
+
+## Troubleshooting
+
+### Plugin not loading
+
+Check that `opencode.json` has the correct plugin path:
+
+```bash
+# npm package
+"plugin": ["@apolenkov/o-switcher@latest"]
+
+# local path (must be absolute or relative to project root)
+"plugin": ["/absolute/path/to/o-switcher"]
+```
+
+### Config validation error on start
+
+O-Switcher validates config strictly. If using manual targets, check:
+- `targets` array is not empty (if provided)
+- Each target has `target_id` and `provider_id`
+- `target_id` values are unique
+
+If not using manual targets, O-Switcher auto-discovers from your OpenCode providers. If no providers are configured, it runs in passthrough mode (no routing).
+
+The error message will show exactly which field is invalid.
+
+### All targets showing CircuitOpen
+
+This means too many failures. Check:
+- Are your API keys valid?
+- Are the providers actually reachable?
+- Use `listTargets` tool to see health scores and states
+- Use `resumeTarget` to manually reset a circuit breaker
+
+### Audit logs
+
+O-Switcher logs all routing decisions to stdout as NDJSON (structured JSON, one line per event). Filter by `request_id` to trace a single request:
+
+```bash
+opencode 2>&1 | grep '"request_id":"YOUR-ID"'
+```
+
+## Next Steps
+
+- [Architecture diagrams](architecture.md) — C4 diagrams and sequence flows
+- [Contributing](../CONTRIBUTING.md) — how to develop and contribute

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "o-switcher",
+  "version": "0.1.0",
+  "description": "Routing and execution resilience layer for OpenCode",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apolenkov/o-switcher.git"
+  },
+  "keywords": [
+    "opencode",
+    "llm",
+    "routing",
+    "resilience",
+    "circuit-breaker",
+    "failover",
+    "retry"
+  ],
+  "main": "dist/plugin.js",
+  "module": "dist/plugin.js",
+  "types": "dist/plugin.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/plugin.js",
+      "require": "./dist/plugin.cjs",
+      "types": "./dist/plugin.d.ts"
+    },
+    "./api": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "cockatiel": "^3.2.1",
+    "eventemitter3": "^5.0.4",
+    "p-queue": "^9.1.2",
+    "pino": "^10.3.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.4.3",
+    "@tsconfig/node20": "^20.1.9",
+    "@types/node": "^22",
+    "pino-pretty": "^13",
+    "tsup": "^8.5.1",
+    "typescript": "^5.4.0",
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}