@extension.dev/mcp 5.5.1 → 5.6.0

package/dist/module.js

@@ -12,6 +12,7 @@ import { execFile, execFileSync } from "node:child_process";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
 import ws_0 from "ws";
 import node_http from "node:http";
+import node_net from "node:net";
 import { extensionInstall, extensionUninstall, getManagedBrowsersCacheRoot } from "extension-install";
 import { promisify } from "node:util";
 var add_feature_namespaceObject = {};
@@ -219,7 +220,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.5.1","El":{"OP":"^4.0.13"}}');
+var package_namespaceObject = JSON.parse('{"rE":"5.6.0","El":{"OP":"^4.0.15"}}');
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -563,6 +564,42 @@ function resolveExtensionInvocation(projectDir) {
 function runExtensionCli(args, options) {
     const { command, prefixArgs } = resolveExtensionInvocation(options?.cwd);
     return new Promise((resolve)=>{
+        let ioDir;
+        let outFd;
+        let errFd;
+        try {
+            ioDir = node_fs.mkdtempSync(node_path.join(node_os.tmpdir(), "extension-mcp-io-"));
+            outFd = node_fs.openSync(node_path.join(ioDir, "stdout"), "a");
+            errFd = node_fs.openSync(node_path.join(ioDir, "stderr"), "a");
+        } catch (err) {
+            resolve({
+                code: 1,
+                stdout: "",
+                stderr: String(err)
+            });
+            return;
+        }
+        const readAll = (name)=>{
+            try {
+                return node_fs.readFileSync(node_path.join(ioDir, name), "utf8");
+            } catch  {
+                return "";
+            }
+        };
+        const cleanup = ()=>{
+            for (const fd of [
+                outFd,
+                errFd
+            ])try {
+                node_fs.closeSync(fd);
+            } catch  {}
+            try {
+                node_fs.rmSync(ioDir, {
+                    recursive: true,
+                    force: true
+                });
+            } catch  {}
+        };
         const child = cross_spawn(command, [
             ...prefixArgs,
             ...args
@@ -570,8 +607,8 @@ function runExtensionCli(args, options) {
             cwd: options?.cwd,
             stdio: [
                 "ignore",
-                "pipe",
-                "pipe"
+                outFd,
+                errFd
             ],
             env: {
                 ...process.env,
@@ -580,20 +617,26 @@ function runExtensionCli(args, options) {
             },
             timeout: options?.timeoutMs ?? 30000
         });
-        let stdout = "";
-        let stderr = "";
-        child.stdout?.on("data", (d)=>stdout += d.toString());
-        child.stderr?.on("data", (d)=>stderr += d.toString());
-        child.on("close", (code)=>resolve({
+        child.on("close", (code)=>{
+            const stdout = readAll("stdout");
+            const stderr = readAll("stderr");
+            cleanup();
+            resolve({
                 code,
                 stdout,
                 stderr
-            }));
-        child.on("error", (err)=>resolve({
+            });
+        });
+        child.on("error", (err)=>{
+            const stdout = readAll("stdout");
+            const stderr = readAll("stderr");
+            cleanup();
+            resolve({
                 code: 1,
                 stdout,
                 stderr: stderr || String(err)
-            }));
+            });
+        });
     });
 }
 function spawnExtensionCli(args, options) {
@@ -2557,6 +2600,32 @@ async function inspect_handler(args) {
     };
     return JSON.stringify(result);
 }
+function summarizeConsoleMessages(messages) {
+    const counts = {};
+    const uniqueByLevel = {};
+    for (const msg of messages){
+        counts[msg.level] = (counts[msg.level] ?? 0) + 1;
+        if (!uniqueByLevel[msg.level]) uniqueByLevel[msg.level] = new Map();
+        const key = msg.text.slice(0, 200);
+        uniqueByLevel[msg.level].set(key, (uniqueByLevel[msg.level].get(key) ?? 0) + 1);
+    }
+    const topMessages = [];
+    for (const [level, msgs] of Object.entries(uniqueByLevel)){
+        const sorted = [
+            ...msgs.entries()
+        ].sort((a, b)=>b[1] - a[1]);
+        for (const [text, count] of sorted.slice(0, 5))topMessages.push({
+            level,
+            text,
+            count
+        });
+    }
+    return {
+        total: messages.length,
+        counts,
+        topMessages: topMessages.sort((a, b)=>b.count - a.count).slice(0, 10)
+    };
+}
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -2666,30 +2735,7 @@ class CDPConnection {
         ];
     }
     getConsoleSummary() {
-        const counts = {};
-        const uniqueByLevel = {};
-        for (const msg of this.consoleMessages){
-            counts[msg.level] = (counts[msg.level] ?? 0) + 1;
-            if (!uniqueByLevel[msg.level]) uniqueByLevel[msg.level] = new Map();
-            const key = msg.text.slice(0, 200);
-            uniqueByLevel[msg.level].set(key, (uniqueByLevel[msg.level].get(key) ?? 0) + 1);
-        }
-        const topMessages = [];
-        for (const [level, msgs] of Object.entries(uniqueByLevel)){
-            const sorted = [
-                ...msgs.entries()
-            ].sort((a, b)=>b[1] - a[1]);
-            for (const [text, count] of sorted.slice(0, 5))topMessages.push({
-                level,
-                text,
-                count
-            });
-        }
-        return {
-            total: this.consoleMessages.length,
-            counts,
-            topMessages: topMessages.sort((a, b)=>b.count - a.count).slice(0, 10)
-        };
+        return summarizeConsoleMessages(this.consoleMessages);
     }
     onEvent(handler) {
         this.eventListeners.add(handler);
@@ -2964,7 +3010,7 @@ class CDPClient extends CDPConnection {
         return result ?? null;
     }
 }
-async function resolveCdpPort(projectPath, browser, options) {
+async function resolveContractPort(projectPath, browser, field, options) {
     const waitMs = options?.waitMs ?? 20000;
     const graceMs = options?.graceMs ?? 2500;
     const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
@@ -2976,9 +3022,9 @@ async function resolveCdpPort(projectPath, browser, options) {
             const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
             contractSeen = true;
             if (null == contractSeenAt) contractSeenAt = Date.now();
-            if ("number" == typeof contract.cdpPort) return {
-                port: contract.cdpPort,
-                source: "contract"
+            if ("number" == typeof contract[field]) return {
+                port: contract[field],
+                contractSeen
             };
         } catch  {
             if (!contractSeen) break;
@@ -2987,13 +3033,32 @@ async function resolveCdpPort(projectPath, browser, options) {
         if (Date.now() >= effectiveDeadline) break;
         await new Promise((resolve)=>setTimeout(resolve, 500));
     }
+    return {
+        port: null,
+        contractSeen
+    };
+}
+async function resolveCdpPort(projectPath, browser, options) {
+    const { port, contractSeen } = await resolveContractPort(projectPath, browser, "cdpPort", options);
+    if (null != port) return {
+        port,
+        source: "contract"
+    };
     if (!contractSeen && await isCdpEndpoint(9222)) return {
         port: 9222,
         source: "default-probe"
     };
     return null;
 }
+async function resolveRdpPort(projectPath, browser, options) {
+    const { port } = await resolveContractPort(projectPath, browser, "rdpPort", options);
+    return null != port ? {
+        port,
+        source: "contract"
+    } : null;
+}
 const CDP_PORT_MISSING_HINT = "The session's ready contract has no CDP port (the browser may still be binding its debug port, or was launched without one). Confirm the session with extension_wait, give it a moment, and retry.";
+const RDP_PORT_MISSING_HINT = "The session's ready contract has no rdpPort. Firefox sessions publish one from extension.js 4.0.15 on; upgrade the project's extension dependency (or remove the local install so the MCP's pinned CLI drives the session) and restart the dev session.";
 function isCdpEndpoint(port) {
     return new Promise((resolve)=>{
         const req = node_http.get({
@@ -3012,9 +3077,640 @@ function isCdpEndpoint(port) {
         });
     });
 }
+function toMcpSpeak(text) {
+    return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/Use --context page --tab <id>/g, 'Use context: "page" (targets the active tab; pass url or tab to pick another)').replace(/--context[= ](background|popup|options|sidebar|devtools|newtab|history|bookmarks|content|page)\b/g, 'context: "$1"').replace(/--tab[= ](\d+|<[\w-]+>)/g, "tab: $1").replace(/--url[= ]"([^"]+)"/g, 'url: "$1"').replace(/--url[= ](<[\w-]+>|\S*(?:\/\/|\*)\S*)/g, 'url: "$1"').replace(/--browser[= ]([\w]+-based|chrome|chromium|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|safari)\b/g, 'browser: "$1"').replace(/--timeout[= ](\d+)/g, "timeout: $1").replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev").replace(/--tab\b/g, "`tab`").replace(/--url\b/g, "`url`").replace(/--context\b/g, "`context`").replace(/--browser\b/g, "`browser`").replace(/--timeout\b/g, "`timeout`");
+}
+function withSessionContext(message, projectPath) {
+    const isControlError = /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
+    if (!isControlError) return message;
+    const dead = deadReadySession(projectPath);
+    if (dead) return `${message}\nLikely cause: the dev server has exited, ${dead.browser} ready.json still says ready but its pid ${dead.pid} is dead. Restart with extension_dev (this is not an allowControl problem); extension_doctor confirms.`;
+    const running = knownSessionBrowsers(projectPath);
+    if (0 === running.length) return message;
+    return `${message} Active session browser(s) for this project: ${running.join(", ")}, pass that as \`browser\`, or restart it via extension_dev with allowControl: true if the control channel is off.`;
+}
+function translateFrame(frame, projectPath) {
+    if (!frame || false !== frame.ok) return frame;
+    if (frame.error && "string" == typeof frame.error.message) frame.error.message = withSessionContext(toMcpSpeak(frame.error.message), projectPath);
+    if ("string" == typeof frame.error?.hint) frame.error.hint = toMcpSpeak(frame.error.hint);
+    if ("string" == typeof frame.hint) frame.hint = toMcpSpeak(frame.hint);
+    return frame;
+}
+async function runActVerb(args, projectPath, timeoutMs) {
+    const { code, stdout, stderr } = await runExtensionCli([
+        ...args,
+        "--output",
+        "json"
+    ], {
+        cwd: projectPath,
+        timeoutMs
+    });
+    const out = stdout.trim();
+    if (out) try {
+        const frame = JSON.parse(out);
+        if (frame && false === frame.ok) return JSON.stringify(translateFrame(frame, projectPath));
+        return out;
+    } catch  {}
+    const message = stderr.trim() || `extension exited with code ${code}`;
+    return JSON.stringify({
+        ok: false,
+        error: {
+            name: "CliError",
+            message: withSessionContext(toMcpSpeak(message), projectPath)
+        }
+    });
+}
+function commonFlags(args) {
+    const flags = [];
+    if (args.context) flags.push("--context", args.context);
+    if (args.url) flags.push("--url", args.url);
+    if (null != args.tab) flags.push("--tab", String(args.tab));
+    if (args.browser) flags.push("--browser", args.browser);
+    if (null != args.timeout) flags.push("--timeout", String(args.timeout));
+    return flags;
+}
+async function listBridgeTabs(projectPath, browser, timeout) {
+    const raw = await runActVerb([
+        "inspect",
+        projectPath,
+        "--list-tabs",
+        "--browser",
+        browser,
+        ...null != timeout ? [
+            "--timeout",
+            String(timeout)
+        ] : []
+    ], projectPath, timeout);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return {
+            error: raw
+        };
+    }
+    if (parsed?.ok === false) return {
+        error: raw
+    };
+    const list = Array.isArray(parsed?.tabs) ? parsed.tabs : Array.isArray(parsed?.value) ? parsed.value : Array.isArray(parsed?.value?.tabs) ? parsed.value.tabs : null;
+    if (!list) return {
+        error: raw
+    };
+    return {
+        tabs: list.map((t)=>({
+                tabId: "number" == typeof t?.tabId ? t.tabId : "number" == typeof t?.id ? t.id : null,
+                url: String(t?.url ?? ""),
+                title: String(t?.title ?? "")
+            }))
+    };
+}
+function matchTabsByUrl(tabs, needle) {
+    const wanted = needle.toLowerCase();
+    const byUrl = tabs.filter((t)=>t.url.toLowerCase().includes(wanted));
+    if (byUrl.length > 0) return byUrl;
+    return tabs.filter((t)=>t.title.toLowerCase().includes(wanted));
+}
+async function pollForBridgeTab(projectPath, browser, url, budgetMs) {
+    const deadline = Date.now() + budgetMs;
+    const wanted = url.replace(/#.*$/, "");
+    for(;;){
+        const listed = await listBridgeTabs(projectPath, browser);
+        if ("tabs" in listed) {
+            for (const t of listed.tabs)if (t.url === wanted || t.url.startsWith(wanted)) return t;
+        }
+        if (Date.now() >= deadline) return null;
+        await new Promise((r)=>setTimeout(r, 250));
+    }
+}
+async function navigateToUrlViaBridge(projectPath, browser, url, timeout) {
+    const expression = `(async () => { const api = typeof browser !== "undefined" ? browser : chrome; const tabs = await api.tabs.query({ active: true, currentWindow: true }); const active = tabs && tabs[0]; const tab = active && active.id != null ? await api.tabs.update(active.id, { url: ${JSON.stringify(url)} }) : await api.tabs.create({ url: ${JSON.stringify(url)} }); return { tabId: tab && tab.id != null ? tab.id : null }; })()`;
+    const raw = await runActVerb([
+        "eval",
+        expression,
+        projectPath,
+        "--context",
+        "background",
+        "--browser",
+        browser,
+        ...null != timeout ? [
+            "--timeout",
+            String(timeout)
+        ] : []
+    ], projectPath, timeout);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.ok === false) {
+            if (!parsed.hint) parsed.hint = "On this browser family URL navigation rides the agent bridge (a background eval of tabs.update), so the dev session must be started with allowEval: true (extension_dev).";
+            return JSON.stringify(parsed);
+        }
+    } catch  {
+        return raw;
+    }
+    const settled = await pollForBridgeTab(projectPath, browser, url, null != timeout ? Math.min(timeout, 6000) : 6000);
+    if (!settled) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NavigateFailed",
+            message: `Navigation to ${url} did not produce a tab reporting that URL. The URL may not exist, or the browser refused the navigation (Firefox rejects privileged about:/chrome: URLs and other extensions' moz-extension: pages).`
+        },
+        hint: "Confirm the URL, or discover open tabs with extension_dom_inspect listTabs: true. For an extension page, the path must match the BUILT manifest."
+    });
+    return JSON.stringify({
+        ok: true,
+        navigated: url,
+        tab: {
+            tabId: settled.tabId,
+            url: settled.url,
+            title: settled.title
+        },
+        hint: "Inspect it with extension_dom_inspect or extension_eval using url or this numeric tab id (context: 'page'/'content')."
+    });
+}
+async function resolveBridgeBaseUrl(projectPath, browser, timeout) {
+    const raw = await runActVerb([
+        "eval",
+        '(typeof browser !== "undefined" ? browser : chrome).runtime.getURL("")',
+        projectPath,
+        "--context",
+        "background",
+        "--browser",
+        browser,
+        ...null != timeout ? [
+            "--timeout",
+            String(timeout)
+        ] : []
+    ], projectPath, timeout);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed?.ok && "string" == typeof parsed.value && parsed.value) return parsed.value.endsWith("/") ? parsed.value : `${parsed.value}/`;
+    } catch  {}
+    return null;
+}
+function rdp_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+function encodeRdpPacket(packet) {
+    const json = Buffer.from(JSON.stringify(packet), "utf8");
+    return Buffer.concat([
+        Buffer.from(`${json.length}:`, "ascii"),
+        json
+    ]);
+}
+class RdpPacketDecoder {
+    push(chunk) {
+        this.buffer = Buffer.concat([
+            this.buffer,
+            chunk
+        ]);
+        const packets = [];
+        for(;;){
+            const colon = this.buffer.indexOf(0x3a);
+            if (-1 === colon) {
+                if (this.buffer.length > 16) throw new Error("RDP stream corrupt: no length prefix");
+                break;
+            }
+            const prefix = this.buffer.subarray(0, colon).toString("ascii");
+            if (!/^\d+$/.test(prefix)) throw new Error(`RDP stream corrupt: bad length prefix "${prefix}"`);
+            const length = Number(prefix);
+            if (this.buffer.length < colon + 1 + length) break;
+            const json = this.buffer.subarray(colon + 1, colon + 1 + length);
+            this.buffer = this.buffer.subarray(colon + 1 + length);
+            packets.push(JSON.parse(json.toString("utf8")));
+        }
+        return packets;
+    }
+    constructor(){
+        rdp_define_property(this, "buffer", Buffer.alloc(0));
+    }
+}
+class RdpSession {
+    static connect(port, timeoutMs = 10000) {
+        return new Promise((resolve, reject)=>{
+            const socket = node_net.connect({
+                host: "127.0.0.1",
+                port
+            });
+            const session = new RdpSession(socket);
+            const decoder = new RdpPacketDecoder();
+            let settledConnect = false;
+            const timer = setTimeout(()=>{
+                if (!settledConnect) {
+                    settledConnect = true;
+                    session.close();
+                    reject(new Error(`RDP connect timed out after ${timeoutMs}ms`));
+                }
+            }, timeoutMs);
+            socket.on("data", (chunk)=>{
+                let packets;
+                try {
+                    packets = decoder.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                } catch  {
+                    session.close();
+                    return;
+                }
+                for (const packet of packets){
+                    if (!settledConnect && "root" === packet.from) {
+                        settledConnect = true;
+                        clearTimeout(timer);
+                        resolve(session);
+                        continue;
+                    }
+                    for (const tap of session.taps)tap(packet);
+                    for(let i = 0; i < session.waiters.length; i++)if (session.waiters[i].match(packet)) {
+                        session.waiters.splice(i, 1)[0].resolve(packet);
+                        break;
+                    }
+                }
+            });
+            socket.on("error", (error)=>{
+                if (!settledConnect) {
+                    settledConnect = true;
+                    clearTimeout(timer);
+                    reject(error);
+                }
+            });
+            socket.on("close", ()=>{
+                session.closed = true;
+                for (const waiter of session.waiters.splice(0))waiter.reject(new Error("RDP connection closed before a reply arrived"));
+            });
+        });
+    }
+    request(actor, packet, timeoutMs = 10000) {
+        return new Promise((resolve, reject)=>{
+            if (this.closed) return void reject(new Error("RDP connection is closed"));
+            const waiter = {
+                match: (p)=>p.from === actor && void 0 === p.type,
+                resolve: (p)=>{
+                    clearTimeout(timer);
+                    if ("string" == typeof p.error) reject(new Error(`RDP actor error: ${p.error}${"string" == typeof p.message ? ` (${p.message})` : ""}`));
+                    else resolve(p);
+                },
+                reject: (error)=>{
+                    clearTimeout(timer);
+                    reject(error);
+                }
+            };
+            const timer = setTimeout(()=>{
+                const at = this.waiters.indexOf(waiter);
+                if (-1 !== at) this.waiters.splice(at, 1);
+                reject(new Error(`RDP request ${String(packet.type)} to ${actor} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.waiters.push(waiter);
+            this.socket.write(encodeRdpPacket({
+                to: actor,
+                ...packet
+            }));
+        });
+    }
+    tap(handler) {
+        this.taps.add(handler);
+        return ()=>this.taps.delete(handler);
+    }
+    close() {
+        this.closed = true;
+        this.socket.destroy();
+    }
+    constructor(socket){
+        rdp_define_property(this, "socket", void 0);
+        rdp_define_property(this, "waiters", void 0);
+        rdp_define_property(this, "taps", void 0);
+        rdp_define_property(this, "closed", void 0);
+        this.socket = socket;
+        this.waiters = [];
+        this.taps = new Set();
+        this.closed = false;
+    }
+}
+async function withSession(port, timeoutMs, work) {
+    const session = await RdpSession.connect(port, timeoutMs);
+    try {
+        return await work(session);
+    } finally{
+        session.close();
+    }
+}
+async function rdpListAddons(port, options) {
+    const timeoutMs = options?.timeoutMs ?? 10000;
+    return withSession(port, timeoutMs, async (session)=>{
+        const reply = await session.request("root", {
+            type: "listAddons"
+        }, timeoutMs);
+        return reply.addons ?? [];
+    });
+}
+async function rdpListTabs(port, options) {
+    const timeoutMs = options?.timeoutMs ?? 10000;
+    return withSession(port, timeoutMs, async (session)=>{
+        const reply = await session.request("root", {
+            type: "listTabs"
+        }, timeoutMs);
+        return reply.tabs ?? [];
+    });
+}
+function formatConsoleArg(arg) {
+    if (null == arg) return String(arg);
+    if ("object" == typeof arg) {
+        const cls = arg.class;
+        return "string" == typeof cls ? `[${cls}]` : "[object]";
+    }
+    return String(arg);
+}
+async function rdpCollectConsoleMessages(port, options) {
+    const timeoutMs = options?.timeoutMs ?? 10000;
+    const settleMs = options?.settleMs ?? 1000;
+    return withSession(port, timeoutMs, async (session)=>{
+        const tabsReply = await session.request("root", {
+            type: "listTabs"
+        }, timeoutMs);
+        const tabs = tabsReply.tabs ?? [];
+        const wanted = options?.urlFilter?.toLowerCase();
+        const tab = wanted ? tabs.find((t)=>String(t.url ?? "").toLowerCase().includes(wanted)) : tabs.find((t)=>true === t.selected) ?? tabs[0];
+        if (!tab?.actor) throw new Error(wanted ? `no open tab matches url: ${options?.urlFilter}` : "no open tabs");
+        const watcherReply = await session.request(String(tab.actor), {
+            type: "getWatcher",
+            isServerTargetSwitchingEnabled: true
+        }, timeoutMs);
+        const watcherActor = String(watcherReply.actor ?? "");
+        if (!watcherActor) throw new Error("tab descriptor returned no watcher");
+        const messages = [];
+        const untap = session.tap((packet)=>{
+            if ("resources-available-array" !== packet.type) return;
+            const array = Array.isArray(packet.array) ? packet.array : [];
+            for (const entry of array){
+                if (!Array.isArray(entry) || entry.length < 2) continue;
+                const [resourceType, resources] = entry;
+                if (Array.isArray(resources)) for (const raw of resources){
+                    const resource = raw;
+                    if ("console-message" === resourceType) {
+                        const args = Array.isArray(resource.arguments) ? resource.arguments : [];
+                        messages.push({
+                            level: String(resource.level ?? "log"),
+                            text: args.map(formatConsoleArg).join(" ")
+                        });
+                    } else if ("error-message" === resourceType) {
+                        const pageError = resource.pageError ?? {};
+                        messages.push({
+                            level: true === pageError.warning ? "warn" : "error",
+                            text: String(pageError.errorMessage ?? "")
+                        });
+                    }
+                }
+            }
+        });
+        try {
+            await session.request(watcherActor, {
+                type: "watchTargets",
+                targetType: "frame"
+            }, timeoutMs);
+            await session.request(watcherActor, {
+                type: "watchResources",
+                resourceTypes: [
+                    "console-message",
+                    "error-message"
+                ]
+            }, timeoutMs);
+            await new Promise((resolve)=>setTimeout(resolve, settleMs));
+        } finally{
+            untap();
+        }
+        return messages;
+    });
+}
+function buildBridgeInspectExpression(opts) {
+    const parts = [
+        "const out = {};"
+    ];
+    if (opts.meta) parts.push("try { out.meta = { url: location.href, title: document.title, readyState: document.readyState }; } catch (e) {}");
+    if (opts.summary) parts.push(`try {
+        const roots = document.querySelectorAll('#extension-root,[data-extension-root]:not([data-extension-root="extension-js-devtools"])');
+        out.summary = {
+          htmlLength: document.documentElement.outerHTML.length,
+          scriptCount: document.querySelectorAll('script').length,
+          styleCount: document.querySelectorAll('style').length,
+          linkCount: document.querySelectorAll('link').length,
+          extensionRootCount: roots.length,
+          bodyChildCount: document.body ? document.body.children.length : 0
+        };
+      } catch (e) { out.summary = {}; }`);
+    if (opts.html) parts.push(`try {
+        const html = ${PAGE_HTML_SCRIPT};
+        const cap = ${JSON.stringify(opts.maxBytes)};
+        out.htmlTruncated = cap > 0 && html.length > cap;
+        out.html = out.htmlTruncated ? html.slice(0, cap) : html;
+      } catch (e) {}`);
+    if (opts.domSnapshot) parts.push(`try { out.domSnapshot = ${domSnapshotScript(500)}; } catch (e) {}`);
+    if (opts.extensionRoots) parts.push(`try { out.extensionRoots = ${EXTENSION_ROOT_META_SCRIPT}; } catch (e) {}`);
+    if (opts.probes.length) parts.push(`out.probes = {};
+      for (const sel of ${JSON.stringify(opts.probes)}) {
+        try {
+          const nodes = document.querySelectorAll(sel);
+          const first = nodes[0];
+          out.probes[sel] = { count: nodes.length, sample: first ? String(first.outerHTML || "").slice(0, 200) : null };
+        } catch (e) { out.probes[sel] = { error: String((e && e.message) || e) }; }
+      }`);
+    parts.push("return out;");
+    return `(() => { ${parts.join("\n")} })()`;
+}
+function closedShadowWalkerCode(cap) {
+    return `
+    (function() {
+      var out = { api: ("openOrClosedShadowRoot" in Element.prototype), closed: [] };
+      function walk(node) {
+        if (!node || node.nodeType !== 1) return;
+        var sr = null;
+        try { sr = node.openOrClosedShadowRoot || null; } catch (e) {}
+        if (sr && sr.mode !== "open") out.closed.push({ host: node.tagName.toLowerCase(), html: String(sr.innerHTML).slice(0, ${cap}) });
+        var kids = node.children;
+        for (var i = 0; i < kids.length; i++) walk(kids[i]);
+        if (sr) { var sk = sr.children; for (var j = 0; j < sk.length; j++) walk(sk[j]); }
+      }
+      walk(document.documentElement);
+      return out;
+    })();
+  `;
+}
+function executeScriptExpression(urlFilter, code) {
+    const pick = urlFilter ? `tabs.find(function (t) { return String(t.url || "").toLowerCase().indexOf(${JSON.stringify(urlFilter.toLowerCase())}) !== -1; })` : "(tabs.find(function (t) { return t.active; }) || tabs[0])";
+    return `browser.tabs.query({}).then(function (tabs) {
+    var tab = ${pick};
+    if (!tab) return { error: "no matching tab" };
+    return browser.tabs.executeScript(tab.id, { code: ${JSON.stringify(code)} }).then(
+      function (results) { return { frames: results }; },
+      function (err) { return { error: String((err && err.message) || err) }; }
+    );
+  })`;
+}
+async function collectGeckoDeepDom(args, browser, urlFilter, cap, result, notes) {
+    const raw = await runActVerb([
+        "eval",
+        executeScriptExpression(urlFilter, closedShadowWalkerCode(cap)),
+        args.projectPath,
+        "--context",
+        "background",
+        "--browser",
+        browser,
+        ...null != args.timeout ? [
+            "--timeout",
+            String(args.timeout)
+        ] : []
+    ], args.projectPath, args.timeout);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        parsed = null;
+    }
+    const value = parsed?.ok === true ? parsed.value : null;
+    const frame = Array.isArray(value?.frames) ? value.frames[0] : null;
+    if (frame && Array.isArray(frame.closed)) {
+        result.closedShadowRoots = frame.closed.map((c)=>({
+                host: String(c.host ?? ""),
+                type: "closed",
+                html: String(c.html ?? "")
+            }));
+        result.deepDom = true;
+        return;
+    }
+    const reason = value?.error ?? parsed?.error?.message ?? "the content-script walk returned nothing";
+    notes.push(`deepDom failed on ${browser}: ${reason}. The walk runs via tabs.executeScript (MV2) and needs the extension to hold host permissions for the target url.`);
+}
+async function collectGeckoConsole(args, browser, urlFilter, result, notes) {
+    const fallbackNote = `Console capture on ${browser} rides the RDP watcher replay and needs a session whose ready contract publishes rdpPort (extension.js 4.0.15+); extension_logs streams the extension's own console either way.`;
+    const resolved = await resolveRdpPort(args.projectPath, browser, {
+        waitMs: 5000
+    });
+    if (!resolved) return void notes.push(fallbackNote);
+    try {
+        const messages = await rdpCollectConsoleMessages(resolved.port, {
+            urlFilter
+        });
+        result.console = summarizeConsoleMessages(messages);
+        result.rdpPort = resolved.port;
+    } catch (error) {
+        notes.push(`Console capture over RDP failed: ${error.message}. ${fallbackNote}`);
+    }
+}
+async function inspectViaBridge(args, browser, include, maxBytes) {
+    const notes = [];
+    if (args.url) {
+        const listed = await listBridgeTabs(args.projectPath, browser, args.timeout);
+        if ("error" in listed) return listed.error;
+        const already = listed.tabs.some((t)=>t.url.includes(args.url));
+        if (!already) {
+            const nav = await navigateToUrlViaBridge(args.projectPath, browser, args.url, args.timeout);
+            try {
+                if (JSON.parse(nav)?.ok !== true) return nav;
+            } catch  {
+                return nav;
+            }
+        }
+    }
+    const expression = buildBridgeInspectExpression({
+        summary: include.has("summary"),
+        meta: true,
+        html: include.has("html"),
+        domSnapshot: include.has("dom_snapshot"),
+        extensionRoots: include.has("extension_roots"),
+        probes: args.probe ?? [],
+        maxBytes
+    });
+    let raw = await runActVerb([
+        "eval",
+        expression,
+        args.projectPath,
+        "--context",
+        "page",
+        ...args.url ? [
+            "--url",
+            args.url
+        ] : [],
+        "--browser",
+        browser,
+        ...null != args.timeout ? [
+            "--timeout",
+            String(args.timeout)
+        ] : []
+    ], args.projectPath, args.timeout);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return raw;
+    }
+    let value = parsed?.ok === true ? parsed.value ?? {} : null;
+    if (null === value && /scripting is not available/i.test(String(parsed?.error?.message ?? ""))) {
+        raw = await runActVerb([
+            "eval",
+            executeScriptExpression(args.url, expression),
+            args.projectPath,
+            "--context",
+            "background",
+            "--browser",
+            browser,
+            ...null != args.timeout ? [
+                "--timeout",
+                String(args.timeout)
+            ] : []
+        ], args.projectPath, args.timeout);
+        try {
+            parsed = JSON.parse(raw);
+        } catch  {
+            return raw;
+        }
+        const frame = Array.isArray(parsed?.value?.frames) ? parsed.value.frames[0] : null;
+        if (parsed?.ok === true && frame && "object" == typeof frame) value = frame;
+        else if (parsed?.ok === true) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "InspectFailed",
+                message: String(parsed?.value?.error ?? "the content-script inspect returned nothing")
+            },
+            hint: "The MV2 fallback inspects via tabs.executeScript, which needs the extension to hold host permissions for the target url."
+        });
+    }
+    if (null === value) return raw;
+    const result = {
+        browser,
+        transport: "bridge"
+    };
+    if (value.meta) {
+        result.target = {
+            url: value.meta.url,
+            title: value.meta.title
+        };
+        if (include.has("meta")) result.meta = value.meta;
+    }
+    if (include.has("summary") && value.summary) result.summary = value.summary;
+    if (include.has("html") && "string" == typeof value.html) {
+        result.html = value.html;
+        if (value.htmlTruncated) result.htmlTruncated = true;
+    }
+    if (include.has("dom_snapshot") && value.domSnapshot) result.domSnapshot = value.domSnapshot;
+    if (include.has("extension_roots") && void 0 !== value.extensionRoots) result.extensionRoots = value.extensionRoots;
+    if (value.probes) {
+        result.probes = value.probes;
+        const jsLooking = (args.probe ?? []).filter((p)=>/^typeof\s|^(chrome|browser|window|document)\.|\(\)|=>|===/.test(p));
+        if (jsLooking.length) result.probeWarning = `Probes are CSS selectors run through querySelectorAll against the live page, NOT JavaScript expressions. ${jsLooking.map((s)=>`"${s}"`).join(", ")} parsed as selectors and will match nothing. To evaluate JS, use extension_eval.`;
+    }
+    const urlFilter = args.url ?? ("string" == typeof value.meta?.url ? value.meta.url : void 0);
+    if (include.has("console")) await collectGeckoConsole(args, browser, urlFilter, result, notes);
+    if (args.deepDom) {
+        const cap = maxBytes > 0 ? maxBytes : 65536;
+        await collectGeckoDeepDom(args, browser, urlFilter, cap, result, notes);
+    }
+    if (notes.length) result.notes = notes;
+    return JSON.stringify(result);
+}
 const source_inspect_schema = {
     name: "extension_source_inspect",
-    description: "Inspect a running extension's live state via Chrome DevTools Protocol: full HTML (with shadow DOM), DOM structure, content script injection, console messages, and CSS selector queries. Requires an active dev or start session.",
+    description: "Inspect a running extension's live state: full HTML (with shadow DOM), DOM structure, content script injection, console messages, and CSS selector queries. Chromium sessions ride Chrome DevTools Protocol. Firefox sessions are fully paired: summary/meta/html/dom_snapshot/extension_roots/probes ride the agent bridge (needs allowEval: true), console rides the RDP watcher replay (engine 4.0.15+), and deepDom walks closed shadow roots via a content-script eval (MV2 sessions with host permissions for the target url; Firefox MV3 background CSP blocks bridge evals entirely). Requires an active dev or start session.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3065,7 +3761,7 @@ const source_inspect_schema = {
             deepDom: {
                 type: "boolean",
                 default: false,
-                description: "Pierce CLOSED shadow roots via CDP (Chromium only). The default path reads open shadow roots; closed ones need this escape hatch."
+                description: "Pierce CLOSED shadow roots. The default path reads open shadow roots; closed ones need this escape hatch. Chromium: CDP DOM pierce. Firefox: a content-script walk via tabs.executeScript (MV2 sessions; the extension needs host permissions for the target url)."
             }
         },
         required: [
@@ -3081,10 +3777,7 @@ async function source_inspect_handler(args) {
         "console"
     ]);
     const maxBytes = args.maxBytes ?? 262144;
-    if (!isChromiumFamily(browser)) return JSON.stringify({
-        error: `Source inspection reads the live DOM over Chrome DevTools Protocol, which ${browser} (Gecko) does not expose. This is a capability limit, not a missing session.`,
-        hint: `For the ${browser} session, read runtime state with extension_logs, or extension_eval / extension_dom_inspect (content/page, an open surface like popup/options/sidebar, or an override page like newtab) which work against Firefox over the control channel. To get CDP DOM inspection, run a Chromium-family dev session (extension_dev with browser: "chrome") in parallel.`
-    });
+    if (!isChromiumFamily(browser)) return inspectViaBridge(args, browser, include, maxBytes);
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return JSON.stringify({
         error: "No active dev session found. Cannot connect to Chrome DevTools Protocol.",
@@ -3188,7 +3881,7 @@ async function source_inspect_handler(args) {
 }
 const list_extensions_schema = {
     name: "extension_list_extensions",
-    description: "List the extensions with a live context in the running dev browser via Chrome DevTools Protocol. Returns each extension's id, name, version, and live contexts (service worker, page). The entry for THIS dev session's extension (the project being served) is flagged ownExtension: true, with name and version resolved from the session's ready contract even when the browser exposes no identity. Other extensions resolve via the read-only Extensions domain when available; their contexts are never attached to or evaluated in, so an id that the domain does not describe stays id-only with a note saying why. A dormant MV3 service worker with no open page may be absent until it wakes. Chromium only (Firefox uses RDP, not yet supported). Requires an active dev or start session.",
+    description: "List the extensions in the running dev browser. Returns each extension's id, name, version, and (on Chromium) live contexts. The entry for THIS dev session's extension (the project being served) is flagged ownExtension: true, with name and version resolved from the session's ready contract even when the browser exposes no identity. On Chromium this rides the Chrome DevTools Protocol: entries are extensions with at least one live context (a dormant MV3 service worker with no open page may be absent until it wakes), and other extensions resolve via the read-only Extensions domain when available. On Firefox this rides the Remote Debugging Protocol root actor (listAddons, engine 4.0.15+): entries are INSTALLED add-ons regardless of live contexts, with temporarilyInstalled marking temporary loads, and carry no contexts. Either way other extensions' contexts are never attached to or evaluated in. Requires an active dev or start session.",
     inputSchema: {
         type: "object",
         properties: {
@@ -3249,9 +3942,10 @@ function readOwnIdentity(projectPath, browser) {
 const UNRESOLVED_NOTE = "Identity unresolved: the browser's Extensions CDP domain returned nothing for this id, and other extensions' contexts are never attached to or evaluated in to read a manifest.";
 async function list_extensions_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
+    if (isGeckoFamily(browser)) return listGeckoExtensions(args.projectPath, browser);
     if (!isChromiumFamily(browser)) return JSON.stringify({
-        error: `Listing extensions for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
-        hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
+        error: `Listing extensions for ${browser} is not supported: no debugging-protocol pairing exists for this browser family.`,
+        hint: "Target a Chromium-family (CDP) or Firefox-family (RDP) dev session."
     });
     const resolved = await resolveCdpPort(args.projectPath, browser);
     if (!resolved) return JSON.stringify({
@@ -3344,6 +4038,70 @@ async function list_extensions_handler(args) {
         cdp.disconnect();
     }
 }
+async function listGeckoExtensions(projectPath, browser) {
+    const resolved = await resolveRdpPort(projectPath, browser);
+    if (!resolved) return JSON.stringify({
+        error: "No active dev session with a Firefox debugger server (RDP) found.",
+        hint: `Start a dev session first with extension_dev, then use extension_wait to confirm it is ready. ${RDP_PORT_MISSING_HINT}`
+    });
+    const rdpPort = resolved.port;
+    try {
+        let addons = null;
+        let lastError = null;
+        for(let attempt = 0; attempt < 3; attempt++)try {
+            addons = await rdpListAddons(rdpPort);
+            break;
+        } catch (error) {
+            lastError = error;
+            if (attempt < 2) await new Promise((resolve)=>setTimeout(resolve, 800));
+        }
+        if (!addons) throw lastError;
+        const own = readOwnIdentity(projectPath, browser);
+        const extensions = addons.filter((addon)=>true === addon.isWebExtension && true !== addon.isSystem && true !== addon.hidden).map((addon)=>{
+            const entry = {
+                id: String(addon.id ?? addon.actor ?? ""),
+                contexts: [],
+                source: "rdp-root"
+            };
+            if ("string" == typeof addon.name) entry.name = addon.name;
+            if ("string" == typeof addon.version) entry.version = addon.version;
+            if (true === addon.temporarilyInstalled) entry.temporarilyInstalled = true;
+            return entry;
+        });
+        if (own?.name) {
+            const byName = extensions.filter((e)=>e.name === own.name);
+            if (1 === byName.length) byName[0].ownExtension = true;
+        }
+        if (!extensions.some((e)=>e.ownExtension)) {
+            const temporary = extensions.filter((e)=>e.temporarilyInstalled);
+            if (1 === temporary.length) {
+                temporary[0].ownExtension = true;
+                if (void 0 === temporary[0].name && own?.name !== void 0) {
+                    temporary[0].name = own.name;
+                    if (void 0 !== own.version) temporary[0].version = own.version;
+                    temporary[0].source = "session-contract";
+                }
+            }
+        }
+        extensions.sort((a, b)=>{
+            if ((a.ownExtension ?? false) !== (b.ownExtension ?? false)) return a.ownExtension ? -1 : 1;
+            return (a.name ?? a.id).localeCompare(b.name ?? b.id);
+        });
+        const ownEntry = extensions.find((e)=>e.ownExtension);
+        return JSON.stringify({
+            rdpPort,
+            browser,
+            count: extensions.length,
+            ownExtensionId: ownEntry?.id ?? null,
+            extensions,
+            note: "Lists INSTALLED add-ons via the RDP root actor (listAddons), regardless of whether a context is currently live, so entries carry no contexts. temporarilyInstalled marks temporary loads; ownExtension marks the extension this dev session serves, matched from the session's ready contract. Add-ons are never attached to or evaluated in."
+        });
+    } catch (error) {
+        return JSON.stringify({
+            error: `Failed to list extensions over RDP: ${error.message}`
+        });
+    }
+}
 const CONTROL_WS_PATH = "/extjs-control";
 const LEVEL_ORDER = [
     "error",
@@ -3665,58 +4423,6 @@ async function logs_handler(args) {
     if (args.follow) return readFromStream(args, browser, limit);
     return readFromFile(args, browser, limit);
 }
-function toMcpSpeak(text) {
-    return text.replace(/`?extension dev(?: [^\s`]*)? --browser[= ]([\w-]+) --allow-control`?/g, 'extension_dev with { browser: "$1", allowControl: true }').replace(/--allow-control/g, "allowControl: true (extension_dev)").replace(/--allow-eval/g, "allowEval: true (extension_dev)").replace(/Use --context page --tab <id>/g, 'Use context: "page" (targets the active tab; pass url or tab to pick another)').replace(/--context[= ](background|popup|options|sidebar|devtools|newtab|history|bookmarks|content|page)\b/g, 'context: "$1"').replace(/--tab[= ](\d+|<[\w-]+>)/g, "tab: $1").replace(/--url[= ]"([^"]+)"/g, 'url: "$1"').replace(/--url[= ](<[\w-]+>|\S*(?:\/\/|\*)\S*)/g, 'url: "$1"').replace(/--browser[= ]([\w]+-based|chrome|chromium|edge|brave|opera|vivaldi|yandex|firefox|waterfox|librewolf|safari)\b/g, 'browser: "$1"').replace(/--timeout[= ](\d+)/g, "timeout: $1").replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev").replace(/--tab\b/g, "`tab`").replace(/--url\b/g, "`url`").replace(/--context\b/g, "`context`").replace(/--browser\b/g, "`browser`").replace(/--timeout\b/g, "`timeout`");
-}
-function withSessionContext(message, projectPath) {
-    const isControlError = /no active control channel|control channel refused|\b1006\b|no executor connected|is the session started with allowControl/i.test(message);
-    if (!isControlError) return message;
-    const dead = deadReadySession(projectPath);
-    if (dead) return `${message}\nLikely cause: the dev server has exited, ${dead.browser} ready.json still says ready but its pid ${dead.pid} is dead. Restart with extension_dev (this is not an allowControl problem); extension_doctor confirms.`;
-    const running = knownSessionBrowsers(projectPath);
-    if (0 === running.length) return message;
-    return `${message} Active session browser(s) for this project: ${running.join(", ")}, pass that as \`browser\`, or restart it via extension_dev with allowControl: true if the control channel is off.`;
-}
-function translateFrame(frame, projectPath) {
-    if (!frame || false !== frame.ok) return frame;
-    if (frame.error && "string" == typeof frame.error.message) frame.error.message = withSessionContext(toMcpSpeak(frame.error.message), projectPath);
-    if ("string" == typeof frame.error?.hint) frame.error.hint = toMcpSpeak(frame.error.hint);
-    if ("string" == typeof frame.hint) frame.hint = toMcpSpeak(frame.hint);
-    return frame;
-}
-async function runActVerb(args, projectPath, timeoutMs) {
-    const { code, stdout, stderr } = await runExtensionCli([
-        ...args,
-        "--output",
-        "json"
-    ], {
-        cwd: projectPath,
-        timeoutMs
-    });
-    const out = stdout.trim();
-    if (out) try {
-        const frame = JSON.parse(out);
-        if (frame && false === frame.ok) return JSON.stringify(translateFrame(frame, projectPath));
-        return out;
-    } catch  {}
-    const message = stderr.trim() || `extension exited with code ${code}`;
-    return JSON.stringify({
-        ok: false,
-        error: {
-            name: "CliError",
-            message: withSessionContext(toMcpSpeak(message), projectPath)
-        }
-    });
-}
-function commonFlags(args) {
-    const flags = [];
-    if (args.context) flags.push("--context", args.context);
-    if (args.url) flags.push("--url", args.url);
-    if (null != args.tab) flags.push("--tab", String(args.tab));
-    if (args.browser) flags.push("--browser", args.browser);
-    if (null != args.timeout) flags.push("--timeout", String(args.timeout));
-    return flags;
-}
 const eval_schema = {
     name: "extension_eval",
     description: "Evaluate an expression in a running extension context. Requires the dev session to be started with allowEval: true (extension_dev; writes a 0600 session token the CLI reads). Context default: on a Chromium session whose manifest is MV3 (the default template) the default is `page` (the active tab), because the MV3 background is a service worker whose CSP blocks eval, so a background default would fail on the most common path; on Firefox/MV2 sessions the default stays `background`. Pass `context: \"background\"` explicitly to target the worker anyway (on Chromium MV3 that returns the CSP explanation). Targeting for context content/page: pass `url` to pick the matching tab, or omit both `url` and `tab` to use the ACTIVE tab; a numeric `tab` id is only needed to disambiguate. Extension surfaces (popup/options/sidebar/devtools) and override pages (newtab/history/bookmarks) evaluate over the in-bundle relay and need NO tab id; the surface must be OPEN (extension_open first; a closed surface returns an explicit error). Use extension_dom_inspect with listTabs: true to enumerate {tabId,url,title}. Wraps `extension eval`.",
@@ -3984,14 +4690,8 @@ async function pollForTarget(port, url, budgetMs) {
         await new Promise((r)=>setTimeout(r, 250));
     }
 }
-async function navigateToUrl(projectPath, browser, url) {
-    if (!isChromiumFamily(browser)) return JSON.stringify({
-        ok: false,
-        error: {
-            name: "Unsupported",
-            message: `URL navigation drives a tab over Chrome DevTools Protocol, which ${browser} (Gecko) does not expose. On Firefox, drive the page via extension_eval (context: "page"/"content") or read extension_logs.`
-        }
-    });
+async function navigateToUrl(projectPath, browser, url, timeout) {
+    if (!isChromiumFamily(browser)) return navigateToUrlViaBridge(projectPath, browser, url, timeout);
     const resolved = await resolveCdpPort(projectPath, browser);
     if (!resolved) return JSON.stringify({
         ok: false,
@@ -4234,16 +4934,32 @@ async function applyPopupBounds(projectPath, browser, targetId) {
 async function openSurfaceAsTab(projectPath, browser, surface) {
     const doc = surfaceDocument(projectPath, browser, surface);
     if (!doc) return missingSurfaceError(projectPath, browser, surface, "so there is no page to render as a tab");
-    const id = await resolveExtensionId(projectPath, browser);
-    if (!id) return JSON.stringify({
-        ok: false,
-        error: {
-            name: "NoExtensionId",
-            message: "Could not resolve the extension id from the live session's CDP targets."
-        },
-        hint: `Confirm the session is ready (extension_wait). ${CDP_PORT_MISSING_HINT}`
-    });
-    const url = `chrome-extension://${id}/${doc}`;
+    let url;
+    let extensionId = null;
+    if (isChromiumFamily(browser)) {
+        extensionId = await resolveExtensionId(projectPath, browser);
+        if (!extensionId) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoExtensionId",
+                message: "Could not resolve the extension id from the live session's CDP targets."
+            },
+            hint: `Confirm the session is ready (extension_wait). ${CDP_PORT_MISSING_HINT}`
+        });
+        url = `chrome-extension://${extensionId}/${doc}`;
+    } else {
+        const base = await resolveBridgeBaseUrl(projectPath, browser);
+        if (!base) return JSON.stringify({
+            ok: false,
+            error: {
+                name: "NoExtensionId",
+                message: "Could not resolve the extension's moz-extension:// base URL from the live session (a background eval of runtime.getURL)."
+            },
+            hint: "Confirm the session is ready (extension_wait) and was started with allowEval: true (extension_dev)."
+        });
+        url = `${base}${doc}`;
+        extensionId = base.replace(/^.*:\/\//, "").replace(/\/$/, "");
+    }
     const raw = await navigateToUrl(projectPath, browser, url);
     try {
         const parsed = JSON.parse(raw);
@@ -4251,14 +4967,14 @@ async function openSurfaceAsTab(projectPath, browser, surface) {
             parsed.renderedAsTab = {
                 surface,
                 document: doc,
-                extensionId: id
+                extensionId
             };
             let popupBounds = null;
             if (("popup" === surface || "action" === surface) && "string" == typeof parsed.target?.targetId) {
                 popupBounds = await applyPopupBounds(projectPath, browser, parsed.target.targetId);
                 if (popupBounds) parsed.renderedAsTab.popupBounds = popupBounds;
             }
-            parsed.hint = `Rendered the ${surface} document in a real tab, which is how you inspect a surface headlessly. ` + (popupBounds ? `The window was resized to the popup's content size (${popupBounds.width}x${popupBounds.height}${popupBounds.clamped ? ", clamped to Chrome's 25x25-800x600 popup bounds" : ""}), approximating real popup rendering. This resizes the WHOLE browser window for the session. It is the same page with the same extension APIs, but window.close() closes the tab. ` : "It is the same page with the same extension APIs, but it is NOT hosted in a popup window: no popup sizing, and window.close() closes the tab. ") + `Inspect it with extension_dom_inspect context: '${surface}' (include: ['html']), or extension_source_inspect with this url. ` + "Do NOT pass this chrome-extension:// url to extension_dom_inspect or extension_eval as a tab target: script injection cannot reach extension pages, only the surface context or CDP can.";
+            parsed.hint = `Rendered the ${surface} document in a real tab, which is how you inspect a surface headlessly. ` + (popupBounds ? `The window was resized to the popup's content size (${popupBounds.width}x${popupBounds.height}${popupBounds.clamped ? ", clamped to Chrome's 25x25-800x600 popup bounds" : ""}), approximating real popup rendering. This resizes the WHOLE browser window for the session. It is the same page with the same extension APIs, but window.close() closes the tab. ` : "It is the same page with the same extension APIs, but it is NOT hosted in a popup window: no popup sizing, and window.close() closes the tab. ") + `Inspect it with extension_dom_inspect context: '${surface}' (include: ['html']), or extension_source_inspect with this url. ` + "Do NOT pass this extension-page url to extension_dom_inspect or extension_eval as a tab target: script injection cannot reach extension pages, only the surface context or CDP can.";
             return JSON.stringify(parsed);
         }
     } catch  {}
@@ -4294,7 +5010,7 @@ const open_schema = {
             },
             url: {
                 type: "string",
-                description: "Navigate a real tab to this URL (Chromium only, via CDP) instead of opening a surface. Use for content-script/webNavigation test pages, or the popup as a page: chrome-extension://<id>/popup.html. Alternative to `surface`."
+                description: "Navigate a real tab to this URL instead of opening a surface (Chromium via CDP; Firefox via the agent bridge, which needs allowEval: true). Use for content-script/webNavigation test pages, or the popup as a page: chrome-extension://<id>/popup.html. Alternative to `surface`."
             },
             asTab: {
                 type: "boolean",
@@ -4317,7 +5033,7 @@ const open_schema = {
 };
 async function open_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
-    if (args.url) return navigateToUrl(args.projectPath, browser, args.url);
+    if (args.url) return navigateToUrl(args.projectPath, browser, args.url, args.timeout);
     const AS_TAB_SURFACES = [
         "popup",
         "options",
@@ -4368,7 +5084,7 @@ async function open_handler(args) {
         const parsed = JSON.parse(raw);
         const msg = String(parsed?.error?.message ?? "");
         if (parsed?.ok === false && /active browser window|no active|headless|user gesture/i.test(msg)) {
-            if (AS_TAB_SURFACES.includes(args.surface) && isChromiumFamily(browser)) {
+            if (AS_TAB_SURFACES.includes(args.surface)) {
                 const fallback = await openSurfaceAsTab(args.projectPath, browser, args.surface);
                 try {
                     const parsedFallback = JSON.parse(fallback);
@@ -4402,9 +5118,10 @@ function matchTargetsByUrl(targets, needle) {
     if (byUrl.length > 0) return byUrl;
     return targets.filter((t)=>t.title.toLowerCase().includes(wanted));
 }
+const RDP_ACTOR_NOTE = "actor is an RDP tab descriptor actor id, NOT a chrome.tabs id: do not pass it as `tab`. Target a tab with `tabUrl` (URL substring) or `url`; if you need a numeric tab id, call extension_dom_inspect with listTabs: true.";
 const dom_inspect_schema = {
     name: "extension_dom_inspect",
-    description: "Inspect a page/content-script DOM via the agent bridge (CDP-free, localhost). Returns a structured snapshot (counts, extension roots, open shadow roots, optional capped HTML). Target a tab by `tabUrl` (case-insensitive URL substring resolved against the browser's live page targets; zero or several matches return the candidates instead of guessing), by `url`, or by numeric `tab`. Discover what is open with listTargets: true (CDP targetIds) or listTabs: true (numeric chrome.tabs ids). Requires the dev session to be started with allowControl: true (extension_dev). For closed shadow roots or deep CDP inspection use extension_source_inspect. Wraps `extension inspect`.",
+    description: "Inspect a page/content-script DOM via the agent bridge (CDP-free, localhost). Returns a structured snapshot (counts, extension roots, open shadow roots, optional capped HTML). Target a tab by `tabUrl` (case-insensitive URL substring resolved against the browser's live page targets; zero or several matches return the candidates instead of guessing), by `url`, or by numeric `tab`. Discover what is open with listTargets: true (Chromium CDP targetIds; Firefox RDP tab actors) or listTabs: true (numeric chrome.tabs ids). Requires the dev session to be started with allowControl: true (extension_dev). For closed shadow roots or deep CDP inspection use extension_source_inspect. Wraps `extension inspect`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -4422,12 +5139,12 @@ const dom_inspect_schema = {
             },
             tabUrl: {
                 type: "string",
-                description: "Target the tab whose URL contains this substring (case-insensitive; titles are checked only when no url matches). Resolved against the live browser's CDP page targets BEFORE inspecting: exactly one match proceeds; zero or several matches return the candidate targets (targetId/url/title) so you can narrow, never a guess. Chromium sessions only; on Firefox use `url`/`tab`. Alternative to `url`."
+                description: "Target the tab whose URL contains this substring (case-insensitive; titles are checked only when no url matches). Resolved against the live browser BEFORE inspecting (Chromium: CDP page targets; Firefox: the agent bridge tab list): exactly one match proceeds; zero or several matches return the candidates so you can narrow, never a guess. Alternative to `url`."
             },
             listTargets: {
                 type: "boolean",
                 default: false,
-                description: "Enumerate the browser's CDP page targets as {targetId,url,title,type} and return, ignoring the other args. The discovery path for `tabUrl`. targetId is a CDP target id, NOT a numeric chrome.tabs id (for those use listTabs)."
+                description: "Enumerate the browser's live page targets and return, ignoring the other args. The discovery path for `tabUrl`. Chromium: CDP page targets as {targetId,url,title,type}. Firefox: RDP tab descriptors as {actor,url,title,type} (engine 4.0.15+). Neither id is a numeric chrome.tabs id (for those use listTabs)."
             },
             listTabs: {
                 type: "boolean",
@@ -4517,6 +5234,43 @@ async function dom_inspect_handler(args) {
     const withConsole = true === args.withConsole ? 50 : false === args.withConsole ? void 0 : args.withConsole;
     if (args.listTargets) {
         const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
+        if (isGeckoFamily(browser)) {
+            const resolved = await resolveRdpPort(args.projectPath, browser);
+            if (!resolved) return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "NoSession",
+                    message: `No active dev session with a Firefox debugger server (RDP) for ${browser}, so listTargets has no browser to ask. Start extension_dev and extension_wait for ready. ${RDP_PORT_MISSING_HINT}`
+                }
+            });
+            try {
+                const tabs = await rdpListTabs(resolved.port);
+                return JSON.stringify({
+                    ok: true,
+                    browser,
+                    transport: "rdp",
+                    targets: tabs.map((t)=>({
+                            actor: String(t.actor ?? ""),
+                            type: "tab",
+                            url: String(t.url ?? ""),
+                            title: String(t.title ?? ""),
+                            ...true === t.selected ? {
+                                selected: true
+                            } : {}
+                        })),
+                    note: RDP_ACTOR_NOTE
+                });
+            } catch (e) {
+                return JSON.stringify({
+                    ok: false,
+                    error: {
+                        name: "RdpError",
+                        message: `Could not list tab targets over RDP: ${e instanceof Error ? e.message : String(e)}`
+                    },
+                    hint: "Confirm the session is ready (extension_wait), then retry. listTabs: true is the bridge alternative (needs allowControl)."
+                });
+            }
+        }
         const cdp = await cdpPortOrError(args.projectPath, browser, "listTargets");
         if ("error" in cdp) return cdp.error;
         try {
@@ -4550,6 +5304,7 @@ async function dom_inspect_handler(args) {
         ] : []
     ], args.projectPath, args.timeout);
     let targetUrl = args.url;
+    let targetTab = args.tab;
     let resolvedTarget = null;
     if (args.tabUrl) {
         if (null != args.tab || args.url) return JSON.stringify({
@@ -4560,48 +5315,79 @@ async function dom_inspect_handler(args) {
             }
         });
         const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
-        const cdp = await cdpPortOrError(args.projectPath, browser, "tabUrl");
-        if ("error" in cdp) return cdp.error;
-        let targets;
-        try {
-            targets = await listPageTargets(cdp.port);
-        } catch (e) {
-            return JSON.stringify({
+        if (isChromiumFamily(browser)) {
+            const cdp = await cdpPortOrError(args.projectPath, browser, "tabUrl");
+            if ("error" in cdp) return cdp.error;
+            let targets;
+            try {
+                targets = await listPageTargets(cdp.port);
+            } catch (e) {
+                return JSON.stringify({
+                    ok: false,
+                    error: {
+                        name: "CdpError",
+                        message: `Could not list page targets to resolve tabUrl: ${e instanceof Error ? e.message : String(e)}`
+                    },
+                    hint: "Confirm the session is ready (extension_wait), then retry, or target with `url`/`tab` instead."
+                });
+            }
+            const matches = matchTargetsByUrl(targets, args.tabUrl);
+            if (0 === matches.length) return JSON.stringify({
                 ok: false,
                 error: {
-                    name: "CdpError",
-                    message: `Could not list page targets to resolve tabUrl: ${e instanceof Error ? e.message : String(e)}`
+                    name: "NoMatchingTarget",
+                    message: `No open page target's url (or title) contains "${args.tabUrl}" (case-insensitive).`
+                },
+                availableTargets: targets,
+                hint: `Pick one from availableTargets and retry with a \`tabUrl\` substring of its url, or open the page first (extension_open with \`url\`). ${TARGET_ID_NOTE}`
+            });
+            if (matches.length > 1) return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "AmbiguousTabUrl",
+                    message: `${matches.length} page targets match "${args.tabUrl}"; refusing to guess which tab you mean.`
+                },
+                matchingTargets: matches,
+                hint: `Narrow \`tabUrl\` to a longer substring that matches exactly one url in matchingTargets. ${TARGET_ID_NOTE}`
+            });
+            resolvedTarget = {
+                ...matches[0]
+            };
+            targetUrl = matches[0].url;
+        } else {
+            const listed = await listBridgeTabs(args.projectPath, browser, args.timeout);
+            if ("error" in listed) return listed.error;
+            const matches = matchTabsByUrl(listed.tabs, args.tabUrl);
+            if (0 === matches.length) return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "NoMatchingTarget",
+                    message: `No open tab's url (or title) contains "${args.tabUrl}" (case-insensitive).`
                 },
-                hint: "Confirm the session is ready (extension_wait), then retry, or target with `url`/`tab` instead."
+                availableTabs: listed.tabs,
+                hint: "Pick one from availableTabs and retry with a `tabUrl` substring of its url, or open the page first (extension_open with `url`)."
             });
+            if (matches.length > 1) return JSON.stringify({
+                ok: false,
+                error: {
+                    name: "AmbiguousTabUrl",
+                    message: `${matches.length} tabs match "${args.tabUrl}"; refusing to guess which tab you mean.`
+                },
+                matchingTabs: matches,
+                hint: "Narrow `tabUrl` to a longer substring that matches exactly one url in matchingTabs, or pass its numeric tabId as `tab`."
+            });
+            resolvedTarget = {
+                ...matches[0]
+            };
+            if (null != matches[0].tabId) targetTab = matches[0].tabId;
+            else targetUrl = matches[0].url;
         }
-        const matches = matchTargetsByUrl(targets, args.tabUrl);
-        if (0 === matches.length) return JSON.stringify({
-            ok: false,
-            error: {
-                name: "NoMatchingTarget",
-                message: `No open page target's url (or title) contains "${args.tabUrl}" (case-insensitive).`
-            },
-            availableTargets: targets,
-            hint: `Pick one from availableTargets and retry with a \`tabUrl\` substring of its url, or open the page first (extension_open with \`url\`). ${TARGET_ID_NOTE}`
-        });
-        if (matches.length > 1) return JSON.stringify({
-            ok: false,
-            error: {
-                name: "AmbiguousTabUrl",
-                message: `${matches.length} page targets match "${args.tabUrl}"; refusing to guess which tab you mean.`
-            },
-            matchingTargets: matches,
-            hint: `Narrow \`tabUrl\` to a longer substring that matches exactly one url in matchingTargets. ${TARGET_ID_NOTE}`
-        });
-        resolvedTarget = matches[0];
-        targetUrl = resolvedTarget.url;
     }
     const cli = [
         "inspect",
         args.projectPath
     ];
-    if (null != args.tab) cli.push("--tab", String(args.tab));
+    if (null != targetTab) cli.push("--tab", String(targetTab));
     if (targetUrl) cli.push("--url", targetUrl);
     if (args.context) cli.push("--context", args.context);
     if (args.include?.length) cli.push("--include", args.include.join(","));