@mozilla/firefox-devtools-mcp 0.10.0 → 0.10.1

package/dist/index.js

@@ -14841,7 +14841,7 @@ var init_constants = __esm({
   "src/config/constants.ts"() {
     "use strict";
     SERVER_NAME = true ? "@mozilla/firefox-devtools-mcp" : "firefox-devtools";
-    SERVER_VERSION = true ? "0.10.0" : "dev";
+    SERVER_VERSION = true ? "0.10.1" : "dev";
   }
 });
 
@@ -15348,68 +15348,6 @@ var init_core3 = __esm({
       getOptions() {
         return this.options;
       }
-      /**
-       * Wait for WebSocket to be in OPEN state
-       */
-      async waitForWebSocketOpen(ws, timeout = 5e3) {
-        if (ws.readyState === 1) {
-          return;
-        }
-        if (ws.readyState === 0) {
-          return new Promise((resolve4, reject) => {
-            const timeoutId = setTimeout(() => {
-              ws.off("open", onOpen);
-              reject(new Error("Timeout waiting for WebSocket to open"));
-            }, timeout);
-            const onOpen = () => {
-              clearTimeout(timeoutId);
-              ws.off("open", onOpen);
-              resolve4();
-            };
-            ws.on("open", onOpen);
-          });
-        }
-        throw new Error(`WebSocket is not open: readyState ${ws.readyState}`);
-      }
-      /**
-       * Send raw BiDi command and get response
-       */
-      async sendBiDiCommand(method, params = {}) {
-        if (!this.driver) {
-          throw new Error("Driver not connected");
-        }
-        const bidi = await this.driver.getBidi();
-        const ws = bidi.socket;
-        await this.waitForWebSocketOpen(ws);
-        const id = Math.floor(Math.random() * 1e6);
-        return new Promise((resolve4, reject) => {
-          const messageHandler = (data) => {
-            try {
-              const payload = JSON.parse(data.toString());
-              if (payload.id === id) {
-                ws.off("message", messageHandler);
-                if (payload.error) {
-                  reject(new Error(`BiDi error: ${JSON.stringify(payload.error)}`));
-                } else {
-                  resolve4(payload.result);
-                }
-              }
-            } catch {
-            }
-          };
-          ws.on("message", messageHandler);
-          const command = {
-            id,
-            method,
-            params
-          };
-          ws.send(JSON.stringify(command));
-          setTimeout(() => {
-            ws.off("message", messageHandler);
-            reject(new Error(`BiDi command timeout: ${method}`));
-          }, 1e4);
-        });
-      }
       /**
        * Close driver and cleanup.
        * - Tries graceful quit() with a timeout; on timeout, force-kills via onQuit_().
@@ -15479,6 +15417,107 @@ var init_core3 = __esm({
   }
 });
 
+// src/firefox/bidi.ts
+import EventEmitter from "events";
+var BiDiFacade;
+var init_bidi = __esm({
+  "src/firefox/bidi.ts"() {
+    "use strict";
+    init_logger();
+    BiDiFacade = class extends EventEmitter {
+      constructor(driver) {
+        super();
+        this.driver = driver;
+      }
+      listening = false;
+      nextCommandId = 1;
+      async subscribe(events) {
+        const bidi = await this.driver.getBidi();
+        if (!this.listening) {
+          this.listenForEvents(bidi.socket);
+          this.listening = true;
+        }
+        await bidi.subscribe(events);
+      }
+      async sendCommand(method, params = {}) {
+        const bidi = await this.driver.getBidi();
+        const ws = bidi.socket;
+        await this.waitForWebSocketOpen(ws);
+        const id = this.nextCommandId++;
+        return new Promise((resolve4, reject) => {
+          const messageHandler = (data) => {
+            try {
+              const payload = JSON.parse(data.toString());
+              if (payload.id === id) {
+                ws.off("message", messageHandler);
+                if (payload.error) {
+                  reject(new Error(`BiDi error: ${JSON.stringify(payload.error)}`));
+                } else {
+                  resolve4(payload.result);
+                }
+              }
+            } catch {
+            }
+          };
+          ws.on("message", messageHandler);
+          const command = {
+            id,
+            method,
+            params
+          };
+          ws.send(JSON.stringify(command));
+          setTimeout(() => {
+            ws.off("message", messageHandler);
+            reject(new Error(`BiDi command timeout: ${method}`));
+          }, 1e4);
+        });
+      }
+      listenForEvents(ws) {
+        ws.on("message", (data) => {
+          let payload;
+          try {
+            payload = JSON.parse(data.toString());
+          } catch {
+            return;
+          }
+          if (payload?.type === "event" && payload.method) {
+            try {
+              this.emit(payload.method, payload.params);
+            } catch (error2) {
+              logDebug(
+                `Error emitting ${payload.method} event: ${error2 instanceof Error ? error2.message : String(error2)}`
+              );
+            }
+          }
+        });
+      }
+      /**
+       * Wait for WebSocket to be in OPEN state
+       */
+      async waitForWebSocketOpen(ws, timeout = 5e3) {
+        if (ws.readyState === 1) {
+          return;
+        }
+        if (ws.readyState === 0) {
+          return new Promise((resolve4, reject) => {
+            const timeoutId = setTimeout(() => {
+              ws.off("open", onOpen);
+              reject(new Error("Timeout waiting for WebSocket to open"));
+            }, timeout);
+            const onOpen = () => {
+              clearTimeout(timeoutId);
+              ws.off("open", onOpen);
+              resolve4();
+            };
+            ws.on("open", onOpen);
+          });
+        }
+        throw new Error(`WebSocket is not open: readyState ${ws.readyState}`);
+      }
+    };
+  }
+});
+
 // src/utils/remote-value.ts
 function remoteValueToNative(rv) {
   if (!rv || typeof rv !== "object") {
@@ -15549,8 +15588,8 @@ var init_console = __esm({
     MAX_CONSOLE_MESSAGES = 1e3;
     CONSOLE_TTL_MS = 5 * 60 * 1e3;
     ConsoleEvents = class {
-      constructor(driver, options = {}) {
-        this.driver = driver;
+      constructor(bidi, options = {}) {
+        this.bidi = bidi;
         this.options = {
           autoClearOnNavigate: false,
           // Changed default to false to preserve logs across tabs
@@ -15563,44 +15602,27 @@ var init_console = __esm({
       /**
        * Subscribe to BiDi console events and navigation lifecycle
        */
-      async subscribe(contextId) {
+      async subscribe() {
         if (this.subscribed) {
           return;
         }
-        const bidi = await this.driver.getBidi();
-        await bidi.subscribe("log.entryAdded", contextId ? [contextId] : void 0);
-        try {
-          await bidi.subscribe("browsingContext.load", contextId ? [contextId] : void 0);
-          await bidi.subscribe("browsingContext.domContentLoaded", contextId ? [contextId] : void 0);
-        } catch {
-          logDebug(
-            "Navigation events subscription skipped (may not be available in this Firefox version)"
-          );
-        }
-        const ws = bidi.socket;
-        ws.on("message", (data) => {
-          try {
-            const payload = JSON.parse(data.toString());
-            if (payload?.method === "log.entryAdded") {
-              const entry = payload.params;
-              const message = {
-                level: entry.level || "info",
-                text: entry.text || (entry.args ? JSON.stringify(entry.args) : ""),
-                timestamp: entry.timestamp || Date.now(),
-                source: entry.source?.realm,
-                args: entry.args
-              };
-              this.consoleMessages.push(message);
-              logDebug(`Console [${message.level}]: ${message.text}`);
-            }
-            if (payload?.method === "browsingContext.load" || payload?.method === "browsingContext.domContentLoaded") {
-              if (this.options.autoClearOnNavigate) {
-                this.clearMessages();
-              }
-            }
-          } catch {
-          }
+        await this.bidi.subscribe("log.entryAdded");
+        await this.bidi.subscribe(["browsingContext.load", "browsingContext.domContentLoaded"]);
+        this.bidi.on("log.entryAdded", (entry) => {
+          const message = {
+            level: entry.level || "info",
+            text: entry.text || (entry.args ? JSON.stringify(entry.args) : ""),
+            timestamp: entry.timestamp || Date.now(),
+            source: entry.source?.realm,
+            args: entry.args
+          };
+          this.consoleMessages.push(message);
+          logDebug(`Console [${message.level}]: ${message.text}`);
         });
+        if (this.options.autoClearOnNavigate) {
+          this.bidi.on("browsingContext.load", () => this.clearMessages());
+          this.bidi.on("browsingContext.domContentLoaded", () => this.clearMessages());
+        }
         this.subscribed = true;
         logDebug("Console listener active with lifecycle hooks");
       }
@@ -15648,9 +15670,8 @@ var init_network = __esm({
     NETWORK_TTL_MS = 5 * 60 * 1e3;
     MAX_ENCODED_DATA_SIZE = 10 * 1e3 * 1e3;
     NetworkEvents = class {
-      constructor(driver, options = {}, sendCommand) {
-        this.driver = driver;
-        this.sendCommand = sendCommand;
+      constructor(bidi, options = {}) {
+        this.bidi = bidi;
         this.options = {
           autoClearOnNavigate: true,
           ...options
@@ -15666,90 +15687,81 @@ var init_network = __esm({
        * Subscribe to BiDi network events and navigation lifecycle
        * Enables monitoring by default (always-on capture)
        */
-      async subscribe(contextId) {
+      async subscribe() {
         if (this.subscribed) {
           return;
         }
-        const bidi = await this.driver.getBidi();
-        await bidi.subscribe("network.beforeRequestSent", contextId ? [contextId] : void 0);
-        await bidi.subscribe("network.responseStarted", contextId ? [contextId] : void 0);
-        await bidi.subscribe("network.responseCompleted", contextId ? [contextId] : void 0);
-        try {
-          await bidi.subscribe("browsingContext.load", contextId ? [contextId] : void 0);
-          await bidi.subscribe("browsingContext.domContentLoaded", contextId ? [contextId] : void 0);
-        } catch {
-          logDebug(
-            "Navigation events subscription skipped (may not be available in this Firefox version)"
-          );
-        }
-        const ws = bidi.socket;
-        ws.on("message", (data) => {
-          try {
-            const payload = JSON.parse(data.toString());
-            if (payload?.method === "browsingContext.load" || payload?.method === "browsingContext.domContentLoaded") {
-              if (this.enabled && this.options.autoClearOnNavigate) {
-                this.clearRequests();
-              }
-              return;
-            }
-            if (!this.enabled) {
-              return;
-            }
-            if (payload?.method === "network.beforeRequestSent") {
-              const req = payload.params;
-              const requestId = req.request?.request || req.requestId;
-              if (!requestId) {
-                return;
-              }
-              this.requestStartTimes.set(requestId, Date.now());
-              const record2 = {
-                id: requestId,
-                url: req.request?.url || "",
-                method: req.request?.method || "GET",
-                timestamp: Date.now(),
-                resourceType: this.guessResourceType(req.request?.url || ""),
-                isXHR: req.initiator?.type === "xmlhttprequest" || req.initiator?.type === "fetch",
-                requestHeaders: this.parseHeaders(req.request?.headers || []),
-                timings: {
-                  requestTime: Date.now()
-                }
-              };
-              this.networkRecords.set(requestId, record2);
-              logDebug(`Network request [${record2.method}]: ${record2.url}`);
-            }
-            if (payload?.method === "network.responseStarted") {
-              const resp = payload.params;
-              const requestId = resp.request?.request || resp.requestId;
-              if (!requestId) {
-                return;
-              }
-              const existing = this.networkRecords.get(requestId);
-              if (existing) {
-                existing.status = resp.response?.status;
-                existing.statusText = resp.response?.statusText || "";
-                existing.responseHeaders = this.parseHeaders(resp.response?.headers || []);
-              }
+        await this.bidi.subscribe([
+          "network.beforeRequestSent",
+          "network.responseStarted",
+          "network.responseCompleted"
+        ]);
+        await this.bidi.subscribe(["browsingContext.load", "browsingContext.domContentLoaded"]);
+        const onLoadEvent = () => {
+          if (this.enabled && this.options.autoClearOnNavigate) {
+            this.clearRequests();
+          }
+        };
+        this.bidi.on("browsingContext.domContentLoaded", onLoadEvent);
+        this.bidi.on("browsingContext.load", onLoadEvent);
+        this.bidi.on("network.beforeRequestSent", (req) => {
+          if (!this.enabled) {
+            return;
+          }
+          const requestId = req.request?.request || req.requestId;
+          if (!requestId) {
+            return;
+          }
+          this.requestStartTimes.set(requestId, Date.now());
+          const record2 = {
+            id: requestId,
+            url: req.request?.url || "",
+            method: req.request?.method || "GET",
+            timestamp: Date.now(),
+            resourceType: this.guessResourceType(req.request?.url || ""),
+            isXHR: req.initiator?.type === "xmlhttprequest" || req.initiator?.type === "fetch",
+            requestHeaders: this.parseHeaders(req.request?.headers || []),
+            timings: {
+              requestTime: Date.now()
             }
-            if (payload?.method === "network.responseCompleted") {
-              const resp = payload.params;
-              const requestId = resp.request?.request || resp.requestId;
-              if (!requestId) {
-                return;
-              }
-              const existing = this.networkRecords.get(requestId);
-              const startTime = this.requestStartTimes.get(requestId);
-              if (existing && startTime) {
-                existing.timings.responseTime = Date.now();
-                existing.timings.duration = Date.now() - startTime;
-                if (!existing.status && resp.response?.status) {
-                  existing.status = resp.response.status;
-                  existing.statusText = resp.response.statusText || "";
-                }
-              }
-              this.requestStartTimes.delete(requestId);
+          };
+          this.networkRecords.set(requestId, record2);
+          logDebug(`Network request [${record2.method}]: ${record2.url}`);
+        });
+        this.bidi.on("network.responseStarted", (resp) => {
+          if (!this.enabled) {
+            return;
+          }
+          const requestId = resp.request?.request || resp.requestId;
+          if (!requestId) {
+            return;
+          }
+          const existing = this.networkRecords.get(requestId);
+          if (existing) {
+            existing.status = resp.response?.status;
+            existing.statusText = resp.response?.statusText || "";
+            existing.responseHeaders = this.parseHeaders(resp.response?.headers || []);
+          }
+        });
+        this.bidi.on("network.responseCompleted", (resp) => {
+          if (!this.enabled) {
+            return;
+          }
+          const requestId = resp.request?.request || resp.requestId;
+          if (!requestId) {
+            return;
+          }
+          const existing = this.networkRecords.get(requestId);
+          const startTime = this.requestStartTimes.get(requestId);
+          if (existing && startTime) {
+            existing.timings.responseTime = Date.now();
+            existing.timings.duration = Date.now() - startTime;
+            if (!existing.status && resp.response?.status) {
+              existing.status = resp.response.status;
+              existing.statusText = resp.response.statusText || "";
             }
-          } catch {
           }
+          this.requestStartTimes.delete(requestId);
         });
         await this.registerDataCollector();
         this.subscribed = true;
@@ -15765,11 +15777,8 @@ var init_network = __esm({
           logDebug("Network body capture disabled, skipping data collector registration");
           return;
         }
-        if (!this.sendCommand) {
-          return;
-        }
         try {
-          const result = await this.sendCommand("network.addDataCollector", {
+          const result = await this.bidi.sendCommand("network.addDataCollector", {
             dataTypes: ["request", "response"],
             maxEncodedDataSize: MAX_ENCODED_DATA_SIZE
           });
@@ -15789,11 +15798,11 @@ var init_network = __esm({
        * when the body was never collected, evicted, or the browser lacks support.
        */
       async fetchBody(requestId, dataType) {
-        if (!this.sendCommand || !this.collectorId) {
+        if (!this.collectorId) {
           return { ok: false, reason: "unsupported" };
         }
         try {
-          const result = await this.sendCommand("network.getData", {
+          const result = await this.bidi.sendCommand("network.getData", {
             request: requestId,
             dataType
           });
@@ -15975,46 +15984,35 @@ var init_debugging = __esm({
     init_logger();
     MAX_LOGPOINT_RESULTS = 100;
     DebuggingEvents = class {
-      constructor(driver, sendBiDiCommand) {
-        this.driver = driver;
-        this.sendBiDiCommand = sendBiDiCommand;
+      constructor(bidi) {
+        this.bidi = bidi;
       }
       logpoints = /* @__PURE__ */ new Map();
       subscribed = false;
       /**
        * Subscribe to moz:debugging events
        */
-      async subscribe(contextId) {
+      async subscribe() {
         if (this.subscribed) {
           return;
         }
-        const bidi = await this.driver.getBidi();
         try {
-          await bidi.subscribe("moz:debugging.paused", contextId ? [contextId] : void 0);
-          await bidi.subscribe("moz:debugging.resumed", contextId ? [contextId] : void 0);
+          await this.bidi.subscribe(["moz:debugging.paused", "moz:debugging.resumed"]);
         } catch {
           logDebug(
             "Debugging events subscription skipped (may not be available in this Firefox version)"
           );
         }
-        const ws = bidi.socket;
-        ws.on("message", (data) => {
-          try {
-            const payload = JSON.parse(data.toString());
-            if (payload?.method === "moz:debugging.paused") {
-              const { context, url, line, column } = payload.params;
-              const logpointId = this.findLogpointByLocation(url, line);
-              if (logpointId) {
-                void this.handleLogpointPause(context, logpointId);
-                return;
-              }
-              logDebug(`moz:Debugging paused in context: ${context} at ${url}:${line}:${column}`);
-            }
-            if (payload?.method === "moz:debugging.resumed") {
-              logDebug(`moz:Debugging resumed in context: ${payload.params.context}`);
-            }
-          } catch {
+        this.bidi.on("moz:debugging.paused", ({ context, url, line, column }) => {
+          const logpointId = this.findLogpointByLocation(url, line);
+          if (logpointId) {
+            void this.handleLogpointPause(context, logpointId);
+            return;
           }
+          logDebug(`moz:Debugging paused in context: ${context} at ${url}:${line}:${column}`);
+        });
+        this.bidi.on("moz:debugging.resumed", (entry) => {
+          logDebug(`moz:Debugging resumed in context: ${entry.context}`);
         });
         this.subscribed = true;
         logDebug("moz:debugging listener active");
@@ -16048,7 +16046,7 @@ var init_debugging = __esm({
         }
         logDebug(`Logpoint hit: ${logpointId} in context ${contextId}`);
         try {
-          const result = await this.sendBiDiCommand("script.evaluate", {
+          const result = await this.bidi.sendCommand("script.evaluate", {
             expression: entry.expression,
             target: { context: contextId },
             awaitPromise: false
@@ -16080,7 +16078,7 @@ var init_debugging = __esm({
               logDebug(`Logpoint ${logpointId}: result buffer capped at ${MAX_LOGPOINT_RESULTS}`);
             }
           }
-          await this.sendBiDiCommand("moz:debugging.resume", { context: contextId }).catch((err) => {
+          await this.bidi.sendCommand("moz:debugging.resume", { context: contextId }).catch((err) => {
             logDebug(`Failed to resume after logpoint: ${String(err)}`);
           });
         }
@@ -16098,8 +16096,8 @@ var init_downloads = __esm({
     MAX_DOWNLOADS = 500;
     DOWNLOAD_TTL_MS = 30 * 60 * 1e3;
     DownloadEvents = class {
-      constructor(driver) {
-        this.driver = driver;
+      constructor(bidi) {
+        this.bidi = bidi;
       }
       downloads = /* @__PURE__ */ new Map();
       subscribed = false;
@@ -16111,65 +16109,53 @@ var init_downloads = __esm({
       /**
        * Subscribe to BiDi download events.
        */
-      async subscribe(contextId) {
+      async subscribe() {
         if (this.subscribed) {
           return;
         }
-        const bidi = await this.driver.getBidi();
-        const contexts = contextId ? [contextId] : void 0;
-        await bidi.subscribe("browsingContext.downloadWillBegin", contexts);
-        await bidi.subscribe("browsingContext.downloadEnd", contexts);
-        const ws = bidi.socket;
-        ws.on("message", (data) => {
-          try {
-            const payload = JSON.parse(data.toString());
-            if (payload?.method === "browsingContext.downloadWillBegin") {
-              const p = payload.params;
-              let key = p.download ?? p.navigation;
-              if (!key) {
-                key = `download-${this.fallbackCounter++}`;
-                this.pendingFallbackKey = key;
-              }
-              this.downloads.set(key, {
-                id: key,
-                context: p.context,
-                navigation: p.navigation ?? null,
-                url: p.url || "",
-                suggestedFilename: p.suggestedFilename || "",
-                status: "in_progress",
-                startTimestamp: p.timestamp ?? Date.now()
-              });
-              logDebug(`Download started: filename=${p.suggestedFilename}, url=${p.url}, id=${key}`);
-            }
-            if (payload?.method === "browsingContext.downloadEnd") {
-              const p = payload.params;
-              let key = p?.download ?? p?.navigation;
-              if (!key) {
-                key = this.pendingFallbackKey ?? `download-${this.fallbackCounter++}`;
-                this.pendingFallbackKey = null;
-              }
-              const existing = this.downloads.get(key) ?? {
-                id: key,
-                context: p.context,
-                navigation: p.navigation ?? null,
-                url: p.url || "",
-                suggestedFilename: "",
-                status: "in_progress",
-                startTimestamp: p.timestamp ?? Date.now()
-              };
-              existing.status = p.status;
-              existing.endTimestamp = p.timestamp ?? Date.now();
-              existing.durationMs = existing.endTimestamp - existing.startTimestamp;
-              if (p.status === "complete" && p.filepath) {
-                existing.filepath = p.filepath;
-              }
-              this.downloads.set(key, existing);
-              logDebug(
-                `Download ${p.status}: filepath=${existing.filepath}, url=${existing.url}, id=${key}`
-              );
-            }
-          } catch {
+        await this.bidi.subscribe(["browsingContext.downloadWillBegin", "browsingContext.downloadEnd"]);
+        this.bidi.on("browsingContext.downloadWillBegin", (p) => {
+          let key = p.download ?? p.navigation;
+          if (!key) {
+            key = `download-${this.fallbackCounter++}`;
+            this.pendingFallbackKey = key;
+          }
+          this.downloads.set(key, {
+            id: key,
+            context: p.context,
+            navigation: p.navigation ?? null,
+            url: p.url || "",
+            suggestedFilename: p.suggestedFilename || "",
+            status: "in_progress",
+            startTimestamp: p.timestamp ?? Date.now()
+          });
+          logDebug(`Download started: filename=${p.suggestedFilename}, url=${p.url}, id=${key}`);
+        });
+        this.bidi.on("browsingContext.downloadEnd", (p) => {
+          let key = p?.download ?? p?.navigation;
+          if (!key) {
+            key = this.pendingFallbackKey ?? `download-${this.fallbackCounter++}`;
+            this.pendingFallbackKey = null;
+          }
+          const existing = this.downloads.get(key) ?? {
+            id: key,
+            context: p.context,
+            navigation: p.navigation ?? null,
+            url: p.url || "",
+            suggestedFilename: "",
+            status: "in_progress",
+            startTimestamp: p.timestamp ?? Date.now()
+          };
+          existing.status = p.status;
+          existing.endTimestamp = p.timestamp ?? Date.now();
+          existing.durationMs = existing.endTimestamp - existing.startTimestamp;
+          if (p.status === "complete" && p.filepath) {
+            existing.filepath = p.filepath;
           }
+          this.downloads.set(key, existing);
+          logDebug(
+            `Download ${p.status}: filepath=${existing.filepath}, url=${existing.url}, id=${key}`
+          );
         });
         this.subscribed = true;
         logDebug("Download listener ready");
@@ -17052,6 +17038,7 @@ var init_firefox = __esm({
   "src/firefox/index.ts"() {
     "use strict";
     init_core3();
+    init_bidi();
     init_logger();
     init_remote_value();
     init_events();
@@ -17060,6 +17047,7 @@ var init_firefox = __esm({
     init_snapshot();
     FirefoxClient = class {
       core;
+      bidi = null;
       consoleEvents = null;
       networkEvents = null;
       debuggingEvents = null;
@@ -17070,31 +17058,52 @@ var init_firefox = __esm({
       constructor(options) {
         this.core = new FirefoxCore(options);
       }
+      getBidi() {
+        if (!this.bidi) {
+          throw new Error("Not connected");
+        }
+        return this.bidi;
+      }
       /**
        * Connect and initialize all modules
        */
       async connect() {
         await this.core.connect();
         const driver = this.core.getDriver();
+        this.bidi = new BiDiFacade(driver);
         this.snapshot = new SnapshotManager(driver);
-        const hasBidi = "getBidi" in driver && typeof driver.getBidi === "function";
-        if (hasBidi) {
-          this.consoleEvents = new ConsoleEvents(driver, {
-            autoClearOnNavigate: false
-          });
-          this.networkEvents = new NetworkEvents(
-            driver,
-            {
-              autoClearOnNavigate: false,
-              captureBodies: this.core.getOptions().captureNetworkBodies !== false
-            },
-            (method, params) => this.core.sendBiDiCommand(method, params ?? {})
-          );
-          this.debuggingEvents = new DebuggingEvents(
-            driver,
-            (method, params) => this.core.sendBiDiCommand(method, params)
-          );
-          this.downloadEvents = new DownloadEvents(driver);
+        this.consoleEvents = new ConsoleEvents(this.bidi, {
+          autoClearOnNavigate: false
+        });
+        try {
+          await this.consoleEvents.subscribe();
+        } catch {
+          logDebug("Unable to subscribe to console events");
+          this.consoleEvents = null;
+        }
+        this.networkEvents = new NetworkEvents(this.bidi, {
+          autoClearOnNavigate: false,
+          captureBodies: this.core.getOptions().captureNetworkBodies !== false
+        });
+        try {
+          await this.networkEvents.subscribe();
+        } catch {
+          logDebug("Unable to subscribe to network events");
+          this.networkEvents = null;
+        }
+        this.debuggingEvents = new DebuggingEvents(this.bidi);
+        try {
+          await this.debuggingEvents.subscribe();
+        } catch {
+          logDebug("Unable to subscribe to debugging events");
+          this.debuggingEvents = null;
+        }
+        this.downloadEvents = new DownloadEvents(this.bidi);
+        try {
+          await this.downloadEvents.subscribe();
+        } catch {
+          logDebug("Unable to subscribe to download events");
+          this.downloadEvents = null;
         }
         this.dom = new DomInteractions(
           driver,
@@ -17104,40 +17113,8 @@ var init_firefox = __esm({
           driver,
           () => this.core.getCurrentContextId(),
           (id) => this.core.setCurrentContextId(id),
-          (method, params) => this.core.sendBiDiCommand(method, params)
+          (method, params) => this.getBidi().sendCommand(method, params)
         );
-        if (this.consoleEvents) {
-          try {
-            await this.consoleEvents.subscribe(void 0);
-          } catch {
-            logDebug("Unable to subscribe to console events");
-            this.consoleEvents = null;
-          }
-        }
-        if (this.networkEvents) {
-          try {
-            await this.networkEvents.subscribe(void 0);
-          } catch {
-            logDebug("Unable to subscribe to network events");
-            this.networkEvents = null;
-          }
-        }
-        if (this.debuggingEvents) {
-          try {
-            await this.debuggingEvents.subscribe();
-          } catch {
-            logDebug("Unable to subscribe to debugging events");
-            this.debuggingEvents = null;
-          }
-        }
-        if (this.downloadEvents) {
-          try {
-            await this.downloadEvents.subscribe(void 0);
-          } catch {
-            logDebug("Unable to subscribe to download events");
-            this.downloadEvents = null;
-          }
-        }
       }
       // ============================================================================
       // DOM / Evaluate
@@ -17149,7 +17126,7 @@ var init_firefox = __esm({
        * native value; throws on a script exception.
        */
       async evaluate(expression) {
-        const result = await this.core.sendBiDiCommand("script.evaluate", {
+        const result = await this.getBidi().sendCommand("script.evaluate", {
           expression,
           awaitPromise: true,
           target: { context: this.core.getCurrentContextId() }
@@ -17394,7 +17371,7 @@ var init_firefox = __esm({
        */
       async setDownloadBehavior(behavior) {
         const downloadBehavior = behavior === "default" ? null : behavior === "allowed" ? { type: "allowed" } : { type: "denied" };
-        await this.core.sendBiDiCommand("browser.setDownloadBehavior", { downloadBehavior });
+        await this.getBidi().sendCommand("browser.setDownloadBehavior", { downloadBehavior });
       }
       // ============================================================================
       // Snapshot
@@ -17446,7 +17423,7 @@ var init_firefox = __esm({
        * @internal
        */
       async sendBiDiCommand(method, params = {}) {
-        return await this.core.sendBiDiCommand(method, params);
+        return await this.getBidi().sendCommand(method, params);
       }
       /**
        * Get WebDriver instance (for advanced operations)
@@ -17491,7 +17468,7 @@ var init_firefox = __esm({
         if (!this.debuggingEvents) {
           throw new Error("Debugging events not available");
         }
-        const result = await this.core.sendBiDiCommand("moz:debugging.setBreakpoint", {
+        const result = await this.getBidi().sendCommand("moz:debugging.setBreakpoint", {
           location: { url, line }
         });
         const logpointId = result.breakpoint;
@@ -17505,7 +17482,7 @@ var init_firefox = __esm({
         if (!this.debuggingEvents) {
           throw new Error("Debugging events not available");
         }
-        await this.core.sendBiDiCommand("moz:debugging.removeBreakpoint", {
+        await this.getBidi().sendCommand("moz:debugging.removeBreakpoint", {
           breakpoint: logpointId
         });
         this.debuggingEvents.removeLogpoint(logpointId);
@@ -17559,11 +17536,56 @@ var init_firefox = __esm({
   }
 });
 
+// src/tools/instructions.ts
+function buildInstructions(moduleNames, toolNames) {
+  const byName = new Map(MODULES.map((m) => [m.name, m]));
+  const capabilities = moduleNames.flatMap((name) => {
+    const module17 = byName.get(name);
+    return module17 ? [`- ${module17.name}: ${module17.description}`] : [];
+  });
+  const sections = [INSTRUCTIONS_INTRO, ["Enabled capabilities:", ...capabilities].join("\n")];
+  const core = CORE_TOOLS.filter((name) => toolNames.has(name));
+  if (core.length > 0) {
+    const groups = TASK_TOOLS.flatMap(({ purpose, tools }) => {
+      const available = tools.filter((name) => toolNames.has(name));
+      return available.length > 0 ? [`${available.join(" / ")} for ${purpose}`] : [];
+    });
+    const extra = groups.length > 0 ? ` Add task-specific tools to the same search: ${groups.join(", ")}.` : "";
+    sections.push(
+      `When these tools are deferred, load the core set in one search rather than one at a time: ${core.join(", ")}.${extra}`
+    );
+  }
+  return sections.join("\n\n");
+}
+var INSTRUCTIONS_INTRO, CORE_TOOLS, TASK_TOOLS;
+var init_instructions = __esm({
+  "src/tools/instructions.ts"() {
+    "use strict";
+    init_tools();
+    INSTRUCTIONS_INTRO = [
+      "Browse and debug the web with Firefox.",
+      "Use this for any browser or web page task: opening a URL, automating a web flow,",
+      "or debugging a page (console errors, network requests, DOM state).",
+      "The task does not need to name Firefox, reach for these tools unless another",
+      "browser is explicitly requested.",
+      "Chrome-only browser tools do not control Firefox, do not assume they cover this."
+    ].join(" ");
+    CORE_TOOLS = ["list_pages", "new_page", "navigate_page", "take_snapshot", "get_page_text"];
+    TASK_TOOLS = [
+      { purpose: "interaction", tools: ["click_by_uid", "fill_by_uid", "hover_by_uid"] },
+      { purpose: "debugging", tools: ["list_console_messages", "list_network_requests"] },
+      { purpose: "visuals", tools: ["screenshot_page", "screenshot_by_uid"] },
+      { purpose: "one-off JS", tools: ["evaluate_script"] }
+    ];
+  }
+});
+
 // src/tools/registry.ts
 function buildToolset(options) {
   const { moduleNames, warnings } = selectModules(options);
   const { toolDefinitions, handlers } = collectTools(moduleNames);
-  return { moduleNames, warnings, toolDefinitions, handlers };
+  const instructions = buildInstructions(moduleNames, new Set(handlers.keys()));
+  return { moduleNames, warnings, toolDefinitions, handlers, instructions };
 }
 function selectModules(options) {
   const { tools: requested, preset, enableScript, enablePrivilegedContext } = options;
@@ -17651,6 +17673,7 @@ var init_registry = __esm({
   "src/tools/registry.ts"() {
     "use strict";
     init_tools();
+    init_instructions();
     privilegedModuleNames = new Set(MODULES.filter((m) => m.privileged).map((m) => m.name));
   }
 });
@@ -17771,7 +17794,8 @@ async function run(parseArgsFn, importMetaUrl, allowPrivileged = false) {
     moduleNames,
     warnings,
     toolDefinitions: allTools,
-    handlers: toolHandlers
+    handlers: toolHandlers,
+    instructions
   } = buildToolset({
     tools: args.tools,
     preset: args.toolPreset,
@@ -17801,7 +17825,8 @@ async function run(parseArgsFn, importMetaUrl, allowPrivileged = false) {
     {
       capabilities: {
         tools: {}
-      }
+      },
+      instructions
     }
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mozilla/firefox-devtools-mcp",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Model Context Protocol (MCP) server for Firefox DevTools automation",
   "author": "Mozilla",
   "license": "MIT OR Apache-2.0",