@relayplane/proxy 1.5.3 → 1.5.5

package/README.md

@@ -1,53 +1,287 @@
-# RelayPlane — Cost Intelligence for AI Agents
+# @relayplane/proxy
 
 [![npm](https://img.shields.io/npm/v/@relayplane/proxy)](https://www.npmjs.com/package/@relayplane/proxy)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/RelayPlane/proxy/blob/main/LICENSE)
 
-**See where every dollar goes. Route to the cheapest model that works. Cut LLM costs ~80%.**
+An open-source LLM proxy that sits between your AI agents and providers. Tracks every request, shows where the money goes, and routes tasks to the right model — all running locally.
 
-RelayPlane is an open-source proxy that sits between your AI agents and LLM providers. It tracks every request, shows you exactly where the money goes, and uses smart routing to send tasks to the right model — all running locally on your machine.
-
-## ⚡ Quick Start
+## Quick Start
 
 ```bash
 npm install -g @relayplane/proxy
 relayplane init
 relayplane start
-# Open http://localhost:4100 — your cost dashboard
+# Dashboard at http://localhost:4100
 ```
 
-Three minutes to full cost visibility. Works with any agent framework — no config changes needed.
+Works with any agent framework that talks to OpenAI or Anthropic APIs. Point your client at `http://localhost:4100` and the proxy handles the rest.
 
-## 🎯 How It Works
+## Supported Providers
 
-**Observe** — Every LLM request is tracked: cost, model, tokens, latency. See it all in the local dashboard.
+**Anthropic** · **OpenAI** · **Google Gemini** · **xAI/Grok** · **OpenRouter** · **DeepSeek** · **Groq** · **Mistral** · **Together** · **Fireworks** · **Perplexity**
 
-**Govern** — The policy engine classifies tasks and routes to the most cost-effective model. Simple file reads → Haiku. Complex architecture → Opus. You set the rules or use the defaults.
+## Configuration
 
-**Learn** *(coming soon)* — Opt into the collective mesh. Share anonymized routing outcomes. As the mesh grows, routing gets smarter for everyone.
+RelayPlane reads configuration from `~/.relayplane/config.json`. Override the path with the `RELAYPLANE_CONFIG_PATH` environment variable.
 
-## 🔌 Supported Providers
+```bash
+# Default location
+~/.relayplane/config.json
 
-All 11 major providers work out of the box:
+# Override with env var
+RELAYPLANE_CONFIG_PATH=/path/to/config.json relayplane start
+```
 
-**Anthropic** · **OpenAI** · **Google Gemini** · **xAI/Grok** · **OpenRouter** · **DeepSeek** · **Groq** · **Mistral** · **Together** · **Fireworks** · **Perplexity**
+A minimal config file:
+
+```json
+{
+  "enabled": true,
+  "modelOverrides": {},
+  "routing": {
+    "mode": "cascade",
+    "cascade": { "enabled": true },
+    "complexity": { "enabled": true }
+  }
+}
+```
+
+All configuration is optional — sensible defaults are applied for every field. The proxy merges your config with its defaults via deep merge, so you only need to specify what you want to change.
+
+## Complexity-Based Routing
+
+The proxy classifies incoming requests by complexity (simple, moderate, complex) based on prompt length, token patterns, and the presence of tools. Each tier maps to a different model.
 
-## 🛡️ Circuit Breaker Safety
+```json
+{
+  "routing": {
+    "complexity": {
+      "enabled": true,
+      "simple": "claude-3-5-haiku-latest",
+      "moderate": "claude-sonnet-4-20250514",
+      "complex": "claude-opus-4-20250514"
+    }
+  }
+}
+```
+
+**How classification works:**
+
+- **Simple** — Short prompts, straightforward Q&A, basic code tasks
+- **Moderate** — Multi-step reasoning, code review, analysis with context
+- **Complex** — Architecture decisions, large codebases, tasks with many tools, long prompts with evaluation/comparison language
+
+The classifier scores requests based on message count, total token length, tool usage, and content patterns (e.g., words like "analyze", "compare", "evaluate" increase the score). This happens locally — no prompt content is sent anywhere.
+
+## Model Overrides
 
-If the proxy ever fails, all traffic automatically bypasses it — your agent talks directly to the provider. When RelayPlane recovers, traffic resumes. No manual intervention. Worst case: you pay what you would have paid anyway.
+Map any model name to a different one. Useful for silently redirecting expensive models to cheaper alternatives without changing your agent configuration:
 
-## 💰 Free Forever
+```json
+{
+  "modelOverrides": {
+    "claude-opus-4-5": "claude-3-5-haiku",
+    "gpt-4o": "gpt-4o-mini"
+  }
+}
+```
+
+Overrides are applied before any other routing logic. The original requested model is logged for tracking.
+
+## Cascade Mode
 
-Everything that runs on your machine is free. No trials, no gates, no artificial limits. Full proxy, local dashboard, all 11 providers, smart routing, policy engine.
+Start with the cheapest model and escalate only when the response shows uncertainty or refusal. This gives you the cost savings of a cheap model with a safety net.
+
+```json
+{
+  "routing": {
+    "mode": "cascade",
+    "cascade": {
+      "enabled": true,
+      "models": [
+        "claude-3-5-haiku-latest",
+        "claude-sonnet-4-20250514",
+        "claude-opus-4-20250514"
+      ],
+      "escalateOn": "uncertainty",
+      "maxEscalations": 2
+    }
+  }
+}
+```
 
-## 🔐 Your Keys Stay Yours
+**`escalateOn` options:**
+
+| Value | Triggers escalation when... |
+|-------|----------------------------|
+| `uncertainty` | Response contains hedging language ("I'm not sure", "it's hard to say", "this is just a guess") |
+| `refusal` | Model refuses to help ("I can't assist with that", "as an AI") |
+| `error` | The request fails outright |
+
+**`maxEscalations`** caps how many times the proxy will retry with a more expensive model. Default: `1`.
+
+The cascade walks through the `models` array in order, starting from the first. Each escalation moves to the next model in the list.
+
+## Smart Aliases
+
+Use semantic model names instead of provider-specific IDs:
+
+| Alias | Resolves to |
+|-------|------------|
+| `rp:best` | `anthropic/claude-sonnet-4-20250514` |
+| `rp:fast` | `anthropic/claude-3-5-haiku-20241022` |
+| `rp:cheap` | `openai/gpt-4o-mini` |
+| `rp:balanced` | `anthropic/claude-3-5-haiku-20241022` |
+| `relayplane:auto` | Same as `rp:balanced` |
+| `rp:auto` | Same as `rp:balanced` |
+
+Use these as the `model` field in your API requests:
+
+```json
+{
+  "model": "rp:fast",
+  "messages": [{"role": "user", "content": "Hello"}]
+}
+```
+
+## Routing Suffixes
+
+Append `:cost`, `:fast`, or `:quality` to any model name to hint at routing preference:
+
+```json
+{
+  "model": "claude-sonnet-4:cost",
+  "messages": [{"role": "user", "content": "Summarize this"}]
+}
+```
+
+| Suffix | Behavior |
+|--------|----------|
+| `:cost` | Optimize for lowest cost |
+| `:fast` | Optimize for lowest latency |
+| `:quality` | Optimize for best output quality |
+
+The suffix is stripped before provider lookup — the base model must still be valid. Suffixes influence routing decisions when the proxy has multiple options.
+
+## Provider Cooldowns / Reliability
+
+When a provider starts failing, the proxy automatically cools it down to avoid hammering a broken endpoint:
+
+```json
+{
+  "reliability": {
+    "cooldowns": {
+      "enabled": true,
+      "allowedFails": 3,
+      "windowSeconds": 60,
+      "cooldownSeconds": 120
+    }
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | `true` | Enable/disable cooldown tracking |
+| `allowedFails` | `3` | Failures within the window before cooldown triggers |
+| `windowSeconds` | `60` | Rolling window for counting failures |
+| `cooldownSeconds` | `120` | How long to avoid the provider after cooldown triggers |
+
+After cooldown expires, the provider is automatically retried. Successful requests clear the failure counter.
+
+## Hybrid Auth
+
+Use your Anthropic MAX subscription token for expensive models (Opus) while using standard API keys for cheaper models (Haiku, Sonnet). This lets you leverage MAX plan pricing where it matters most.
+
+```json
+{
+  "auth": {
+    "anthropicMaxToken": "sk-ant-oat-...",
+    "useMaxForModels": ["opus", "claude-opus"]
+  }
+}
+```
+
+**How it works:**
+
+- When a request targets a model matching any pattern in `useMaxForModels`, the proxy uses `anthropicMaxToken` with `Authorization: Bearer` header (OAuth-style)
+- All other Anthropic requests use the standard `ANTHROPIC_API_KEY` env var with `x-api-key` header
+- Pattern matching is case-insensitive substring match — `"opus"` matches `claude-opus-4-20250514`
+
+Set your standard key in the environment as usual:
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-api03-..."
+```
+
+## Telemetry
+
+The proxy collects anonymized telemetry to improve routing decisions. Here's exactly what's collected:
+
+- **device_id** — Random anonymous ID (no PII)
+- **task_type** — Inferred from token patterns, NOT from prompt content
+- **model** — Which model was used
+- **tokens_in/out** — Token counts
+- **latency_ms** — Response time
+- **cost_usd** — Estimated cost
+
+**Never collected:** prompts, responses, file paths, or anything that could identify you or your project.
+
+### Disabling telemetry
+
+```bash
+# Via environment variable
+RELAYPLANE_TELEMETRY=0 relayplane start
+
+# Or in config — telemetry can be disabled programmatically via the config module
+```
+
+### Audit mode
+
+Audit mode buffers telemetry events in memory so you can inspect exactly what would be sent before it goes anywhere. Useful for compliance review.
+
+### Offline mode
+
+```bash
+relayplane start --offline
+```
+
+Disables all network calls except the actual LLM requests. No telemetry transmission, no cloud features. The proxy still tracks everything locally for your dashboard.
+
+## Dashboard
+
+The built-in dashboard runs at [http://localhost:4100](http://localhost:4100) (or `/dashboard`). It shows:
+
+- Total requests, success rate, average latency
+- Cost breakdown by model and provider
+- Recent request history with routing decisions
+- Savings from routing optimizations
+- Provider health status
+
+### API Endpoints
+
+The dashboard is powered by JSON endpoints you can use directly:
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /v1/telemetry/stats` | Aggregate statistics (total requests, costs, model counts) |
+| `GET /v1/telemetry/runs?limit=N` | Recent request history |
+| `GET /v1/telemetry/savings` | Cost savings from smart routing |
+| `GET /v1/telemetry/health` | Provider health and cooldown status |
+
+## Circuit Breaker
+
+If the proxy ever fails, all traffic automatically bypasses it — your agent talks directly to the provider. When RelayPlane recovers, traffic resumes. No manual intervention needed.
+
+## Your Keys Stay Yours
 
 RelayPlane requires your own provider API keys. We never see your prompts, keys, or data. All execution is local.
 
-## 📄 License
+## License
 
-[MIT](https://github.com/RelayPlane/proxy/blob/main/LICENSE) — open source, free forever.
+[MIT](https://github.com/RelayPlane/proxy/blob/main/LICENSE)
 
 ---
 
 [relayplane.com](https://relayplane.com) · [GitHub](https://github.com/RelayPlane/proxy)
+

package/dist/cli.js

@@ -87,6 +87,238 @@ async function checkForUpdate() {
         return null; // Network error, offline, etc. — silently skip
     }
 }
+const CREDENTIALS_PATH = (0, path_1.join)((0, os_1.homedir)(), '.relayplane', 'credentials.json');
+function loadCredentials() {
+    try {
+        if ((0, fs_1.existsSync)(CREDENTIALS_PATH)) {
+            return JSON.parse((0, fs_1.readFileSync)(CREDENTIALS_PATH, 'utf8'));
+        }
+    }
+    catch { }
+    return null;
+}
+function saveCredentials(creds) {
+    const dir = (0, path_1.dirname)(CREDENTIALS_PATH);
+    if (!(0, fs_1.existsSync)(dir))
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    (0, fs_1.writeFileSync)(CREDENTIALS_PATH, JSON.stringify(creds, null, 2) + '\n');
+}
+function clearCredentials() {
+    try {
+        if ((0, fs_1.existsSync)(CREDENTIALS_PATH)) {
+            (0, fs_1.writeFileSync)(CREDENTIALS_PATH, '{}');
+        }
+    }
+    catch { }
+}
+const API_URL = process.env.RELAYPLANE_API_URL || 'https://api.relayplane.com';
+// ============================================
+// LOGIN COMMAND (Device OAuth Flow)
+// ============================================
+async function handleLoginCommand() {
+    const existing = loadCredentials();
+    if (existing?.apiKey) {
+        console.log('');
+        console.log('  ✅ Already logged in');
+        if (existing.email)
+            console.log(`     Account: ${existing.email}`);
+        if (existing.plan)
+            console.log(`     Plan: ${existing.plan}`);
+        console.log('');
+        console.log('  Run `relayplane logout` first to switch accounts.');
+        console.log('');
+        return;
+    }
+    console.log('');
+    console.log('  🔐 Logging in to RelayPlane...');
+    console.log('');
+    try {
+        // Start device auth flow
+        const startRes = await fetch(`${API_URL}/v1/cli/device/start`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ client: 'relayplane-proxy', version: VERSION }),
+        });
+        if (!startRes.ok) {
+            console.error('  ❌ Failed to start login flow. Is the API reachable?');
+            process.exit(1);
+        }
+        const { deviceCode, userCode, verificationUrl, pollIntervalSec, expiresIn } = await startRes.json();
+        console.log(`  Open this URL in your browser:`);
+        console.log('');
+        console.log(`    ${verificationUrl}`);
+        console.log('');
+        console.log(`  And enter this code:`);
+        console.log('');
+        console.log(`    📋 ${userCode}`);
+        console.log('');
+        console.log(`  Waiting for approval (expires in ${Math.floor(expiresIn / 60)} minutes)...`);
+        // Try to open browser automatically
+        try {
+            const { exec: execCmd } = await import('child_process');
+            const openCmd = process.platform === 'darwin' ? 'open'
+                : process.platform === 'win32' ? 'start'
+                    : 'xdg-open';
+            execCmd(`${openCmd} "${verificationUrl}"`);
+        }
+        catch { }
+        // Poll for approval
+        const deadline = Date.now() + expiresIn * 1000;
+        while (Date.now() < deadline) {
+            await new Promise(r => setTimeout(r, (pollIntervalSec || 5) * 1000));
+            const pollRes = await fetch(`${API_URL}/v1/cli/device/poll`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ deviceCode }),
+            });
+            if (!pollRes.ok)
+                continue;
+            const pollData = await pollRes.json();
+            if (pollData.status === 'approved') {
+                saveCredentials({
+                    apiKey: pollData.accessToken,
+                    plan: pollData.plan || 'free',
+                    teamId: pollData.teamId,
+                    teamName: pollData.teamName,
+                    loggedInAt: new Date().toISOString(),
+                });
+                console.log('');
+                console.log('  ✅ Login successful!');
+                if (pollData.teamName)
+                    console.log(`     Team: ${pollData.teamName}`);
+                console.log(`     Plan: ${pollData.plan || 'free'}`);
+                console.log('');
+                console.log('  ☁️  Cloud sync will activate on next proxy start.');
+                console.log('');
+                return;
+            }
+            if (pollData.status === 'denied') {
+                console.log('');
+                console.log('  ❌ Login denied.');
+                console.log('');
+                process.exit(1);
+            }
+            if (pollData.status === 'expired') {
+                console.log('');
+                console.log('  ⏰ Login expired. Please try again.');
+                console.log('');
+                process.exit(1);
+            }
+            // Still pending, continue polling
+            process.stdout.write('.');
+        }
+        console.log('');
+        console.log('  ⏰ Login timed out. Please try again.');
+        console.log('');
+        process.exit(1);
+    }
+    catch (err) {
+        console.error('  ❌ Login failed:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}
+// ============================================
+// LOGOUT COMMAND
+// ============================================
+function handleLogoutCommand() {
+    const creds = loadCredentials();
+    clearCredentials();
+    console.log('');
+    if (creds?.apiKey) {
+        console.log('  ✅ Logged out successfully.');
+        console.log('     Cloud sync will stop on next proxy restart.');
+    }
+    else {
+        console.log('  ℹ️  Not logged in.');
+    }
+    console.log('');
+}
+// ============================================
+// UPGRADE COMMAND
+// ============================================
+function handleUpgradeCommand() {
+    const url = 'https://relayplane.com/pricing';
+    console.log('');
+    console.log('  🚀 Opening pricing page...');
+    console.log(`     ${url}`);
+    console.log('');
+    try {
+        const { exec: execCmd } = require('child_process');
+        const openCmd = process.platform === 'darwin' ? 'open'
+            : process.platform === 'win32' ? 'start'
+                : 'xdg-open';
+        execCmd(`${openCmd} "${url}"`);
+    }
+    catch { }
+}
+// ============================================
+// ENHANCED STATUS COMMAND  
+// ============================================
+async function handleCloudStatusCommand() {
+    const creds = loadCredentials();
+    console.log('');
+    console.log('  📊 RelayPlane Status');
+    console.log('  ════════════════════');
+    console.log('');
+    // Proxy status
+    let proxyReachable = false;
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 2000);
+        const res = await fetch('http://127.0.0.1:4100/health', { signal: controller.signal });
+        clearTimeout(timeout);
+        proxyReachable = res.ok;
+    }
+    catch { }
+    console.log(`  Proxy:       ${proxyReachable ? '🟢 Running' : '🔴 Stopped'}`);
+    // Auth status
+    if (creds?.apiKey) {
+        console.log(`  Account:     ✅ Logged in${creds.email ? ` (${creds.email})` : ''}`);
+        console.log(`  Plan:        ${creds.plan || 'free'}`);
+        console.log(`  API Key:     ••••${creds.apiKey.slice(-4)}`);
+        // Check cloud sync
+        if (proxyReachable) {
+            console.log(`  Cloud sync:  ☁️  Active`);
+        }
+        else {
+            console.log(`  Cloud sync:  ⏸️  Proxy not running`);
+        }
+        // Try to get fresh plan info from API
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 3000);
+            const res = await fetch(`${API_URL}/v1/cli/teams/current`, {
+                signal: controller.signal,
+                headers: { 'Authorization': `Bearer ${creds.apiKey}` },
+            });
+            clearTimeout(timeout);
+            if (res.ok) {
+                const data = await res.json();
+                if (data.plan && data.plan !== creds.plan) {
+                    creds.plan = data.plan;
+                    saveCredentials(creds);
+                    console.log(`  Plan (live):  ${data.plan}`);
+                }
+                if (data.teamName)
+                    console.log(`  Team:        ${data.teamName}`);
+            }
+        }
+        catch { }
+    }
+    else {
+        console.log(`  Account:     ❌ Not logged in`);
+        console.log(`  Plan:        free (local only)`);
+        console.log(`  Cloud sync:  ❌ Disabled`);
+    }
+    console.log('');
+    if (!creds?.apiKey) {
+        console.log('  Run `relayplane login` to enable cloud features.');
+    }
+    else if (creds.plan === 'free') {
+        console.log('  Run `relayplane upgrade` to unlock cloud dashboard.');
+    }
+    console.log('');
+}
 function printHelp() {
     console.log(`
 RelayPlane Proxy - Intelligent AI Model Routing
@@ -97,7 +329,10 @@ Usage:
 
 Commands:
   (default)              Start the proxy server
-  status                 Show proxy status (circuit state, stats, process info)
+  login                  Log in to RelayPlane (opens browser)
+  logout                 Clear stored credentials
+  status                 Show proxy status, plan, and cloud sync
+  upgrade                Open pricing page in browser
   enable                 Enable RelayPlane in openclaw.json
   disable                Disable RelayPlane in openclaw.json
   telemetry [on|off|status]  Manage telemetry settings
@@ -469,8 +704,20 @@ async function main() {
         handleConfigCommand(args.slice(1));
         process.exit(0);
     }
+    if (command === 'login') {
+        await handleLoginCommand();
+        process.exit(0);
+    }
+    if (command === 'logout') {
+        handleLogoutCommand();
+        process.exit(0);
+    }
+    if (command === 'upgrade') {
+        handleUpgradeCommand();
+        process.exit(0);
+    }
     if (command === 'status') {
-        await handleStatusCommand();
+        await handleCloudStatusCommand();
         process.exit(0);
     }
     if (command === 'mesh') {
@@ -547,6 +794,7 @@ async function main() {
     console.log('');
     // Show modes
     const telemetryEnabled = (0, config_js_1.isTelemetryEnabled)();
+    const creds = loadCredentials();
     console.log('  Mode:');
     if (offline) {
         console.log('    🔒 Offline (no telemetry transmission)');
@@ -560,6 +808,13 @@ async function main() {
     else {
         console.log('    📴 Telemetry disabled');
     }
+    // Cloud sync status
+    if (creds?.apiKey && !offline) {
+        console.log(`    ☁️  Cloud sync: active (plan: ${creds.plan || 'free'})`);
+    }
+    else if (!creds?.apiKey) {
+        console.log('    💻 Local only (run `relayplane login` for cloud sync)');
+    }
     console.log('');
     console.log('  Providers:');
     if (hasAnthropicKey)