@extension.dev/mcp 4.2.0 → 4.2.2

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## 4.2.2
+
+Agent-ergonomics release from the 4.2.1 fresh-eyes walk: the two changes
+that removed nearly all friction a real MCP client hit.
+
+- Session-aware browser default. Tools that target a running session
+  (`extension_logs`, `extension_reload`, `extension_eval`,
+  `extension_storage`, `extension_open`, `extension_dom_inspect`,
+  `extension_list_extensions`, `extension_source_inspect`,
+  `extension_wait`) no longer hard-default `browser` to a constant that
+  could disagree with the session `extension_dev` actually started.
+  Omitting `browser` now resolves to the active session's browser:
+  in-memory registry first, then the freshest live `ready.json` contract
+  on disk (dead pids ignored), then the old constant. Starting a session
+  with `browser: "chrome"` and calling `extension_logs` with no args now
+  just works instead of erroring about a missing chromium channel.
+- Error hints speak the MCP tool surface, not the CLI. Act-verb error
+  prose is rewritten before returning: `` `extension dev
+  --browser=chromium --allow-control` `` becomes `extension_dev with
+  { browser: "chromium", allowControl: true }`, and stray
+  `--allow-control` / `--allow-eval` / `--browser=<x>` mentions become
+  their tool-argument names. Result data is never touched — only
+  error/hint prose. Tool descriptions now name `allowControl` /
+  `allowEval` directly, so agents no longer discover the gates by
+  fuzzing the schema.
+- The no-channel error now names the session that IS running ("Active
+  session browser(s) for this project: chrome — pass that as `browser`"),
+  so an agent retargets instead of spawning a second, conflicting
+  session. Same for the `extension_logs` follow miss.
+- `extension_list_extensions` / `extension_source_inspect` accept
+  `browser: "chromium"` (the default dev target) instead of rejecting it
+  as non-Chromium.
+- Tests: session-browser resolution + hint-translation suite (137 total).
+
+## 4.2.1
+
+`extension_build` failures no longer kill the MCP server process
+(fatal-error path returned a rejected promise the server didn't catch).
+CDP-dependent tools resolve the debug port from the session's ready
+contract instead of assuming 9222 (plus a test-only engine pin
+override, `EXTENSION_MCP_CLI_VERSION`).
+
 ## 4.2.0
 
 Session lifecycle + determinism release. Tool count 27 -> 28.

package/README.md

@@ -96,7 +96,7 @@ cp node_modules/@extension.dev/mcp/claude/commands/*.md ~/my-extension/.claude/c
 | see | `extension_dom_inspect` | CDP-free DOM snapshot |
 | see | `extension_list_extensions` | List loaded extensions (Chromium) |
 | see | `extension_logs` | Stream logs from every context |
-| act | `extension_eval` | Evaluate in a context (`--allow-eval`) |
+| act | `extension_eval` | Evaluate in a context (needs `allowEval: true` on `extension_dev`) |
 | act | `extension_storage` | Read/write `chrome.storage` |
 | act | `extension_reload` | Reload extension or tab |
 | act | `extension_open` | Open a surface / trigger `action`, `command` |

package/dist/module.js

@@ -9,8 +9,8 @@ import node_os from "node:os";
 import { extensionBuild } from "extension-develop";
 import cross_spawn from "cross-spawn";
 import { filterKeysForThisBrowser } from "browser-extension-manifest-fields";
-import node_net from "node:net";
 import ws from "ws";
+import node_http from "node:http";
 import { clearCredentials, exchangeAndPersist, fetchLoginConfig, pollForToken, publish, readCredentials, resolveApiBase, resolveToken, safeApiBase, startDeviceCode } from "@extension.dev/core";
 import { extensionInstall, getManagedBrowsersCacheRoot } from "extension-install";
 import { execFile } from "node:child_process";
@@ -183,7 +183,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"4.2.0","El":{"OP":"^4.0.8"}}');
+var package_namespaceObject = JSON.parse('{"rE":"4.2.2","El":{"OP":"^4.0.8"}}');
 const create_schema = {
     name: "extension_create",
     description: "Create a new browser extension project from a template in the extension.dev template catalog. Use extension_list_templates to see available options.",
@@ -401,7 +401,8 @@ async function build_handler(args) {
         const summary = await extensionBuild(args.projectPath, {
             browser: args.browser ?? "chrome",
             zip: args.zip ?? false,
-            zipSource: args.zipSource ?? false
+            zipSource: args.zipSource ?? false,
+            exitOnError: false
         });
         return JSON.stringify({
             success: true,
@@ -417,6 +418,10 @@ async function build_handler(args) {
     }
 }
 const PINNED_CLI_VERSION = String(package_namespaceObject.El.OP ?? "latest").replace(/^[\^~]/, "");
+function pinnedCliVersion() {
+    const override = String(process.env.EXTENSION_MCP_CLI_VERSION || "").trim();
+    return override || PINNED_CLI_VERSION;
+}
 function resolveExtensionInvocation(projectDir) {
     if (projectDir) {
         const bin = node_path.join(projectDir, "node_modules", ".bin", "win32" === process.platform ? "extension.cmd" : "extension");
@@ -431,7 +436,7 @@ function resolveExtensionInvocation(projectDir) {
     return {
         command: "npx",
         prefixArgs: [
-            `extension@${PINNED_CLI_VERSION}`
+            `extension@${pinnedCliVersion()}`
         ]
     };
 }
@@ -1571,6 +1576,110 @@ class CDPClient extends CDPConnection {
         return result ?? null;
     }
 }
+async function resolveCdpPort(projectPath, browser, options) {
+    const waitMs = options?.waitMs ?? 20000;
+    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+    const deadline = Date.now() + waitMs;
+    let contractSeen = false;
+    for(;;){
+        try {
+            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+            contractSeen = true;
+            if ("number" == typeof contract.cdpPort) return {
+                port: contract.cdpPort,
+                source: "contract"
+            };
+        } catch  {
+            if (!contractSeen) break;
+        }
+        if (Date.now() >= deadline) break;
+        await new Promise((resolve)=>setTimeout(resolve, 500));
+    }
+    if (!contractSeen && await isCdpEndpoint(9222)) return {
+        port: 9222,
+        source: "default-probe"
+    };
+    return 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.";
+function isCdpEndpoint(port) {
+    return new Promise((resolve)=>{
+        const req = node_http.get({
+            host: "127.0.0.1",
+            port,
+            path: "/json/version",
+            timeout: 1000
+        }, (res)=>{
+            res.resume();
+            resolve(200 === res.statusCode);
+        });
+        req.on("error", ()=>resolve(false));
+        req.on("timeout", ()=>{
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+function contractSightings(projectPath) {
+    const root = node_path.resolve(projectPath, "dist", "extension-js");
+    let dirs;
+    try {
+        dirs = node_fs.readdirSync(root);
+    } catch  {
+        return [];
+    }
+    const sightings = [];
+    for (const dir of dirs){
+        const readyPath = node_path.join(root, dir, "ready.json");
+        try {
+            const stat = node_fs.statSync(readyPath);
+            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+            if (contract?.status !== "ready") continue;
+            sightings.push({
+                browser: dir,
+                mtimeMs: stat.mtimeMs,
+                pid: "number" == typeof contract.pid ? contract.pid : void 0
+            });
+        } catch  {}
+    }
+    return sightings;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function knownSessionBrowsers(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const browsers = [];
+    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
+    for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
+    return Array.from(new Set(browsers));
+}
+function resolveSessionBrowser(projectPath, explicit, fallback = "chromium") {
+    if (explicit) return {
+        browser: explicit,
+        source: "explicit"
+    };
+    const resolved = node_path.resolve(projectPath);
+    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
+    if (mine.length > 0) return {
+        browser: mine[mine.length - 1].browser,
+        source: "session"
+    };
+    const sightings = contractSightings(projectPath).filter((s)=>void 0 === s.pid || pidAlive(s.pid)).sort((a, b)=>b.mtimeMs - a.mtimeMs);
+    if (sightings.length > 0) return {
+        browser: sightings[0].browser,
+        source: "contract"
+    };
+    return {
+        browser: fallback,
+        source: "fallback"
+    };
+}
 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.",
@@ -1614,7 +1723,7 @@ const source_inspect_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             maxBytes: {
                 type: "number",
@@ -1632,30 +1741,8 @@ const source_inspect_schema = {
         ]
     }
 };
-async function findCdpPort(projectPath, browser) {
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-    try {
-        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-        if ("number" == typeof contract.cdpPort) return contract.cdpPort;
-    } catch  {}
-    const defaultPort = 9222;
-    return new Promise((resolve)=>{
-        const socket = new node_net.Socket();
-        socket.setTimeout(1000);
-        socket.on("connect", ()=>{
-            socket.destroy();
-            resolve(defaultPort);
-        });
-        socket.on("error", ()=>resolve(null));
-        socket.on("timeout", ()=>{
-            socket.destroy();
-            resolve(null);
-        });
-        socket.connect(defaultPort, "127.0.0.1");
-    });
-}
 async function source_inspect_handler(args) {
-    const browser = args.browser ?? "chrome";
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     const include = new Set(args.include ?? [
         "summary",
         "meta",
@@ -1664,18 +1751,20 @@ async function source_inspect_handler(args) {
     const maxBytes = args.maxBytes ?? 262144;
     const isChromium = [
         "chrome",
+        "chromium",
         "edge",
         "chromium-based"
     ].includes(browser);
     if (!isChromium) return JSON.stringify({
         error: `Source inspection for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
-        hint: "Use --browser=chrome for source inspection, or use the CLI: npx extension dev --source"
+        hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
     });
-    const cdpPort = await findCdpPort(args.projectPath, browser);
-    if (!cdpPort) return JSON.stringify({
+    const resolved = await resolveCdpPort(args.projectPath, browser);
+    if (!resolved) return JSON.stringify({
         error: "No active dev session found. Cannot connect to Chrome DevTools Protocol.",
-        hint: "Start a dev session first with extension_dev, then use extension_wait to confirm it is ready."
+        hint: `Start a dev session first with extension_dev, then use extension_wait to confirm it is ready. ${CDP_PORT_MISSING_HINT}`
     });
+    const cdpPort = resolved.port;
     const cdp = new CDPClient();
     try {
         const allTargets = await CDPClient.discoverTargets(cdpPort);
@@ -1769,7 +1858,7 @@ const list_extensions_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             }
         },
         required: [
@@ -1778,26 +1867,38 @@ const list_extensions_schema = {
     }
 };
 async function list_extensions_handler(args) {
-    const browser = args.browser ?? "chrome";
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     const isChromium = [
         "chrome",
+        "chromium",
         "edge",
         "chromium-based"
     ].includes(browser);
     if (!isChromium) return JSON.stringify({
         error: `Listing extensions for ${browser} uses RDP (Remote Debug Protocol). Currently only Chromium CDP is supported.`,
-        hint: "Use --browser=chrome."
+        hint: 'Pass browser: "chrome" (against a Chromium-family dev session).'
     });
-    const cdpPort = await list_extensions_findCdpPort(args.projectPath, browser);
-    if (!cdpPort) return JSON.stringify({
+    const resolved = await resolveCdpPort(args.projectPath, browser);
+    if (!resolved) return JSON.stringify({
         error: "No active dev session found. Cannot connect to Chrome DevTools Protocol.",
-        hint: "Start a dev session first with extension_dev, then use extension_wait to confirm it is ready."
+        hint: `Start a dev session first with extension_dev, then use extension_wait to confirm it is ready. ${CDP_PORT_MISSING_HINT}`
     });
+    const cdpPort = resolved.port;
     const cdp = new CDPClient();
     try {
-        const browserWsUrl = await CDPClient.discoverBrowserWsUrl(cdpPort);
-        await cdp.connect(browserWsUrl);
-        const targets = await cdp.getTargets();
+        let targets = null;
+        let lastError = null;
+        for(let attempt = 0; attempt < 3; attempt++)try {
+            const browserWsUrl = await CDPClient.discoverBrowserWsUrl(cdpPort);
+            await cdp.connect(browserWsUrl);
+            targets = await cdp.getTargets();
+            break;
+        } catch (error) {
+            lastError = error;
+            cdp.disconnect();
+            if (attempt < 2) await new Promise((resolve)=>setTimeout(resolve, 800));
+        }
+        if (!targets) throw lastError;
         const byId = new Map();
         for (const t of targets){
             const url = String(t.url ?? "");
@@ -1849,28 +1950,6 @@ async function list_extensions_handler(args) {
         cdp.disconnect();
     }
 }
-async function list_extensions_findCdpPort(projectPath, browser) {
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-    try {
-        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-        if ("number" == typeof contract.cdpPort) return contract.cdpPort;
-    } catch  {}
-    const defaultPort = 9222;
-    return new Promise((resolve)=>{
-        const socket = new node_net.Socket();
-        socket.setTimeout(1000);
-        socket.on("connect", ()=>{
-            socket.destroy();
-            resolve(defaultPort);
-        });
-        socket.on("error", ()=>resolve(null));
-        socket.on("timeout", ()=>{
-            socket.destroy();
-            resolve(null);
-        });
-        socket.connect(defaultPort, "127.0.0.1");
-    });
-}
 const CONTROL_WS_PATH = "/extjs-control";
 const LEVEL_ORDER = [
     "error",
@@ -1933,8 +2012,7 @@ const logs_schema_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium",
-                description: "Which dist/extension-js/<browser>/ to read. Defaults to chromium (the default dev target)."
+                description: "Which dist/extension-js/<browser>/ to read. Defaults to the active dev session's browser for this project (falls back to chromium)."
             },
             level: {
                 type: "string",
@@ -2075,10 +2153,14 @@ async function readFromFile(args, browser, limit) {
 }
 async function readFromStream(args, browser, limit) {
     const ready = readReadyContract(args.projectPath, browser);
-    if (!ready) return JSON.stringify({
-        error: `No active control channel found for ${browser}.`,
-        hint: `Run extension_dev (browser: ${browser}) and wait for it to be ready, then retry. For past logs without a live channel, call without follow.`
-    });
+    if (!ready) {
+        const running = knownSessionBrowsers(args.projectPath).filter((b)=>b !== browser);
+        const retarget = running.length ? `An active session exists for browser(s): ${running.join(", ")} — pass that as \`browser\`. Otherwise run` : "Run";
+        return JSON.stringify({
+            error: `No active control channel found for ${browser}.`,
+            hint: `${retarget} extension_dev (browser: ${browser}) and wait for it to be ready, then retry. For past logs without a live channel, call without follow.`
+        });
+    }
     const followMs = Math.min(Math.max(args.followMs ?? 4000, 500), 15000);
     const matches = makeFilter(args);
     const events = [];
@@ -2141,11 +2223,27 @@ async function readFromStream(args, browser, limit) {
     });
 }
 async function logs_handler(args) {
-    const browser = args.browser ?? "chromium";
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const limit = args.limit && args.limit > 0 ? args.limit : 200;
     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(/--browser[= ]([\w-]+)/g, 'browser: "$1"').replace(/`extension dev`/g, "extension_dev").replace(/\bextension dev\b/g, "extension_dev");
+}
+function withSessionContext(message, projectPath) {
+    if (!/no active control channel/i.test(message)) return message;
+    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,
@@ -2157,14 +2255,16 @@ async function runActVerb(args, projectPath, timeoutMs) {
     });
     const out = stdout.trim();
     if (out) try {
-        JSON.parse(out);
+        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: stderr.trim() || `extension exited with code ${code}`
+            message: withSessionContext(toMcpSpeak(message), projectPath)
         }
     });
 }
@@ -2179,7 +2279,7 @@ function commonFlags(args) {
 }
 const eval_schema = {
     name: "extension_eval",
-    description: "Evaluate an expression in a running extension context (service worker, content script, popup, options, sidebar). Requires the dev session to be started with --allow-eval (writes a 0600 session token the CLI reads). Wraps `extension eval`.",
+    description: "Evaluate an expression in a running extension context (service worker, content script, popup, options, sidebar). Requires the dev session to be started with allowEval: true (extension_dev; writes a 0600 session token the CLI reads). Wraps `extension eval`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2215,7 +2315,7 @@ const eval_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2229,16 +2329,20 @@ const eval_schema = {
     }
 };
 async function eval_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     return runActVerb([
         "eval",
         args.expression,
         args.projectPath,
-        ...commonFlags(args)
+        ...commonFlags({
+            ...args,
+            browser
+        })
     ], args.projectPath, args.timeout);
 }
 const storage_schema = {
     name: "extension_storage",
-    description: "Read or write chrome.storage in a running extension. Requires the dev session to be started with --allow-control. Wraps `extension storage get|set`.",
+    description: "Read or write chrome.storage in a running extension. Requires the dev session to be started with allowControl: true (extension_dev). Wraps `extension storage get|set`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2284,7 +2388,7 @@ const storage_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2298,6 +2402,7 @@ const storage_schema = {
     }
 };
 async function storage_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const cli = [
         "storage",
         args.action,
@@ -2316,13 +2421,13 @@ async function storage_handler(args) {
         cli.push("--value", JSON.stringify(args.value));
     }
     if (args.context) cli.push("--context", args.context);
-    if (args.browser) cli.push("--browser", args.browser);
+    cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
     return runActVerb(cli, args.projectPath, args.timeout);
 }
 const reload_schema = {
     name: "extension_reload",
-    description: "Reload a running extension (background) or a tab. Requires the dev session to be started with --allow-control. Wraps `extension reload`.",
+    description: "Reload a running extension (background) or a tab. Requires the dev session to be started with allowControl: true (extension_dev). Wraps `extension reload`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2345,7 +2450,7 @@ const reload_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2358,15 +2463,19 @@ const reload_schema = {
     }
 };
 async function reload_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     return runActVerb([
         "reload",
         args.projectPath,
-        ...commonFlags(args)
+        ...commonFlags({
+            ...args,
+            browser
+        })
     ], args.projectPath, args.timeout);
 }
 const open_schema = {
     name: "extension_open",
-    description: "Open an extension surface or replay an event in a running session. 'popup'/'options'/'sidebar' open UI surfaces. 'action' triggers the toolbar action: opens the action's popup, or (no popup) replays chrome.action.onClicked. 'command' replays a chrome.commands.onCommand keyboard shortcut (pass `name`). NOTE: action/command replay invokes your listener WITHOUT a user gesture, so the gesture-derived activeTab grant does not apply (the result includes gesture:false and a warning when activeTab is declared). Requires --allow-control. Wraps `extension open`.",
+    description: "Open an extension surface or replay an event in a running session. 'popup'/'options'/'sidebar' open UI surfaces. 'action' triggers the toolbar action: opens the action's popup, or (no popup) replays chrome.action.onClicked. 'command' replays a chrome.commands.onCommand keyboard shortcut (pass `name`). NOTE: action/command replay invokes your listener WITHOUT a user gesture, so the gesture-derived activeTab grant does not apply (the result includes gesture:false and a warning when activeTab is declared). Requires the dev session to be started with allowControl: true (extension_dev). Wraps `extension open`.",
     inputSchema: {
         type: "object",
         properties: {
@@ -2391,7 +2500,7 @@ const open_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2405,19 +2514,20 @@ const open_schema = {
     }
 };
 async function open_handler(args) {
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser);
     const cli = [
         "open",
         args.surface,
         args.projectPath
     ];
     if ("command" === args.surface && args.name) cli.push("--name", args.name);
-    if (args.browser) cli.push("--browser", args.browser);
+    cli.push("--browser", browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
     return runActVerb(cli, args.projectPath, args.timeout);
 }
 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). Requires --allow-control. 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). 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: {
@@ -2466,7 +2576,7 @@ const dom_inspect_schema = {
             },
             browser: {
                 type: "string",
-                default: "chromium"
+                description: "Browser session to target. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2502,7 +2612,7 @@ async function dom_inspect_handler(args) {
     if (args.include?.length) cli.push("--include", args.include.join(","));
     if (null != args.maxBytes) cli.push("--max-bytes", String(args.maxBytes));
     if (null != args.withConsole) cli.push("--with-console", String(args.withConsole));
-    if (args.browser) cli.push("--browser", args.browser);
+    cli.push("--browser", resolveSessionBrowser(args.projectPath, args.browser).browser);
     if (null != args.timeout) cli.push("--timeout", String(args.timeout));
     return runActVerb(cli, args.projectPath, args.timeout);
 }
@@ -2659,8 +2769,7 @@ const wait_schema = {
             },
             browser: {
                 type: "string",
-                default: "chrome",
-                description: "Browser to check readiness for"
+                description: "Browser to check readiness for. Defaults to the active dev session's browser for this project."
             },
             timeout: {
                 type: "number",
@@ -2674,7 +2783,7 @@ const wait_schema = {
     }
 };
 async function wait_handler(args) {
-    const browser = args.browser ?? "chrome";
+    const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
     const timeout = args.timeout ?? 60000;
     const readyPath = node_path.resolve(args.projectPath, "dist", "extension-js", browser, "ready.json");
     const start = Date.now();
@@ -3139,7 +3248,7 @@ async function install_browser_handler(args) {
             status: "installed",
             browser: args.browser,
             duration: Date.now() - start,
-            hint: `Browser "${args.browser}" is now available. Use extension_dev or extension_start with --browser=${args.browser}.`
+            hint: `Browser "${args.browser}" is now available. Use extension_dev or extension_start with browser: "${args.browser}".`
         });
     } catch (err) {
         return JSON.stringify({

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

@@ -1,3 +1,13 @@
+/**
+ * Translate CLI-speak in an error message into the MCP tool surface
+ * (fresh-eyes walk, friction #2). The CLI's hints say things like
+ * "Run `extension dev --browser=chromium --allow-control` first" — correct
+ * for a human at a terminal, a dead end for an agent that only has the MCP
+ * tools. Rewrite flags to their tool-argument names so the hint is actionable
+ * on the surface the caller is actually using. Result data is never touched —
+ * only error/hint prose.
+ */
+export declare function toMcpSpeak(text: string): string;
 /**
  * Run an `extension <verb> … --output json` act command and return its result
  * JSON as a string (the MCP tool payload). The CLI prints the control-channel
@@ -6,6 +16,8 @@
  *
  * Per lockstep invariant #1 the act tools wrap the CLI verb rather than talking
  * to the control WS directly — so MCP behavior can never drift from the CLI.
+ * Error PROSE is the one exception: hints are rewritten from CLI flags to MCP
+ * tool arguments before returning (see toMcpSpeak).
  */
 export declare function runActVerb(args: string[], projectPath: string, timeoutMs?: number): Promise<string>;
 /** Shared input fields for act tools. */

package/dist/src/lib/cdp-port.d.ts

@@ -0,0 +1,7 @@
+export declare function resolveCdpPort(projectPath: string, browser: string, options?: {
+    waitMs?: number;
+}): Promise<{
+    port: number;
+    source: "contract" | "default-probe";
+} | null>;
+export declare 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.";

package/dist/src/lib/session-browser.d.ts

@@ -0,0 +1,7 @@
+export interface ResolvedBrowser {
+    browser: string;
+    source: "explicit" | "session" | "contract" | "fallback";
+}
+/** Browsers with a live session for this project (registry + disk contracts). */
+export declare function knownSessionBrowsers(projectPath: string): string[];
+export declare function resolveSessionBrowser(projectPath: string, explicit: string | undefined, fallback?: string): ResolvedBrowser;

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

@@ -38,7 +38,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

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

@@ -29,7 +29,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

package/dist/src/tools/list-extensions.d.ts

@@ -10,7 +10,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
         };
         required: string[];

package/dist/src/tools/logs-schema.d.ts

@@ -10,7 +10,6 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
                 description: string;
             };
             level: {

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

@@ -20,7 +20,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

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

@@ -20,7 +20,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

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

@@ -30,7 +30,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             maxBytes: {
                 type: string;

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

@@ -33,7 +33,7 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
+                description: string;
             };
             timeout: {
                 type: string;

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

@@ -10,7 +10,6 @@ export declare const schema: {
             };
             browser: {
                 type: string;
-                default: string;
                 description: string;
             };
             timeout: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "MCP server that lets AI agents build, run, inspect, and publish browser extensions. 28 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, and Firefox.",
   "license": "MIT",
   "author": {