api-key-lb 1.0.0

package/README.md

@@ -0,0 +1,125 @@
+# api-key-lb
+
+Transparent API key load balancer with session-aware sticky routing. Works with any OpenAI-compatible API.
+
+**Why?** Agentic systems (Hermes, OpenCode, Claude Code, etc.) build up context caches per API key. If you round-robin between keys, you lose cache affinity on every other request. This proxy uses sticky routing — same session always hits the same key.
+
+## Features
+
+- **Session-aware sticky routing** — same session fingerprint → same key (cache-friendly)
+- **Automatic 429 fallback** — throttled key triggers fallback, reverts when unthrottled
+- **Works with anything** — Hermes, OpenCode/kimaki, Claude Code, curl, any OpenAI-compatible client
+- **Zero-config target** — proxy is transparent, forwards any path to the target API
+- **Health endpoint** — `GET /health` for monitoring
+- **macOS LaunchAgent** — auto-starts on login, auto-restarts on crash
+
+## Quick Start
+
+```bash
+# Install globally (or use directly from this dir)
+npm install -g .
+
+# Setup — saves config, patches known configs, installs LaunchAgent
+api-key-lb setup \
+  --keys "sk-key1,sk-key2" \
+  --target "https://api.z.ai" \
+  --port 4577
+
+# Check status
+api-key-lb status
+
+# Stop
+api-key-lb stop
+```
+
+## Config
+
+Priority: CLI flags → env vars → config file → defaults
+
+**Config file:** `~/.config/api-key-lb/config.json`
+
+```json
+{
+  "target": "https://api.z.ai",
+  "keys": "key1,key2",
+  "port": 4577,
+  "cooldown_ms": 60000,
+  "session_ttl_ms": 3600000
+}
+```
+
+**Environment variables:**
+
+| Variable | Default | Description |
+|---|---|---|
+| `API_KEYS` | required | Comma-separated API keys |
+| `TARGET` | `https://api.openai.com` | Target API base URL |
+| `PORT` | `4577` | Proxy listen port |
+| `COOLDOWN_MS` | `60000` | 429 cooldown per key |
+| `SESSION_TTL_MS` | `3600000` | Session sticky TTL |
+| `API_KEY_LB_CONFIG` | — | Path to config file |
+
+## How Sticky Routing Works
+
+1. Extracts a session fingerprint from the request body (session_id, conversation_id, or model+system prompt hash)
+2. Hashes the fingerprint to deterministically pick a key
+3. Same fingerprint always routes to the same key
+4. Different sessions get distributed across keys
+5. On 429: falls back to alternate key, reverts to sticky when unthrottled
+
+## Connecting Your Tools
+
+Just change the base URL to point at the proxy:
+
+**Hermes** (`~/.hermes/config.yaml`):
+```yaml
+model:
+  base_url: http://127.0.0.1:4577/api/coding/paas/v4
+```
+
+**OpenCode** (`~/.config/opencode/opencode.json`):
+```json
+{
+  "provider": {
+    "zai": {
+      "options": {
+        "baseURL": "http://127.0.0.1:4577/api/coding/paas/v4"
+      }
+    }
+  }
+}
+```
+
+**Any OpenAI-compatible client:**
+```bash
+curl http://127.0.0.1:4577/v1/chat/completions \
+  -H "Authorization: Bearer anything" \
+  -d '{"model":"gpt-4","messages":[...]}'
+```
+
+The `Authorization` header gets replaced by the proxy — the key you pass doesn't matter.
+
+## Health Check
+
+```bash
+curl http://127.0.0.1:4577/health
+```
+
+Returns per-key stats: requests, errors, cache hits, throttle status, active sessions.
+
+## Architecture
+
+```
+┌─────────┐     ┌──────────────────┐     ┌──────────┐
+│ Client   │────▶│ api-key-lb proxy │────▶│ API      │
+│ (Hermes) │     │  :4577           │     │ (z.ai)   │
+│ (OpenCode)│    │  sticky routing  │     │          │
+│ (curl)   │     │  429 fallback    │     │          │
+└─────────┘     └──────────────────┘     └──────────┘
+```
+
+The proxy is fully transparent — it forwards whatever path/headers the client sends, only replacing the `Authorization` bearer token and `Host` header.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "api-key-lb",
+  "version": "1.0.0",
+  "description": "Transparent API key load balancer with session-aware sticky routing. Works with any OpenAI-compatible API provider.",
+  "main": "src/proxy.mjs",
+  "bin": {
+    "api-key-lb": "./src/cli.mjs"
+  },
+  "files": [
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/proxy.mjs",
+    "setup": "node src/cli.mjs setup",
+    "status": "node src/cli.mjs status"
+  },
+  "keywords": ["proxy", "load-balancer", "api-keys", "openai", "openrouter", "cache-affinity", "rate-limit", "sticky-routing"],
+  "author": "jairodri",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jairodri/api-key-lb"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+/**
+ * api-key-lb CLI — setup, status, and config management
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const command = process.argv[2] || 'help';
+const args = process.argv.slice(3);
+
+const HOME = os.homedir();
+const CONFIG_DIR = path.join(HOME, '.config', 'api-key-lb');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const DEFAULT_PORT = 4577;
+
+// ─── Commands ──────────────────────────────────────────────────────────
+
+function cmdSetup() {
+  console.log('🔧 api-key-lb setup\n');
+
+  // 1. Ensure config dir
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+
+  // 2. Load or create config
+  let cfg = {};
+  if (fs.existsSync(CONFIG_PATH)) {
+    cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+    console.log(`  Found existing config at ${CONFIG_PATH}`);
+  } else {
+    console.log(`  Creating config at ${CONFIG_PATH}`);
+  }
+
+  // Parse CLI args
+  const keysArg = findArg('--keys') || findArg('-k');
+  const targetArg = findArg('--target') || findArg('-t');
+  const portArg = findArg('--port') || findArg('-p');
+
+  if (keysArg) cfg.keys = keysArg;
+  if (targetArg) cfg.target = targetArg;
+  if (portArg) cfg.port = parseInt(portArg, 10);
+
+  cfg.port = cfg.port || DEFAULT_PORT;
+
+  if (!cfg.keys) {
+    console.error('  ERROR: --keys required. Usage: api-key-lb setup --keys key1,key2 [--target URL] [--port PORT]');
+    process.exit(1);
+  }
+  if (!cfg.target) {
+    console.error('  ERROR: --target required. Usage: api-key-lb setup --keys key1,key2 --target https://api.z.ai');
+    process.exit(1);
+  }
+
+  // Normalize keys to array
+  if (typeof cfg.keys === 'string') cfg.keys = cfg.keys.split(',').map(k => k.trim());
+
+  // 3. Write config
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2));
+  console.log(`  ✅ Config saved (${cfg.keys.length} keys, target: ${cfg.target})`);
+
+  // 4. Patch agentic system configs
+  patchHermes(cfg);
+  patchOpenCode(cfg);
+
+  // 5. Install LaunchAgent (macOS)
+  installLaunchAgent(cfg);
+
+  console.log('\n  ✅ Setup complete. Start with: api-key-lb start');
+}
+
+function cmdStatus() {
+  const port = getPort();
+  try {
+    const result = execSync(`curl -s http://127.0.0.1:${port}/health`, { timeout: 3000 }).toString();
+    const health = JSON.parse(result);
+    console.log('📊 api-key-lb status\n');
+    console.log(`  Status:   ${health.status}`);
+    console.log(`  Target:   ${health.target}`);
+    console.log(`  Sessions: ${health.sessions}`);
+    console.log(`  Uptime:   ${(health.uptime_ms / 1000 / 60).toFixed(1)} min\n`);
+    for (const key of health.keys) {
+      console.log(`  Key #${key.id} (${key.key}...)`);
+      console.log(`    Requests: ${key.requests}  Errors: ${key.errors}  Cache hits: ${key.cache_hits}  Status: ${key.status}`);
+    }
+  } catch {
+    console.log('❌ Proxy not running on port ' + port);
+    console.log('   Start with: api-key-lb start');
+  }
+}
+
+function cmdStart() {
+  const port = getPort();
+  // Check if already running
+  try {
+    const result = execSync(`curl -s http://127.0.0.1:${port}/health`, { timeout: 2000 }).toString();
+    const health = JSON.parse(result);
+    console.log(`✅ Already running on port ${port} (${health.keys.length} keys, ${health.sessions} sessions)`);
+    return;
+  } catch {
+    // Not running — start it
+  }
+
+  const env = {
+    ...process.env,
+    API_KEY_LB_CONFIG: CONFIG_PATH,
+  };
+
+  console.log(`Starting api-key-lb on port ${port}...`);
+  import(path.join(__dirname, 'proxy.mjs'));
+}
+
+function cmdStop() {
+  const port = getPort();
+  try {
+    // Find the proxy process
+    const pid = execSync(`lsof -ti:${port} -sTCP:LISTEN`, { encoding: 'utf8' }).trim();
+    if (pid) {
+      process.kill(parseInt(pid, 10), 'SIGTERM');
+      console.log(`✅ Stopped proxy (PID ${pid})`);
+    }
+  } catch {
+    console.log('Proxy not running');
+  }
+}
+
+function cmdHelp() {
+  console.log(`
+api-key-lb — Transparent API Key Load Balancer
+
+Usage:
+  api-key-lb setup    --keys key1,key2 --target https://api.z.ai [--port 4577]
+  api-key-lb start    Start the proxy (or show status if running)
+  api-key-lb stop     Stop the proxy
+  api-key-lb status   Show proxy health and key stats
+
+Setup options:
+  -k, --keys    Comma-separated API keys
+  -t, --target  Target API base URL (e.g. https://api.z.ai, https://openrouter.ai/api/v1)
+  -p, --port    Proxy port (default: 4577)
+
+Config file: ~/.config/api-key-lb/config.json
+LaunchAgent: ~/Library/LaunchAgents/com.api-key-lb.plist (macOS)
+
+Environment variables (override config):
+  API_KEYS=key1,key2       API keys to balance
+  TARGET=https://...       Target API URL
+  PORT=4577                Proxy port
+  COOLDOWN_MS=60000        429 cooldown in ms
+  SESSION_TTL_MS=3600000   Session sticky TTL in ms
+`);
+}
+
+// ─── Config Patching ───────────────────────────────────────────────────
+
+function patchHermes(cfg) {
+  const hermesConfig = path.join(HOME, '.hermes', 'config.yaml');
+  if (!fs.existsSync(hermesConfig)) {
+    console.log('  ⏭ Hermes config not found — skipping');
+    return;
+  }
+
+  let content = fs.readFileSync(hermesConfig, 'utf8');
+  const proxyUrl = `http://127.0.0.1:${cfg.port}`;
+
+  // Find lines like: base_url: https://api.z.ai/...
+  // that match the target domain and replace with proxy
+  try {
+    const targetHost = new URL(cfg.target).hostname;
+    const regex = new RegExp(`(base_url:\\s*)https?://${targetHost.replace(/\./g, '\\.')}`, 'g');
+    if (regex.test(content)) {
+      content = content.replace(regex, `$1${proxyUrl}`);
+      fs.writeFileSync(hermesConfig, content);
+      console.log(`  ✅ Patched Hermes config → ${proxyUrl}`);
+    } else {
+      console.log(`  ⏭ Hermes config doesn't reference ${targetHost} — skipping`);
+    }
+  } catch (e) {
+    console.log(`  ⚠️  Could not patch Hermes: ${e.message}`);
+  }
+}
+
+function patchOpenCode(cfg) {
+  const opencodeConfig = path.join(HOME, '.config', 'opencode', 'opencode.json');
+  if (!fs.existsSync(opencodeConfig)) {
+    console.log('  ⏭ OpenCode config not found — skipping');
+    return;
+  }
+
+  try {
+    const content = JSON.parse(fs.readFileSync(opencodeConfig, 'utf8'));
+    const proxyUrl = `http://127.0.0.1:${cfg.port}`;
+    const targetHost = new URL(cfg.target).hostname;
+    let patched = false;
+
+    // Walk all providers — find any whose baseURL targets our API host
+    if (content.provider) {
+      for (const [name, provider] of Object.entries(content.provider)) {
+        if (provider.options?.baseURL?.includes(targetHost) && !provider.options.baseURL.includes('127.0.0.1')) {
+          // Replace the target host with proxy, keeping the path
+          const originalPath = new URL(provider.options.baseURL).pathname;
+          provider.options.baseURL = `${proxyUrl}${originalPath}`;
+          console.log(`  ✅ Patched OpenCode provider "${name}" → ${provider.options.baseURL}`);
+          patched = true;
+        }
+      }
+    }
+
+    if (patched) {
+      fs.writeFileSync(opencodeConfig, JSON.stringify(content, null, 2));
+    } else {
+      console.log(`  ⏭ OpenCode config doesn't reference ${targetHost} directly — skipping`);
+    }
+  } catch (e) {
+    console.log(`  ⚠️  Could not patch OpenCode: ${e.message}`);
+  }
+}
+
+function installLaunchAgent(cfg) {
+  if (process.platform !== 'darwin') {
+    console.log('  ⏭ LaunchAgent only supported on macOS — skipping');
+    return;
+  }
+
+  const plistPath = path.join(HOME, 'Library', 'LaunchAgents', 'com.api-key-lb.plist');
+  const proxyPath = path.resolve(__dirname, 'proxy.mjs');
+  const logPath = path.join(CONFIG_DIR, 'proxy.log');
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.api-key-lb</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${process.execPath}</string>
+        <string>${proxyPath}</string>
+    </array>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>API_KEY_LB_CONFIG</key>
+        <string>${CONFIG_PATH}</string>
+    </dict>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${logPath}</string>
+    <key>StandardErrorPath</key>
+    <string>${logPath}</string>
+</dict>
+</plist>`;
+
+  fs.writeFileSync(plistPath, plist);
+  console.log(`  ✅ LaunchAgent installed at ${plistPath}`);
+
+  // Unload old if exists, load new
+  try {
+    execSync(`launchctl unload ${plistPath} 2>/dev/null`, { stdio: 'pipe' });
+  } catch {}
+  try {
+    execSync(`launchctl load ${plistPath}`);
+    console.log('  ✅ LaunchAgent loaded (starts on login)');
+  } catch (e) {
+    console.log(`  ⚠️  Could not load LaunchAgent: ${e.message}`);
+    console.log(`     Run manually: launchctl load ${plistPath}`);
+  }
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────
+
+function findArg(flag) {
+  const idx = args.indexOf(flag);
+  return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
+}
+
+function getPort() {
+  if (fs.existsSync(CONFIG_PATH)) {
+    try {
+      return JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8')).port || DEFAULT_PORT;
+    } catch {}
+  }
+  return parseInt(process.env.PORT, 10) || DEFAULT_PORT;
+}
+
+// ─── Dispatch ──────────────────────────────────────────────────────────
+switch (command) {
+  case 'setup': cmdSetup(); break;
+  case 'start': cmdStart(); break;
+  case 'stop': cmdStop(); break;
+  case 'status': cmdStatus(); break;
+  case 'help': case '--help': case '-h': cmdHelp(); break;
+  default: console.log(`Unknown command: ${command}\n`); cmdHelp(); break;
+}

package/src/proxy.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+/**
+ * api-key-lb — Transparent API Key Load Balancer
+ *
+ * Sits between any agentic system and an OpenAI-compatible API.
+ * Routes requests with session-aware sticky routing for context cache affinity.
+ * Falls back to alternate keys on 429s, then reverts to sticky key.
+ *
+ * Features:
+ *   - Works with any OpenAI-compatible API (z.ai, OpenRouter, OpenAI, etc.)
+ *   - Session-aware sticky routing (hashes request fingerprint → same key)
+ *   - Automatic 429 fallback with configurable cooldown
+ *   - Zero-config: point your client at the proxy, it handles the rest
+ *   - Health endpoint for monitoring
+ *
+ * Usage:
+ *   ZAI_KEYS=key1,key2 TARGET=https://api.z.ai PORT=4577 node proxy.mjs
+ *
+ * Or via config file:
+ *   node proxy.mjs --config ./api-key-lb.json
+ */
+
+import http from 'node:http';
+import https from 'node:https';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { URL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+
+// ─── Config ────────────────────────────────────────────────────────────
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function loadConfig() {
+  // 1. CLI --config flag
+  const configIdx = process.argv.indexOf('--config');
+  if (configIdx !== -1 && process.argv[configIdx + 1]) {
+    const configPath = path.resolve(process.argv[configIdx + 1]);
+    return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  }
+
+  // 2. ENV-based config file path
+  if (process.env.API_KEY_LB_CONFIG) {
+    return JSON.parse(fs.readFileSync(process.env.API_KEY_LB_CONFIG, 'utf8'));
+  }
+
+  // 3. Look for config in common locations
+  const searchPaths = [
+    path.join(process.cwd(), 'api-key-lb.json'),
+    path.join(__dirname, '..', 'api-key-lb.json'),
+    path.join(process.env.HOME || '~', '.config', 'api-key-lb', 'config.json'),
+  ];
+  for (const p of searchPaths) {
+    if (fs.existsSync(p)) {
+      return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+  }
+
+  // 4. Pure env vars
+  return {};
+}
+
+function resolveConfig(fileConfig) {
+  const env = (key, fileKey, defaultVal) => {
+    if (process.env[key]) return process.env[key];
+    if (fileConfig[fileKey] !== undefined) return String(fileConfig[fileKey]);
+    return defaultVal;
+  };
+
+  const rawKeys = process.env.API_KEYS || fileConfig.keys || '';
+  const keys = (Array.isArray(rawKeys) ? rawKeys : rawKeys.split(',')).map(k => k.trim()).filter(Boolean);
+  const target = env('TARGET', 'target', 'https://api.openai.com');
+  const port = parseInt(env('PORT', 'port', '4577'), 10);
+  const cooldownMs = parseInt(env('COOLDOWN_MS', 'cooldown_ms', '60000'), 10);
+  const sessionTTL = parseInt(env('SESSION_TTL_MS', 'session_ttl_ms', '3600000'), 10);
+
+  return { keys, target, port, cooldownMs, sessionTTL };
+}
+
+const fileConfig = loadConfig();
+const config = resolveConfig(fileConfig);
+
+if (config.keys.length === 0) {
+  console.error('ERROR: No API keys. Set API_KEYS=key1,key2,... or use a config file.');
+  console.error('  See: api-key-lb --help');
+  process.exit(1);
+}
+
+// ─── Key State ─────────────────────────────────────────────────────────
+const keyState = config.keys.map((key, i) => ({
+  id: i,
+  key,
+  throttledUntil: 0,
+  requestCount: 0,
+  errorCount: 0,
+  cacheHits: 0,
+}));
+
+// ─── Session Tracking ──────────────────────────────────────────────────
+const sessionKeyMap = new Map();
+const SESSION_MAX = 2000;
+
+function hashToKeyIndex(str) {
+  const hash = crypto.createHash('sha256').update(str).digest();
+  return hash[0] % config.keys.length;
+}
+
+function extractSessionId(body) {
+  if (!body || body.length === 0) return null;
+  try {
+    const json = JSON.parse(body.toString('utf8'));
+
+    // 1. Explicit session identifiers (OpenCode, custom agents)
+    const candidates = [
+      json.session_id,
+      json.sessionId,
+      json.conversation_id,
+      json.conversationId,
+      json.thread_id,
+    ];
+    for (const c of candidates) {
+      if (c && typeof c === 'string') return c;
+    }
+
+    // 2. Check messages metadata
+    const msgs = json.messages || [];
+    for (const msg of msgs) {
+      if (msg.custom_fields?.session_id) return msg.custom_fields.session_id;
+      if (msg.metadata?.session_id) return msg.metadata.session_id;
+    }
+
+    // 3. Fingerprint: model + system prompt prefix (stable across a session)
+    if (msgs.length > 0) {
+      const systemMsg = msgs.find(m => m.role === 'system');
+      if (systemMsg) {
+        return `${json.model || ''}:${systemMsg.content.slice(0, 500)}`;
+      }
+    }
+  } catch {
+    // Not JSON — ignore
+  }
+  return null;
+}
+
+function pruneSessions() {
+  if (sessionKeyMap.size <= SESSION_MAX) return;
+  const entries = [...sessionKeyMap.entries()];
+  sessionKeyMap.clear();
+  // Keep most recent half
+  entries.slice(-Math.floor(SESSION_MAX / 2)).forEach(([k, v]) => sessionKeyMap.set(k, v));
+}
+
+function getKeyForSession(sessionId) {
+  let stickyIndex;
+  if (sessionId && sessionKeyMap.has(sessionId)) {
+    stickyIndex = sessionKeyMap.get(sessionId);
+  } else if (sessionId) {
+    stickyIndex = hashToKeyIndex(sessionId);
+    sessionKeyMap.set(sessionId, stickyIndex);
+    pruneSessions();
+  } else {
+    stickyIndex = -1;
+  }
+
+  const now = Date.now();
+
+  // Try sticky key first
+  if (stickyIndex >= 0) {
+    const sticky = keyState[stickyIndex];
+    if (sticky.throttledUntil <= now) {
+      return { state: sticky, isSticky: true };
+    }
+    console.log(`[STICKY] Key #${sticky.id} throttled, trying alternate for session ${sessionId?.slice(0, 30)}...`);
+  }
+
+  // Try all keys, prefer unthrottled
+  for (let i = 0; i < config.keys.length; i++) {
+    if (keyState[i].throttledUntil <= now) {
+      return { state: keyState[i], isSticky: false };
+    }
+  }
+
+  // All throttled — pick soonest unlock
+  const soonest = keyState.reduce((best, s) =>
+    s.throttledUntil < best.throttledUntil ? s : best
+  );
+  return { state: soonest, isSticky: false };
+}
+
+function markThrottled(state, retryAfterMs) {
+  state.throttledUntil = Date.now() + (retryAfterMs || config.cooldownMs);
+  state.errorCount++;
+  console.log(`[THROTTLE] Key #${state.id} throttled until ${new Date(state.throttledUntil).toISOString()}`);
+}
+
+// ─── Request Handler ───────────────────────────────────────────────────
+function handleRequest(req, res) {
+  const chunks = [];
+  req.on('data', chunk => chunks.push(chunk));
+  req.on('end', () => {
+    const body = Buffer.concat(chunks);
+    const sessionId = extractSessionId(body);
+    const { state: initialState, isSticky } = getKeyForSession(sessionId);
+    const attempts = [];
+
+    function tryRequest(ks, wasSticky) {
+      attempts.push(ks.id);
+      ks.requestCount++;
+
+      if (sessionId && attempts.length === 1) {
+        console.log(`[ROUTE] session=${sessionId.slice(0, 30)}... → key #${ks.id} (${wasSticky ? 'sticky' : 'fallback'})`);
+      }
+
+      const targetUrl = new URL(req.url, config.target);
+      const headers = { ...req.headers };
+      headers['authorization'] = `Bearer ${ks.key}`;
+      headers['host'] = targetUrl.host;
+      delete headers['connection'];
+
+      const options = {
+        hostname: targetUrl.hostname,
+        port: targetUrl.port || 443,
+        path: targetUrl.pathname + targetUrl.search,
+        method: req.method,
+        headers,
+      };
+
+      const proxyReq = https.request(options, (proxyRes) => {
+        if (proxyRes.statusCode === 429) {
+          const retryAfter = parseInt(proxyRes.headers['retry-after'] || '0', 10);
+          const retryAfterMs = retryAfter > 0 ? retryAfter * 1000 : config.cooldownMs;
+          markThrottled(ks, retryAfterMs);
+
+          const drainChunks = [];
+          proxyRes.on('data', c => drainChunks.push(c));
+          proxyRes.on('end', () => {
+            if (attempts.length < config.keys.length) {
+              const { state: nextKey } = getKeyForSession(sessionId);
+              console.log(`[RETRY] 429 on key #${ks.id}, falling back to key #${nextKey.id}`);
+              tryRequest(nextKey, false);
+            } else {
+              console.log(`[FAIL] All keys exhausted for ${req.method} ${req.url}`);
+              res.writeHead(proxyRes.statusCode, proxyRes.headers);
+              res.end(Buffer.concat(drainChunks));
+            }
+          });
+          return;
+        }
+
+        // Detect cache hits
+        const cacheHeader = proxyRes.headers['x-cache'] || proxyRes.headers['x-cached'];
+        if (cacheHeader === 'HIT' || cacheHeader === 'hit') {
+          ks.cacheHits++;
+        }
+
+        if (proxyRes.statusCode >= 500) {
+          console.log(`[ERROR] Key #${ks.id} got ${proxyRes.statusCode} for ${req.method} ${req.url}`);
+        } else if (attempts.length > 1) {
+          console.log(`[OK] Key #${ks.id} succeeded after ${attempts.length} attempts`);
+        }
+
+        res.writeHead(proxyRes.statusCode, proxyRes.headers);
+        proxyRes.pipe(res);
+      });
+
+      proxyReq.on('error', (err) => {
+        console.error(`[ERROR] Key #${ks.id} request failed:`, err.message);
+        if (attempts.length < config.keys.length) {
+          const { state: nextKey } = getKeyForSession(sessionId);
+          tryRequest(nextKey, false);
+        } else {
+          res.writeHead(502, { 'content-type': 'application/json' });
+          res.end(JSON.stringify({ error: 'proxy_error', message: err.message }));
+        }
+      });
+
+      if (body.length > 0) proxyReq.write(body);
+      proxyReq.end();
+    }
+
+    tryRequest(initialState, isSticky);
+  });
+}
+
+// ─── Health Endpoint ───────────────────────────────────────────────────
+function handleHealth(req, res) {
+  const now = Date.now();
+  const info = keyState.map(s => ({
+    id: s.id,
+    key: s.key.slice(0, 8) + '...',
+    requests: s.requestCount,
+    errors: s.errorCount,
+    cache_hits: s.cacheHits,
+    status: s.throttledUntil > now ? 'throttled' : 'ready',
+  }));
+  res.writeHead(200, { 'content-type': 'application/json' });
+  res.end(JSON.stringify({
+    status: 'ok',
+    target: config.target.replace(/\/\/[^@]+@/, '//***@'),
+    keys: info,
+    sessions: sessionKeyMap.size,
+    uptime_ms: process.uptime() * 1000 | 0,
+  }, null, 2));
+}
+
+// ─── Server ────────────────────────────────────────────────────────────
+const server = http.createServer((req, res) => {
+  if (req.url === '/health' && req.method === 'GET') {
+    return handleHealth(req, res);
+  }
+  handleRequest(req, res);
+});
+
+server.listen(config.port, '127.0.0.1', () => {
+  console.log(`[START] api-key-lb proxy listening on http://127.0.0.1:${config.port}`);
+  console.log(`[START] ${config.keys.length} key(s) loaded`);
+  console.log(`[START] Target: ${config.target}`);
+  console.log(`[START] Routing: session-aware sticky`);
+  console.log(`[START] Cooldown: ${config.cooldownMs}ms`);
+  console.log(`[START] Health: http://127.0.0.1:${config.port}/health`);
+});
+
+// Status log every 5 minutes
+setInterval(() => {
+  const now = Date.now();
+  const status = keyState.map(s => ({
+    id: s.id,
+    reqs: s.requestCount,
+    errs: s.errorCount,
+    cache: s.cacheHits,
+    status: s.throttledUntil > now ? `throttled ${((s.throttledUntil - now) / 1000)|0}s` : 'ready',
+  }));
+  console.log(`[STATUS] ${JSON.stringify(status)} sessions=${sessionKeyMap.size}`);
+}, 300000);