@jagilber-org/index-server 1.19.1

package/dist/dashboard/server/ThinClient.js

@@ -0,0 +1,237 @@
+"use strict";
+/**
+ * ThinClient - Stdio-to-HTTP bridge for MCP clients.
+ *
+ * **EXPERIMENTAL** — APIs, configuration, and behavior may change.
+ *
+ * A lightweight process that MCP hosts (VS Code, Claude) spawn via stdio.
+ * Instead of loading the full index, it forwards JSON-RPC frames to
+ * the leader server's HTTP endpoint.
+ *
+ * Flow:  MCP Host --stdio--> ThinClient --HTTP--> Leader Server
+ *
+ * Features:
+ * - Reads JSON-RPC frames from stdin, POSTs to leader
+ * - Writes responses to stdout
+ * - Auto-discovers leader from instance state files
+ * - Reconnects on leader failover
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ThinClient = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const http_1 = __importDefault(require("http"));
+const DEFAULT_MAX_RETRIES = 5;
+const DEFAULT_RETRY_DELAY = 500;
+const LOCK_FILE = 'leader.lock';
+class ThinClient {
+    leaderUrl;
+    stateDir;
+    maxRetries;
+    retryDelayMs;
+    _connected = false;
+    _stopped = false;
+    healthTimer = null;
+    constructor(options = {}) {
+        this.leaderUrl = options.leaderUrl ?? null;
+        this.stateDir = options.stateDir ?? null;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.retryDelayMs = options.retryDelayMs ?? DEFAULT_RETRY_DELAY;
+    }
+    get connected() { return this._connected; }
+    /**
+     * Discover the leader URL from the state directory.
+     */
+    discoverLeader() {
+        if (!this.stateDir)
+            return null;
+        const lockPath = path_1.default.join(this.stateDir, LOCK_FILE);
+        try {
+            if (!fs_1.default.existsSync(lockPath))
+                return null;
+            const raw = fs_1.default.readFileSync(lockPath, 'utf8');
+            const entry = JSON.parse(raw);
+            if (entry.host && entry.port) {
+                return `http://${entry.host}:${entry.port}/mcp`;
+            }
+        }
+        catch {
+            // Can't read lock file
+        }
+        return null;
+    }
+    /**
+     * Resolve the leader URL (explicit or discovered).
+     * Re-discovers if the cached URL might be stale (leader changed port/host).
+     */
+    resolveLeaderUrl() {
+        if (this.leaderUrl && this.stateDir) {
+            // Validate cached URL still matches current leader.lock
+            const freshUrl = this.discoverLeader();
+            if (freshUrl && freshUrl !== this.leaderUrl) {
+                this.leaderUrl = freshUrl;
+                this._connected = false;
+            }
+        }
+        else if (!this.leaderUrl) {
+            const discovered = this.discoverLeader();
+            if (discovered) {
+                this.leaderUrl = discovered;
+            }
+        }
+        return this.leaderUrl;
+    }
+    /**
+     * Send a JSON-RPC request to the leader and return the response.
+     */
+    async sendRpc(method, params = {}, id = 1) {
+        const url = this.resolveLeaderUrl();
+        if (!url) {
+            throw new Error('No leader URL available');
+        }
+        let lastError = null;
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            try {
+                const response = await this.httpPost(`${url}/rpc`, {
+                    jsonrpc: '2.0',
+                    method,
+                    params,
+                    id,
+                });
+                this._connected = true;
+                return response;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                this._connected = false;
+                // On failure, try re-discovering leader (may have failed over)
+                if (this.stateDir && attempt < this.maxRetries - 1) {
+                    this.leaderUrl = null; // Force re-discovery
+                    await this.sleep(this.retryDelayMs * Math.pow(2, attempt));
+                }
+            }
+        }
+        throw lastError ?? new Error('Failed to connect to leader');
+    }
+    /**
+     * Check if the leader is healthy.
+     */
+    async checkHealth() {
+        const url = this.resolveLeaderUrl();
+        if (!url)
+            return false;
+        try {
+            const response = await this.httpGet(`${url}/health`);
+            return response?.status === 'ok';
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Process a raw JSON-RPC frame (as received from stdin).
+     */
+    async processFrame(frame) {
+        let parsed;
+        try {
+            parsed = JSON.parse(frame);
+        }
+        catch {
+            return JSON.stringify({
+                jsonrpc: '2.0',
+                error: { code: -32700, message: 'Parse error' },
+                id: null,
+            });
+        }
+        try {
+            const result = await this.sendRpc(parsed.method, parsed.params, parsed.id);
+            return JSON.stringify(result);
+        }
+        catch (err) {
+            return JSON.stringify({
+                jsonrpc: '2.0',
+                error: { code: -32603, message: err instanceof Error ? err.message : 'Internal error' },
+                id: parsed.id ?? null,
+            });
+        }
+    }
+    stop() {
+        this._stopped = true;
+        this._connected = false;
+        if (this.healthTimer) {
+            clearInterval(this.healthTimer);
+            this.healthTimer = null;
+        }
+    }
+    async httpPost(url, body) {
+        const bodyStr = JSON.stringify(body);
+        return new Promise((resolve, reject) => {
+            const urlObj = new URL(url);
+            const req = http_1.default.request({
+                hostname: urlObj.hostname,
+                port: parseInt(urlObj.port),
+                path: urlObj.pathname,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(bodyStr),
+                },
+                timeout: 10000,
+            }, (res) => {
+                let data = '';
+                res.on('data', (chunk) => { data += chunk; });
+                res.on('end', () => {
+                    try {
+                        resolve(JSON.parse(data));
+                    }
+                    catch {
+                        reject(new Error(`Invalid JSON response: ${data.slice(0, 100)}`));
+                    }
+                });
+            });
+            req.on('error', reject);
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new Error('Request timeout'));
+            });
+            req.write(bodyStr);
+            req.end();
+        });
+    }
+    async httpGet(url) {
+        return new Promise((resolve, reject) => {
+            const urlObj = new URL(url);
+            const req = http_1.default.request({
+                hostname: urlObj.hostname,
+                port: parseInt(urlObj.port),
+                path: urlObj.pathname,
+                method: 'GET',
+                timeout: 5000,
+            }, (res) => {
+                let data = '';
+                res.on('data', (chunk) => { data += chunk; });
+                res.on('end', () => {
+                    try {
+                        resolve(JSON.parse(data));
+                    }
+                    catch {
+                        reject(new Error(`Invalid JSON response`));
+                    }
+                });
+            });
+            req.on('error', reject);
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new Error('Request timeout'));
+            });
+            req.end();
+        });
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.ThinClient = ThinClient;

package/dist/dashboard/server/WebSocketManager.d.ts

@@ -0,0 +1,161 @@
+/**
+ * WebSocketManager - Phase 1 Dashboard Foundation
+ *
+ * Manages WebSocket connections for real-time dashboard updates.
+ * Provides bidirectional communication between dashboard clients and server.
+ */
+import { WebSocket } from 'ws';
+import { Server as HttpServer } from 'http';
+import { MetricsSnapshot } from './MetricsCollector.js';
+export interface DashboardMessage {
+    type: string;
+    timestamp: number;
+    data?: unknown;
+}
+export interface MetricsUpdateMessage extends DashboardMessage {
+    type: 'metrics_update';
+    data: MetricsSnapshot;
+}
+export interface ToolCallMessage extends DashboardMessage {
+    type: 'tool_call';
+    data: {
+        toolName: string;
+        success: boolean;
+        responseTime: number;
+        clientId?: string;
+        errorType?: string;
+    };
+}
+export interface ClientConnectMessage extends DashboardMessage {
+    type: 'client_connect';
+    data: {
+        clientId: string;
+        timestamp: number;
+    };
+}
+export interface ClientDisconnectMessage extends DashboardMessage {
+    type: 'client_disconnect';
+    data: {
+        clientId: string;
+        timestamp: number;
+        duration: number;
+    };
+}
+export interface ErrorMessage extends DashboardMessage {
+    type: 'error';
+    data: {
+        message: string;
+        stack?: string;
+        severity: 'low' | 'medium' | 'high' | 'critical';
+    };
+}
+export interface GenericMessage extends DashboardMessage {
+    type: 'welcome' | 'pong' | 'subscribed';
+    data?: unknown;
+}
+export interface MessagingEventMessage extends DashboardMessage {
+    type: 'message_received' | 'message_purged';
+    data?: {
+        messageId?: string;
+        channel?: string;
+        count?: number;
+    };
+}
+export interface SyntheticTraceMessage extends DashboardMessage {
+    type: 'synthetic_trace';
+    data: {
+        runId: string;
+        seq: number;
+        total?: number;
+        method: string;
+        success: boolean;
+        durationMs: number;
+        started: number;
+        ended: number;
+        error?: string;
+        skipped?: boolean;
+    };
+}
+export type DashboardEventMessage = MetricsUpdateMessage | ToolCallMessage | ClientConnectMessage | ClientDisconnectMessage | ErrorMessage | GenericMessage | SyntheticTraceMessage | MessagingEventMessage;
+interface ExtendedWebSocket extends WebSocket {
+    isAlive?: boolean;
+    clientId?: string;
+    connectedAt?: number;
+    lastActivity?: number;
+    ipAddress?: string;
+    userAgent?: string;
+}
+export interface WebSocketManagerOptions {
+    path?: string;
+    maxConnections?: number;
+    pingInterval?: number;
+    pongTimeout?: number;
+}
+export declare class WebSocketManager {
+    private wss;
+    private clients;
+    private options;
+    private pingTimer?;
+    private persistenceManager;
+    constructor(options?: WebSocketManagerOptions);
+    /**
+     * Initialize WebSocket server
+     */
+    initialize(server: HttpServer): void;
+    /**
+     * Broadcast message to all connected clients
+     */
+    broadcast(message: DashboardEventMessage): void;
+    /**
+     * Send message to specific client
+     */
+    sendToClient(client: ExtendedWebSocket, message: DashboardEventMessage): void;
+    /**
+     * Get connected client count
+     */
+    getClientCount(): number;
+    /**
+     * Get all connected clients
+     */
+    getClients(): ExtendedWebSocket[];
+    /**
+     * Close all connections and cleanup
+     */
+    close(): void;
+    private handleConnection;
+    private handleClientMessage;
+    private sendError;
+    private startHeartbeat;
+    /** Generate a UUID using crypto.randomUUID if available */
+    private safeGenerateClientId;
+    /** Send current metrics snapshot to a specific client */
+    private sendCurrentMetrics;
+    /** Broadcast fresh metrics snapshot to all clients */
+    private broadcastMetricsSnapshot;
+    /**
+     * Return lightweight summaries of active websocket connections with real IDs and durations.
+     * Exposed via /api/admin/connections for dashboard consumption.
+     */
+    getActiveConnectionSummaries(): {
+        id: string;
+        connectedAt: number;
+        durationMs: number;
+    }[];
+    /**
+     * Persist current WebSocket connection state to disk
+     */
+    private persistConnectionState;
+    /**
+     * Update connection activity timestamp
+     */
+    updateConnectionActivity(clientId: string): boolean;
+}
+/**
+ * Get or create the global WebSocket manager instance
+ */
+export declare function getWebSocketManager(): WebSocketManager;
+/**
+ * Set a custom WebSocket manager instance (useful for testing)
+ */
+export declare function setWebSocketManager(manager: WebSocketManager | null): void;
+export {};