mcp-server-andru-intelligence 1.1.0 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Andru Revenue Intelligence MCP Server
 
-The revenue intelligence system that technical founders wish existed when they were Googling "how to interview a VP Sales" at 2 AM. ICP scoring, buyer persona profiling, competitive battlecards, MBTI-adapted messaging, and pre-meeting briefs — built on 20 years of B2B sales pattern data.
+19 buyer intelligence tools for technical founders who sell to enterprises. ICP scoring, buyer persona simulation, competitive battlecards, MBTI-adapted messaging, deal classification, sales hiring blueprints, VC thesis matching, founder wellness, and pre-meeting briefs — built on 20 years of B2B sales pattern data.
 
 Works immediately — no pipeline data required. Describe your product and Andru delivers pre-built buyer intelligence in seconds. Run a full pipeline for intelligence tuned to your specific market.
 
@@ -23,7 +23,7 @@ ANDRU_API_KEY=sk_live_... npx mcp-server-andru-intelligence
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
 | `ANDRU_API_KEY` | Yes | — | Your Andru Platform API key |
-| `ANDRU_API_URL` | No | `https://api.andru.ai` | API base URL |
+| `ANDRU_API_URL` | No | `https://hs-andru-test.onrender.com` | API base URL |
 
 Get your API key at [platform.andru-ai.com/settings/api-keys](https://platform.andru-ai.com/settings/api-keys).
 
@@ -94,6 +94,30 @@ claude mcp add andru-intelligence npx mcp-server-andru-intelligence \
 | `get_syndication_status` | Shows whether your CRM has your current intelligence or is running on stale data | <200ms |
 | `trigger_syndication` | Pushes latest intelligence into your CRM — detects which platforms are out of date and updates only what's stale | 5-15s |
 
+### Founder Tools
+
+| Tool | What It Does | Latency |
+|------|-------------|---------|
+| `get_sales_blueprint` | First sales hire blueprint — JD, comp model, interview questions, and 90-day ramp plan for the stage you're at | 10-20s |
+| `get_thesis_match` | Match your company against VC investment theses — top 5 fits with reasoning for why each thesis applies | 10-20s |
+| `get_founder_wellness` | Burnout risk assessment with recovery recommendations — because 54% of founders are severely stressed and 81% hide it | <200ms |
+| `simulate_buyer_persona` | Practice your pitch against a simulated CFO, CTO, or VP Sales — get the objections before the real meeting | 5-15s |
+
+## CLI
+
+All 19 tools are also available from the command line via the companion [`andru-intel`](https://www.npmjs.com/package/andru-intel) package:
+
+```bash
+npx andru-intel list                    # see all 19 tools
+npx andru-intel score "AI code review"  # instant ICP (works offline)
+npx andru-intel persona CFO             # buyer persona deep dive
+npx andru-intel blueprint --stage "Series A" --arr "$2M"
+npx andru-intel thesis "AI sales platform" --stage "Seed"
+npx andru-intel roleplay CTO
+npx andru-intel wellness
+npx andru-intel run get_competitive_positioning --companyName "Acme"
+```
+
 ## Cold-Start Support
 
 7 tools work without any pipeline data — just describe your product:
@@ -125,7 +149,7 @@ Claude Desktop/Code  →  MCP Server (stdio)  →  Andru API (HTTPS)
 Andru also supports the Agent-to-Agent (A2A) protocol for direct agent-to-agent communication. The AgentCard is available at:
 
 ```
-https://platform.andru-ai.com/.well-known/agent.json
+https://hs-andru-test.onrender.com/.well-known/agent.json
 ```
 
 ## Also Available As

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-andru-intelligence",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "mcpName": "io.github.geter-andru/andru-intelligence",
   "description": "Buyer intelligence for technical founders who sell to enterprises — know who to target, what to say, and when to walk away. 19 MCP tools + CLI: ICP scoring, persona simulation, battlecards, deal classification, prospect discovery, sales hiring, investor matching, founder wellness.",
   "type": "module",
@@ -23,7 +23,9 @@
     "saas"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0"
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^12.6.2",
+    "ws": "^8.19.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/cache.js

@@ -0,0 +1,250 @@
+/**
+ * SQLite Cache Layer (Phase 8 — Local Agent Runtime)
+ *
+ * Provides offline-capable caching for MCP tool results, resources,
+ * and ANDRU_SOUL.md content. Data persists at ~/.andru/cache.db.
+ *
+ * Cache hierarchy:
+ *   1. SQLite (hot path — <1ms reads)
+ *   2. Backend API (warm path — network call)
+ *   3. Stale cache (cold path — expired but better than nothing)
+ *
+ * @module cache
+ */
+
+import Database from 'better-sqlite3';
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const CACHE_DIR = join(homedir(), '.andru');
+const DB_PATH = join(CACHE_DIR, 'cache.db');
+
+// Default TTLs in seconds
+const TTL = {
+  tool_result: 300,       // 5 min — tool outputs change often
+  resource: 1800,         // 30 min — ICP profiles, pipeline data
+  soul: 86400,            // 24h — soul content rarely changes
+  prospect: 3600,         // 1h — prospect watch list data
+  icp_profile: 1800,      // 30 min — ICP profiles
+  pipeline: 600,          // 10 min — pipeline data
+};
+
+let db = null;
+
+/**
+ * Initialize the SQLite cache. Creates ~/.andru/ and tables if needed.
+ * Safe to call multiple times — idempotent.
+ *
+ * @returns {Database} The database instance
+ */
+export function initCache() {
+  if (db) return db;
+
+  // Ensure ~/.andru/ exists
+  if (!existsSync(CACHE_DIR)) {
+    mkdirSync(CACHE_DIR, { recursive: true });
+  }
+
+  db = new Database(DB_PATH);
+
+  // WAL mode for better concurrent read performance
+  db.pragma('journal_mode = WAL');
+
+  // Create tables
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS cache_entries (
+      key TEXT PRIMARY KEY,
+      category TEXT NOT NULL DEFAULT 'general',
+      value TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      access_count INTEGER DEFAULT 0,
+      last_accessed_at INTEGER
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_cache_category ON cache_entries(category);
+    CREATE INDEX IF NOT EXISTS idx_cache_expires ON cache_entries(expires_at);
+
+    CREATE TABLE IF NOT EXISTS sync_state (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+  `);
+
+  // Clean expired entries on init (background housekeeping)
+  cleanExpired();
+
+  return db;
+}
+
+/**
+ * Get a cached value by key. Returns null if not found or expired.
+ * Optionally returns stale entries when allowStale=true (for offline fallback).
+ *
+ * @param {string} key - Cache key
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowStale=false] - Return expired entries as fallback
+ * @returns {{ value: any, stale: boolean } | null}
+ */
+export function get(key, { allowStale = false } = {}) {
+  if (!db) initCache();
+
+  const now = Math.floor(Date.now() / 1000);
+  const row = db.prepare(
+    'SELECT value, expires_at FROM cache_entries WHERE key = ?'
+  ).get(key);
+
+  if (!row) return null;
+
+  const isExpired = row.expires_at < now;
+
+  if (isExpired && !allowStale) return null;
+
+  // Update access stats
+  db.prepare(
+    'UPDATE cache_entries SET access_count = access_count + 1, last_accessed_at = ? WHERE key = ?'
+  ).run(now, key);
+
+  try {
+    return { value: JSON.parse(row.value), stale: isExpired };
+  } catch {
+    return { value: row.value, stale: isExpired };
+  }
+}
+
+/**
+ * Set a cache entry.
+ *
+ * @param {string} key - Cache key
+ * @param {any} value - Value to cache (will be JSON-stringified)
+ * @param {object} [opts]
+ * @param {string} [opts.category='general'] - Category for bulk operations
+ * @param {number} [opts.ttl] - TTL in seconds (defaults to category TTL)
+ */
+export function set(key, value, { category = 'general', ttl } = {}) {
+  if (!db) initCache();
+
+  const now = Math.floor(Date.now() / 1000);
+  const effectiveTtl = ttl || TTL[category] || TTL.tool_result;
+  const expiresAt = now + effectiveTtl;
+
+  const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+
+  db.prepare(`
+    INSERT OR REPLACE INTO cache_entries (key, category, value, created_at, expires_at, access_count, last_accessed_at)
+    VALUES (?, ?, ?, ?, ?, 0, ?)
+  `).run(key, category, serialized, now, expiresAt, now);
+}
+
+/**
+ * Get all entries matching a category. Returns fresh + optionally stale.
+ *
+ * @param {string} category
+ * @param {object} [opts]
+ * @param {boolean} [opts.allowStale=false]
+ * @returns {Array<{ key: string, value: any, stale: boolean }>}
+ */
+export function getByCategory(category, { allowStale = false } = {}) {
+  if (!db) initCache();
+
+  const now = Math.floor(Date.now() / 1000);
+  const query = allowStale
+    ? 'SELECT key, value, expires_at FROM cache_entries WHERE category = ?'
+    : 'SELECT key, value, expires_at FROM cache_entries WHERE category = ? AND expires_at >= ?';
+
+  const params = allowStale ? [category] : [category, now];
+  const rows = db.prepare(query).all(...params);
+
+  return rows.map(row => {
+    try {
+      return {
+        key: row.key,
+        value: JSON.parse(row.value),
+        stale: row.expires_at < now,
+      };
+    } catch {
+      return { key: row.key, value: row.value, stale: row.expires_at < now };
+    }
+  });
+}
+
+/**
+ * Invalidate a specific key or all keys in a category.
+ *
+ * @param {string} keyOrCategory - Cache key or category name
+ * @param {object} [opts]
+ * @param {boolean} [opts.isCategory=false] - If true, delete all entries in category
+ */
+export function invalidate(keyOrCategory, { isCategory = false } = {}) {
+  if (!db) initCache();
+
+  if (isCategory) {
+    db.prepare('DELETE FROM cache_entries WHERE category = ?').run(keyOrCategory);
+  } else {
+    db.prepare('DELETE FROM cache_entries WHERE key = ?').run(keyOrCategory);
+  }
+}
+
+/**
+ * Get or set sync state (for tracking last-sync timestamps, etc.).
+ */
+export function getSyncState(key) {
+  if (!db) initCache();
+  const row = db.prepare('SELECT value FROM sync_state WHERE key = ?').get(key);
+  if (!row) return null;
+  try { return JSON.parse(row.value); } catch { return row.value; }
+}
+
+export function setSyncState(key, value) {
+  if (!db) initCache();
+  const now = Math.floor(Date.now() / 1000);
+  const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+  db.prepare(
+    'INSERT OR REPLACE INTO sync_state (key, value, updated_at) VALUES (?, ?, ?)'
+  ).run(key, serialized, now);
+}
+
+/**
+ * Cache stats for diagnostics.
+ */
+export function getStats() {
+  if (!db) initCache();
+
+  const now = Math.floor(Date.now() / 1000);
+  const total = db.prepare('SELECT COUNT(*) as count FROM cache_entries').get();
+  const fresh = db.prepare('SELECT COUNT(*) as count FROM cache_entries WHERE expires_at >= ?').get(now);
+  const stale = total.count - fresh.count;
+  const categories = db.prepare(
+    'SELECT category, COUNT(*) as count FROM cache_entries GROUP BY category'
+  ).all();
+
+  return {
+    total: total.count,
+    fresh: fresh.count,
+    stale,
+    categories: Object.fromEntries(categories.map(c => [c.category, c.count])),
+    dbPath: DB_PATH,
+  };
+}
+
+/**
+ * Remove all expired entries.
+ */
+export function cleanExpired() {
+  if (!db) return;
+  const now = Math.floor(Date.now() / 1000);
+  const result = db.prepare('DELETE FROM cache_entries WHERE expires_at < ?').run(now);
+  return result.changes;
+}
+
+/**
+ * Close the database connection. Call on process exit.
+ */
+export function closeCache() {
+  if (db) {
+    db.close();
+    db = null;
+  }
+}

package/src/cachedClient.js

@@ -0,0 +1,127 @@
+/**
+ * Cache-Enhanced Andru API Client (Phase 8)
+ *
+ * Wraps the base AndruClient with SQLite caching:
+ *   - On success: cache result, return it
+ *   - On failure: serve from cache (stale OK)
+ *   - Offline: serve from cache transparently
+ *
+ * @module cachedClient
+ */
+
+import { get, set } from './cache.js';
+
+/**
+ * Create a cache-enhanced wrapper around the base client.
+ *
+ * @param {import('./client.js').AndruClient} client - Base API client
+ * @returns {object} Client with same interface but cache-backed
+ */
+export function createCachedClient(client) {
+  return {
+    /**
+     * Execute a tool with cache fallback.
+     */
+    async callTool(name, args) {
+      const cacheKey = `tool:${name}:${stableHash(args)}`;
+
+      try {
+        const result = await client.callTool(name, args);
+
+        // Cache successful results (not errors)
+        if (!result.isError) {
+          set(cacheKey, result, { category: 'tool_result' });
+        }
+
+        return result;
+      } catch (err) {
+        // Network failure — try cache
+        const cached = get(cacheKey, { allowStale: true });
+        if (cached) {
+          return {
+            ...cached.value,
+            _fromCache: true,
+            _stale: cached.stale,
+          };
+        }
+        throw err;
+      }
+    },
+
+    /**
+     * Read a resource with cache fallback.
+     */
+    async readResource(uri) {
+      const cacheKey = `resource:${uri}`;
+
+      try {
+        const result = await client.readResource(uri);
+        set(cacheKey, result, { category: 'resource' });
+        return result;
+      } catch (err) {
+        const cached = get(cacheKey, { allowStale: true });
+        if (cached) {
+          return {
+            ...cached.value,
+            _fromCache: true,
+            _stale: cached.stale,
+          };
+        }
+        throw err;
+      }
+    },
+
+    /**
+     * List tools — uses static catalog, no caching needed.
+     */
+    async listTools() {
+      return client.listTools();
+    },
+
+    /**
+     * List resources — uses static catalog, no caching needed.
+     */
+    async listResources() {
+      return client.listResources();
+    },
+
+    /**
+     * Pre-warm the cache with frequently-used data.
+     * Called after initial WebSocket sync.
+     */
+    async warmCache() {
+      const essentialResources = [
+        'andru://icp/profile',
+        'andru://pipeline/summary',
+        'andru://soul/voice',
+      ];
+
+      const results = [];
+      for (const uri of essentialResources) {
+        try {
+          const result = await client.readResource(uri);
+          set(`resource:${uri}`, result, { category: 'resource' });
+          results.push({ uri, status: 'cached' });
+        } catch {
+          results.push({ uri, status: 'failed' });
+        }
+      }
+      return results;
+    },
+  };
+}
+
+/**
+ * Stable hash for cache keys — deterministic JSON key ordering.
+ * Simple but effective for cache key generation.
+ */
+function stableHash(obj) {
+  if (!obj || typeof obj !== 'object') return String(obj || '');
+  const sorted = JSON.stringify(obj, Object.keys(obj).sort());
+  // Simple string hash (djb2)
+  let hash = 5381;
+  for (let i = 0; i < sorted.length; i++) {
+    hash = ((hash << 5) + hash + sorted.charCodeAt(i)) & 0xffffffff;
+  }
+  return hash.toString(36);
+}

package/src/cli.js

@@ -19,7 +19,7 @@
  *
  * Environment:
  *   ANDRU_API_KEY  (required) — Your Andru Platform API key
- *   ANDRU_API_URL  (optional) — API base URL (default: https://api.andru.ai)
+ *   ANDRU_API_URL  (optional) — API base URL (default: https://hs-andru-test.onrender.com)
  */
 
 import { tools } from './catalog.js';
@@ -40,8 +40,8 @@ Examples:
   andru-intel get_sales_blueprint --companyStage "Series A" --arrTarget "$5M"
 
 Environment:
-  ANDRU_API_KEY   Your API key (get one at https://app.andru.ai/settings/api-keys)
-  ANDRU_API_URL   API endpoint (default: https://api.andru.ai)
+  ANDRU_API_KEY   Your API key (get one at https://platform.andru-ai.com/settings/api-keys)
+  ANDRU_API_URL   API endpoint (default: https://hs-andru-test.onrender.com)
 
 ${tools.length} tools available. Run 'andru-intel list' to see them all.
 `);
@@ -166,13 +166,13 @@ async function main() {
   const apiKey = process.env.ANDRU_API_KEY;
   if (!apiKey) {
     console.error('ANDRU_API_KEY not set.');
-    console.error('Get your API key at https://app.andru.ai/settings/api-keys');
+    console.error('Get your API key at https://platform.andru-ai.com/settings/api-keys');
     console.error('');
     console.error('Usage: ANDRU_API_KEY=sk_live_... andru-intel ' + toolName + ' [args]');
     process.exit(1);
   }
 
-  const apiUrl = process.env.ANDRU_API_URL || 'https://api.andru.ai';
+  const apiUrl = process.env.ANDRU_API_URL || 'https://hs-andru-test.onrender.com';
   const client = new AndruClient(apiKey, apiUrl);
   const toolArgs = parseArgs(argv.slice(1));
 

package/src/client.js

@@ -5,14 +5,14 @@
  * Authenticates via X-API-Key header.
  */
 
-const DEFAULT_API_URL = 'https://api.andru.ai';
+const DEFAULT_API_URL = 'https://hs-andru-test.onrender.com';
 const REQUEST_TIMEOUT_MS = 60_000; // 60s for AI-calling tools
-const PACKAGE_VERSION = '0.2.0';
+const PACKAGE_VERSION = '1.3.0';
 
 export class AndruClient {
   /**
    * @param {string} apiKey - Andru Platform API key
-   * @param {string} [baseUrl] - API base URL (default: https://api.andru.ai)
+   * @param {string} [baseUrl] - API base URL (default: https://hs-andru-test.onrender.com)
    */
   constructor(apiKey, baseUrl = DEFAULT_API_URL) {
     this.apiKey = apiKey;

package/src/index.js

@@ -8,7 +8,7 @@
  *
  * Environment variables:
  *   ANDRU_API_KEY  (required) — Your Andru Platform API key
- *   ANDRU_API_URL  (optional) — API base URL (default: https://api.andru.ai)
+ *   ANDRU_API_URL  (optional) — API base URL (default: https://hs-andru-test.onrender.com)
  *
  * Usage:
  *   ANDRU_API_KEY=sk_live_... npx mcp-server-andru-intelligence
@@ -30,20 +30,37 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { AndruClient } from './client.js';
 import { createServer } from './server.js';
+import { initCache, closeCache, getStats } from './cache.js';
+import { createCachedClient } from './cachedClient.js';
+import { startSync, stopSync } from './sync.js';
 
 async function main() {
   const apiKey = process.env.ANDRU_API_KEY;
-  const apiUrl = process.env.ANDRU_API_URL || 'https://api.andru.ai';
+  const apiUrl = process.env.ANDRU_API_URL || 'https://hs-andru-test.onrender.com';
+  const cacheEnabled = process.env.ANDRU_CACHE !== 'false'; // Default: enabled
+
+  // Initialize SQLite cache (Phase 8)
+  if (cacheEnabled) {
+    try {
+      initCache();
+      const stats = getStats();
+      console.error(`[Andru MCP] Cache initialized: ${stats.total} entries (${stats.fresh} fresh) at ${stats.dbPath}`);
+    } catch (err) {
+      console.error('[Andru MCP] Cache init failed (continuing without cache):', err.message);
+    }
+  }
 
   // When no API key, server still starts (tool listing works from static catalog,
   // but tool execution will return an error). This allows registry scanners
   // to discover tools without needing credentials.
   let client = null;
   if (apiKey) {
-    client = new AndruClient(apiKey, apiUrl);
+    const baseClient = new AndruClient(apiKey, apiUrl);
+    // Wrap with cache layer (Phase 8)
+    client = cacheEnabled ? createCachedClient(baseClient) : baseClient;
   } else {
     console.error('[Andru MCP] Warning: ANDRU_API_KEY not set. Tool listing works, but execution requires an API key.');
-    console.error('[Andru MCP] Get your API key at https://app.andru.ai/settings/api-keys');
+    console.error('[Andru MCP] Get your API key at https://platform.andru-ai.com/settings/api-keys');
   }
 
   const server = createServer(client);
@@ -55,6 +72,49 @@ async function main() {
   if (client) {
     console.error(`[Andru MCP] API endpoint: ${apiUrl}`);
   }
+
+  // Start WebSocket sync (Phase 8) — keeps cache fresh via backend events
+  if (cacheEnabled && apiKey) {
+    const wsUrl = deriveWsUrl(apiUrl);
+    startSync({
+      wsUrl,
+      token: apiKey,
+      onSync: (event) => {
+        console.error(`[Andru MCP] Sync event: ${event.type}`);
+      },
+      onError: (err) => {
+        console.error(`[Andru MCP] Sync error: ${err.message}`);
+      },
+    });
+    console.error(`[Andru MCP] Cache sync connecting to ${wsUrl}`);
+  }
+
+  // Cleanup on exit
+  process.on('SIGINT', () => {
+    stopSync();
+    closeCache();
+    process.exit(0);
+  });
+  process.on('SIGTERM', () => {
+    stopSync();
+    closeCache();
+    process.exit(0);
+  });
+}
+
+/**
+ * Derive WebSocket URL from HTTP API URL.
+ * https://hs-andru-test.onrender.com → wss://hs-andru-test.onrender.com/ws
+ * http://localhost:3001 → ws://localhost:3001/ws
+ */
+function deriveWsUrl(apiUrl) {
+  const wsOverride = process.env.ANDRU_WS_URL;
+  if (wsOverride) return wsOverride;
+
+  return apiUrl
+    .replace(/^https:/, 'wss:')
+    .replace(/^http:/, 'ws:')
+    .replace(/\/+$/, '') + '/ws';
 }
 
 main().catch((err) => {

package/src/server.js

@@ -1,8 +1,9 @@
 /**
- * Andru MCP Server (Thin Proxy)
+ * Andru MCP Server (Thin Proxy + Local Cache)
  *
  * Lists tools and resources from the static catalog (no network needed).
  * Proxies tool execution and resource reads to the Andru backend API.
+ * Phase 8: Falls back to SQLite cache when offline.
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -17,7 +18,7 @@ import { tools, resources } from './catalog.js';
 /**
  * Create an MCP server backed by the Andru API.
  *
- * @param {import('./client.js').AndruClient | null} client — null during scan mode (no API key)
+ * @param {import('./client.js').AndruClient | import('./cachedClient.js').CachedClient | null} client — null during scan mode (no API key). When Phase 8 cache is active, this is a cachedClient wrapper.
  * @returns {Server}
  */
 export function createServer(client) {

package/src/sync.js

@@ -0,0 +1,238 @@
+/**
+ * WebSocket Sync Client (Phase 8 — Local Agent Runtime)
+ *
+ * Connects to the backend WebSocket server (Phase 6) and keeps
+ * the local SQLite cache fresh. Handles:
+ *
+ * - Auth via Supabase/API token
+ * - Cache invalidation events from backend
+ * - Reconnection with exponential backoff
+ * - Initial bulk sync on first connect
+ *
+ * @module sync
+ */
+
+import WebSocket from 'ws';
+import { set, invalidate, getSyncState, setSyncState } from './cache.js';
+
+const RECONNECT_DELAYS = [1000, 2000, 4000, 8000, 15000, 30000];
+const HEARTBEAT_INTERVAL_MS = 25000; // Slightly under server's 30s
+
+let ws = null;
+let reconnectAttempt = 0;
+let heartbeatTimer = null;
+let reconnectTimer = null;
+let isConnecting = false;
+
+/**
+ * Start the sync client. Connects to backend WebSocket and
+ * keeps the local cache updated.
+ *
+ * @param {object} opts
+ * @param {string} opts.wsUrl - WebSocket URL (e.g., wss://hs-andru-test.onrender.com/ws)
+ * @param {string} opts.token - Auth token (Supabase JWT or API key)
+ * @param {function} [opts.onSync] - Called when sync event received
+ * @param {function} [opts.onError] - Called on connection error
+ */
+export function startSync({ wsUrl, token, onSync, onError }) {
+  if (ws || isConnecting) return;
+  isConnecting = true;
+
+  try {
+    ws = new WebSocket(wsUrl);
+  } catch (err) {
+    isConnecting = false;
+    if (onError) onError(err);
+    scheduleReconnect({ wsUrl, token, onSync, onError });
+    return;
+  }
+
+  ws.on('open', () => {
+    isConnecting = false;
+    reconnectAttempt = 0;
+
+    // Authenticate
+    ws.send(JSON.stringify({ type: 'auth', token }));
+
+    // Start client heartbeat
+    heartbeatTimer = setInterval(() => {
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: 'ping' }));
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+  });
+
+  ws.on('message', (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(raw.toString());
+    } catch {
+      return;
+    }
+
+    // Auth confirmed — request initial sync
+    if (msg.type === 'auth_ok') {
+      requestInitialSync();
+      return;
+    }
+
+    // Cache invalidation events from backend
+    if (msg.type === 'cache_invalidate') {
+      handleCacheInvalidation(msg);
+      if (onSync) onSync(msg);
+      return;
+    }
+
+    // Bulk sync response
+    if (msg.type === 'sync_data') {
+      handleBulkSync(msg);
+      if (onSync) onSync(msg);
+      return;
+    }
+
+    // Data update pushed from backend (e.g., ICP profile changed)
+    if (msg.type === 'data_update') {
+      handleDataUpdate(msg);
+      if (onSync) onSync(msg);
+      return;
+    }
+
+    // Soul preamble update (only the compressed preamble — never the full soul)
+    if (msg.type === 'soul_update') {
+      // Security: only cache the preamble, never full soul content
+      if (msg.preamble) {
+        set('soul:preamble', msg.preamble, { category: 'soul' });
+      }
+      if (msg.versionHash) {
+        set('soul:version', msg.versionHash, { category: 'soul' });
+      }
+      if (onSync) onSync(msg);
+      return;
+    }
+  });
+
+  ws.on('close', (code) => {
+    cleanup();
+    // Don't reconnect if auth failed
+    if (code === 4003) {
+      if (onError) onError(new Error('Authentication failed'));
+      return;
+    }
+    scheduleReconnect({ wsUrl, token, onSync, onError });
+  });
+
+  ws.on('error', (err) => {
+    cleanup();
+    if (onError) onError(err);
+    scheduleReconnect({ wsUrl, token, onSync, onError });
+  });
+}
+
+/**
+ * Stop the sync client. Closes WebSocket and cancels timers.
+ */
+export function stopSync() {
+  if (reconnectTimer) {
+    clearTimeout(reconnectTimer);
+    reconnectTimer = null;
+  }
+  cleanup();
+  reconnectAttempt = 0;
+}
+
+/**
+ * Whether the sync client is currently connected and authenticated.
+ */
+export function isSyncConnected() {
+  return ws !== null && ws.readyState === WebSocket.OPEN;
+}
+
+// ─── Internal ────────────────────────────────────────────────────────────────
+
+function cleanup() {
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+  if (ws) {
+    ws.removeAllListeners();
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      ws.close();
+    }
+    ws = null;
+  }
+  isConnecting = false;
+}
+
+function scheduleReconnect(opts) {
+  if (reconnectTimer) return;
+  const delay = RECONNECT_DELAYS[Math.min(reconnectAttempt, RECONNECT_DELAYS.length - 1)];
+  reconnectAttempt++;
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = null;
+    startSync(opts);
+  }, delay);
+}
+
+/**
+ * Request bulk data sync from backend.
+ * Sends last-sync timestamp so backend only sends changes.
+ */
+function requestInitialSync() {
+  if (!ws || ws.readyState !== WebSocket.OPEN) return;
+
+  const lastSync = getSyncState('last_sync_ts');
+
+  // Subscribe to cache invalidation channel
+  ws.send(JSON.stringify({
+    type: 'subscribe',
+    channels: ['cache:updates'],
+  }));
+
+  // Request any data that changed since our last sync
+  ws.send(JSON.stringify({
+    type: 'sync_request',
+    since: lastSync || 0,
+  }));
+}
+
+/**
+ * Handle cache invalidation from backend.
+ */
+function handleCacheInvalidation(msg) {
+  if (msg.key) {
+    invalidate(msg.key);
+  }
+  if (msg.category) {
+    invalidate(msg.category, { isCategory: true });
+  }
+}
+
+/**
+ * Handle bulk sync data from backend.
+ */
+function handleBulkSync(msg) {
+  if (!msg.entries || !Array.isArray(msg.entries)) return;
+
+  for (const entry of msg.entries) {
+    set(entry.key, entry.value, {
+      category: entry.category || 'general',
+      ttl: entry.ttl,
+    });
+  }
+
+  // Record sync timestamp
+  setSyncState('last_sync_ts', Date.now());
+}
+
+/**
+ * Handle individual data update from backend.
+ */
+function handleDataUpdate(msg) {
+  if (!msg.key || msg.value === undefined) return;
+
+  set(msg.key, msg.value, {
+    category: msg.category || 'general',
+    ttl: msg.ttl,
+  });
+}