@extension.dev/mcp 10.10.0 → 10.10.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "extension-mcp",
       "source": "./",
       "description": "MCP tools for browser extension development: scaffold from 50+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox.",
-      "version": "10.10.0",
+      "version": "10.10.1",
       "category": "development",
       "author": {
         "name": "Cezar Augusto"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "extension-mcp",
   "description": "MCP tools for browser extension development: scaffold from 50+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox. Ships /extension, /extension-add, /extension-debug, and /extension-publish commands.",
-  "version": "10.10.0",
+  "version": "10.10.1",
   "author": {
     "name": "Cezar Augusto",
     "email": "hello@extension.dev",

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## 10.10.1
+
+Five Gecko findings from one agent session on Firefox and Waterfox
+(BUGS_TO_FIX_MCP.md entries 5 to 9), each replayed against a live Firefox
+Nightly before and after the fix where the shape allowed it, plus four more
+that followed them the same week, and the engine release that carries the
+root-cause fix for the first of them.
+
+- `extension-create`, `extension-develop` and `extension-install` move from
+  4.1.29 to 4.1.30. That engine settles a promise before a surface relay
+  replies to an eval (the root cause behind the first entry below, filed
+  from this repo as extension.js 512), names a missing tab, a refused url,
+  a closed surface and a browser exit on every act verb instead of a
+  generic refusal, and lets `reload` resolve a surface's tab. The relay
+  wrapper below stays: a project that pins an older engine in its own
+  node_modules still drives that engine.
+
+- `extension_eval` on a surface that answers through the in-bundle relay
+  (every Gecko session, and Chromium MV2) never hands the relay a promise.
+  The relay evaluates synchronously and passes the raw value to
+  `sendResponse`; a promise is not cloneable, Firefox reports that to the
+  sender as no reply, and the bridge then called the surface "not open"
+  while the page was still running the expression. The wrapper now settles
+  a thenable inside the page under a token, and the tool polls until it is
+  done: an async expression returns its value, a rejection answers `E_EVAL`
+  with the page's own message, and one that never settles answers
+  `E_WAIT_TIMEOUT` naming where the result will land. The engine's "open it
+  first: extension open newtab" hint is now spoken as the tool call it means.
+- `extension_inspect` on Gecko reads a page inside the extension through
+  its surface relay: a url that matches a declared surface document (the
+  full `moz-extension://` address, the document path, or its file name)
+  routes to that context instead of the tab injection, which Firefox
+  refuses into extension pages with "Missing host permission for the tab".
+  An extension url that matches no declared surface says so and names the
+  ones the manifest declares.
+- `extension_stop` reaps the browser the launcher recorded in `ready.json`
+  (`browserPid`, `launcherPid`, and any process holding `profilePath`), so
+  a Firefox started on a custom profile, or one whose argv never names the
+  project, no longer survives a `stopped` answer with `reaped: []`.
+- `extension_doctor` no longer calls a Gecko session unhealthy over a
+  browser exit that the executor outlived: Firefox hands a fresh profile to
+  a relaunched process and the first one exits 0, which the engine's browser
+  leg reports as a failure while storage probes and evals keep answering.
+  That leg becomes a warning that says so, and any other failure still
+  counts.
+- `extension_browsers` detect finds a managed binary as deep as the cache
+  writes it (a Firefox Nightly sits six levels down inside its app bundle),
+  so it no longer reports the system Firefox as available while
+  `extension_dev` launches the cached Nightly. When both exist, the entry
+  carries `systemBinaryPath` and a `devLaunches` line saying which one dev
+  starts and how to choose the other. `extension_wait` reports `browserPid`
+  and `profilePath` from the contract.
+- `extension_open` with surface `sidebar` on Gecko no longer stops at the
+  engine's "sidePanel not available", a Chromium API named on a Firefox
+  engine. It asks the sidebar relay whether the `sidebar_action` panel is
+  open and reports `status: "already-open"` when it is (Firefox opens the
+  panel at install, so it usually is); when it is not, the document is
+  rendered as a tab with the gesture rule stated (Firefox opens the panel
+  only from the toolbar button or View > Sidebar, Bugzilla 1392624).
+- `extension_eval` with context `page` and a `moz-extension://` url on
+  Gecko evaluates through the surface relay of the document that url names,
+  with a warning naming the context to pass next time, instead of "chrome.
+  scripting is not available ... use context background". An extension url
+  that matches no declared surface says which surfaces the manifest
+  declares. The url-to-surface mapping now lives in one place for inspect
+  and eval.
+- `extension_dev` with `port: 0` no longer warns "Requested port 0 was not
+  available": 0 asks the engine for any free port, so the note now says
+  which port it picked, and the collision wording stays for a numbered port
+  the server could not bind.
+
 ## 10.10.0
 
 Safari was the one engine this server treated as a dead end, while the

package/dist/module.js

@@ -192,6 +192,7 @@ __webpack_require__.d(start_namespaceObject, {
 var stop_namespaceObject = {};
 __webpack_require__.r(stop_namespaceObject);
 __webpack_require__.d(stop_namespaceObject, {
+    contractProcessHints: ()=>contractProcessHints,
     handler: ()=>stop_handler,
     schema: ()=>stop_schema,
     stopOne: ()=>stopOne
@@ -227,7 +228,7 @@ __webpack_require__.d(wait_namespaceObject, {
     handler: ()=>wait_handler,
     schema: ()=>wait_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"10.10.0","El":{"OP":"4.1.29"}}');
+var package_namespaceObject = JSON.parse('{"rE":"10.10.1","El":{"OP":"4.1.30"}}');
 const ENVELOPE_SCHEMA = 1;
 const collectWarnings = (warnings)=>{
     if (!warnings) return [];
@@ -4104,8 +4105,31 @@ function processCommand(pid) {
         return "";
     }
 }
-function sessionProcessPids(projectPath) {
+function contractProcessHints(projectPath, browser) {
+    try {
+        const contract = JSON.parse(node_fs.readFileSync(bridge_readyContractPath(projectPath, browser), "utf8"));
+        const pids = [
+            contract.browserPid,
+            contract.launcherPid
+        ].filter((pid)=>"number" == typeof pid && Number.isInteger(pid) && pid > 0);
+        return {
+            ..."string" == typeof contract.profilePath && contract.profilePath.trim() ? {
+                profilePath: contract.profilePath
+            } : {},
+            pids
+        };
+    } catch  {
+        return {
+            pids: []
+        };
+    }
+}
+function sessionProcessPids(projectPath, hints = {
+    pids: []
+}) {
     const pids = new Set();
+    if (hints.profilePath) for (const pid of pgrepPids(escapeRegex(hints.profilePath)))pids.add(pid);
+    for (const pid of hints.pids)if (pid !== process.pid && isAlive(pid)) pids.add(pid);
     for (const form of projectPathForms(projectPath)){
         const escaped = escapeRegex(form);
         const patterns = [
@@ -4118,8 +4142,10 @@ function sessionProcessPids(projectPath) {
         ...pids
     ].filter((pid)=>PLAUSIBLE_SESSION_BINARY.test(processCommand(pid)));
 }
-function reapSessionProcesses(projectPath) {
-    const pids = sessionProcessPids(projectPath);
+function reapSessionProcesses(projectPath, hints = {
+    pids: []
+}) {
+    const pids = sessionProcessPids(projectPath, hints);
     for (const pid of pids)try {
         process.kill(pid, "SIGKILL");
     } catch  {}
@@ -4158,8 +4184,9 @@ function pidFromReadyContract(projectPath, browser) {
 async function stopOne(projectPath, browser) {
     const session = findSessionInfo(projectPath, browser);
     const pid = session?.pid ?? pidFromReadyContract(projectPath, browser);
+    const hints = contractProcessHints(projectPath, browser);
     if (null == pid) {
-        const reaped = reapSessionProcesses(projectPath);
+        const reaped = reapSessionProcesses(projectPath, hints);
         removeSessionMarker(projectPath, browser);
         return {
             projectPath,
@@ -4181,7 +4208,7 @@ async function stopOne(projectPath, browser) {
         }
         detail = isAlive(pid) ? "Sent SIGTERM and SIGKILL but the process still reports alive; it may be exiting." : "Terminated.";
     } else detail = "Process was already gone; cleaned up session records.";
-    const reaped = reapSessionProcesses(projectPath);
+    const reaped = reapSessionProcesses(projectPath, hints);
     removeSession(projectPath, browser);
     removeSessionMarker(projectPath, browser);
     try {
@@ -4189,7 +4216,7 @@ async function stopOne(projectPath, browser) {
             force: true
         });
     } catch  {}
-    const survivors = sessionProcessPids(projectPath);
+    const survivors = sessionProcessPids(projectPath, hints);
     const stopped = !isAlive(pid) && 0 === survivors.length;
     if (survivors.length) detail += ` Warning: ${survivors.length} browser process(es) still alive after reap (pids ${survivors.join(", ")}).`;
     else if (reaped.length) detail += ` Reaped ${reaped.length} browser process(es).`;
@@ -4553,7 +4580,8 @@ async function dev_handler(args) {
     } : {
         requestedPort: args.port ?? 8080
     };
-    const portNote = null !== boundPort ? void 0 !== args.port && args.port !== boundPort ? `Requested port ${args.port} was not available; the dev server bound ${boundPort} (read from the engine's ready.json contract, the same source extension_wait reports).` : null : "The engine has not stamped its ready.json contract yet, so the bound port is not known at response time (a taken port makes the server bind the next free one). extension_wait reports the bound port from that contract once it lands; requestedPort above is only what was asked for.";
+    const autoAssigned = 0 === args.port;
+    const portNote = null !== boundPort ? void 0 !== args.port && args.port !== boundPort ? autoAssigned ? `Port 0 asked the engine for any free port and it picked ${boundPort} (read from the engine's ready.json contract, the same source extension_wait reports).` : `Requested port ${args.port} was not available; the dev server bound ${boundPort} (read from the engine's ready.json contract, the same source extension_wait reports).` : null : autoAssigned ? "Port 0 asked the engine for any free port, and it has not stamped its ready.json contract yet, so the port it picked is not known at response time. extension_wait reports it from that contract once it lands." : "The engine has not stamped its ready.json contract yet, so the bound port is not known at response time (a taken port makes the server bind the next free one). extension_wait reports the bound port from that contract once it lands; requestedPort above is only what was asked for.";
     return envelope_envelope({
         ok: true,
         command: dev_schema.name,
@@ -4743,7 +4771,7 @@ async function start_handler(args) {
     });
 }
 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`");
+    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(/\bextension open (popup|options|sidebar|newtab|history|bookmarks)\b/g, 'extension_open with surface: "$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`");
 }
 const CONTROL_CHANNEL_DOWN_CODES = new Set([
     "E_CONTROL_DENIED",
@@ -6606,6 +6634,10 @@ async function open_handler(args) {
         const refusal = readGestureRefusal(raw);
         if (refusal) return openSidebarThroughGesture(args.projectPath, browser, refusal);
     }
+    if ("sidebar" === args.surface && isGeckoFamily(browser)) {
+        const refusal = readUnsupportedRefusal(raw);
+        if (refusal) return openGeckoSidebar(args.projectPath, browser, refusal, args.timeout);
+    }
     return AS_TAB_SURFACES.includes(args.surface) ? confirmSurfaceTarget(args.projectPath, browser, args.surface, raw) : raw;
 }
 const E_USER_GESTURE_REQUIRED = "E_USER_GESTURE_REQUIRED";
@@ -6621,6 +6653,73 @@ function readGestureRefusal(raw) {
     const message = String(parsed.error?.message ?? "");
     return code === E_USER_GESTURE_REQUIRED || /user gesture/i.test(message) ? parsed : null;
 }
+function readUnsupportedRefusal(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch  {
+        return null;
+    }
+    if (parsed?.ok !== false) return null;
+    const code = "string" == typeof parsed.error?.code ? parsed.error.code : "";
+    const message = String(parsed.error?.message ?? "");
+    return "E_NOT_IMPLEMENTED" === code || /not available/i.test(message) ? parsed : null;
+}
+const GECKO_SIDEBAR_GESTURE = "Firefox opens a sidebar_action panel only from a user gesture (the toolbar button or View > Sidebar; Bugzilla 1392624), and the engine's open verb carries none, so it cannot open the panel";
+async function openGeckoSidebar(projectPath, browser, refusal, timeout) {
+    const doc = surfaceDocument(projectPath, browser, "sidebar");
+    if (!doc) return missingSurfaceError(projectPath, browser, "sidebar", "so there is no sidebar panel to open");
+    const probe = await runActVerb([
+        "inspect",
+        projectPath,
+        "--context",
+        "sidebar",
+        "--include",
+        "summary",
+        "--browser",
+        browser,
+        ...null != timeout ? [
+            "--timeout",
+            String(timeout)
+        ] : []
+    ], projectPath, timeout, open_schema.name);
+    let open = null;
+    try {
+        const parsed = JSON.parse(probe);
+        if (parsed?.ok === true) open = parsed;
+    } catch  {}
+    if (open) {
+        const url = "string" == typeof open.value?.url ? open.value.url : "string" == typeof open.value?.meta?.url ? open.value.meta.url : void 0;
+        return envelope_envelope({
+            ok: true,
+            command: open_schema.name,
+            status: "already-open",
+            value: {
+                surface: "sidebar",
+                document: doc,
+                alreadyOpen: true,
+                ...url ? {
+                    url
+                } : {}
+            },
+            hint: `The sidebar panel is open in the ${browser} window already: read it with extension_dom_snapshot context: 'sidebar' or run code in it with extension_eval context: 'sidebar'. ${GECKO_SIDEBAR_GESTURE}, and it did not need to.`
+        });
+    }
+    const fallback = await openSurfaceAsTab(projectPath, browser, "sidebar");
+    try {
+        const parsedFallback = JSON.parse(fallback);
+        if (parsedFallback?.ok) {
+            addWarning(parsedFallback, `${GECKO_SIDEBAR_GESTURE}, and the panel is not open now, so the sidebar document was rendered as a tab instead. The DOM is the same document the panel would show; the panel hosting stays unverified. A person opens the real panel from the toolbar button or View > Sidebar.`);
+            return actFrameJson(parsedFallback);
+        }
+    } catch  {}
+    refusal.error = {
+        ...refusal.error ?? {},
+        message: `${GECKO_SIDEBAR_GESTURE}. Rendering the document ${doc} as a tab failed as well.`
+    };
+    refusal.hint = "Start the session with allowEval: true so the document can be opened by url through the bridge, or open the panel from the toolbar button in the dev browser and read it with extension_dom_snapshot context: 'sidebar'.";
+    return actFrameJson(refusal);
+}
 const SIDEBAR_GESTURE_WARNING = "Chrome opens the side panel only from a user gesture and the engine's open verb carries none, so the server opened the extension's own sidebar page in a tab, dispatched a synthetic click on it over CDP and called chrome.sidePanel.open from inside that click, then closed the tab. The panel that opened is the real one; the toolbar wiring (action.onClicked or sidePanel.setPanelBehavior) was not exercised.";
 async function openSidebarThroughGesture(projectPath, browser, refusal) {
     const doc = surfaceDocument(projectPath, browser, "sidebar");
@@ -8949,6 +9048,25 @@ function capabilityProbeChecks(parsed) {
     return value?.checks;
 }
 const CONTROL_OFF_BY_CHOICE = /\bwas not started with --allow-control\b/i;
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function reconcileRelaunchedBrowser(checks, contract) {
+    const exitedLeg = checks.find((leg)=>"browser" === leg.check && "fail" === leg.status && /\bexited\b/i.test(String(leg.detail ?? "")));
+    if (!exitedLeg) return false;
+    const executorAnswered = checks.some((leg)=>("executor" === leg.check || "control-channel" === leg.check) && "pass" === leg.status);
+    const browserAlive = "number" == typeof contract?.browserPid && pidIsAlive(contract.browserPid);
+    if (!executorAnswered && !browserAlive) return false;
+    exitedLeg.status = "warn";
+    exitedLeg.detail = `${exitedLeg.detail ?? "browser exited"}. ${browserAlive ? `The browser pid the launcher recorded (${contract?.browserPid}) is alive` : "The executor answered a probe after that exit"}, so the session is live and the recorded exit was an earlier process: Firefox hands a fresh profile to a relaunched process and the first one exits 0.`;
+    exitedLeg.remediation = "Nothing to do. If a later call finds the session unreachable, extension_stop and extension_dev again.";
+    return true;
+}
 function controlOffByChoiceLeg(checks) {
     return checks.find((leg)=>"control-channel" === leg.check && "fail" === leg.status && "string" == typeof leg.detail && CONTROL_OFF_BY_CHOICE.test(leg.detail)) ?? null;
 }
@@ -8991,17 +9109,9 @@ async function doctor_handler(args) {
         }
         let healthy = 0 === code;
         const contract = readContractForDiagnosis(projectPath, browser);
-        if (contract?.status === "error") {
-            healthy = false;
-            const browserExited = "browser_exited" === contract.code || void 0 !== contract.browserExitCode;
-            const detail = browserExited ? `The ${browser} browser for this session exited unexpectedly${null != contract.browserExitCode ? ` (exit code ${contract.browserExitCode})` : ""}; the extension may have been rejected or the browser crashed. The session cannot be driven.` : contract.errors && contract.errors.length ? contract.errors.join("; ") : contract.message || "The dev session recorded status: error in ready.json.";
-            checks.push({
-                check: "runtime-errors",
-                status: "fail",
-                detail: toMcpSpeak(detail),
-                remediation: browserExited ? "Read extension_logs and the session log for the rejection cause, call extension_stop to clean up, then relaunch." : "The build or extension load failed. Fix the reported error, let the dev server recompile, then re-run doctor."
-            });
-        } else {
+        const relaunched = reconcileRelaunchedBrowser(checks, contract);
+        if (relaunched) healthy = !checks.some((leg)=>"fail" === leg.status);
+        if (contract?.status !== "error" || relaunched) {
             const errs = recentErrorLogs(projectPath, browser);
             if (errs.length) {
                 healthy = false;
@@ -9012,6 +9122,16 @@ async function doctor_handler(args) {
                     remediation: "The extension is throwing at runtime. Inspect with extension_logs. A chrome.* API called without its permission is a common cause: extension_manifest_validate catches a permission MISSING FROM permissions[], but it does not model host-permission scope (e.g. webRequest with no matching host_permissions) or gesture requirements (e.g. activeTab without a user gesture), so a valid:true there does not rule those out."
                 });
             }
+        } else {
+            healthy = false;
+            const browserExited = "browser_exited" === contract.code || void 0 !== contract.browserExitCode;
+            const detail = browserExited ? `The ${browser} browser for this session exited unexpectedly${null != contract.browserExitCode ? ` (exit code ${contract.browserExitCode})` : ""}; the extension may have been rejected or the browser crashed. The session cannot be driven.` : contract.errors && contract.errors.length ? contract.errors.join("; ") : contract.message || "The dev session recorded status: error in ready.json.";
+            checks.push({
+                check: "runtime-errors",
+                status: "fail",
+                detail: toMcpSpeak(detail),
+                remediation: browserExited ? "Read extension_logs and the session log for the rejection cause, call extension_stop to clean up, then relaunch." : "The build or extension load failed. Fix the reported error, let the dev server recompile, then re-run doctor."
+            });
         }
         const engineVersion = projectEngineVersion(projectPath);
         if (engineVersion) {
@@ -11967,6 +12087,32 @@ const inspect_schema_schema = {
         ]
     }
 };
+const EXTENSION_PAGE_CONTEXTS = [
+    "popup",
+    "options",
+    "sidebar",
+    "newtab",
+    "history",
+    "bookmarks"
+];
+const EXTENSION_ORIGIN = /^(moz|chrome|safari-web)-extension:\/\//;
+function isExtensionUrl(url) {
+    return "string" == typeof url && EXTENSION_ORIGIN.test(url);
+}
+function surfaceForExtensionUrl(projectPath, browser, url) {
+    const bare = url.replace(EXTENSION_ORIGIN, "").replace(/^[^/]*\//, (m)=>EXTENSION_ORIGIN.test(url) ? "" : m).replace(/^\.?\//, "").replace(/[?#].*$/, "");
+    if (!bare) return null;
+    for (const context of EXTENSION_PAGE_CONTEXTS){
+        const document = surfaceDocument(projectPath, browser, context);
+        if (document) {
+            if (bare === document || bare.endsWith(`/${document}`) || document.endsWith(`/${bare}`)) return {
+                context,
+                document
+            };
+        }
+    }
+    return null;
+}
 const inspect_gecko_TOOL = inspect_schema_schema.name;
 function buildBridgeInspectExpression(opts) {
     const parts = [
@@ -12084,7 +12230,22 @@ async function collectGeckoConsole(args, browser, urlFilter, result, notes) {
 }
 async function inspectViaBridge(args, browser, include, maxBytes) {
     const notes = [];
-    if (args.url) {
+    const surface = args.url ? surfaceForExtensionUrl(args.projectPath, browser, args.url) : null;
+    if (args.url && !surface && EXTENSION_ORIGIN.test(args.url)) {
+        const declared = declaredSurfaces(args.projectPath, browser) ?? [];
+        return envelope_envelope({
+            ok: false,
+            command: inspect_gecko_TOOL,
+            status: "no-surface",
+            error: {
+                code: "E_NO_SURFACE_DOCUMENT",
+                name: "NoSurfaceDocument",
+                message: `${args.url} is a page inside the extension, and on ${browser} a page inside the extension is read through its own surface relay, but that path matches none of the surface documents the manifest declares${declared.length ? ` (${declared.join(", ")})` : ""}. Script injection cannot reach an extension page at all.`
+            },
+            hint: declared.length ? `Pass the declared document path (extension_open surface: "${declared[0]}" opens one), or read it with extension_dom_snapshot context: "${declared[0]}".` : "Declare the page as a surface in the manifest (action.default_popup, options_ui.page, sidebar_action.default_panel or chrome_url_overrides) and rebuild."
+        });
+    }
+    if (args.url && !surface) {
         const listed = await listBridgeTabs(args.projectPath, browser, args.timeout, inspect_gecko_TOOL);
         if ("error" in listed) return listed.error;
         const already = listed.tabs.some((t)=>t.url.includes(args.url));
@@ -12111,8 +12272,8 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
         expression,
         args.projectPath,
         "--context",
-        "page",
-        ...args.url ? [
+        surface ? surface.context : "page",
+        ...args.url && !surface ? [
             "--url",
             args.url
         ] : [],
@@ -12166,7 +12327,11 @@ async function inspectViaBridge(args, browser, include, maxBytes) {
     if (null === value) return raw;
     const result = {
         browser,
-        transport: "bridge"
+        transport: "bridge",
+        ...surface ? {
+            surface: surface.context,
+            document: surface.document
+        } : {}
     };
     if (value.meta) {
         result.target = {
@@ -12642,6 +12807,69 @@ async function listGeckoExtensions(projectPath, browser) {
         });
     }
 }
+const RELAY_MARK = "__extensionDevRelay";
+function cloneHelper() {
+    return `var clone = function (v) {
+    if (v === undefined) return null;
+    try {
+      if (typeof structuredClone === "function") { structuredClone(v); return v; }
+      return JSON.parse(JSON.stringify(v));
+    } catch (e) { return String(v); }
+  };`;
+}
+function relaySafeExpression(expression, token) {
+    const src = JSON.stringify(expression);
+    const key = JSON.stringify(token);
+    return `(function () {
+  ${cloneHelper()}
+  var value = (0, eval)(${src});
+  if (value && typeof value.then === "function") {
+    var store = globalThis.${RELAY_MARK} = globalThis.${RELAY_MARK} || {};
+    store[${key}] = { done: false };
+    Promise.resolve(value).then(function (settled) {
+      store[${key}] = { done: true, ok: true, value: clone(settled) };
+    }, function (error) {
+      store[${key}] = { done: true, ok: false, name: (error && error.name) || "EvalError", message: (error && error.message) || String(error) };
+    });
+    return { ${RELAY_MARK}: 1, done: false, token: ${key} };
+  }
+  return { ${RELAY_MARK}: 1, done: true, ok: true, value: clone(value) };
+})()`;
+}
+function relayPollExpression(token) {
+    const key = JSON.stringify(token);
+    return `(function () {
+  var store = globalThis.${RELAY_MARK};
+  var entry = store && store[${key}];
+  if (!entry) return { ${RELAY_MARK}: 1, done: true, ok: false, name: "RelayLost", message: "the page reloaded or navigated before the expression settled, so its result is gone" };
+  if (!entry.done) return { ${RELAY_MARK}: 1, done: false, token: ${key} };
+  delete store[${key}];
+  return { ${RELAY_MARK}: 1, done: true, ok: entry.ok, value: entry.value, name: entry.name, message: entry.message };
+})()`;
+}
+function readRelayFrame(value) {
+    if (!value || "object" != typeof value || Array.isArray(value)) return null;
+    const frame = value;
+    if (1 !== frame[RELAY_MARK] || "boolean" != typeof frame.done) return null;
+    return {
+        done: frame.done,
+        ..."boolean" == typeof frame.ok ? {
+            ok: frame.ok
+        } : {},
+        ..."value" in frame ? {
+            value: frame.value
+        } : {},
+        ..."string" == typeof frame.name ? {
+            name: frame.name
+        } : {},
+        ..."string" == typeof frame.message ? {
+            message: frame.message
+        } : {},
+        ..."string" == typeof frame.token ? {
+            token: frame.token
+        } : {}
+    };
+}
 const eval_schema = {
     name: "extension_eval",
     description: "Evaluate an expression in a running extension context. Start the session with allowEval:true (extension_dev), which writes a 0600 session token. Context defaults to 'background', except on a Chromium MV3 session (the default template) where it defaults to 'page', the active tab, because the MV3 service worker CSP blocks eval; pass context:'background' to target the worker anyway and get that explanation back. For content and page, pass `url` to pick the tab, or omit both `url` and `tab` for the active tab; a numeric `tab` only disambiguates. Extension surfaces (popup, options, sidebar, devtools) and override pages (newtab, history, bookmarks) need no tab id but must already be open: open one with extension_open first, because a closed one returns an explicit error. On a Chromium MV3 session those pages, and context:'page' with a chrome-extension:// url, evaluate over CDP, the inspector path the extension page CSP does not govern; elsewhere they evaluate over the in-bundle relay. Call extension_dom_snapshot with listTabs:true to enumerate {tabId, url, title}.",
@@ -12704,14 +12932,6 @@ function resolveDefaultEvalContext(projectPath, browser) {
     if (!isChromiumFamily(browser)) return "background";
     return 3 === chromiumManifestVersion(projectPath, browser) ? "page" : "background";
 }
-const EXTENSION_PAGE_CONTEXTS = [
-    "popup",
-    "options",
-    "sidebar",
-    "newtab",
-    "history",
-    "bookmarks"
-];
 function wantsExtensionPageOverCdp(projectPath, browser, context, url) {
     if (!isChromiumFamily(browser) || !context) return false;
     if ("page" === context) return "string" == typeof url && /^chrome-extension:\/\//.test(url);
@@ -12834,6 +13054,78 @@ async function evaluateOnWebKitPage(args, browser, info) {
         });
     }
 }
+const RELAY_POLL_MS = 300;
+const RELAY_DEFAULT_BUDGET_MS = 30000;
+function tryParseFrame(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed && "object" == typeof parsed ? parsed : null;
+    } catch  {
+        return null;
+    }
+}
+async function evaluateThroughRelay(args, browser, context) {
+    const token = node_crypto.randomUUID();
+    const budgetMs = args.timeout ?? RELAY_DEFAULT_BUDGET_MS;
+    const deadline = Date.now() + budgetMs;
+    const run = (expression)=>runActVerb([
+            "eval",
+            ...commonFlags({
+                ...args,
+                context,
+                browser
+            }),
+            "--",
+            expression,
+            args.projectPath
+        ], args.projectPath, args.timeout, eval_schema.name);
+    let raw = await run(relaySafeExpression(args.expression, token));
+    let parsed = tryParseFrame(raw);
+    if (!parsed || true !== parsed.ok) return raw;
+    let frame = readRelayFrame(parsed.value);
+    if (!frame) return raw;
+    let polls = 0;
+    while(!frame.done){
+        if (Date.now() >= deadline) return envelope_envelope({
+            ok: false,
+            command: eval_schema.name,
+            status: "eval-pending",
+            error: {
+                code: "E_WAIT_TIMEOUT",
+                name: "EvalPending",
+                message: `The expression returned a promise that had not settled after ${budgetMs} ms; it is still running in the ${context} page.`
+            },
+            value: {
+                context,
+                token,
+                polls
+            },
+            hint: `Its outcome lands in globalThis.${RELAY_MARK}[${JSON.stringify(token)}] inside the ${context} page when it settles ({done, ok, value}): read it with extension_eval in the same context, or pass a larger timeout to wait here.`
+        });
+        await new Promise((r)=>setTimeout(r, RELAY_POLL_MS));
+        polls += 1;
+        raw = await run(relayPollExpression(token));
+        parsed = tryParseFrame(raw);
+        if (!parsed || true !== parsed.ok) return raw;
+        const next = readRelayFrame(parsed.value);
+        if (!next) return raw;
+        frame = next;
+    }
+    if (false === frame.ok) return envelope_envelope({
+        ok: false,
+        command: eval_schema.name,
+        status: "eval-failed",
+        error: {
+            code: "E_EVAL",
+            name: frame.name || "EvalError",
+            message: frame.message || "the expression rejected"
+        },
+        hint: `The expression threw, or the promise it returned rejected, inside the ${context} page.`
+    });
+    parsed.value = void 0 === frame.value ? null : frame.value;
+    if (polls > 0) parsed.hint = `The expression returned a promise; the ${context} page settled it and this call polled ${polls} time${1 === polls ? "" : "s"} for the result. ` + ("string" == typeof parsed.hint ? parsed.hint : "");
+    return actFrameJson(parsed);
+}
 async function eval_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     if (WEBKIT_FAMILY.has(browser) && "page" === args.context) {
@@ -12843,6 +13135,35 @@ async function eval_handler(args) {
     const defaulted = !args.context && "page" === resolveDefaultEvalContext(args.projectPath, browser);
     const context = defaulted ? "page" : args.context;
     if (wantsExtensionPageOverCdp(args.projectPath, browser, context, args.url)) return evaluateOnChromiumExtensionPage(args, browser, context);
+    if ("page" === context && isExtensionUrl(args.url)) {
+        const surface = surfaceForExtensionUrl(args.projectPath, browser, args.url);
+        if (surface) {
+            const raw = await evaluateThroughRelay({
+                ...args,
+                url: void 0,
+                tab: void 0
+            }, browser, surface.context);
+            const parsed = tryParseFrame(raw);
+            if (parsed) {
+                addWarning(parsed, `${args.url} is the extension's own ${surface.context} document (${surface.document}), which script injection cannot reach on any engine, so this evaluated through the ${surface.context} surface relay. Pass context: "${surface.context}" directly next time.`);
+                return actFrameJson(parsed);
+            }
+            return raw;
+        }
+        const declared = declaredSurfaces(args.projectPath, browser) ?? [];
+        return envelope_envelope({
+            ok: false,
+            command: eval_schema.name,
+            status: "no-surface",
+            error: {
+                code: "E_NO_SURFACE_DOCUMENT",
+                name: "NoSurfaceDocument",
+                message: `${args.url} is a page inside the extension, which script injection cannot reach, and it matches none of the surface documents the manifest declares${declared.length ? ` (${declared.join(", ")})` : ""}.`
+            },
+            hint: declared.length ? `Evaluate in a declared surface with context: "${declared[0]}" (open it first with extension_open), or read a web page by url.` : "Declare the page as a surface in the manifest (action.default_popup, options_ui.page, sidebar_action.default_panel or chrome_url_overrides) and rebuild."
+        });
+    }
+    if (context && EXTENSION_PAGE_CONTEXTS.includes(context)) return evaluateThroughRelay(args, browser, context);
     const raw = await runActVerb([
         "eval",
         ...commonFlags({
@@ -14531,6 +14852,12 @@ async function wait_handler(args) {
                         pid: contract.pid,
                         distPath: contract.distPath,
                         manifestPath: contract.manifestPath,
+                        ..."number" == typeof contract.browserPid ? {
+                            browserPid: contract.browserPid
+                        } : {},
+                        ..."string" == typeof contract.profilePath && contract.profilePath ? {
+                            profilePath: contract.profilePath
+                        } : {},
                         compiledAt: contract.compiledAt,
                         startedAt: contract.startedAt,
                         budgetMs,
@@ -15387,44 +15714,58 @@ function resolveCacheRoot() {
     if (home) return node_path.join(home, ".cache", "extension.js", "browsers");
     return node_path.resolve(process.cwd(), ".cache", "extension.js", "browsers");
 }
-function findManagedBinary(browser) {
-    const browserDir = node_path.join(resolveCacheRoot(), browser);
+const MANAGED_SEARCH_DEPTH = 8;
+const MANAGED_EXEC_NAMES = {
+    chrome: [
+        "chrome",
+        "chrome.exe",
+        "Google Chrome for Testing"
+    ],
+    chromium: [
+        "chrome",
+        "chromium",
+        "chrome.exe",
+        "chromium.exe",
+        "Chromium"
+    ],
+    edge: [
+        "msedge",
+        "msedge.exe",
+        "microsoft-edge",
+        "Microsoft Edge"
+    ],
+    firefox: [
+        "firefox",
+        "firefox.exe",
+        "firefox-bin"
+    ]
+};
+function executableInsideBundle(bundle, names) {
+    const macos = node_path.join(bundle, "Contents", "MacOS");
+    try {
+        for (const entry of node_fs.readdirSync(macos, {
+            withFileTypes: true
+        }))if (entry.isFile() && names.includes(entry.name)) return node_path.join(macos, entry.name);
+    } catch  {}
+    return null;
+}
+function findManagedBinary(browser, cacheRoot = resolveCacheRoot()) {
+    const browserDir = node_path.join(cacheRoot, browser);
     if (!node_fs.existsSync(browserDir)) return null;
-    const execNames = {
-        chrome: [
-            "chrome",
-            "chrome.exe",
-            "Google Chrome for Testing"
-        ],
-        chromium: [
-            "chrome",
-            "chromium",
-            "chrome.exe",
-            "chromium.exe",
-            "Chromium.app"
-        ],
-        edge: [
-            "msedge",
-            "msedge.exe",
-            "microsoft-edge",
-            "Microsoft Edge"
-        ],
-        firefox: [
-            "firefox",
-            "firefox.exe",
-            "Firefox.app"
-        ]
-    };
-    const names = execNames[browser] ?? [];
+    const names = MANAGED_EXEC_NAMES[browser] ?? [];
     function search(dir, depth) {
-        if (depth > 4) return null;
+        if (depth > MANAGED_SEARCH_DEPTH) return null;
         try {
             for (const entry of node_fs.readdirSync(dir, {
                 withFileTypes: true
             })){
                 const full = node_path.join(dir, entry.name);
                 if (entry.isFile() && names.includes(entry.name)) return full;
-                if (entry.isDirectory() && depth < 4) {
+                if (entry.isDirectory() && entry.name.endsWith(".app")) {
+                    const inside = executableInsideBundle(full, names);
+                    if (inside) return inside;
+                }
+                if (entry.isDirectory() && depth < MANAGED_SEARCH_DEPTH) {
                     const found = search(full, depth + 1);
                     if (found) return found;
                 }
@@ -15475,14 +15816,16 @@ async function detectBrowsers(browsers) {
         const isWebkit = WEBKIT_FAMILY.has(browser);
         let binaryPath = findManagedBinary(browser);
         let source = "managed";
+        const systemBinaryPath = findSystemBinary(browser);
         if (!binaryPath) {
-            binaryPath = findSystemBinary(browser);
+            binaryPath = systemBinaryPath;
             source = binaryPath ? "system" : "not_found";
         }
         let version = null;
         if (binaryPath && !isWebkit) version = await getVersion(binaryPath, browser);
         else if (binaryPath && isWebkit) version = await readSafariVersion(binaryPath);
         const automation = isWebkit && binaryPath ? await detectSafariAutomation(binaryPath) : null;
+        const shadowedSystem = "managed" === source && systemBinaryPath && systemBinaryPath !== binaryPath ? systemBinaryPath : null;
         detected.push({
             browser,
             binaryPath,
@@ -15493,6 +15836,10 @@ async function detectBrowsers(browsers) {
             rdpSupport: isGecko,
             ...automation ? {
                 automation
+            } : {},
+            ...shadowedSystem ? {
+                systemBinaryPath: shadowedSystem,
+                devLaunches: `extension_dev launches the managed binary above, not the system install at ${shadowedSystem}; pass ${isGecko ? "geckoBinary" : "chromiumBinary"} to extension_dev to use the system one.`
             } : {}
         });
     }

package/dist/src/lib/extension-surfaces.d.ts

@@ -0,0 +1,7 @@
+export declare const EXTENSION_PAGE_CONTEXTS: string[];
+export declare const EXTENSION_ORIGIN: RegExp;
+export declare function isExtensionUrl(url: string | undefined): boolean;
+export declare function surfaceForExtensionUrl(projectPath: string, browser: string, url: string): {
+    context: string;
+    document: string;
+} | null;

package/dist/src/lib/relay-eval.d.ts

@@ -0,0 +1,12 @@
+export declare const RELAY_MARK = "__extensionDevRelay";
+export interface RelayFrame {
+    done: boolean;
+    ok?: boolean;
+    value?: unknown;
+    name?: string;
+    message?: string;
+    token?: string;
+}
+export declare function relaySafeExpression(expression: string, token: string): string;
+export declare function relayPollExpression(token: string): string;
+export declare function readRelayFrame(value: unknown): RelayFrame | null;

package/dist/src/lib/types.d.ts

@@ -65,6 +65,9 @@ export interface ReadyContract {
     compiledAt?: string | null;
     executorAttachedAt?: string;
     runtime?: string;
+    profilePath?: string;
+    browserPid?: number | null;
+    launcherPid?: number;
 }
 export interface ProcessInfo {
     pid: number;

package/dist/src/tools/detect-browsers.d.ts

@@ -1 +1,2 @@
+export declare function findManagedBinary(browser: string, cacheRoot?: string): string | null;
 export declare function detectBrowsers(browsers?: string[]): Promise<string>;

package/dist/src/tools/eval.d.ts

@@ -1,4 +1,5 @@
 import { type ActArgs } from "../lib/act";
+import { EXTENSION_PAGE_CONTEXTS } from "../lib/extension-surfaces";
 export declare const schema: {
     name: string;
     description: string;
@@ -40,7 +41,7 @@ export declare const schema: {
 };
 export declare function chromiumManifestVersion(projectPath: string, browser: string): 2 | 3 | null;
 export declare function resolveDefaultEvalContext(projectPath: string, browser: string): "background" | "page";
-export declare const EXTENSION_PAGE_CONTEXTS: string[];
+export { EXTENSION_PAGE_CONTEXTS };
 export declare function wantsExtensionPageOverCdp(projectPath: string, browser: string, context: string | undefined, url: string | undefined): boolean;
 export declare function handler(args: ActArgs & {
     expression: string;

package/dist/src/tools/inspect-gecko.d.ts

@@ -1,3 +1,5 @@
+import { surfaceForExtensionUrl } from "../lib/extension-surfaces";
+export { surfaceForExtensionUrl };
 export declare function inspectViaBridge(args: {
     projectPath: string;
     url?: string;

package/dist/src/tools/stop.d.ts

@@ -30,6 +30,11 @@ interface StopOutcome {
     detail: string;
     carrierRemoved?: string;
 }
+export interface ContractProcessHints {
+    profilePath?: string;
+    pids: number[];
+}
+export declare function contractProcessHints(projectPath: string, browser: string): ContractProcessHints;
 export declare function stopOne(projectPath: string, browser: string): Promise<StopOutcome>;
 export declare function handler(args: {
     projectPath?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "10.10.0",
+  "version": "10.10.1",
   "description": "MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex) build, run, inspect, and publish browser extensions. 30 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, Firefox, Safari, and every Chromium- or Gecko-based browser (Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf). Powered by extension.dev and Extension.js.",
   "mcpName": "io.github.extensiondev/mcp",
   "license": "Apache-2.0",
@@ -91,9 +91,9 @@
     "@modelcontextprotocol/sdk": "^1.12.1",
     "browser-extension-manifest-fields": "^2.2.9",
     "cross-spawn": "^7.0.6",
-    "extension-create": "4.1.29",
-    "extension-develop": "4.1.29",
-    "extension-install": "4.1.29",
+    "extension-create": "4.1.30",
+    "extension-develop": "4.1.30",
+    "extension-install": "4.1.30",
     "ws": "^8.20.0"
   },
   "devDependencies": {

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://extension.dev",
-  "version": "10.10.0",
+  "version": "10.10.1",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@extension.dev/mcp",
-      "version": "10.10.0",
+      "version": "10.10.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"