@runtimescope/mcp-server 0.6.2 → 0.7.1

package/dist/index.js

@@ -5,6 +5,7 @@ import { execSync as execSync2 } from "child_process";
 import { existsSync as existsSync2 } from "fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { join as join2 } from "path";
 import {
   CollectorServer,
   ProjectManager,
@@ -17,9 +18,12 @@ import {
   SessionManager,
   HttpServer,
   SqliteStore,
+  isSqliteAvailable,
   AuthManager,
   Redactor,
-  resolveTlsConfig
+  resolveTlsConfig,
+  PmStore,
+  ProjectDiscovery
 } from "@runtimescope/collector";
 
 // src/tools/network.ts
@@ -224,7 +228,7 @@ function registerIssueTools(server, store, apiDiscovery, processMonitor) {
       const allIssues = [...detectIssues(events)];
       if (apiDiscovery) {
         try {
-          allIssues.push(...apiDiscovery.detectIssues(events));
+          allIssues.push(...apiDiscovery.detectIssues());
         } catch {
         }
       }
@@ -290,7 +294,7 @@ function registerTimelineTools(server, store) {
     "Get a chronological view of ALL events (network requests, console messages) interleaved by timestamp. Essential for understanding causal chains \u2014 e.g. seeing that an API call failed, then an error was logged, then another retry fired. Events are in chronological order (oldest first).",
     {
       since_seconds: z4.number().optional().describe("Only return events from the last N seconds (default: 60)"),
-      event_types: z4.array(z4.enum(["network", "console", "session", "state", "render", "performance", "dom_snapshot", "database"])).optional().describe("Filter by event types (default: all)"),
+      event_types: z4.array(z4.enum(["network", "console", "session", "state", "render", "performance", "dom_snapshot", "database", "custom"])).optional().describe("Filter by event types (default: all)"),
       limit: z4.number().optional().describe("Max events to return (default: 200, max: 1000)")
     },
     async ({ since_seconds, event_types, limit }) => {
@@ -413,6 +417,14 @@ function formatTimelineEvent(event) {
         error: de.error ?? null
       };
     }
+    case "custom": {
+      const ce = event;
+      return {
+        ...base,
+        name: ce.name,
+        properties: ce.properties ?? null
+      };
+    }
     default:
       return base;
   }
@@ -1963,34 +1975,160 @@ function registerInfraTools(server, infraConnector) {
 // src/tools/session-diff.ts
 import { z as z15 } from "zod";
 import { compareSessions } from "@runtimescope/collector";
-function registerSessionDiffTools(server, sessionManager) {
+function registerSessionDiffTools(server, sessionManager, collector) {
+  server.tool(
+    "create_session_snapshot",
+    "Capture a point-in-time snapshot of a live or recent session. Use before/after code changes to compare how your app behaves at different moments. Each session can have multiple snapshots.",
+    {
+      session_id: z15.string().optional().describe("Session ID (defaults to first active session)"),
+      label: z15.string().optional().describe('Label for this snapshot (e.g., "before-fix", "baseline", "after-deploy")'),
+      project: z15.string().optional().describe("Project name")
+    },
+    async ({ session_id, label, project }) => {
+      const sessionId = session_id ?? collector.getFirstSessionId();
+      if (!sessionId) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({
+            summary: "No active session found. Connect an SDK first.",
+            data: null,
+            issues: ["No active sessions \u2014 connect an SDK with RuntimeScope.init()"],
+            metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null }
+          }, null, 2) }]
+        };
+      }
+      const projectName = project ?? collector.getProjectForSession(sessionId) ?? "default";
+      const snapshot = sessionManager.createSnapshot(sessionId, projectName, label);
+      const response = {
+        summary: `Snapshot captured for session ${sessionId.slice(0, 8)}${label ? ` (label: "${label}")` : ""}. ${snapshot.metrics.totalEvents} events, ${snapshot.metrics.errorCount} errors.`,
+        data: {
+          sessionId: snapshot.sessionId,
+          project: snapshot.project,
+          label: snapshot.label ?? null,
+          createdAt: new Date(snapshot.createdAt).toISOString(),
+          metrics: {
+            totalEvents: snapshot.metrics.totalEvents,
+            errorCount: snapshot.metrics.errorCount,
+            endpointCount: Object.keys(snapshot.metrics.endpoints).length,
+            componentCount: Object.keys(snapshot.metrics.components).length,
+            storeCount: Object.keys(snapshot.metrics.stores).length,
+            webVitalCount: Object.keys(snapshot.metrics.webVitals).length,
+            queryCount: Object.keys(snapshot.metrics.queries).length
+          }
+        },
+        issues: [],
+        metadata: {
+          timeRange: { from: snapshot.metrics.connectedAt, to: snapshot.metrics.disconnectedAt },
+          eventCount: snapshot.metrics.totalEvents,
+          sessionId: snapshot.sessionId
+        }
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+      };
+    }
+  );
+  server.tool(
+    "get_session_snapshots",
+    "List all snapshots for a session. Use with compare_sessions to track how your app changed over time within a single session.",
+    {
+      session_id: z15.string().describe("Session ID"),
+      project: z15.string().optional().describe("Project name")
+    },
+    async ({ session_id, project }) => {
+      const projectName = project ?? collector.getProjectForSession(session_id) ?? "default";
+      const snapshots = sessionManager.getSessionSnapshots(projectName, session_id);
+      const response = {
+        summary: `${snapshots.length} snapshot(s) for session ${session_id.slice(0, 8)}.`,
+        data: snapshots.map((s) => ({
+          id: s.id,
+          sessionId: s.sessionId,
+          label: s.label ?? null,
+          createdAt: new Date(s.createdAt).toISOString(),
+          totalEvents: s.metrics.totalEvents,
+          errorCount: s.metrics.errorCount,
+          endpointCount: Object.keys(s.metrics.endpoints).length,
+          componentCount: Object.keys(s.metrics.components).length
+        })),
+        issues: [],
+        metadata: {
+          timeRange: snapshots.length > 0 ? { from: snapshots[0].createdAt, to: snapshots[snapshots.length - 1].createdAt } : { from: 0, to: 0 },
+          eventCount: snapshots.length,
+          sessionId: session_id
+        }
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+      };
+    }
+  );
   server.tool(
     "compare_sessions",
-    "Compare two sessions: render counts, API latency, errors, Web Vitals, and query performance. Shows regressions and improvements.",
+    "Compare two sessions or two snapshots: render counts, API latency, errors, Web Vitals, and query performance. Shows regressions and improvements. Use snapshot_a/snapshot_b to compare specific snapshots within or across sessions.",
     {
-      session_a: z15.string().describe("First session ID (baseline)"),
-      session_b: z15.string().describe("Second session ID (comparison)"),
+      session_a: z15.string().optional().describe("First session ID (baseline) \u2014 used when comparing sessions"),
+      session_b: z15.string().optional().describe("Second session ID (comparison) \u2014 used when comparing sessions"),
+      snapshot_a: z15.number().optional().describe("First snapshot ID (baseline) \u2014 used when comparing snapshots"),
+      snapshot_b: z15.number().optional().describe("Second snapshot ID (comparison) \u2014 used when comparing snapshots"),
       project: z15.string().optional().describe("Project name")
     },
-    async ({ session_a, session_b, project }) => {
+    async ({ session_a, session_b, snapshot_a, snapshot_b, project }) => {
       const projectName = project ?? "default";
-      const history = sessionManager.getSessionHistory(projectName, 100);
-      const snapshotA = history.find((s) => s.sessionId === session_a);
-      const snapshotB = history.find((s) => s.sessionId === session_b);
-      if (!snapshotA || !snapshotB) {
+      let metricsA = null;
+      let metricsB = null;
+      let labelA = "";
+      let labelB = "";
+      if (snapshot_a != null && snapshot_b != null) {
+        const snapA = sessionManager.getSnapshotById(projectName, snapshot_a);
+        const snapB = sessionManager.getSnapshotById(projectName, snapshot_b);
+        if (!snapA || !snapB) {
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              summary: "Could not find one or both snapshots.",
+              data: null,
+              issues: [
+                !snapA ? `Snapshot ${snapshot_a} not found` : null,
+                !snapB ? `Snapshot ${snapshot_b} not found` : null
+              ].filter(Boolean),
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null }
+            }, null, 2) }]
+          };
+        }
+        metricsA = snapA.metrics;
+        metricsB = snapB.metrics;
+        labelA = snapA.label ? ` (${snapA.label})` : ` (snapshot #${snapshot_a})`;
+        labelB = snapB.label ? ` (${snapB.label})` : ` (snapshot #${snapshot_b})`;
+      } else if (session_a && session_b) {
+        const history = sessionManager.getSessionHistory(projectName, 100);
+        const snapshotA = history.find((s) => s.sessionId === session_a);
+        const snapshotB = history.find((s) => s.sessionId === session_b);
+        if (!snapshotA || !snapshotB) {
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              summary: "Could not find one or both sessions in history.",
+              data: null,
+              issues: [
+                !snapshotA ? `Session ${session_a} not found` : null,
+                !snapshotB ? `Session ${session_b} not found` : null
+              ].filter(Boolean),
+              metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null }
+            }, null, 2) }]
+          };
+        }
+        metricsA = snapshotA.metrics;
+        metricsB = snapshotB.metrics;
+        labelA = ` (session ${session_a.slice(0, 8)})`;
+        labelB = ` (session ${session_b.slice(0, 8)})`;
+      } else {
         return {
           content: [{ type: "text", text: JSON.stringify({
-            summary: "Could not find one or both sessions in history.",
+            summary: "Provide either session_a + session_b or snapshot_a + snapshot_b.",
             data: null,
-            issues: [
-              !snapshotA ? `Session ${session_a} not found` : null,
-              !snapshotB ? `Session ${session_b} not found` : null
-            ].filter(Boolean),
+            issues: ["Must provide either two session IDs or two snapshot IDs to compare."],
             metadata: { timeRange: { from: 0, to: 0 }, eventCount: 0, sessionId: null }
           }, null, 2) }]
         };
       }
-      const diff = compareSessions(snapshotA.metrics, snapshotB.metrics);
+      const diff = compareSessions(metricsA, metricsB);
       const regressions = [
         ...diff.endpointDeltas.filter((d) => d.classification === "regression"),
         ...diff.componentDeltas.filter((d) => d.classification === "regression"),
@@ -2004,7 +2142,7 @@ function registerSessionDiffTools(server, sessionManager) {
         ...diff.queryDeltas.filter((d) => d.classification === "improvement")
       ];
       const response = {
-        summary: `Session comparison: ${regressions.length} regression(s), ${improvements.length} improvement(s). Error delta: ${diff.overallDelta.errorCountDelta >= 0 ? "+" : ""}${diff.overallDelta.errorCountDelta}.`,
+        summary: `Comparison${labelA} vs${labelB}: ${regressions.length} regression(s), ${improvements.length} improvement(s). Error delta: ${diff.overallDelta.errorCountDelta >= 0 ? "+" : ""}${diff.overallDelta.errorCountDelta}.`,
         data: {
           endpointDeltas: diff.endpointDeltas.map((d) => ({
             ...d,
@@ -2030,7 +2168,7 @@ function registerSessionDiffTools(server, sessionManager) {
         },
         issues: regressions.map((r) => `Regression: ${r.key} (${(r.percentChange * 100).toFixed(1)}% worse)`),
         metadata: {
-          timeRange: { from: snapshotA.createdAt, to: snapshotB.createdAt },
+          timeRange: { from: metricsA.connectedAt, to: metricsB.disconnectedAt },
           eventCount: 2,
           sessionId: null
         }
@@ -4353,8 +4491,241 @@ RuntimeScope.init({
   );
 }
 
-// src/tools/history.ts
+// src/tools/custom-events.ts
 import { z as z26 } from "zod";
+function registerCustomEventTools(server, store) {
+  server.tool(
+    "get_custom_events",
+    "Get custom business/product events tracked via RuntimeScope.track(). Shows event catalog (all unique event names with counts) and recent occurrences. Use this to see what events are being tracked and their frequency.",
+    {
+      name: z26.string().optional().describe("Filter by event name (exact match)"),
+      since_seconds: z26.number().optional().describe("Only events from the last N seconds (default: 300)"),
+      session_id: z26.string().optional().describe("Filter by session ID")
+    },
+    async ({ name, since_seconds, session_id }) => {
+      const sinceSeconds = since_seconds ?? 300;
+      const events = store.getCustomEvents({
+        name,
+        sinceSeconds,
+        sessionId: session_id
+      });
+      const catalog = {};
+      for (const e of events) {
+        if (!catalog[e.name]) {
+          catalog[e.name] = { count: 0, lastSeen: 0, sampleProperties: void 0 };
+        }
+        catalog[e.name].count++;
+        if (e.timestamp > catalog[e.name].lastSeen) {
+          catalog[e.name].lastSeen = e.timestamp;
+          catalog[e.name].sampleProperties = e.properties;
+        }
+      }
+      const catalogList = Object.entries(catalog).sort((a, b) => b[1].lastSeen - a[1].lastSeen).map(([eventName, info]) => ({
+        name: eventName,
+        count: info.count,
+        lastSeen: new Date(info.lastSeen).toISOString(),
+        sampleProperties: info.sampleProperties
+      }));
+      const sessions = store.getSessionInfo();
+      const sessionId = session_id ?? sessions[0]?.sessionId ?? null;
+      const response = {
+        summary: `${events.length} custom event(s) across ${catalogList.length} unique event name(s) in the last ${sinceSeconds}s.${name ? ` Filtered by: "${name}".` : ""}`,
+        data: {
+          catalog: catalogList,
+          recentEvents: events.slice(0, 100).map((e) => ({
+            name: e.name,
+            timestamp: new Date(e.timestamp).toISOString(),
+            properties: e.properties,
+            sessionId: e.sessionId
+          }))
+        },
+        issues: [],
+        metadata: {
+          timeRange: {
+            from: events.length > 0 ? events[events.length - 1].timestamp : 0,
+            to: events.length > 0 ? events[0].timestamp : 0
+          },
+          eventCount: events.length,
+          sessionId
+        }
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+      };
+    }
+  );
+  server.tool(
+    "get_event_flow",
+    "Analyze a user flow as a funnel. Given an ordered list of custom event names (steps), shows how many sessions completed each step, where drop-offs happen, and what errors/failures occurred between steps. Each step includes correlated telemetry (network errors, console errors, failed DB queries) that happened between the previous step and this one \u2014 this is the key to finding WHY a step failed.",
+    {
+      steps: z26.array(z26.string()).min(2).describe('Ordered list of custom event names representing the flow (e.g. ["create_profile", "generate_campaign", "export_ad"])'),
+      since_seconds: z26.number().optional().describe("Only analyze events from the last N seconds (default: 3600)"),
+      session_id: z26.string().optional().describe("Analyze a specific session (default: all sessions)")
+    },
+    async ({ steps, since_seconds, session_id }) => {
+      const sinceSeconds = since_seconds ?? 3600;
+      const allCustom = store.getCustomEvents({ sinceSeconds, sessionId: session_id });
+      const bySession = /* @__PURE__ */ new Map();
+      for (const e of allCustom) {
+        if (!bySession.has(e.sessionId)) bySession.set(e.sessionId, []);
+        bySession.get(e.sessionId).push(e);
+      }
+      for (const events of bySession.values()) {
+        events.sort((a, b) => a.timestamp - b.timestamp);
+      }
+      const networkErrors = store.getNetworkRequests({ sinceSeconds, sessionId: session_id }).filter((e) => e.status >= 400 || e.errorPhase);
+      const consoleErrors = store.getConsoleMessages({ sinceSeconds, sessionId: session_id }).filter((e) => e.level === "error");
+      const dbErrors = store.getDatabaseEvents({ sinceSeconds, sessionId: session_id }).filter((e) => !!e.error);
+      const stepResults = steps.map(() => ({
+        step: "",
+        sessionsReached: 0,
+        sessionsCompleted: 0,
+        avgTimeFromPrevMs: null,
+        correlatedErrors: { networkErrors: [], consoleErrors: [], dbErrors: [] }
+      }));
+      const totalSessions = bySession.size;
+      const completedFlows = [];
+      for (const [sessionId, sessionEvents] of bySession) {
+        let prevStepTime = null;
+        let completedAll = true;
+        for (let i = 0; i < steps.length; i++) {
+          const stepName = steps[i];
+          stepResults[i].step = stepName;
+          const occurrence = sessionEvents.find(
+            (e) => e.name === stepName && (prevStepTime === null || e.timestamp >= prevStepTime)
+          );
+          if (!occurrence) {
+            completedAll = false;
+            if (prevStepTime !== null) {
+              const gapEnd = sessionEvents[sessionEvents.length - 1]?.timestamp ?? Date.now();
+              collectCorrelatedErrors(stepResults[i], sessionId, prevStepTime, gapEnd, networkErrors, consoleErrors, dbErrors);
+            }
+            break;
+          }
+          stepResults[i].sessionsReached++;
+          if (prevStepTime !== null) {
+            const delta = occurrence.timestamp - prevStepTime;
+            if (stepResults[i].avgTimeFromPrevMs === null) {
+              stepResults[i].avgTimeFromPrevMs = delta;
+            } else {
+              stepResults[i].avgTimeFromPrevMs = (stepResults[i].avgTimeFromPrevMs * (stepResults[i].sessionsReached - 1) + delta) / stepResults[i].sessionsReached;
+            }
+            collectCorrelatedErrors(stepResults[i], sessionId, prevStepTime, occurrence.timestamp, networkErrors, consoleErrors, dbErrors);
+          } else {
+            stepResults[i].sessionsReached++;
+          }
+          stepResults[i].sessionsCompleted++;
+          prevStepTime = occurrence.timestamp;
+        }
+        if (completedAll && prevStepTime !== null) {
+          const firstStep = sessionEvents.find((e) => e.name === steps[0]);
+          if (firstStep) {
+            completedFlows.push({ sessionId, totalDurationMs: prevStepTime - firstStep.timestamp });
+          }
+        }
+      }
+      for (let i = 0; i < stepResults.length; i++) {
+        stepResults[i].step = steps[i];
+      }
+      for (const step of stepResults) {
+        step.correlatedErrors.networkErrors = dedup(step.correlatedErrors.networkErrors, 5);
+        step.correlatedErrors.consoleErrors = dedup(step.correlatedErrors.consoleErrors, 5);
+        step.correlatedErrors.dbErrors = dedup(step.correlatedErrors.dbErrors, 5);
+      }
+      const funnelSteps = stepResults.map((s, i) => ({
+        step: s.step,
+        reached: s.sessionsCompleted,
+        conversionRate: i === 0 ? totalSessions > 0 ? `${(s.sessionsCompleted / totalSessions * 100).toFixed(1)}%` : "0%" : stepResults[i - 1].sessionsCompleted > 0 ? `${(s.sessionsCompleted / stepResults[i - 1].sessionsCompleted * 100).toFixed(1)}%` : "0%",
+        avgTimeFromPrev: s.avgTimeFromPrevMs !== null ? `${Math.round(s.avgTimeFromPrevMs)}ms` : null,
+        errorsBetweenSteps: {
+          network: s.correlatedErrors.networkErrors.length,
+          console: s.correlatedErrors.consoleErrors.length,
+          database: s.correlatedErrors.dbErrors.length
+        },
+        correlatedErrors: s.correlatedErrors
+      }));
+      const avgCompletionTime = completedFlows.length > 0 ? Math.round(completedFlows.reduce((sum, f) => sum + f.totalDurationMs, 0) / completedFlows.length) : null;
+      const issues = [];
+      for (let i = 1; i < funnelSteps.length; i++) {
+        const prev = funnelSteps[i - 1].reached;
+        const curr = funnelSteps[i].reached;
+        if (prev > 0 && curr / prev < 0.5) {
+          issues.push(`Major drop-off at "${steps[i]}": only ${(curr / prev * 100).toFixed(0)}% conversion from "${steps[i - 1]}"`);
+        }
+        const totalErrors = funnelSteps[i].errorsBetweenSteps.network + funnelSteps[i].errorsBetweenSteps.console + funnelSteps[i].errorsBetweenSteps.database;
+        if (totalErrors > 0) {
+          issues.push(`${totalErrors} error(s) detected between "${steps[i - 1]}" and "${steps[i]}"`);
+        }
+      }
+      const response = {
+        summary: `Flow analysis: ${steps.length} steps, ${totalSessions} session(s), ${completedFlows.length} completed the full flow.${avgCompletionTime ? ` Avg completion: ${avgCompletionTime}ms.` : ""}`,
+        data: {
+          totalSessions,
+          completedFlows: completedFlows.length,
+          avgCompletionTimeMs: avgCompletionTime,
+          funnel: funnelSteps
+        },
+        issues,
+        metadata: {
+          timeRange: {
+            from: allCustom.length > 0 ? allCustom[allCustom.length - 1].timestamp : 0,
+            to: allCustom.length > 0 ? allCustom[0].timestamp : 0
+          },
+          eventCount: allCustom.length,
+          sessionId: session_id ?? null
+        }
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(response, null, 2) }]
+      };
+    }
+  );
+}
+function collectCorrelatedErrors(result, sessionId, fromTs, toTs, networkErrors, consoleErrors, dbErrors) {
+  for (const e of networkErrors) {
+    if (e.sessionId === sessionId && e.timestamp >= fromTs && e.timestamp <= toTs) {
+      result.correlatedErrors.networkErrors.push({
+        url: e.url,
+        status: e.status,
+        method: e.method,
+        timestamp: new Date(e.timestamp).toISOString()
+      });
+    }
+  }
+  for (const e of consoleErrors) {
+    if (e.sessionId === sessionId && e.timestamp >= fromTs && e.timestamp <= toTs) {
+      result.correlatedErrors.consoleErrors.push({
+        message: e.message.length > 200 ? e.message.slice(0, 200) + "..." : e.message,
+        timestamp: new Date(e.timestamp).toISOString()
+      });
+    }
+  }
+  for (const e of dbErrors) {
+    if (e.sessionId === sessionId && e.timestamp >= fromTs && e.timestamp <= toTs) {
+      result.correlatedErrors.dbErrors.push({
+        query: e.query.length > 150 ? e.query.slice(0, 150) + "..." : e.query,
+        error: e.error,
+        timestamp: new Date(e.timestamp).toISOString()
+      });
+    }
+  }
+}
+function dedup(arr, limit) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const item of arr) {
+    const key = JSON.stringify(item);
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(item);
+      if (result.length >= limit) break;
+    }
+  }
+  return result;
+}
+
+// src/tools/history.ts
+import { z as z27 } from "zod";
 var EVENT_TYPES = [
   "network",
   "console",
@@ -4393,13 +4764,13 @@ function registerHistoryTools(server, collector, projectManager) {
     "get_historical_events",
     "Query past events from persistent SQLite storage. Use this to access events beyond the in-memory buffer (last 10K events). Events persist across Claude Code restarts. Filter by project, event type, time range, and session.",
     {
-      project: z26.string().describe("Project/app name (the appName used in SDK init)"),
-      event_types: z26.array(z26.enum(EVENT_TYPES)).optional().describe('Filter by event types (e.g., ["network", "console"])'),
-      since: z26.string().optional().describe('Start time \u2014 relative ("2h", "7d", "30m") or ISO date string'),
-      until: z26.string().optional().describe("End time \u2014 relative or ISO date string"),
-      session_id: z26.string().optional().describe("Filter by specific session ID"),
-      limit: z26.number().optional().default(200).describe("Max events to return (default 200, max 1000)"),
-      offset: z26.number().optional().default(0).describe("Pagination offset")
+      project: z27.string().describe("Project/app name (the appName used in SDK init)"),
+      event_types: z27.array(z27.enum(EVENT_TYPES)).optional().describe('Filter by event types (e.g., ["network", "console"])'),
+      since: z27.string().optional().describe('Start time \u2014 relative ("2h", "7d", "30m") or ISO date string'),
+      until: z27.string().optional().describe("End time \u2014 relative or ISO date string"),
+      session_id: z27.string().optional().describe("Filter by specific session ID"),
+      limit: z27.number().optional().default(200).describe("Max events to return (default 200, max 1000)"),
+      offset: z27.number().optional().default(0).describe("Pagination offset")
     },
     async ({ project, event_types, since, until, session_id, limit, offset }) => {
       const sqliteStore = collector.getSqliteStore(project);
@@ -4588,36 +4959,74 @@ async function main() {
   const sessionManager = new SessionManager(projectManager, sqliteStores, store);
   collector.onDisconnect((sessionId, projectName) => {
     try {
-      sessionManager.createSnapshot(sessionId, projectName);
+      sessionManager.createSnapshot(sessionId, projectName, "auto-disconnect");
       console.error(`[RuntimeScope] Session ${sessionId} metrics saved to SQLite`);
     } catch {
     }
   });
-  const RETENTION_DAYS = parseInt(process.env.RUNTIMESCOPE_RETENTION_DAYS ?? "30", 10);
-  const cutoffMs = Date.now() - RETENTION_DAYS * 24 * 60 * 60 * 1e3;
-  for (const projectName of projectManager.listProjects()) {
-    const dbPath = projectManager.getProjectDbPath(projectName);
-    if (existsSync2(dbPath)) {
+  const AUTO_SNAPSHOT_INTERVAL_MS = 5 * 60 * 1e3;
+  let autoSnapshotCount = 0;
+  const autoSnapshotTimer = setInterval(() => {
+    const sessions = collector.getConnectedSessions();
+    if (sessions.length === 0) return;
+    autoSnapshotCount++;
+    const minutes = autoSnapshotCount * 5;
+    for (const { sessionId, projectName } of sessions) {
       try {
-        const tempStore = new SqliteStore({ dbPath });
-        const deleted = tempStore.deleteOldEvents(cutoffMs);
-        if (deleted > 0) {
-          console.error(`[RuntimeScope] Pruned ${deleted} events older than ${RETENTION_DAYS}d from "${projectName}"`);
-        }
-        tempStore.close();
+        sessionManager.createSnapshot(sessionId, projectName, `auto-${minutes}m`);
       } catch {
       }
     }
+  }, AUTO_SNAPSHOT_INTERVAL_MS);
+  if (isSqliteAvailable()) {
+    const RETENTION_DAYS = parseInt(process.env.RUNTIMESCOPE_RETENTION_DAYS ?? "30", 10);
+    const cutoffMs = Date.now() - RETENTION_DAYS * 24 * 60 * 60 * 1e3;
+    for (const projectName of projectManager.listProjects()) {
+      const dbPath = projectManager.getProjectDbPath(projectName);
+      if (existsSync2(dbPath)) {
+        try {
+          const tempStore = new SqliteStore({ dbPath });
+          const deleted = tempStore.deleteOldEvents(cutoffMs);
+          if (deleted > 0) {
+            console.error(`[RuntimeScope] Pruned ${deleted} events older than ${RETENTION_DAYS}d from "${projectName}"`);
+          }
+          tempStore.close();
+        } catch {
+        }
+      }
+    }
+  }
+  let pmStore;
+  let discovery;
+  if (isSqliteAvailable()) {
+    const pmDbPath = join2(projectManager.rootDir, "pm.db");
+    pmStore = new PmStore({ dbPath: pmDbPath });
+    discovery = new ProjectDiscovery(pmStore, projectManager);
+    discovery.discoverAll().then((result) => {
+      console.error(`[RuntimeScope] PM: ${result.projectsDiscovered} projects, ${result.sessionsDiscovered} sessions discovered`);
+    }).catch((err) => {
+      console.error("[RuntimeScope] PM discovery error:", err.message);
+    });
   }
   const httpServer = new HttpServer(store, processMonitor, {
     authManager,
-    allowedOrigins: corsOrigins
+    allowedOrigins: corsOrigins,
+    rateLimiter: collector.getRateLimiter(),
+    pmStore,
+    discovery,
+    getConnectedSessions: () => collector.getConnectedSessions()
   });
   try {
     await httpServer.start({ port: HTTP_PORT2, tls: tlsConfig });
   } catch (err) {
     console.error("[RuntimeScope] HTTP API failed to start:", err.message);
   }
+  collector.onConnect((sessionId, projectName) => {
+    httpServer.broadcastSessionChange("session_connected", sessionId, projectName);
+  });
+  collector.onDisconnect((sessionId, projectName) => {
+    httpServer.broadcastSessionChange("session_disconnected", sessionId, projectName);
+  });
   const scanner = new PlaywrightScanner();
   const mcp = new McpServer({
     name: "runtimescope",
@@ -4638,7 +5047,7 @@ async function main() {
   registerDatabaseTools(mcp, store, connectionManager, schemaIntrospector, dataBrowser);
   registerProcessMonitorTools(mcp, processMonitor);
   registerInfraTools(mcp, infraConnector);
-  registerSessionDiffTools(mcp, sessionManager);
+  registerSessionDiffTools(mcp, sessionManager, collector);
   registerReconMetadataTools(mcp, store, collector);
   registerReconDesignTokenTools(mcp, store, collector);
   registerReconFontTools(mcp, store);
@@ -4649,6 +5058,7 @@ async function main() {
   registerReconAssetTools(mcp, store);
   registerReconStyleDiffTools(mcp, store);
   registerScannerTools(mcp, store, scanner);
+  registerCustomEventTools(mcp, store);
   registerHistoryTools(mcp, collector, projectManager);
   const transport = new StdioServerTransport();
   await mcp.connect(transport);
@@ -4660,11 +5070,13 @@ async function main() {
   const shutdown = async () => {
     if (shuttingDown) return;
     shuttingDown = true;
+    clearInterval(autoSnapshotTimer);
     processMonitor.stop();
     await scanner.shutdown();
     await connectionManager.closeAll();
     await httpServer.stop();
     collector.stop();
+    pmStore?.close();
     process.exit(0);
   };
   process.on("SIGINT", () => {