@relayplane/proxy 1.5.46 → 1.7.2

package/README.md

@@ -3,14 +3,25 @@
 [![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)
 
-An open-source LLM proxy that sits between your AI agents and providers. Tracks every request, shows where the money goes, and offers configurable task-aware routing — all running locally.
+An open-source LLM proxy that sits between your AI agents and providers. Tracks every request, shows where the money goes, and offers configurable task-aware routing — all running **locally, for free**.
 
-**Key features:**
+**Free, open-source proxy features:**
 - 📊 Per-request cost tracking across 11+ providers
-- 💰 **Cache-aware cost tracking** — accurately tracks Anthropic prompt caching with cache read savings, creation costs, and true per-request costs including cached tokens
+- 💰 **Cache-aware cost tracking** — accurately tracks Anthropic prompt caching with cache read savings, creation costs, and true per-request costs
 - 🔀 Configurable task-aware routing (complexity-based, cascade, model overrides)
-- 🛡️ Circuit breaker architecture — if the proxy fails, your agent doesn't notice
-- 📈 Local dashboard with cost breakdown, savings analysis, and provider health
+- 🛡️ Circuit breaker — if the proxy fails, your agent doesn't notice
+- 📈 **Local dashboard** at `localhost:4100` — cost breakdown, savings analysis, provider health
+- 💵 **Budget enforcement** — daily/hourly/per-request spend limits with block, warn, downgrade, or alert actions
+- 🔍 **Anomaly detection** — catches runaway agent loops, cost spikes, and token explosions in real time
+- 🔔 **Cost alerts** — threshold alerts at configurable percentages, webhook delivery, alert history
+- ⬇️ **Auto-downgrade** — automatically switches to cheaper models when budget thresholds are hit
+- 📦 **Aggressive cache** — exact-match response caching with gzipped disk persistence
+- 🧠 **Osmosis mesh** — opt-in collective learning layer that shares anonymized routing signals across users (free, opt-in)
+- 🔧 **systemd/launchd service** — `relayplane service install` for always-on operation with auto-restart
+- 🏥 **Health watchdog** — `/health` endpoint with uptime tracking and active probing
+- 🛡️ **Config resilience** — atomic writes, automatic backup/restore, credential separation
+
+> **Cloud dashboard available separately** — see [Cloud Dashboard & Pro Features](#cloud-dashboard--pro-features) below. Your prompts always stay local.
 
 ## Quick Start
 
@@ -55,29 +66,38 @@ A minimal config file:
 
 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.
 
-## Architecture (Current)
+## Architecture
 
 ```text
 Client (Claude Code / Aider / Cursor)
         |
         |  OpenAI/Anthropic-compatible request
         v
-+-----------------------------------------------+
-| RelayPlane Proxy (local)                       |
-|-----------------------------------------------|
-| 1) Parse request                               |
-| 2) Infer task/complexity (pre-request)         |
-| 3) Select route/model                          |
-|    - explicit model / passthrough             |
-|    - relayplane:auto/cost/fast/quality        |
-|    - configured complexity/cascade rules       |
-| 4) Forward request to provider                 |
-| 5) Return provider response                    |
-| 6) (Optional) record telemetry metadata        |
-+-----------------------------------------------+
++-------------------------------------------------------+
+| RelayPlane Proxy (local)                               |
+|-------------------------------------------------------|
+| 1) Parse request                                       |
+| 2) Cache check (exact or aggressive mode)              |
+|    └─ HIT → return cached response (skip provider)    |
+| 3) Budget check (daily/hourly/per-request limits)      |
+|    └─ BREACH → block / warn / downgrade / alert       |
+| 4) Anomaly detection (velocity, cost spike, loops)     |
+|    └─ DETECTED → alert + optional block               |
+| 5) Auto-downgrade (if budget threshold exceeded)       |
+|    └─ Rewrite model to cheaper alternative             |
+| 6) Infer task/complexity (pre-request)                 |
+| 7) Select route/model                                  |
+|    - explicit model / passthrough                     |
+|    - relayplane:auto/cost/fast/quality                |
+|    - configured complexity/cascade rules               |
+| 8) Forward request to provider                         |
+| 9) Return provider response + cache it                 |
+| 10) Record telemetry + update budget tracking          |
+| 11) Mesh sync (push anonymized routing signals)        |
++-------------------------------------------------------+
         |
         v
-Provider APIs (Anthropic/OpenAI/Gemini/xAI/Moonshot/...)
+Provider APIs (Anthropic/OpenAI/Gemini/xAI/...)
 ```
 
 ## How It Works
@@ -278,6 +298,15 @@ When enabled, the proxy sends anonymized metadata to `api.relayplane.com`:
 
 **Never collected:** prompts, responses, file paths, or anything that could identify you or your project. Your prompts go directly to LLM providers, never through RelayPlane servers.
 
+> **Cloud dashboard setup:** To see your data at [relayplane.com/dashboard](https://relayplane.com/dashboard), run `relayplane login` then `relayplane telemetry on`. This is the explicit opt-in — you're choosing to send anonymous metadata to power the cloud dashboard. You can disable anytime.
+
+When the proxy connects and telemetry is enabled, it will confirm:
+```
+[RelayPlane] Cloud dashboard connected — telemetry enabled.
+Your prompts stay local. Only anonymous metadata (model, tokens, cost) is sent.
+Disable anytime: relayplane telemetry off
+```
+
 ### 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.
@@ -315,10 +344,258 @@ The dashboard is powered by JSON endpoints you can use directly:
 | `GET /v1/telemetry/savings` | Cost savings from smart routing |
 | `GET /v1/telemetry/health` | Provider health and cooldown status |
 
+## Budget Enforcement
+
+Set spending limits to prevent runaway costs. The budget manager tracks spend in rolling daily and hourly windows using SQLite with an in-memory cache for <5ms hot-path checks.
+
+```json
+{
+  "budget": {
+    "enabled": true,
+    "dailyUsd": 50,
+    "hourlyUsd": 10,
+    "perRequestUsd": 2,
+    "onBreach": "downgrade",
+    "downgradeTo": "claude-sonnet-4-6",
+    "alertThresholds": [50, 80, 95]
+  }
+}
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | `false` | Enable budget enforcement |
+| `dailyUsd` | `50` | Daily spend limit |
+| `hourlyUsd` | `10` | Hourly spend limit |
+| `perRequestUsd` | `2` | Max cost for a single request |
+| `onBreach` | `"downgrade"` | Action: `block`, `warn`, `downgrade`, or `alert` |
+| `downgradeTo` | `"claude-sonnet-4-6"` | Model to use when downgrading |
+| `alertThresholds` | `[50, 80, 95]` | Fire alerts at these % of daily limit |
+
+```bash
+relayplane budget status          # See current spend vs limits
+relayplane budget set --daily 25  # Change daily limit
+relayplane budget set --hourly 5  # Change hourly limit
+relayplane budget reset           # Reset spend counters
+```
+
+## Anomaly Detection
+
+Catches runaway agent loops and cost spikes using a sliding window over the last 100 requests.
+
+```json
+{
+  "anomaly": {
+    "enabled": true,
+    "velocityThreshold": 50,
+    "tokenExplosionUsd": 5.0,
+    "repetitionThreshold": 20,
+    "windowMs": 300000
+  }
+}
+```
+
+**Detection types:**
+
+| Type | Triggers when... |
+|------|-------------------|
+| `velocity_spike` | Request rate exceeds threshold in 5-minute window |
+| `cost_acceleration` | Spend rate is doubling every minute |
+| `repetition` | Same model + similar token count >20 times in 5 min |
+| `token_explosion` | Single request estimated cost exceeds $5 |
+
+## Cost Alerts
+
+Get notified when spending crosses thresholds. Alerts are deduplicated per window and stored in SQLite for history.
+
+```json
+{
+  "alerts": {
+    "enabled": true,
+    "webhookUrl": "https://hooks.slack.com/...",
+    "cooldownMs": 300000,
+    "maxHistory": 500
+  }
+}
+```
+
+Alert types: `threshold` (budget %), `anomaly` (detection triggers), `breach` (limit exceeded). Severity levels: `info`, `warning`, `critical`.
+
+```bash
+relayplane alerts list            # Show recent alerts
+relayplane alerts counts          # Count by type (threshold/anomaly/breach)
+```
+
+## Auto-Downgrade
+
+When budget hits a configurable threshold (default 80%), the proxy automatically rewrites expensive models to cheaper alternatives. Adds `X-RelayPlane-Downgraded` headers so your agent knows.
+
+```json
+{
+  "downgrade": {
+    "enabled": true,
+    "thresholdPercent": 80,
+    "mapping": {
+      "claude-opus-4-6": "claude-sonnet-4-6",
+      "gpt-4o": "gpt-4o-mini",
+      "gemini-2.5-pro": "gemini-2.0-flash"
+    }
+  }
+}
+```
+
+Built-in mappings cover all major Anthropic, OpenAI, and Google models. Override with your own.
+
+## Response Cache
+
+Caches LLM responses to avoid duplicate API calls. SHA-256 hash of the canonical request → cached response with gzipped disk persistence.
+
+```json
+{
+  "cache": {
+    "enabled": true,
+    "mode": "exact",
+    "maxSizeMb": 100,
+    "defaultTtlSeconds": 3600,
+    "onlyWhenDeterministic": true
+  }
+}
+```
+
+| Mode | Behavior |
+|------|----------|
+| `exact` | Cache only identical requests (default) |
+| `aggressive` | Broader matching with shorter TTL (30 min default) |
+
+Only caches deterministic requests (temperature=0) by default. Skips responses with tool calls.
+
+```bash
+relayplane cache status   # Entries, size, hit rate, saved cost
+relayplane cache stats    # Detailed breakdown by model and task type
+relayplane cache clear    # Wipe the cache
+relayplane cache on/off   # Toggle caching
+```
+
+## Osmosis Mesh
+
+Opt-in collective learning layer. Share anonymized routing signals (model, task type, tokens, cost — never prompts) and benefit from the network's routing intelligence.
+
+```json
+{
+  "mesh": {
+    "enabled": true,
+    "endpoint": "https://osmosis-mesh-dev.fly.dev",
+    "sync_interval_ms": 60000,
+    "contribute": true
+  }
+}
+```
+
+Auto-enabled for authenticated users. Contribution is opt-in — set `contribute: false` to consume signals without sharing.
+
+```bash
+relayplane mesh status              # Atoms local/synced, last sync, endpoint
+relayplane mesh on/off              # Enable/disable mesh
+relayplane mesh sync                # Force sync now
+relayplane mesh contribute on/off   # Toggle contribution
+```
+
+## System Service
+
+Install RelayPlane as a system service for always-on operation with auto-restart on crash.
+
+```bash
+# Linux (systemd)
+sudo relayplane service install     # Install + enable + start
+sudo relayplane service uninstall   # Stop + disable + remove
+relayplane service status           # Check service state
+
+# macOS (launchd)
+relayplane service install          # Install as LaunchAgent
+relayplane service uninstall        # Remove LaunchAgent
+relayplane service status           # Check loaded state
+```
+
+The service unit includes `WatchdogSec=30` (systemd) and `KeepAlive` (launchd) for automatic health monitoring and restart. API keys from your current environment are captured into the service definition.
+
+## Config Resilience
+
+Configuration is protected against corruption:
+
+- **Atomic writes** — config is written to a `.tmp` file then renamed (no partial writes)
+- **Automatic backup** — `config.json.bak` is updated before every save
+- **Auto-restore** — if `config.json` is corrupt/missing, the proxy restores from backup
+- **Credential separation** — API keys live in `credentials.json`, surviving config resets
+
 ## 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.
 
+## CLI Reference
+
+```
+relayplane [command] [options]
+```
+
+| Command | Description |
+|---------|-------------|
+| `(default)` / `start` | Start the proxy server |
+| `init` | Initialize config and show setup instructions |
+| `status` | Show proxy status, plan, and cloud sync info |
+| `login` | Log in to RelayPlane (device OAuth flow) |
+| `logout` | Clear stored credentials |
+| `upgrade` | Open pricing page |
+| `enable` / `disable` | Toggle proxy routing in OpenClaw config |
+| `telemetry on\|off\|status` | Manage telemetry |
+| `stats` | Show usage statistics and savings |
+| `config [set-key <key>]` | Show or update configuration |
+| `budget status\|set\|reset` | Manage spend limits |
+| `alerts list\|counts` | View cost alert history |
+| `cache status\|stats\|clear\|on\|off` | Manage response cache |
+| `mesh status\|on\|off\|sync\|contribute` | Manage Osmosis mesh |
+| `service install\|uninstall\|status` | System service management |
+| `autostart on\|off\|status` | Legacy autostart (systemd) |
+
+**Server options:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--port <n>` | `4100` | Port to listen on |
+| `--host <s>` | `127.0.0.1` | Host to bind to |
+| `--offline` | — | No network calls except LLM endpoints |
+| `--audit` | — | Show telemetry payloads before sending |
+| `-v, --verbose` | — | Verbose logging |
+
+## Cloud Dashboard & Pro Features
+
+The proxy is fully functional without a cloud account. All features above are **local and free**.
+
+For teams that want persistent cloud analytics, email digests, and shared routing intelligence, [relayplane.com](https://relayplane.com) offers:
+
+| Feature | Plan |
+|---------|------|
+| Cloud dashboard — run history, cost trends, analytics | Starter ($9/mo) |
+| Policy engine — budget rules, model allowlists, approval gates | Starter |
+| Weekly cost digest emails | Starter |
+| Routing recommendations from collective intelligence | Starter |
+| 90-day history, data export | Pro ($29/mo) |
+| Cloud anomaly alerts (email, webhook) | Pro |
+| Team access & shared dashboards | Max ($99/mo) |
+| Governance & compliance rules | Max |
+
+**[View pricing →](https://relayplane.com/pricing)**
+
+### Connecting to Cloud
+
+```bash
+relayplane login          # authenticate with your cloud account
+relayplane telemetry on   # opt in to send anonymous metadata (model, tokens, cost, latency)
+```
+
+> **Privacy-first:** Enabling cloud telemetry sends only anonymous metadata — model name, token counts, cost, latency. Your prompts, inputs, and outputs **never leave your machine**. You can disable anytime: `relayplane telemetry off`.
+
+---
+
 ## Your Keys Stay Yours
 
 RelayPlane requires your own provider API keys. Your prompts go directly to LLM providers — never through RelayPlane servers. All proxy execution is local. Telemetry (anonymous metadata only) is opt-in.

package/assets/relayplane-proxy.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=RelayPlane Proxy - Intelligent AI Model Routing
+After=network.target
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=notify
+User=root
+ExecStart=/usr/bin/relayplane
+Restart=always
+RestartSec=5
+WatchdogSec=30
+StandardOutput=journal
+StandardError=journal
+Environment=HOME=/root
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target

package/dist/alerts.d.ts

@@ -0,0 +1,72 @@
+/**
+ * RelayPlane Cost Alerts & Webhooks
+ *
+ * Alert types: threshold (budget %), anomaly, breach.
+ * Webhook delivery via POST to configured URL.
+ * SQLite storage for alert history.
+ * Alert deduplication per window.
+ *
+ * @packageDocumentation
+ */
+import type { AnomalyDetail } from './anomaly.js';
+export interface AlertsConfig {
+    enabled: boolean;
+    /** Webhook URL for alert delivery */
+    webhookUrl?: string;
+    /** Alert cooldown in ms to prevent spam (default: 300000 = 5 min) */
+    cooldownMs: number;
+    /** Max alerts stored in history */
+    maxHistory: number;
+}
+export type AlertType = 'threshold' | 'anomaly' | 'breach';
+export interface Alert {
+    id: string;
+    type: AlertType;
+    message: string;
+    severity: 'info' | 'warning' | 'critical';
+    timestamp: number;
+    data: Record<string, unknown>;
+    delivered: boolean;
+}
+export declare const DEFAULT_ALERTS_CONFIG: AlertsConfig;
+export declare class AlertManager {
+    private config;
+    private db;
+    private _initialized;
+    private dedup;
+    private memoryAlerts;
+    private alertCounter;
+    constructor(config?: Partial<AlertsConfig>);
+    /** Initialize SQLite storage */
+    init(): void;
+    updateConfig(config: Partial<AlertsConfig>): void;
+    getConfig(): AlertsConfig;
+    /**
+     * Fire a threshold alert (budget % crossed)
+     */
+    fireThreshold(threshold: number, currentPercent: number, currentSpend: number, limit: number): Alert | null;
+    /**
+     * Fire an anomaly alert
+     */
+    fireAnomaly(anomaly: AnomalyDetail): Alert | null;
+    /**
+     * Fire a breach alert (budget limit exceeded)
+     */
+    fireBreach(breachType: string, currentSpend: number, limit: number): Alert | null;
+    /**
+     * Get recent alerts
+     */
+    getRecent(limit?: number): Alert[];
+    /**
+     * Get alert count by type
+     */
+    getCounts(): Record<AlertType, number>;
+    close(): void;
+    private isDuplicate;
+    private createAlert;
+    private storeAlert;
+    private deliverWebhook;
+}
+export declare function getAlertManager(config?: Partial<AlertsConfig>): AlertManager;
+export declare function resetAlertManager(): void;
+//# sourceMappingURL=alerts.d.ts.map

package/dist/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../src/alerts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAIlD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3D,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,OAAO,CAAC;CACpB;AAID,eAAO,MAAM,qBAAqB,EAAE,YAInC,CAAC;AAyBF,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,YAAY,CAAS;IAG7B,OAAO,CAAC,KAAK,CAAkC;IAE/C,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,YAAY,CAAK;gBAEb,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC;IAI1C,gCAAgC;IAChC,IAAI,IAAI,IAAI;IAkCZ,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAIjD,SAAS,IAAI,YAAY;IAIzB;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAW3G;;OAEG;IACH,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,KAAK,GAAG,IAAI;IAUjD;;OAEG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI;IAUjF;;OAEG;IACH,SAAS,CAAC,KAAK,GAAE,MAAW,GAAG,KAAK,EAAE;IAkBtC;;OAEG;IACH,SAAS,IAAI,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC;IAetC,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,UAAU;IAqBlB,OAAO,CAAC,cAAc;CA8BvB;AAMD,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAK5E;AAED,wBAAgB,iBAAiB,IAAI,IAAI,CAExC"}