@cnstra/devtools-server 1.1.1 → 1.2.0

package/dist/index.cjs

@@ -1,998 +1,250 @@
 'use strict';
 
-var http = require('http');
-var fs = require('fs');
-var path = require('path');
-var module$1 = require('module');
-var ws = require('ws');
-
-// src/start.ts
-var _require = module$1.createRequire(path.join(process.cwd(), "package.json"));
-function findPanelUIDir() {
-  try {
-    const pkg = _require.resolve("@cnstra/devtools-panel-ui/package.json");
-    return path.join(path.dirname(pkg), "dist");
-  } catch {
-  }
-  try {
-    const here = path.dirname(_require.resolve("@cnstra/devtools-server/package.json"));
-    const monorepoPath = path.join(here, "..", "..", "devtools-panel-ui", "dist");
-    if (fs.existsSync(path.join(monorepoPath, "index.html"))) return monorepoPath;
-  } catch {
-  }
-  return null;
-}
-function makeCNSAdapter(cns, registry) {
-  return {
-    addResponseListener: (l) => cns.addResponseListener(l),
-    stimulate: (signal, opts) => cns.stimulate(signal, opts),
-    getNeurons: () => [...registry.getNamedNeurons().entries()].map(([name, n]) => ({
-      name,
-      axon: n.axon,
-      dendrites: n.dendrites
-    })),
-    getCollaterals: () => {
-      const out = [];
-      for (const [, n] of registry.getNamedNeurons()) {
-        for (const [key, col] of Object.entries(n.axon)) {
-          out.push({ name: key, createSignal: (p) => col.createSignal(p) });
-        }
-      }
-      return out;
-    }
-  };
-}
-var MIME = {
-  html: "text/html",
-  js: "application/javascript",
-  css: "text/css",
-  svg: "image/svg+xml",
-  png: "image/png",
-  woff2: "font/woff2"
-};
-function serveStatic(panelUIDir) {
-  return (_req, res) => {
-    const url = _req.url ?? "/";
-    const safe = url.split("?")[0].replace(/\.\./g, "");
-    const file = safe === "/" ? "/index.html" : safe;
-    const full = path.join(panelUIDir, file);
-    if (fs.existsSync(full) && full.startsWith(panelUIDir)) {
-      const ext = full.split(".").pop() ?? "";
-      res.writeHead(200, { "Content-Type": MIME[ext] ?? "text/plain" });
-      res.end(fs.readFileSync(full));
-    } else {
-      const idx = path.join(panelUIDir, "index.html");
-      if (fs.existsSync(idx)) {
-        res.writeHead(200, { "Content-Type": "text/html" });
-        res.end(fs.readFileSync(idx));
-      } else {
-        res.writeHead(503);
-        res.end("DevTools UI not built. Run: npm run build --workspace=@cnstra/devtools-panel-ui");
-      }
-    }
-  };
-}
-async function startDevTools(cns, registry, options = {}) {
-  const port = options.port ?? 3141;
-  const appId = options.appId ?? "app";
-  const logEnabled = options.consoleLogEnabled ?? false;
-  const panelUIDir = findPanelUIDir();
-  if (!panelUIDir) {
-    console.warn(
-      "\n\u26A0\uFE0F  CNStra DevTools UI not found.\n   WebSocket server will start but the UI will not be served.\n   Install @cnstra/devtools-panel-ui or build it from the monorepo.\n"
-    );
-  }
-  const httpServer = http.createServer(
-    panelUIDir ? serveStatic(panelUIDir) : (_, res) => {
-      res.writeHead(503);
-      res.end("DevTools UI not available. See console for details.");
-    }
-  );
-  const wss = new ws.WebSocketServer({ server: httpServer });
-  const { CNSDevToolsServerRepositoryInMemory } = await import('@cnstra/devtools-server-repository-in-memory');
-  const dtServer = new CNSDevToolsServer(
-    new CNSDevToolsServerRepositoryInMemory(),
-    { consoleLogEnabled: logEnabled }
-  );
-  const clients = /* @__PURE__ */ new Set();
-  wss.on("connection", (ws$1) => {
-    clients.add(ws$1);
-    ws$1.on("message", async (data) => {
-      try {
-        const msg = JSON.parse(data.toString());
-        const result = await dtServer.handleMessage(ws$1, msg);
-        if (result) {
-          const payload = JSON.stringify(result);
-          clients.forEach((c) => {
-            if (c.readyState === ws.WebSocket.OPEN) c.send(payload);
-          });
-        }
-      } catch {
-      }
-    });
-    ws$1.on("close", () => {
-      clients.delete(ws$1);
-      dtServer.handleDisconnect(ws$1);
-    });
-  });
-  await new Promise((resolve) => httpServer.listen(port, resolve));
-  const url = `http://localhost:${port}`;
-  const { CNSDevTools } = await import('@cnstra/devtools');
-  const { CNSDevToolsTransportWs } = await import('@cnstra/devtools-transport-ws');
-  const transport = new CNSDevToolsTransportWs({
-    url: `ws://localhost:${port}`
-  });
-  const devtools = new CNSDevTools(appId, transport, {
-    devToolsInstanceName: appId,
-    consoleLogEnabled: logEnabled
-  });
-  devtools.registerCNS(makeCNSAdapter(cns, registry), "main");
-  if (logEnabled || process.stdout.isTTY) {
-    console.log(`
-\u{1F9E0} CNStra DevTools: ${url}
-`);
-  }
-  const shouldOpen = options.open ?? process.stdout.isTTY;
-  if (shouldOpen) {
-    const { exec } = await import('child_process');
-    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-    exec(`${cmd} ${url}`);
-  }
-  return {
-    url,
-    stop: () => {
-      wss.close();
-      httpServer.close();
-    }
-  };
-}
+var devtoolsDto = require('@cnstra/devtools-dto');
 
 // src/index.ts
-var CNSDevToolsServer = class _CNSDevToolsServer {
-  constructor(repository, options = {}) {
+var CNSDevToolsServer = class {
+  constructor(repository) {
     this.repository = repository;
-    this.options = options;
-    this.stopped = false;
+    /** WebSocket → appId (for app clients) */
     this.appSockets = /* @__PURE__ */ new Map();
-    this.clientSockets = /* @__PURE__ */ new Set();
-    this.lastInitByApp = /* @__PURE__ */ new Map();
-    this.stimulationBuffer = [];
-    // Track app connection times
-    this.appFirstSeenAt = /* @__PURE__ */ new Map();
-    this.appLastSeenAt = /* @__PURE__ */ new Map();
-    this.replaysByApp = /* @__PURE__ */ new Map();
-    // server metrics sampling
+    /** appId → WebSocket[] (one app may have multiple CNS instances) */
+    this.appWsByAppId = /* @__PURE__ */ new Map();
+    /** WebSocket clients that registered as UI clients */
+    this.uiClients = /* @__PURE__ */ new Set();
     this.lastCpuUsage = process.cpuUsage();
     this.lastCpuTime = Date.now();
   }
-  static sanitizeValue(value, depth = 0, limits = {
-    maxDepth: 5,
-    maxString: 2e3,
-    maxArray: 200,
-    maxObjectKeys: 200
-  }) {
-    if (value === null || value === void 0) return value;
-    if (depth >= limits.maxDepth) return "[MaxDepth]";
-    const t = typeof value;
-    if (t === "string") {
-      const s = value;
-      return s.length > limits.maxString ? s.slice(0, limits.maxString) + `\u2026[+${s.length - limits.maxString}]` : s;
-    }
-    if (t === "number" || t === "boolean" || t === "bigint" || t === "symbol")
-      return value;
-    if (t === "function") return "[Function]";
-    if (value instanceof Error) {
-      return {
-        name: value.name,
-        message: value.message,
-        stack: value.stack
-      };
-    }
-    if (Array.isArray(value)) {
-      const arr = value;
-      const slice = arr.slice(0, limits.maxArray);
-      const mapped = slice.map(
-        (v) => this.sanitizeValue(v, depth + 1, limits)
-      );
-      if (arr.length > slice.length)
-        mapped.push(`[\u2026+${arr.length - slice.length} items]`);
-      return mapped;
+  // ─── Message entry point ─────────────────────────────────────────────────
+  async handleMessage(ws, raw) {
+    if (typeof raw !== "string" && typeof raw !== "object") return;
+    let data;
+    try {
+      data = typeof raw === "string" ? JSON.parse(raw) : raw;
+    } catch {
+      return;
     }
-    if (t === "object") {
-      const out = {};
-      const entries = Object.entries(value);
-      const slice = entries.slice(0, limits.maxObjectKeys);
-      for (const [k, v] of slice) {
-        out[k] = this.sanitizeValue(v, depth + 1, limits);
+    if (!data || typeof data !== "object" || !("type" in data)) return;
+    const type = data.type;
+    if (type === "batch") {
+      const result = devtoolsDto.CNSDTOAppBatchMessageSchema.safeParse(data);
+      if (!result.success) return;
+      for (const item of result.data.items) {
+        await this.handleAppBatchItem(ws, item);
       }
-      if (entries.length > slice.length) {
-        out["\u2026"] = `+${entries.length - slice.length} keys`;
-      }
-      return out;
+      return;
     }
-    return value;
-  }
-  log(...args) {
-    if (this.options.consoleLogEnabled) {
-      console.log(...args);
+    const clientResult = devtoolsDto.CNSDTOClientMessageSchema.safeParse(data);
+    if (!clientResult.success) return;
+    const msg = clientResult.data;
+    switch (msg.type) {
+      case "client.connect":
+        await this.handleClientConnect(ws);
+        break;
+      case "apps.query":
+        await this.handleAppsQuery(ws, msg.requestId);
+        break;
+      case "topology.query":
+        await this.handleTopologyQuery(ws, msg.requestId, msg.cnsId, msg.appId);
+        break;
+      case "stimulations.query":
+        await this.handleStimulationsQuery(ws, msg);
+        break;
+      case "hops.query":
+        await this.handleHopsQuery(ws, msg);
+        break;
+      case "replay.start":
+        await this.handleReplayStart(ws, msg);
+        break;
     }
   }
-  isNeuronResponseMessage(message) {
-    return message !== null && typeof message === "object" && "stimulationId" in message && "neuronId" in message && "appId" in message && "collateralName" in message && "timestamp" in message && typeof message.stimulationId === "string" && typeof message.neuronId === "string" && typeof message.appId === "string" && typeof message.collateralName === "string" && typeof message.timestamp === "number" && !("type" in message);
+  addClient(ws) {
+    this.uiClients.add(ws);
+    if (this.uiClients.size === 1) this.startMetrics();
   }
-  isMessageWithType(message) {
-    return message !== null && typeof message === "object" && "type" in message && typeof message.type === "string";
+  removeClient(ws) {
+    this.uiClients.delete(ws);
+    this.appSockets.delete(ws);
+    if (this.uiClients.size === 0) this.stopMetrics();
   }
-  // Expose sockets map size for tests
-  /** @internal */
-  get connectedAppCount() {
-    return this.appSockets.size;
+  async getActiveApps() {
+    return this.repository.listApps();
   }
-  static applyWindowAndPaginate(items, params) {
-    const { fromTimestamp, toTimestamp } = params;
-    const offset = Math.max(0, params.offset ?? 0);
-    const limit = params.limit !== void 0 && params.limit > 0 ? params.limit : void 0;
-    const filtered = items.filter(
-      (item) => (fromTimestamp === void 0 || item.timestamp >= fromTimestamp) && (toTimestamp === void 0 || item.timestamp <= toTimestamp)
-    ).slice().sort((a, b) => a.timestamp - b.timestamp);
-    if (offset > 0 || limit !== void 0) {
-      return filtered.slice(
-        offset,
-        limit !== void 0 ? offset + limit : void 0
-      );
-    }
-    return filtered;
+  stop() {
+    this.stopMetrics();
   }
-  async handleMessage(ws, message) {
-    if (!this.isMessageWithType(message)) {
-      if (this.options.consoleLogEnabled) {
-        console.warn("Unknown message format:", message);
-      }
-      return null;
-    }
-    switch (message.type) {
-      case "devtools-client-connect":
-        this.log("DevTools client connecting...");
-        this.addClient(ws);
-        if (!this.metricsTimer) {
-          this.startMetricsLoop();
-        }
-        ws.send(JSON.stringify({ type: "devtools-client-connected" }));
-        this.log("DevTools client connected, total clients:", this.clientSockets.size);
-        return { type: "devtools-client-connected" };
-      case "init":
-        return this.handleInit(ws, message);
-      case "batch":
-        return this.handleBatch(
-          ws,
-          message
-        );
-      case "neuron-response-batch":
-      case "response-batch":
-        return this.handleResponseBatch(
-          ws,
-          message
-        );
-      case "stimulate":
-        return this.handleStimulate(ws, message);
-      case "stimulate-accepted":
-        try {
-          const msg = message;
-          const cmdId = msg.stimulationCommandId;
-          const appId = msg.appId;
-          if (cmdId && appId) {
-            const arr = this.replaysByApp.get(appId) || [];
-            for (let i = arr.length - 1; i >= 0; i--) {
-              if (arr[i].stimulationCommandId === cmdId) {
-                arr[i].result = "accepted";
-                break;
-              }
-            }
-            this.replaysByApp.set(appId, arr);
-          }
-        } catch {
-        }
-        return message;
-      case "stimulate-rejected":
-        try {
-          const msg = message;
-          const cmdId = msg.stimulationCommandId;
-          const appId = msg.appId;
-          if (cmdId && appId) {
-            const arr = this.replaysByApp.get(appId) || [];
-            for (let i = arr.length - 1; i >= 0; i--) {
-              if (arr[i].stimulationCommandId === cmdId) {
-                arr[i].result = "rejected";
-                break;
-              }
-            }
-            this.replaysByApp.set(appId, arr);
-          }
-        } catch {
-        }
-        return message;
-      case "stimulation":
-        return this.handleStimulation(
-          ws,
-          message
-        );
-      case "apps:get-topology": {
-        const inits = Array.from(this.lastInitByApp.values());
-        return { type: "apps:topology", inits };
-      }
-      case "apps:get-stimulations": {
-        const msg = message;
-        const {
-          appId,
-          limit,
-          fromTimestamp,
-          toTimestamp,
-          offset,
-          hasError,
-          errorContains,
-          collateralName,
-          neuronId
-        } = msg;
-        let stimulations = [];
-        if (appId) {
-          stimulations = await this.repository.getStimulationsByApp(
-            appId,
-            {
-              fromTimestamp,
-              toTimestamp,
-              limit,
-              offset,
-              hasError,
-              errorContains,
-              collateralName,
-              neuronId
-            }
-          );
-        } else {
-          const apps = await this.repository.listApps();
-          for (const app of apps) {
-            const appStimulations = await this.repository.getStimulationsByApp(
-              app.appId,
-              {
-                fromTimestamp,
-                toTimestamp,
-                limit,
-                offset,
-                hasError,
-                errorContains,
-                collateralName,
-                neuronId
-              }
-            );
-            stimulations = stimulations.concat(appStimulations);
-          }
-          return {
-            type: "stimulation-batch",
-            stimulations
-          };
-        }
-        return {
-          type: "stimulation-batch",
-          stimulations
-        };
-      }
-      case "apps:get-replays": {
-        const msg = message;
-        const { appId, limit, fromTimestamp, toTimestamp, offset } = msg;
-        if (!appId) {
-          return { type: "apps:replays", replays: [] };
-        }
-        let list = this.replaysByApp.get(appId) || [];
-        if (fromTimestamp !== void 0) {
-          list = list.filter((r) => r.timestamp >= fromTimestamp);
-        }
-        if (toTimestamp !== void 0) {
-          list = list.filter((r) => r.timestamp <= toTimestamp);
-        }
-        list = list.sort((a, b) => b.timestamp - a.timestamp);
-        if (offset !== void 0 && offset > 0) {
-          list = list.slice(offset);
-        }
-        if (limit !== void 0 && limit > 0) {
-          list = list.slice(0, limit);
-        }
-        return { type: "apps:replays", appId, replays: list };
-      }
-      // Export endpoints (JSON export over WS)
-      case "apps:export-topology": {
-        const { appId } = message;
-        const inits = Array.from(this.lastInitByApp.values());
-        if (appId) {
-          const filtered = inits.filter((init) => {
-            const baseAppId = init.appId || init.devToolsInstanceId;
-            return baseAppId === appId;
-          });
-          return { type: "apps:topology", inits: filtered };
-        }
-        return { type: "apps:topology", inits };
-      }
-      case "apps:export-stimulations": {
-        const {
-          appId,
-          limit,
-          fromTimestamp,
-          toTimestamp,
-          offset,
-          hasError,
-          errorContains,
-          collateralName,
-          neuronId
-        } = message;
-        let stimulations = [];
-        if (appId) {
-          stimulations = await this.repository.getStimulationsByApp(
-            appId,
-            {
-              fromTimestamp,
-              toTimestamp,
-              limit,
-              offset,
-              hasError,
-              errorContains,
-              collateralName,
-              neuronId
-            }
-          );
-        } else {
-          const apps = await this.repository.listApps();
-          for (const app of apps) {
-            const appStimulations = await this.repository.getStimulationsByApp(
-              app.appId,
-              {
-                fromTimestamp,
-                toTimestamp,
-                limit,
-                offset,
-                hasError,
-                errorContains,
-                collateralName,
-                neuronId
-              }
-            );
-            stimulations = stimulations.concat(appStimulations);
-          }
-        }
-        return {
-          type: "apps:export-stimulations",
-          stimulations
-        };
-      }
-      case "apps:export-snapshot": {
-        const { appId, limitResponses, limitStimulations } = message;
-        const inits = Array.from(this.lastInitByApp.values());
-        const topology = appId ? inits.filter(
-          (init) => (init.appId || init.devToolsInstanceId) === appId
-        ) : inits;
-        let stimulations = [];
-        if (appId) {
-          stimulations = await this.repository.getStimulationsByApp(
-            appId
-          );
-        } else {
-          const apps = await this.repository.listApps();
-          for (const app of apps) {
-            const appStimulations = await this.repository.getStimulationsByApp(
-              app.appId
-            );
-            stimulations = stimulations.concat(appStimulations);
-          }
-        }
-        const responses = [];
-        if (appId) {
-          const cnsIds = await this.repository.getCnsByApp(appId);
-          for (const cnsId of cnsIds) {
-            const cnsResponses = await this.repository.getResponsesByCns(cnsId);
-            responses.push(...cnsResponses);
-          }
-        } else {
-          const apps = await this.repository.listApps();
-          for (const app of apps) {
-            const cnsIds = await this.repository.getCnsByApp(
-              app.appId
-            );
-            for (const cnsId of cnsIds) {
-              const cnsResponses = await this.repository.getResponsesByCns(cnsId);
-              responses.push(...cnsResponses);
-            }
-          }
-        }
-        const tail = (arr, n) => typeof n === "number" && n > 0 ? arr.slice(Math.max(0, arr.length - n)) : arr;
-        const sanitizedStim = tail(stimulations, limitStimulations).map(
-          (s) => ({
-            ...s,
-            payload: _CNSDevToolsServer.sanitizeValue(
-              s.payload
-            )
-          })
-        );
-        const sanitizedResp = tail(responses, limitResponses).map(
-          (r) => ({
-            ...r,
-            payload: _CNSDevToolsServer.sanitizeValue(
-              r.payload
-            ),
-            contexts: _CNSDevToolsServer.sanitizeValue(
-              r.contexts
-            )
-          })
-        );
-        const snapshot = {
-          type: "apps:snapshot",
-          appId: appId || null,
-          topology,
-          stimulations: sanitizedStim,
-          responses: sanitizedResp,
-          createdAt: Date.now()
-        };
-        try {
-          const sizeBytes = Buffer.byteLength(
-            JSON.stringify(snapshot)
-          );
-          snapshot.sizeBytes = sizeBytes;
-          const maxBytes = 5 * 1024 * 1024;
-          if (sizeBytes > maxBytes) {
-            snapshot.warning = `Snapshot size ${sizeBytes} bytes exceeds ${maxBytes} bytes; consider narrowing filters.`;
-          }
-        } catch {
-        }
-        return snapshot;
-      }
-      case "cns:export-responses": {
-        const {
-          cnsId,
-          limit,
-          fromTimestamp,
-          toTimestamp,
-          offset,
-          hasError,
-          errorContains,
-          neuronId,
-          collateralName
-        } = message;
-        const responsesAll = await this.repository.getResponsesByCns(
-          cnsId,
-          {
-            fromTimestamp,
-            toTimestamp,
-            limit,
-            offset,
-            hasError,
-            errorContains,
-            neuronId,
-            collateralName
-          }
-        );
-        return {
-          type: "cns:export-responses",
-          cnsId,
-          responses: responsesAll
-        };
-      }
-      // REST-like over WS
-      case "apps:list": {
-        const apps = await this.repository.listApps();
-        return { type: "apps:list", apps };
-      }
-      case "apps:get-cns": {
-        const { appId } = message;
-        const cnsIds = await this.repository.getCnsByApp(appId);
-        const cns = cnsIds.map((cnsId) => ({ cnsId, appId }));
-        return { type: "apps:cns", appId, cns };
-      }
-      case "apps:get-responses": {
-        const {
-          appId,
-          limit,
-          fromTimestamp,
-          toTimestamp,
-          offset,
-          hasError,
-          errorContains,
-          neuronId,
-          collateralName
-        } = message;
-        let allResponses = [];
-        if (appId) {
-          const cnsIds = await this.repository.getCnsByApp(appId);
-          for (const cnsId of cnsIds) {
-            const responses = await this.repository.getResponsesByCns(cnsId, {
-              fromTimestamp,
-              toTimestamp,
-              hasError,
-              errorContains,
-              neuronId,
-              collateralName
-            });
-            allResponses = allResponses.concat(responses);
-          }
-        } else {
-          const apps = await this.repository.listApps();
-          for (const app of apps) {
-            const cnsIds = await this.repository.getCnsByApp(
-              app.appId
-            );
-            for (const cnsId of cnsIds) {
-              const responses = await this.repository.getResponsesByCns(cnsId, {
-                fromTimestamp,
-                toTimestamp,
-                hasError,
-                errorContains,
-                neuronId,
-                collateralName
-              });
-              allResponses = allResponses.concat(responses);
-            }
-          }
-        }
-        allResponses.sort((a, b) => b.timestamp - a.timestamp);
-        const response = {
-          type: "apps:responses",
-          appId: appId || "all",
-          responses: allResponses,
-          total: allResponses.length,
-          offset: offset || 0,
-          limit: limit || allResponses.length
-        };
-        ws.send(JSON.stringify(response));
-        return response;
-      }
-      case "cns:get-responses": {
-        const msg = message;
-        const {
-          cnsId,
-          limit,
-          fromTimestamp,
-          toTimestamp,
-          offset,
-          hasError,
-          errorContains,
-          neuronId,
-          collateralName
-        } = msg;
-        if (!cnsId) {
-          return { type: "cns:responses", cnsId: "", responses: [] };
-        }
-        const responses = await this.repository.getResponsesByCns(
-          cnsId,
-          {
-            fromTimestamp,
-            toTimestamp,
-            limit,
-            offset,
-            hasError,
-            errorContains,
-            neuronId,
-            collateralName
-          }
-        );
-        return { type: "cns:responses", cnsId, responses };
-      }
-      default:
-        this.log("Unknown message type:", message.type);
-        return null;
+  // ─── App batch item handlers ──────────────────────────────────────────────
+  async handleAppBatchItem(ws, item) {
+    switch (item.type) {
+      case "topology":
+        await this.handleTopology(ws, item);
+        break;
+      case "stimulation.started":
+        await this.handleStimulationStarted(ws, item.stimulation);
+        break;
+      case "stimulation.hop":
+        await this.handleStimulationHop(item.hop);
+        break;
+      case "stimulation.completed":
+        await this.handleStimulationCompleted(item);
+        break;
     }
   }
-  async handleInit(ws, message) {
-    const baseAppId = message.appId || message.devToolsInstanceId;
-    const cnsId = message.cnsId || message.devToolsInstanceId;
-    if (!baseAppId || !cnsId) {
-      throw new Error("Invalid InitMessage: missing appId or cnsId");
-    }
-    this.lastInitByApp.set(cnsId, message);
+  async handleTopology(ws, msg) {
+    const { appId, cnsId, appName, version, timestamp, neurons, collaterals, dendrites } = msg;
     const now = Date.now();
-    if (!this.appFirstSeenAt.has(baseAppId)) {
-      this.appFirstSeenAt.set(baseAppId, now);
-    }
-    this.appLastSeenAt.set(baseAppId, now);
     const app = {
-      appId: baseAppId,
-      appName: message.appName,
-      version: message.version,
-      firstSeenAt: this.appFirstSeenAt.get(baseAppId),
+      id: appId,
+      name: appName,
+      version,
+      connectedAt: now,
       lastSeenAt: now
     };
     await this.repository.upsertApp(app);
-    this.appSockets.set(cnsId, ws);
-    const existingNeurons = await this.repository.getNeuronsByCns(cnsId);
-    const existingCollaterals = await this.repository.getCollateralsByCns(
-      cnsId
-    );
-    const existingDendrites = await this.repository.getDendritesByCns(
-      cnsId
+    await this.repository.addCnsToApp(appId, cnsId);
+    await this.repository.saveTopology({ appId, cnsId, appName, version, timestamp, neurons, collaterals, dendrites });
+    this.appSockets.set(ws, appId);
+    if (!this.appWsByAppId.has(appId)) this.appWsByAppId.set(appId, /* @__PURE__ */ new Set());
+    this.appWsByAppId.get(appId).add(ws);
+    const topologyBroadcast = {
+      type: "topology.result",
+      requestId: "__broadcast__",
+      snapshots: await this.repository.getTopology(cnsId)
+    };
+    this.broadcast({ type: "app.connected", app, topology: { cnsId, neurons, collaterals, dendrites } });
+    this.broadcastRaw(JSON.stringify(topologyBroadcast));
+  }
+  async handleStimulationStarted(ws, stimulation) {
+    const appId = this.appSockets.get(ws);
+    if (appId) {
+      const apps = await this.repository.listApps();
+      const app = apps.find((a) => a.id === appId);
+      if (app) await this.repository.upsertApp({ ...app, lastSeenAt: Date.now() });
+    }
+    await this.repository.saveStimulation(stimulation);
+    this.broadcast({ type: "stimulation.started", stimulation });
+  }
+  async handleStimulationHop(hop) {
+    await this.repository.saveHop(hop);
+    this.broadcast({ type: "stimulation.hop", hop });
+  }
+  async handleStimulationCompleted(item) {
+    await this.repository.completeStimulation(
+      item.stimulationId,
+      item.completedAt,
+      item.hopCount,
+      item.hasError
     );
-    for (const neuron of existingNeurons) {
-      if (this.repository.removeNeuron) {
-        await this.repository.removeNeuron(neuron.id);
-      }
-    }
-    for (const collateral of existingCollaterals) {
-      if (this.repository.removeCollateral) {
-        await this.repository.removeCollateral(collateral.id);
-      }
-    }
-    for (const dendrite of existingDendrites) {
-      if (this.repository.removeDendrite) {
-        await this.repository.removeDendrite(dendrite.id);
-      }
-    }
-    for (const neuron of message.neurons || []) {
-      await this.repository.upsertNeuron(neuron);
-    }
-    for (const collateral of message.collaterals || []) {
-      await this.repository.upsertCollateral(collateral);
-    }
-    for (const dendrite of message.dendrites || []) {
-      await this.repository.upsertDendrite(dendrite);
-    }
-    await this.repository.addCnsToApp(app.appId, cnsId);
-    this.log(`App connected: ${message.appName} (${message.devToolsInstanceId})`);
-    this.log(`Topology: ${message.neurons.length} neurons, ${message.collaterals.length} collaterals, ${message.dendrites.length} dendrites`);
-    const apps = await this.repository.listApps();
-    this.broadcastToClients({
-      type: "app:added",
-      app
+    this.broadcast({
+      type: "stimulation.completed",
+      stimulationId: item.stimulationId,
+      completedAt: item.completedAt,
+      hopCount: item.hopCount,
+      hasError: item.hasError
     });
-    this.log("Broadcasting apps:active to", this.clientSockets.size, "clients:", {
-      appsCount: apps.length,
-      appIds: apps.map((a) => a.appId)
-    });
-    this.broadcastToClients({
-      type: "apps:active",
-      apps
+  }
+  // ─── UI client query handlers ─────────────────────────────────────────────
+  async handleClientConnect(ws) {
+    this.addClient(ws);
+    this.send(ws, { type: "apps.result", requestId: "__init__", items: await this.repository.listApps() });
+    this.send(ws, {
+      type: "topology.result",
+      requestId: "__init__",
+      snapshots: await this.repository.getTopology()
     });
-    return {
-      type: "apps:active",
-      apps
-    };
   }
-  async handleBatch(ws, message) {
-    this.log("Server handling batch with", message.items?.length || 0, "items");
-    if (!Array.isArray(message.items)) {
-      if (this.options.consoleLogEnabled) {
-        console.warn("Invalid batch message - no items array");
-      }
+  async handleAppsQuery(ws, requestId) {
+    const items = await this.repository.listApps();
+    this.send(ws, { type: "apps.result", requestId, items });
+  }
+  async handleTopologyQuery(ws, requestId, cnsId, appId) {
+    let snapshots = await this.repository.getTopology(cnsId);
+    if (appId) snapshots = snapshots.filter((s) => s.appId === appId);
+    this.send(ws, { type: "topology.result", requestId, snapshots });
+  }
+  async handleStimulationsQuery(ws, msg) {
+    const appId = msg.appId ?? (msg.cnsId ? await this.repository.findAppByCns(msg.cnsId) : void 0);
+    if (!appId) {
+      this.send(ws, { type: "stimulations.result", requestId: msg.requestId, items: [], total: 0, offset: 0 });
       return;
     }
-    const responses = [];
-    for (const item of message.items || []) {
-      const actualMessage = item.payload || item;
-      if (item.type === "response") {
-        responses.push(actualMessage);
-      } else {
-        this.log("Batch item (non-response):", {
-          type: actualMessage?.type
-        });
-        await this.handleMessage(ws, actualMessage);
-      }
-    }
-    if (responses.length > 0) {
-      this.log("Creating response-batch with", responses.length, "responses");
-      const responseBatch = {
-        type: "response-batch",
-        devToolsInstanceId: responses[0].cnsId || responses[0].appId || "unknown",
-        responses
-      };
-      await this.handleResponseBatch(
-        ws,
-        responseBatch
-      );
-    }
-  }
-  async handleResponseBatch(ws, message) {
-    const replayResponses = (message.responses || []).filter((r) => {
-      const stimId = r.stimulationId || "";
-      return typeof stimId === "string" && stimId.includes("-replay-");
+    const { items, total } = await this.repository.getStimulations(appId, msg.filter ?? {});
+    this.send(ws, {
+      type: "stimulations.result",
+      requestId: msg.requestId,
+      items,
+      total,
+      offset: msg.filter?.offset ?? 0
     });
-    if (replayResponses.length > 0) {
-      this.log("[Server] Received REPLAY response-batch:", {
-        totalResponses: message.responses?.length || 0,
-        replayResponsesCount: replayResponses.length,
-        replayStimIds: replayResponses.slice(0, 3).map((r) => r.stimulationId),
-        replayAppIds: replayResponses.slice(0, 3).map((r) => r.appId)
-      });
-    }
-    if (message.responses && message.responses.length > 0) {
-      const appId = message.responses[0].appId;
-      if (appId) {
-        this.appLastSeenAt.set(appId, Date.now());
-      }
-    }
-    for (const response of message.responses) {
-      await this.repository.saveResponse(response);
-    }
-    this.broadcastToClients(message);
-    return message;
   }
-  async handleStimulate(ws, message) {
-    const cnsIdFromCmd = message.cnsId;
-    const appIdFromCmd = message.appId;
-    try {
+  async handleHopsQuery(ws, msg) {
+    const items = await this.repository.getHops(msg.stimulationId);
+    this.send(ws, { type: "hops.result", requestId: msg.requestId, items });
+  }
+  async handleReplayStart(ws, msg) {
+    const appId = msg.appId ?? (msg.cnsId ? await this.repository.findAppByCns(msg.cnsId) : void 0);
+    const appSockets = appId ? this.appWsByAppId.get(appId) : void 0;
+    if (!appSockets || appSockets.size === 0) {
+      this.send(ws, { type: "replay.rejected", replayId: msg.replayId, reason: "App not connected" });
+      return;
+    }
+    const newStimulationId = `${msg.stimulationId}-replay-${Date.now()}`;
+    this.send(ws, { type: "replay.accepted", replayId: msg.replayId, newStimulationId });
+    const payload = JSON.stringify(msg);
+    for (const appWs of appSockets) {
       try {
-        const entry = {
-          stimulationCommandId: message.stimulationCommandId,
-          appId: message.appId,
-          cnsId: message.cnsId,
-          collateralName: message.collateralName,
-          payload: message.payload,
-          contexts: message.contexts,
-          options: message.options,
-          timestamp: Date.now()
-        };
-        const arr = this.replaysByApp.get(entry.appId) || [];
-        arr.push(entry);
-        if (arr.length > 1e3) arr.splice(0, arr.length - 1e3);
-        this.replaysByApp.set(entry.appId, arr);
+        appWs.send(payload);
       } catch {
       }
-      if (cnsIdFromCmd) {
-        const appWs = this.appSockets.get(cnsIdFromCmd);
-        if (appWs && appWs.readyState === 1) {
-          appWs.send(JSON.stringify(message));
-          this.log(`Stimulate forwarded to cns ${cnsIdFromCmd}`);
-        } else {
-          if (this.options.consoleLogEnabled) {
-            console.warn(`CNS socket not available for ${cnsIdFromCmd}`);
-          }
-        }
-      } else if (appIdFromCmd) {
-        const cnsIds = await this.repository.getCnsByApp(appIdFromCmd);
-        let count = 0;
-        for (const cnsId of cnsIds) {
-          const appWs = this.appSockets.get(cnsId);
-          if (appWs && appWs.readyState === 1) {
-            appWs.send(JSON.stringify(message));
-            count++;
-          }
-        }
-        this.log(`Stimulate forwarded to ${count} CNS of app ${appIdFromCmd}`);
-      } else {
-        let count = 0;
-        for (const [, appWs] of Array.from(this.appSockets.entries())) {
-          if (appWs.readyState === 1) {
-            appWs.send(JSON.stringify(message));
-            count++;
-          }
-        }
-      }
-    } catch (e) {
-      if (this.options.consoleLogEnabled) {
-        console.error("Failed to forward stimulate:", e);
-      }
     }
-    return null;
   }
-  async handleDisconnect(ws) {
-    for (const [cnsId, socket] of Array.from(this.appSockets.entries())) {
-      if (socket === ws) {
-        this.appSockets.delete(cnsId);
-        this.log(`CNS disconnected: ${cnsId}`);
-        const sepIdx = cnsId.indexOf(":");
-        const baseAppId = sepIdx > 0 ? cnsId.slice(0, sepIdx) : cnsId;
-        this.lastInitByApp.delete(cnsId);
-        await this.repository.removeCnsFromApp(baseAppId, cnsId);
-        break;
-      }
-    }
-    this.clientSockets.delete(ws);
-  }
-  addClient(ws) {
-    this.clientSockets.add(ws);
-    if (!this.metricsTimer) {
-      this.startMetricsLoop();
-    }
-    const eventedWs = ws;
-    const remove = () => this.removeClient(ws);
-    if (eventedWs.on) {
-      eventedWs.on("close", remove);
-      eventedWs.on("error", remove);
-    } else if (eventedWs.addEventListener) {
-      eventedWs.addEventListener("close", remove);
-      eventedWs.addEventListener("error", remove);
-    }
-  }
-  removeClient(ws) {
-    this.clientSockets.delete(ws);
+  // ─── Broadcast helpers ────────────────────────────────────────────────────
+  broadcast(message) {
+    this.broadcastRaw(JSON.stringify(message));
   }
-  async handleStimulation(ws, message) {
-    await this.repository.saveStimulation(message);
-    this.stimulationBuffer.push(message);
-    this.broadcastToClients({
-      type: "stimulation-batch",
-      stimulations: [message]
-    });
-  }
-  broadcastToClients(message) {
-    const messageStr = JSON.stringify(message);
-    let sentCount = 0;
-    this.clientSockets.forEach((clientWs) => {
-      if (clientWs.readyState === 1) {
-        try {
-          clientWs.send(messageStr);
-          sentCount++;
-        } catch (error) {
-          if (this.options.consoleLogEnabled) {
-            console.error("Failed to send message to client:", error);
-          }
-        }
+  broadcastRaw(payload) {
+    for (const client of this.uiClients) {
+      try {
+        if (client.readyState === 1) client.send(payload);
+      } catch {
       }
-    });
-    if (sentCount !== this.clientSockets.size && this.options.consoleLogEnabled) {
-      console.warn(
-        `Sent message to ${sentCount}/${this.clientSockets.size} clients`
-      );
     }
   }
-  startMetricsLoop() {
-    if (this.metricsTimer) {
-      return;
+  send(ws, message) {
+    try {
+      if (ws.readyState === 1) ws.send(JSON.stringify(message));
+    } catch {
     }
-    this.lastCpuUsage = process.cpuUsage();
-    this.lastCpuTime = Date.now();
+  }
+  // ─── Metrics ──────────────────────────────────────────────────────────────
+  startMetrics() {
+    if (this.metricsTimer) return;
     this.metricsTimer = setInterval(() => {
-      if (this.stopped) {
-        clearInterval(this.metricsTimer);
-        this.metricsTimer = void 0;
-        return;
-      }
-      try {
-        const mem = process.memoryUsage();
-        const now = Date.now();
-        const cpu = process.cpuUsage(this.lastCpuUsage);
-        const elapsedMs = Math.max(1, now - this.lastCpuTime);
-        const userMs = cpu.user / 1e3;
-        const systemMs = cpu.system / 1e3;
-        const cpuPercent = Math.min(
-          100,
-          Math.round((userMs + systemMs) / elapsedMs * 100)
-        );
-        this.lastCpuUsage = process.cpuUsage();
-        this.lastCpuTime = now;
-        const payload = {
-          type: "server:metrics",
-          timestamp: now,
-          rssMB: Math.round(mem.rss / 1024 / 1024 * 100) / 100,
-          heapUsedMB: Math.round(mem.heapUsed / 1024 / 1024 * 100) / 100,
-          heapTotalMB: Math.round(mem.heapTotal / 1024 / 1024 * 100) / 100,
-          externalMB: Math.round(mem.external / 1024 / 1024 * 100) / 100,
-          cpuPercent
-        };
-        this.broadcastToClients(payload);
-      } catch {
-      }
+      const mem = process.memoryUsage();
+      const now = Date.now();
+      const cpu = process.cpuUsage(this.lastCpuUsage);
+      const elapsed = (now - this.lastCpuTime) * 1e3;
+      const cpuPercent = elapsed > 0 ? (cpu.user + cpu.system) / elapsed * 100 : 0;
+      this.lastCpuUsage = process.cpuUsage();
+      this.lastCpuTime = now;
+      this.broadcast({
+        type: "server.metrics",
+        timestamp: now,
+        rssMB: mem.rss / 1024 / 1024,
+        heapUsedMB: mem.heapUsed / 1024 / 1024,
+        heapTotalMB: mem.heapTotal / 1024 / 1024,
+        cpuPercent
+      });
     }, 1e3);
   }
-  async getActiveApps() {
-    return await this.repository.listApps();
-  }
-  stop() {
-    this.log("Stopping server.");
-    this.stopped = true;
+  stopMetrics() {
     if (this.metricsTimer) {
       clearInterval(this.metricsTimer);
       this.metricsTimer = void 0;
     }
-    for (const ws of Array.from(this.appSockets.values())) {
-      ws.close();
-    }
-    this.appSockets.clear();
-    for (const ws of Array.from(this.clientSockets)) {
-      ws.close();
-    }
-    this.clientSockets.clear();
-    this.lastInitByApp.clear();
-    this.stimulationBuffer = [];
-    this.appFirstSeenAt.clear();
-    this.appLastSeenAt.clear();
-    this.replaysByApp.clear();
   }
 };
 
 exports.CNSDevToolsServer = CNSDevToolsServer;
-exports.startDevTools = startDevTools;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map