@jagilber-org/index-server 1.19.1

package/dist/dashboard/server/AdminPanel.js

@@ -0,0 +1,792 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminPanel = void 0;
+exports.getAdminPanel = getAdminPanel;
+/**
+ * Index Server Admin - Enterprise Administration Interface
+ *
+ * Thin coordinator that delegates to:
+ * - AdminPanelConfig  — server configuration rendering/serialization
+ * - AdminPanelState   — admin session state management
+ *
+ * Retains direct responsibility for maintenance operations, backup/restore,
+ * system health monitoring, and admin statistics.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const v8_1 = __importDefault(require("v8"));
+const runtimeConfig_1 = require("../../config/runtimeConfig");
+const MetricsCollector_1 = require("./MetricsCollector");
+const indexContext_1 = require("../../services/indexContext");
+const AdminPanelConfig_1 = require("./AdminPanelConfig");
+const AdminPanelState_1 = require("./AdminPanelState");
+const backupZip_1 = require("../../services/backupZip");
+const adm_zip_1 = __importDefault(require("adm-zip"));
+class AdminPanel {
+    panelConfig;
+    panelState;
+    maintenanceInfo;
+    indexStatsCache = null;
+    lastUptimeSeconds = 0;
+    get backupRoot() {
+        return (0, runtimeConfig_1.getRuntimeConfig)().dashboard.admin.backupsDir || path_1.default.join(process.cwd(), 'backups');
+    }
+    get instructionsRoot() {
+        return (0, runtimeConfig_1.getRuntimeConfig)().index.baseDir || path_1.default.join(process.cwd(), 'instructions');
+    }
+    // CPU tracking for leak detection
+    cpuHistory = [];
+    lastCpuUsage = null;
+    maxCpuHistoryEntries = 100;
+    // Memory tracking for leak detection
+    memoryHistory = [];
+    maxMemoryHistoryEntries = 100;
+    constructor() {
+        this.panelConfig = new AdminPanelConfig_1.AdminPanelConfig();
+        this.panelState = new AdminPanelState_1.AdminPanelState();
+        this.maintenanceInfo = {
+            lastBackup: null,
+            nextScheduledMaintenance: null,
+            maintenanceMode: false,
+            systemHealth: { status: 'healthy', issues: [], recommendations: [] }
+        };
+    }
+    // ── Config delegation ──────────────────────────────────────────────────────────────
+    getAdminConfig() {
+        return this.panelConfig.getAdminConfig();
+    }
+    updateAdminConfig(updates) {
+        return this.panelConfig.updateAdminConfig(updates);
+    }
+    // ── Session state delegation ────────────────────────────────────────────────────────
+    getActiveSessions() {
+        return this.panelState.getActiveSessions(this.panelConfig.sessionTimeout);
+    }
+    createAdminSession(userId, ipAddress, userAgent) {
+        return this.panelState.createAdminSession(userId, ipAddress, userAgent);
+    }
+    terminateSession(sessionId) {
+        return this.panelState.terminateSession(sessionId);
+    }
+    /**
+     * Get system maintenance information
+     */
+    getMaintenanceInfo() {
+        // Update system health
+        this.updateSystemHealth();
+        return JSON.parse(JSON.stringify(this.maintenanceInfo));
+    }
+    /**
+     * Set maintenance mode
+     */
+    setMaintenanceMode(enabled, message) {
+        try {
+            this.maintenanceInfo.maintenanceMode = enabled;
+            if (enabled) {
+                process.stderr.write(`[admin] Maintenance mode ENABLED${message ? `: ${message}` : ''}\n`);
+            }
+            else {
+                process.stderr.write(`[admin] Maintenance mode DISABLED\n`);
+            }
+            return {
+                success: true,
+                message: `Maintenance mode ${enabled ? 'enabled' : 'disabled'}`
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to set maintenance mode: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    /**
+     * Perform system backup
+     */
+    async performBackup() {
+        try {
+            const backupRoot = this.backupRoot;
+            if (!fs_1.default.existsSync(backupRoot))
+                fs_1.default.mkdirSync(backupRoot, { recursive: true });
+            const now = new Date();
+            const iso = now.toISOString();
+            const baseTs = iso.replace(/[-:]/g, '').replace(/\..+/, '');
+            const ms = String(now.getMilliseconds()).padStart(3, '0');
+            const backupId = `backup_${baseTs}_${ms}`;
+            const zipPath = path_1.default.join(backupRoot, `${backupId}.zip`);
+            const instructionsDir = this.instructionsRoot;
+            let fileCount = 0;
+            if (fs_1.default.existsSync(instructionsDir)) {
+                fileCount = fs_1.default.readdirSync(instructionsDir).filter(f => f.toLowerCase().endsWith('.json')).length;
+            }
+            const manifest = {
+                backupId,
+                createdAt: now.toISOString(),
+                instructionCount: fileCount,
+                schemaVersion: this.indexStatsCache?.schemaVersion || 'unknown',
+            };
+            (0, backupZip_1.createZipBackupWithManifest)(instructionsDir, zipPath, manifest);
+            this.maintenanceInfo.lastBackup = new Date();
+            process.stderr.write(`[admin] System backup completed: ${backupId}.zip (${fileCount} files)\n`);
+            return { success: true, message: 'System backup completed successfully', backupId, files: fileCount };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Backup failed: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    listBackups() {
+        const backupRoot = this.backupRoot;
+        if (!fs_1.default.existsSync(backupRoot))
+            return [];
+        const results = [];
+        for (const entry of fs_1.default.readdirSync(backupRoot)) {
+            const full = path_1.default.join(backupRoot, entry);
+            try {
+                const stat = fs_1.default.statSync(full);
+                if ((0, backupZip_1.isZipBackup)(entry) && stat.isFile()) {
+                    // Zip backup
+                    const id = entry.replace(/\.zip$/i, '');
+                    let createdAt = new Date(stat.mtime).toISOString();
+                    let instructionCount = 0;
+                    let schemaVersion;
+                    const manifest = (0, backupZip_1.readZipManifest)(full);
+                    if (manifest) {
+                        createdAt = manifest.createdAt || createdAt;
+                        instructionCount = manifest.instructionCount || 0;
+                        schemaVersion = manifest.schemaVersion;
+                    }
+                    else {
+                        instructionCount = (0, backupZip_1.listZipInstructionFiles)(full).length;
+                    }
+                    results.push({ id, createdAt, instructionCount, schemaVersion, sizeBytes: stat.size });
+                }
+                else if (stat.isDirectory()) {
+                    // Legacy directory backup
+                    const manifestPath = path_1.default.join(full, 'manifest.json');
+                    let createdAt = new Date(stat.mtime).toISOString();
+                    let instructionCount = 0;
+                    let schemaVersion;
+                    if (fs_1.default.existsSync(manifestPath)) {
+                        try {
+                            const mf = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+                            createdAt = mf.createdAt || createdAt;
+                            instructionCount = mf.instructionCount || 0;
+                            schemaVersion = mf.schemaVersion;
+                        }
+                        catch { /* ignore */ }
+                    }
+                    else {
+                        instructionCount = fs_1.default.readdirSync(full).filter(f => f.toLowerCase().endsWith('.json')).length;
+                    }
+                    const sizeBytes = fs_1.default.readdirSync(full).reduce((sum, f) => {
+                        try {
+                            return sum + fs_1.default.statSync(path_1.default.join(full, f)).size;
+                        }
+                        catch {
+                            return sum;
+                        }
+                    }, 0);
+                    results.push({ id: entry, createdAt, instructionCount, schemaVersion, sizeBytes });
+                }
+            }
+            catch { /* ignore individual entry errors */ }
+        }
+        results.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+        return results;
+    }
+    restoreBackup(backupId) {
+        try {
+            if (!backupId)
+                return { success: false, message: 'backupId required' };
+            const backupRoot = this.backupRoot;
+            const zipPath = path_1.default.join(backupRoot, `${backupId}.zip`);
+            const backupDir = path_1.default.join(backupRoot, backupId);
+            const isZip = fs_1.default.existsSync(zipPath);
+            const isDir = fs_1.default.existsSync(backupDir) && fs_1.default.statSync(backupDir).isDirectory();
+            if (!isZip && !isDir)
+                return { success: false, message: `Backup not found: ${backupId}` };
+            const instructionsDir = this.instructionsRoot;
+            if (!fs_1.default.existsSync(instructionsDir))
+                fs_1.default.mkdirSync(instructionsDir, { recursive: true });
+            // Pre-restore safety backup (as zip)
+            const existing = fs_1.default.readdirSync(instructionsDir).filter(f => f.toLowerCase().endsWith('.json'));
+            if (existing.length) {
+                const safetyId = `pre_restore_${Date.now()}`;
+                const safetyZipPath = path_1.default.join(backupRoot, `${safetyId}.zip`);
+                (0, backupZip_1.createZipBackupWithManifest)(instructionsDir, safetyZipPath, {
+                    type: 'pre-restore',
+                    createdAt: new Date().toISOString(),
+                    source: backupId,
+                    originalCount: existing.length,
+                });
+                process.stderr.write(`[admin] Pre-restore safety backup created: ${safetyId}.zip\n`);
+            }
+            let restored = 0;
+            if (isZip) {
+                restored = (0, backupZip_1.extractZipBackup)(zipPath, instructionsDir);
+                // Don't count manifest.json as a restored instruction
+            }
+            else {
+                // Legacy directory restore
+                for (const f of fs_1.default.readdirSync(backupDir)) {
+                    if (f.toLowerCase().endsWith('.json') && f !== 'manifest.json') {
+                        fs_1.default.copyFileSync(path_1.default.join(backupDir, f), path_1.default.join(instructionsDir, f));
+                        restored++;
+                    }
+                }
+            }
+            this.indexStatsCache = null;
+            process.stderr.write(`[admin] Restored backup ${backupId} (${restored} instruction files)\n`);
+            return { success: true, message: `Backup ${backupId} restored`, restored };
+        }
+        catch (error) {
+            return { success: false, message: `Restore failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    /** Delete a backup zip or directory (safety checks on name) */
+    deleteBackup(backupId) {
+        try {
+            if (!backupId)
+                return { success: false, message: 'backupId required' };
+            const backupRoot = this.backupRoot;
+            // Check for zip first, then legacy directory
+            const zipPath = path_1.default.join(backupRoot, `${backupId}.zip`);
+            const dirPath = path_1.default.join(backupRoot, backupId);
+            const hasZip = fs_1.default.existsSync(zipPath);
+            const hasDir = fs_1.default.existsSync(dirPath) && fs_1.default.statSync(dirPath).isDirectory();
+            if (!hasZip && !hasDir)
+                return { success: false, message: `Backup not found: ${backupId}` };
+            if (!/^backup_|^instructions-|^pre_restore_|^auto-backup-/.test(backupId)) {
+                return { success: false, message: 'Refusing to delete unexpected backup name' };
+            }
+            if (hasZip)
+                fs_1.default.unlinkSync(zipPath);
+            if (hasDir)
+                fs_1.default.rmSync(dirPath, { recursive: true, force: true });
+            process.stderr.write(`[admin] Deleted backup ${backupId}\n`);
+            return { success: true, message: `Backup ${backupId} deleted`, removed: true };
+        }
+        catch (error) {
+            return { success: false, message: `Delete failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    /** Prune backups keeping newest N (by createdAt / mtime). Returns count pruned. */
+    pruneBackups(retain) {
+        try {
+            if (retain < 0)
+                return { success: false, message: 'retain must be >= 0' };
+            const backupRoot = this.backupRoot;
+            if (!fs_1.default.existsSync(backupRoot))
+                return { success: true, message: 'No backups to prune', pruned: 0 };
+            const entries = fs_1.default.readdirSync(backupRoot)
+                .map(name => {
+                const full = path_1.default.join(backupRoot, name);
+                // Derive the logical ID (strip .zip extension)
+                const id = name.endsWith('.zip') ? name.replace(/\.zip$/i, '') : name;
+                return { name, id, full };
+            })
+                .filter(d => {
+                try {
+                    const stat = fs_1.default.statSync(d.full);
+                    if (d.name.endsWith('.zip') && stat.isFile())
+                        return /^backup_|^instructions-|^pre_restore_|^auto-backup-/.test(d.id);
+                    if (stat.isDirectory())
+                        return /^backup_|^instructions-|^pre_restore_|^auto-backup-/.test(d.id);
+                    return false;
+                }
+                catch {
+                    return false;
+                }
+            });
+            // sort newest first by mtime
+            entries.sort((a, b) => {
+                try {
+                    return fs_1.default.statSync(b.full).mtime.getTime() - fs_1.default.statSync(a.full).mtime.getTime();
+                }
+                catch {
+                    return 0;
+                }
+            });
+            if (retain === 0) {
+                let prunedAll = 0;
+                for (const d of entries) {
+                    try {
+                        if (d.name.endsWith('.zip'))
+                            fs_1.default.unlinkSync(d.full);
+                        else
+                            fs_1.default.rmSync(d.full, { recursive: true, force: true });
+                        prunedAll++;
+                    }
+                    catch { /* ignore */ }
+                }
+                process.stderr.write(`[admin] Pruned all backups (${prunedAll})\n`);
+                return { success: true, message: `Pruned ${prunedAll} backups`, pruned: prunedAll };
+            }
+            const toDelete = entries.slice(retain);
+            let pruned = 0;
+            for (const d of toDelete) {
+                try {
+                    if (d.name.endsWith('.zip'))
+                        fs_1.default.unlinkSync(d.full);
+                    else
+                        fs_1.default.rmSync(d.full, { recursive: true, force: true });
+                    pruned++;
+                }
+                catch { /* ignore */ }
+            }
+            process.stderr.write(`[admin] Pruned ${pruned} backup(s); retained ${entries.length - pruned}\n`);
+            return { success: true, message: `Pruned ${pruned} backups (retained ${entries.length - pruned})`, pruned };
+        }
+        catch (error) {
+            return { success: false, message: `Prune failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    /** Export a backup — returns the zip file path for streaming, or falls back to JSON bundle for legacy dirs */
+    exportBackup(backupId) {
+        try {
+            if (!backupId)
+                return { success: false, message: 'backupId required' };
+            const zipPath = path_1.default.join(this.backupRoot, `${backupId}.zip`);
+            if (fs_1.default.existsSync(zipPath) && fs_1.default.statSync(zipPath).isFile()) {
+                return { success: true, message: 'Export ready', zipPath };
+            }
+            // Legacy directory fallback
+            const backupDir = path_1.default.join(this.backupRoot, backupId);
+            if (!fs_1.default.existsSync(backupDir) || !fs_1.default.statSync(backupDir).isDirectory())
+                return { success: false, message: `Backup not found: ${backupId}` };
+            let manifest = {};
+            const manifestPath = path_1.default.join(backupDir, 'manifest.json');
+            if (fs_1.default.existsSync(manifestPath)) {
+                try {
+                    manifest = JSON.parse(fs_1.default.readFileSync(manifestPath, 'utf-8'));
+                }
+                catch { /* ignore */ }
+            }
+            const files = {};
+            for (const f of fs_1.default.readdirSync(backupDir)) {
+                if (f.toLowerCase().endsWith('.json') && f !== 'manifest.json') {
+                    try {
+                        files[f] = JSON.parse(fs_1.default.readFileSync(path_1.default.join(backupDir, f), 'utf-8'));
+                    }
+                    catch { /* skip corrupt */ }
+                }
+            }
+            return { success: true, message: 'Export ready', bundle: { manifest, files } };
+        }
+        catch (error) {
+            return { success: false, message: `Export failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    /** Import a backup from a JSON bundle uploaded by the client — creates a zip */
+    importBackup(bundle) {
+        try {
+            if (!bundle || typeof bundle !== 'object' || !bundle.files || typeof bundle.files !== 'object') {
+                return { success: false, message: 'Invalid bundle: must contain a "files" object' };
+            }
+            const now = new Date();
+            const baseTs = now.toISOString().replace(/[-:]/g, '').replace(/\..+/, '');
+            const ms = String(now.getMilliseconds()).padStart(3, '0');
+            const backupId = `backup_${baseTs}_${ms}`;
+            const zipPath = path_1.default.join(this.backupRoot, `${backupId}.zip`);
+            if (!fs_1.default.existsSync(this.backupRoot))
+                fs_1.default.mkdirSync(this.backupRoot, { recursive: true });
+            const zip = new adm_zip_1.default();
+            let written = 0;
+            for (const [name, content] of Object.entries(bundle.files)) {
+                if (typeof name !== 'string' || !name.toLowerCase().endsWith('.json'))
+                    continue;
+                const safeName = path_1.default.basename(name);
+                if (safeName !== name || safeName.includes('..'))
+                    continue; // path traversal guard
+                zip.addFile(safeName, Buffer.from(JSON.stringify(content, null, 2)));
+                written++;
+            }
+            const manifest = {
+                backupId,
+                createdAt: now.toISOString(),
+                instructionCount: written,
+                schemaVersion: bundle.manifest?.schemaVersion || 'imported',
+                source: 'file-import',
+            };
+            zip.addFile('manifest.json', Buffer.from(JSON.stringify(manifest, null, 2)));
+            zip.writeZip(zipPath);
+            process.stderr.write(`[admin] Imported backup from file: ${backupId}.zip (${written} files)\n`);
+            return { success: true, message: `Imported ${written} files as ${backupId}`, backupId, files: written };
+        }
+        catch (error) {
+            return { success: false, message: `Import failed: ${error instanceof Error ? error.message : String(error)}` };
+        }
+    }
+    /**
+     * Calculate current CPU usage with historical tracking
+     */
+    calculateCpuUsage() {
+        const currentCpuUsage = process.cpuUsage();
+        let cpuPercent = 0;
+        let userTime = 0;
+        let systemTime = 0;
+        if (this.lastCpuUsage) {
+            // Calculate delta since last measurement
+            const userDelta = currentCpuUsage.user - this.lastCpuUsage.user;
+            const systemDelta = currentCpuUsage.system - this.lastCpuUsage.system;
+            const totalDelta = userDelta + systemDelta;
+            // Convert microseconds to percentage (assuming 1 second interval)
+            // For more accurate results, you'd want to track the actual time interval
+            cpuPercent = Math.min((totalDelta / 1000000) * 100, 100);
+            userTime = userDelta / 1000000; // Convert to seconds
+            systemTime = systemDelta / 1000000; // Convert to seconds
+        }
+        this.lastCpuUsage = currentCpuUsage;
+        // Add to history for leak detection
+        const historyEntry = {
+            timestamp: Date.now(),
+            user: userTime,
+            system: systemTime,
+            percent: cpuPercent
+        };
+        this.cpuHistory.push(historyEntry);
+        // Keep only recent entries
+        if (this.cpuHistory.length > this.maxCpuHistoryEntries) {
+            this.cpuHistory.shift();
+        }
+        return {
+            user: userTime,
+            system: systemTime,
+            percent: cpuPercent
+        };
+    }
+    /**
+     * Analyze CPU trends for potential leaks
+     */
+    analyzeCpuTrends() {
+        if (this.cpuHistory.length < 10) {
+            return { trend: 'stable', avgUsage: 0, peakUsage: 0 };
+        }
+        const recent = this.cpuHistory.slice(-10);
+        const avgUsage = recent.reduce((sum, entry) => sum + entry.percent, 0) / recent.length;
+        const peakUsage = Math.max(...recent.map(entry => entry.percent));
+        // Simple trend analysis - compare first half vs second half
+        const firstHalf = recent.slice(0, 5);
+        const secondHalf = recent.slice(5);
+        const firstAvg = firstHalf.reduce((sum, entry) => sum + entry.percent, 0) / firstHalf.length;
+        const secondAvg = secondHalf.reduce((sum, entry) => sum + entry.percent, 0) / secondHalf.length;
+        let trend = 'stable';
+        const difference = secondAvg - firstAvg;
+        if (Math.abs(difference) > 5) {
+            trend = difference > 0 ? 'increasing' : 'decreasing';
+        }
+        return { trend, avgUsage, peakUsage };
+    }
+    /**
+     * Analyze memory usage trends for leak detection
+     */
+    analyzeMemoryTrends() {
+        if (this.memoryHistory.length < 10) {
+            return { trend: 'stable', avgHeapUsed: 0, peakHeapUsed: 0, growthRate: 0 };
+        }
+        const recent = this.memoryHistory.slice(-10);
+        const avgHeapUsed = recent.reduce((sum, entry) => sum + entry.heapUsed, 0) / recent.length;
+        const peakHeapUsed = Math.max(...recent.map(entry => entry.heapUsed));
+        // Calculate growth rate (bytes per minute)
+        const firstEntry = recent[0];
+        const lastEntry = recent[recent.length - 1];
+        const timeDiffMinutes = (lastEntry.timestamp - firstEntry.timestamp) / (1000 * 60);
+        const growthRate = timeDiffMinutes > 0 ? (lastEntry.heapUsed - firstEntry.heapUsed) / timeDiffMinutes : 0;
+        // Simple trend analysis - compare first half vs second half
+        const firstHalf = recent.slice(0, 5);
+        const secondHalf = recent.slice(5);
+        const firstAvg = firstHalf.reduce((sum, entry) => sum + entry.heapUsed, 0) / firstHalf.length;
+        const secondAvg = secondHalf.reduce((sum, entry) => sum + entry.heapUsed, 0) / secondHalf.length;
+        let trend = 'stable';
+        const difference = secondAvg - firstAvg;
+        // Consider memory leak if growth is > 10MB or growth rate > 1MB/min
+        if (Math.abs(difference) > 10 * 1024 * 1024 || Math.abs(growthRate) > 1024 * 1024) {
+            trend = difference > 0 ? 'increasing' : 'decreasing';
+        }
+        return { trend, avgHeapUsed, peakHeapUsed, growthRate };
+    }
+    /**
+     * Get comprehensive admin statistics
+     */
+    getAdminStats() {
+        // Use real metrics snapshot (deterministic values)
+        const collector = (0, MetricsCollector_1.getMetricsCollector)();
+        const snapshot = collector.getCurrentSnapshot();
+        // Aggregate total requests from tool metrics
+        let totalRequests = 0;
+        Object.values(snapshot.tools).forEach(t => { totalRequests += t.callCount; });
+        // Get index validation summary for accurate accepted vs raw counts
+        let accepted = 0, scanned = 0, skipped = 0;
+        try {
+            const st = (0, indexContext_1.getIndexState)();
+            if (st.loadSummary) {
+                accepted = st.loadSummary.accepted;
+                scanned = st.loadSummary.scanned;
+                skipped = st.loadSummary.skipped;
+            }
+            else {
+                accepted = st.list.length;
+                scanned = st.loadDebug?.scanned ?? accepted;
+                skipped = Math.max(0, scanned - accepted);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        // Count physical *.json files (raw) deterministically from FS (may equal scanned; retained for transparency)
+        const indexDir = this.instructionsRoot;
+        let rawFileCount = scanned; // default to scanned
+        try {
+            if (fs_1.default.existsSync(indexDir)) {
+                rawFileCount = fs_1.default.readdirSync(indexDir).filter(f => f.toLowerCase().endsWith('.json')).length;
+            }
+        }
+        catch { /* ignore */ }
+        // Recompute schema version snapshot only when any of these counts change
+        const cacheNeedsUpdate = !this.indexStatsCache || this.indexStatsCache.acceptedInstructions !== accepted || this.indexStatsCache.rawFileCount !== rawFileCount || this.indexStatsCache.skippedInstructions !== skipped;
+        if (cacheNeedsUpdate) {
+            const schemaVersions = new Set();
+            try {
+                if (fs_1.default.existsSync(indexDir)) {
+                    const files = fs_1.default.readdirSync(indexDir).filter(f => f.toLowerCase().endsWith('.json')).slice(0, 200); // cap scan
+                    for (const f of files) {
+                        try {
+                            const raw = fs_1.default.readFileSync(path_1.default.join(indexDir, f), 'utf-8');
+                            const json = JSON.parse(raw);
+                            if (typeof json.schemaVersion === 'string')
+                                schemaVersions.add(json.schemaVersion);
+                        }
+                        catch { /* ignore parse */ }
+                    }
+                }
+            }
+            catch { /* ignore */ }
+            const schemaVersion = schemaVersions.size === 0 ? 'unknown' : (schemaVersions.size === 1 ? Array.from(schemaVersions)[0] : `mixed(${Array.from(schemaVersions).join(',')})`);
+            this.indexStatsCache = {
+                totalInstructions: accepted, // maintain backward compatibility; semantic now accepted
+                acceptedInstructions: accepted,
+                rawFileCount,
+                skippedInstructions: skipped,
+                lastUpdated: new Date(),
+                version: snapshot.server.version,
+                schemaVersion
+            };
+        }
+        const memUsage = snapshot.server.memoryUsage; // already captured in snapshot
+        const cpuUsage = this.calculateCpuUsage(); // Calculate current CPU usage
+        // Ensure cache populated (should be by logic above, but safeguard for strict types)
+        if (!this.indexStatsCache) {
+            this.indexStatsCache = {
+                totalInstructions: accepted,
+                acceptedInstructions: accepted,
+                rawFileCount,
+                skippedInstructions: skipped,
+                lastUpdated: new Date(),
+                version: snapshot.server.version,
+                schemaVersion: 'unknown'
+            };
+        }
+        return {
+            // Total historical websocket connections (connected + disconnected)
+            totalConnections: snapshot.connections.totalConnections,
+            // Active websocket connections (live WS clients). Previously this returned only admin sessions size,
+            // which caused the UI to show 0 even when multiple WS clients were connected. This now reflects
+            // real-time active websocket connections from metrics.
+            activeConnections: snapshot.connections.activeConnections,
+            // Preserve visibility into admin (logical) sessions separately.
+            adminActiveSessions: this.panelState.activeSessions.size,
+            totalRequests,
+            errorRate: snapshot.performance.errorRate,
+            avgResponseTime: snapshot.performance.avgResponseTime,
+            uptime: Math.floor(snapshot.server.uptime / 1000), // seconds
+            memoryUsage: {
+                heapUsed: memUsage.heapUsed,
+                heapTotal: memUsage.heapTotal,
+                external: memUsage?.external ?? 0,
+                ...(memUsage?.heapLimit ? { heapLimit: memUsage.heapLimit } : {})
+            },
+            cpuUsage,
+            toolMetrics: snapshot.tools,
+            indexStats: this.indexStatsCache
+        };
+    }
+    updateSystemHealth() {
+        const issues = [];
+        const recommendations = [];
+        // Check memory usage and track history
+        const memUsage = process.memoryUsage();
+        // Use V8 heap_size_limit for percentage -- heapTotal tracks closely
+        // behind heapUsed and would false-alarm at low absolute usage.
+        const v8Stats = v8_1.default.getHeapStatistics();
+        const heapLimit = v8Stats.heap_size_limit || memUsage.heapTotal;
+        const memPercent = (memUsage.heapUsed / heapLimit) * 100;
+        // Track memory history for leak detection
+        this.memoryHistory.push({
+            timestamp: Date.now(),
+            heapUsed: memUsage.heapUsed,
+            heapTotal: memUsage.heapTotal,
+            external: memUsage.external,
+            rss: memUsage.rss
+        });
+        // Maintain memory history buffer
+        if (this.memoryHistory.length > this.maxMemoryHistoryEntries) {
+            this.memoryHistory.shift();
+        }
+        if (memPercent > 80) {
+            issues.push('High memory usage detected');
+            recommendations.push('Consider restarting the server or increasing memory limits');
+        }
+        // Check memory trends for leak detection
+        const memoryTrends = this.analyzeMemoryTrends();
+        if (memoryTrends.trend === 'increasing' && memoryTrends.growthRate > 1024 * 1024) {
+            issues.push('Memory leak detected - heap growing consistently');
+            recommendations.push('Investigate memory usage patterns and potential leaks');
+        }
+        if (memoryTrends.growthRate > 5 * 1024 * 1024) { // > 5MB/min growth
+            issues.push('Rapid memory growth detected');
+            recommendations.push('Monitor memory usage closely and consider restart if growth continues');
+        }
+        // Check CPU usage and trends
+        const cpuTrends = this.analyzeCpuTrends();
+        if (cpuTrends.avgUsage > 80) {
+            issues.push('High CPU usage detected');
+            recommendations.push('Review server load and consider scaling');
+        }
+        if (cpuTrends.trend === 'increasing' && cpuTrends.avgUsage > 50) {
+            issues.push('CPU usage trend increasing');
+            recommendations.push('Monitor for potential CPU leaks or resource contention');
+        }
+        if (cpuTrends.peakUsage > 95) {
+            issues.push('CPU usage spikes detected');
+            recommendations.push('Investigate CPU-intensive operations');
+        }
+        // Check uptime (regression & long-running)
+        const currentUptimeSeconds = Math.floor(process.uptime());
+        const uptimeHours = currentUptimeSeconds / 3600;
+        if (this.lastUptimeSeconds > 0 && currentUptimeSeconds < this.lastUptimeSeconds) {
+            // Uptime decreased => restart/regression
+            issues.push('Uptime regression detected (server restart)');
+            recommendations.push('Review restart reason and ensure intentional');
+        }
+        else if (uptimeHours > 72) {
+            recommendations.push('Consider scheduled restart for optimal performance');
+        }
+        this.lastUptimeSeconds = currentUptimeSeconds;
+        // Check error rate
+        const errorRate = this.getErrorRate();
+        if (errorRate > 5) {
+            issues.push('Elevated error rate detected');
+            recommendations.push('Review error logs and investigate root causes');
+        }
+        // Determine overall health status
+        let status = 'healthy';
+        if (issues.length > 0) {
+            status = (memPercent > 90 || errorRate > 10 || cpuTrends.avgUsage > 90 || memoryTrends.growthRate > 10 * 1024 * 1024) ? 'critical' : 'warning';
+        }
+        this.maintenanceInfo.systemHealth = {
+            status,
+            issues,
+            recommendations,
+            cpuTrend: cpuTrends.trend,
+            memoryTrend: memoryTrends.trend,
+            memoryGrowthRate: memoryTrends.growthRate
+        };
+    }
+    /** Return immutable copy of session history */
+    getSessionHistory(limit) {
+        return this.panelState.getSessionHistory(limit);
+    }
+    async clearSessionHistory() {
+        return this.panelState.clearSessionHistory();
+    }
+    updateSessionActivity(sessionId) {
+        return this.panelState.updateSessionActivity(sessionId);
+    }
+    getTotalConnections() {
+        return (0, MetricsCollector_1.getMetricsCollector)().getCurrentSnapshot().connections.totalConnections;
+    }
+    getTotalRequests() {
+        const snap = (0, MetricsCollector_1.getMetricsCollector)().getCurrentSnapshot();
+        return Object.values(snap.tools).reduce((sum, t) => sum + t.callCount, 0);
+    }
+    getErrorRate() {
+        return (0, MetricsCollector_1.getMetricsCollector)().getCurrentSnapshot().performance.errorRate;
+    }
+    getAvgResponseTime() {
+        return (0, MetricsCollector_1.getMetricsCollector)().getCurrentSnapshot().performance.avgResponseTime;
+    }
+    getIndexInstructionCount() {
+        const indexDir = this.instructionsRoot;
+        try {
+            if (fs_1.default.existsSync(indexDir)) {
+                return fs_1.default.readdirSync(indexDir).filter(f => f.toLowerCase().endsWith('.json')).length;
+            }
+        }
+        catch {
+            // ignore
+        }
+        return 0;
+    }
+    /**
+     * Restart server components
+     */
+    async restartServer(component = 'all') {
+        try {
+            process.stderr.write(`[admin] Restart requested for component: ${component}\n`);
+            // In real implementation, this would perform actual component restarts
+            await new Promise(resolve => setTimeout(resolve, 2000));
+            return {
+                success: true,
+                message: `${component} restart completed successfully`
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Restart failed: ${error instanceof Error ? error.message : String(error)}`
+            };
+        }
+    }
+    /**
+     * Clear server caches
+     */
+    clearCaches() {
+        try {
+            const cleared = [];
+            // Clear instruction cache
+            cleared.push('instruction_cache');
+            // Clear metrics cache
+            cleared.push('metrics_cache');
+            // Clear response cache
+            cleared.push('response_cache');
+            process.stderr.write(`[admin] Caches cleared: ${cleared.join(', ')}\n`);
+            return {
+                success: true,
+                message: 'All caches cleared successfully',
+                cleared
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                message: `Failed to clear caches: ${error instanceof Error ? error.message : String(error)}`,
+                cleared: []
+            };
+        }
+    }
+}
+exports.AdminPanel = AdminPanel;
+// Singleton instance
+let adminPanelInstance = null;
+function getAdminPanel() {
+    if (!adminPanelInstance) {
+        adminPanelInstance = new AdminPanel();
+    }
+    return adminPanelInstance;
+}