@mehmoodqureshi/chrome-mcp 0.6.5 → 0.6.7

package/dist/src/cli.js

@@ -142,6 +142,10 @@ async function main() {
     if (runTasksCommand(process.argv.slice(2)))
         return;
     const cfg = (0, config_1.parseArgs)(process.argv.slice(2));
+    // Apply verbosity before anything else logs, so `--log-level silent` really is
+    // silent from the first line rather than from wherever the first log happened
+    // to sit after startup.
+    (0, server_2.setLogLevel)(cfg.logLevel);
     if (cfg.showHelp) {
         process.stdout.write(config_1.HELP_TEXT);
         return;
@@ -164,6 +168,15 @@ async function main() {
         onDisplacement: (d) => (0, server_2.logErr)(`SECURITY: extension connection displaced (different id: ${d.differentId})`),
     });
     const port = await bridge.start();
+    // Never includes the pairing token — only the resolved, non-secret config.
+    (0, server_2.logDebug)(`resolved config: ${JSON.stringify({
+        wsPort: port,
+        dataDir: cfg.dataDir,
+        profile: cfg.profile,
+        task: cfg.task,
+        prefer: cfg.prefer,
+        policy: cfg.policy,
+    })}`);
     const handshakePath = (0, auth_1.writeHandshake)(dataDir, { port, token });
     (0, server_2.logErr)(`pairing handshake written to ${handshakePath} (mode 0600; token not logged)`);
     if (process.env.CHROME_MCP_TOKEN) {

package/dist/src/executor/stub-executor.d.ts

@@ -23,6 +23,31 @@ export interface StubOptions {
     /** A URL the backend claims to already know, as the extension reports on every
      *  result frame. Set it to assert the gate uses it INSTEAD of calling tabsList. */
     cachedUrl?: string;
+    /** Background (non-active) tabs, so a test can target one by an explicit tabId
+     *  and check the gate authorizes against THAT tab rather than the active one. */
+    backgroundTabs?: Array<{
+        tabId: TabId;
+        url: string;
+    }>;
+    /** When true, tabs exist but none is flagged active — the case the gate used to
+     *  paper over by silently gating against `tabs[0]`. */
+    noActiveTab?: boolean;
+    /** Text returned by `getText`. Set it large to exercise the output cap. */
+    textPayload?: string;
+    /** HTML returned by `getHtml`. Set it large to exercise the output cap. */
+    htmlPayload?: string;
+    /**
+     * How many of the first content reads reject with `EXTENSION_DISCONNECTED`
+     * before one succeeds — models MV3 recycling the service worker mid-command,
+     * the fault the dispatch layer retries once.
+     */
+    disconnectReads?: number;
+    /**
+     * Same, but for the mutating `type` path. Mutations are deliberately NOT
+     * retried — repeating a write could submit a form twice — so a test can assert
+     * exactly one attempt was made.
+     */
+    disconnectWrites?: number;
 }
 export declare class StubExecutor implements Executor {
     readonly backend: BackendKind;
@@ -30,13 +55,25 @@ export declare class StubExecutor implements Executor {
     private readonly evalThrows;
     private readonly tabsListThrows;
     private readonly noTabs;
+    private readonly textPayload;
+    private readonly htmlPayload;
+    private remainingDisconnects;
+    private remainingWriteDisconnects;
     private readonly blankTabUrl;
     private readonly cached;
+    private readonly backgroundTabs;
+    private readonly noActiveTab;
     /** How many times the gate actually asked for the tab list — the round-trip
      *  counter the caching path exists to keep at zero. */
     tabsListCalls: number;
     private ready;
     constructor(opts?: StubOptions);
+    /** Fail this read if a scripted disconnect is still pending, then consume it. */
+    private maybeDisconnect;
+    /** How many scripted disconnects are left (lets a test assert one was consumed). */
+    get pendingDisconnects(): number;
+    /** Same for the write path — a mutating call must consume exactly one. */
+    get pendingWriteDisconnects(): number;
     private tab;
     cachedActiveUrl(): string | null;
     status(): ExecutorStatus;

package/dist/src/executor/stub-executor.js

@@ -20,8 +20,14 @@ class StubExecutor {
     evalThrows;
     tabsListThrows;
     noTabs;
+    textPayload;
+    htmlPayload;
+    remainingDisconnects;
+    remainingWriteDisconnects;
     blankTabUrl;
     cached;
+    backgroundTabs;
+    noActiveTab;
     /** How many times the gate actually asked for the tab list — the round-trip
      *  counter the caching path exists to keep at zero. */
     tabsListCalls = 0;
@@ -33,13 +39,34 @@ class StubExecutor {
         this.noTabs = opts.noTabs ?? false;
         this.blankTabUrl = opts.blankTabUrl ?? false;
         this.cached = opts.cachedUrl ?? null;
+        this.backgroundTabs = opts.backgroundTabs ?? [];
+        this.noActiveTab = opts.noActiveTab ?? false;
+        this.textPayload = opts.textPayload ?? 'stub text';
+        this.htmlPayload = opts.htmlPayload ?? '<html><body><a href="https://example.com">Example</a></body></html>';
+        this.remainingDisconnects = opts.disconnectReads ?? 0;
+        this.remainingWriteDisconnects = opts.disconnectWrites ?? 0;
+    }
+    /** Fail this read if a scripted disconnect is still pending, then consume it. */
+    maybeDisconnect() {
+        if (this.remainingDisconnects <= 0)
+            return;
+        this.remainingDisconnects--;
+        throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub: service worker recycled mid-command');
+    }
+    /** How many scripted disconnects are left (lets a test assert one was consumed). */
+    get pendingDisconnects() {
+        return this.remainingDisconnects;
+    }
+    /** Same for the write path — a mutating call must consume exactly one. */
+    get pendingWriteDisconnects() {
+        return this.remainingWriteDisconnects;
     }
     tab() {
         return {
             tabId: 'extension:stub:1',
             url: this.blankTabUrl ? '' : this.url,
             title: 'Stub Page',
-            active: true,
+            active: !this.noActiveTab,
             index: 0,
         };
     }
@@ -68,7 +95,18 @@ class StubExecutor {
         this.tabsListCalls++;
         if (this.tabsListThrows)
             throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub bridge is down');
-        return this.noTabs ? [] : [this.tab()];
+        if (this.noTabs)
+            return [];
+        return [
+            this.tab(),
+            ...this.backgroundTabs.map((t, i) => ({
+                tabId: t.tabId,
+                url: t.url,
+                title: 'Stub Background Page',
+                active: false,
+                index: i + 1,
+            })),
+        ];
     }
     async tabSelect(tabId) {
         return { ...this.tab(), tabId };
@@ -98,6 +136,10 @@ class StubExecutor {
         return ok;
     }
     async type() {
+        if (this.remainingWriteDisconnects > 0) {
+            this.remainingWriteDisconnects--;
+            throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub: service worker recycled mid-command');
+        }
         return ok;
     }
     async fill() {
@@ -116,10 +158,12 @@ class StubExecutor {
         return ok;
     }
     async getText(_t) {
-        return { text: 'stub text', ref: 'el_stub_1' };
+        this.maybeDisconnect();
+        return { text: this.textPayload, ref: 'el_stub_1' };
     }
     async getHtml() {
-        return { html: '<html><body><a href="https://example.com">Example</a></body></html>' };
+        this.maybeDisconnect();
+        return { html: this.htmlPayload };
     }
     async snapshot() {
         return {

package/dist/src/mcp/batch.js

@@ -23,6 +23,17 @@ const validators_1 = require("./validators");
 const MAX_OPS = 50;
 const DEFAULT_CONCURRENCY = 6;
 const MAX_CONCURRENCY = 16;
+/**
+ * Default ceiling on the TOTAL payload a batch returns.
+ *
+ * Each op is individually bounded, but a batch multiplies: 50 screenshots or 50
+ * `get_html` reads compose into one unbounded result — which is exactly the case
+ * `batch` is most useful for. Past the budget, an op's blocks are replaced by a
+ * one-line summary so the caller still learns it ran and what it produced.
+ */
+const DEFAULT_MAX_RESULT_BYTES = 1024 * 1024;
+const MIN_RESULT_BYTES = 4 * 1024;
+const MAX_RESULT_BYTES = 32 * 1024 * 1024;
 /** Validate the `ops` envelope. Structural problems throw (the whole batch is
  *  malformed); per-op semantic problems are handled later as per-op errors. */
 function parseOps(raw) {
@@ -70,6 +81,7 @@ async function runBatch(rawArgs, deps) {
     }
     const stopOnError = (0, validators_1.optionalBoolean)(a, 'stopOnError') ?? false;
     const concurrency = (0, validators_1.optionalNumber)(a, 'maxConcurrency', { min: 1, max: MAX_CONCURRENCY }) ?? DEFAULT_CONCURRENCY;
+    const maxResultBytes = (0, validators_1.optionalNumber)(a, 'maxResultBytes', { min: MIN_RESULT_BYTES, max: MAX_RESULT_BYTES }) ?? DEFAULT_MAX_RESULT_BYTES;
     /** Run one op through the firewall, after the per-op guards. Never throws. */
     const runOne = async (op) => {
         if (op.tool === 'batch')
@@ -99,11 +111,26 @@ async function runBatch(rawArgs, deps) {
         const results = await mapLimit(ops, concurrency, (op) => runOne(op));
         outcomes = results.map((result) => ({ status: result.isError ? 'error' : 'ok', result }));
     }
-    return renderBatch(ops, outcomes, mode);
+    return renderBatch(ops, outcomes, mode, maxResultBytes);
+}
+/** Approximate wire size of one content block (base64 image data dominates when present). */
+function blockBytes(block) {
+    const b = block;
+    if (typeof b.text === 'string')
+        return Buffer.byteLength(b.text, 'utf8');
+    if (typeof b.data === 'string')
+        return b.data.length;
+    return 0;
+}
+/** A one-line stand-in for an op whose blocks were dropped to stay inside the budget. */
+function elidedSummary(index, tool, blocks, bytes) {
+    const kinds = [...new Set(blocks.map((b) => b.type))].join('+') || 'none';
+    return `--- op ${index} (${tool}) omitted: ${blocks.length} ${kinds} block(s), ~${bytes} bytes — batch result budget reached; re-run this op on its own to see it ---`;
 }
 /** Compose the per-op outcomes into one MCP result: a JSON summary block first,
- *  then each executed op's own content blocks (text/images flow through intact). */
-function renderBatch(ops, outcomes, mode) {
+ *  then each executed op's own content blocks (text/images flow through intact),
+ *  stopping at `budget` bytes so one batch cannot flood the caller's context. */
+function renderBatch(ops, outcomes, mode, budget) {
     const summary = outcomes.map((o, i) => ({ index: i, tool: ops[i].tool, status: o.status }));
     const counts = {
         total: ops.length,
@@ -111,17 +138,42 @@ function renderBatch(ops, outcomes, mode) {
         error: summary.filter((s) => s.status === 'error').length,
         skipped: summary.filter((s) => s.status === 'skipped').length,
     };
-    const content = [
-        { type: 'text', text: JSON.stringify({ batch: { mode, ...counts }, results: summary }, null, 2) },
-    ];
+    // Render the payload first so the header can report how much was elided — the
+    // caller needs that number to decide whether to re-run anything.
+    const body = [];
+    let spent = 0;
+    let omittedOps = 0;
+    let omittedBytes = 0;
     for (let i = 0; i < outcomes.length; i++) {
         const o = outcomes[i];
         if (!o.result)
             continue; // skipped ops carry no payload
-        content.push({ type: 'text', text: `--- op ${i} (${ops[i].tool}) ${o.status} ---` });
-        for (const block of o.result.content)
-            content.push(block);
+        const blocks = o.result.content;
+        const size = blocks.reduce((n, b) => n + blockBytes(b), 0);
+        if (spent + size > budget && spent > 0) {
+            // `spent > 0` guarantees the first op always gets through: a single op
+            // larger than the whole budget is still more useful than an empty batch.
+            body.push({ type: 'text', text: elidedSummary(i, ops[i].tool, blocks, size) });
+            omittedOps++;
+            omittedBytes += size;
+            continue;
+        }
+        body.push({ type: 'text', text: `--- op ${i} (${ops[i].tool}) ${o.status} ---` });
+        for (const block of blocks)
+            body.push(block);
+        spent += size;
     }
+    const header = {
+        batch: {
+            mode,
+            ...counts,
+            ...(omittedOps > 0
+                ? { omittedOps, omittedBytes, resultBudgetBytes: budget, note: 'some op payloads were omitted to stay within the batch result budget; raise maxResultBytes or re-run those ops individually' }
+                : {}),
+        },
+        results: summary,
+    };
+    const content = [{ type: 'text', text: JSON.stringify(header, null, 2) }, ...body];
     // The batch ran successfully even if some ops failed; only flag isError when
     // nothing succeeded, so a host sees partial success as success.
     const isError = ops.length > 0 && counts.ok === 0;

package/dist/src/mcp/limits.d.ts

@@ -0,0 +1,43 @@
+/**
+ * src/mcp/limits.ts — output size caps for the page-read tools.
+ *
+ * `eval` has been capped at 256 KB since 0.1 (MAX_EVAL_BYTES) and `screenshot`
+ * reports `truncated` with the real height, but the three tools that read page
+ * CONTENT — get_html, get_text, read_as_markdown — were unbounded. A single
+ * `get_html` on an ordinary content-heavy page can be several megabytes, which is
+ * enough to consume an agent's entire context window in one call, and the caller
+ * has no way to ask for less.
+ *
+ * The cap is applied server-side, after the read: the full payload is still
+ * written to the task's `results/` directory by the handlers that save artifacts,
+ * so nothing is lost on disk — only what crosses into the model's context is
+ * bounded.
+ */
+/** Default cap on a single content read, matching the long-standing eval cap. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+/** Floor/ceiling for a caller-supplied `maxBytes`. */
+export declare const MIN_OUTPUT_BYTES = 1024;
+export declare const MAX_OUTPUT_BYTES: number;
+export interface Truncation {
+    /** The (possibly shortened) text. */
+    text: string;
+    /** True when `text` is shorter than the input. */
+    truncated: boolean;
+    /** UTF-8 byte length of the ORIGINAL text. */
+    totalBytes: number;
+    /** UTF-8 byte length of `text`. */
+    returnedBytes: number;
+}
+/** Truncate plain text (or markdown) to a byte budget. */
+export declare function capText(text: string, maxBytes?: number): Truncation;
+/**
+ * Truncate HTML to a byte budget, backing up to the last tag boundary.
+ *
+ * Cutting mid-tag (`<div class="fo`) hands the caller markup that no parser will
+ * accept and that an LLM will happily hallucinate the rest of. Ending on a `>`
+ * keeps every returned tag complete — the document is still truncated, but every
+ * element in it is well-formed up to the cut.
+ */
+export declare function capHtml(html: string, maxBytes?: number): Truncation;
+/** The metadata fields appended to a truncated read's envelope. */
+export declare function truncationMeta(t: Truncation): Record<string, unknown>;

package/dist/src/mcp/limits.js

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * src/mcp/limits.ts — output size caps for the page-read tools.
+ *
+ * `eval` has been capped at 256 KB since 0.1 (MAX_EVAL_BYTES) and `screenshot`
+ * reports `truncated` with the real height, but the three tools that read page
+ * CONTENT — get_html, get_text, read_as_markdown — were unbounded. A single
+ * `get_html` on an ordinary content-heavy page can be several megabytes, which is
+ * enough to consume an agent's entire context window in one call, and the caller
+ * has no way to ask for less.
+ *
+ * The cap is applied server-side, after the read: the full payload is still
+ * written to the task's `results/` directory by the handlers that save artifacts,
+ * so nothing is lost on disk — only what crosses into the model's context is
+ * bounded.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_OUTPUT_BYTES = exports.MIN_OUTPUT_BYTES = exports.DEFAULT_MAX_OUTPUT_BYTES = void 0;
+exports.capText = capText;
+exports.capHtml = capHtml;
+exports.truncationMeta = truncationMeta;
+/** Default cap on a single content read, matching the long-standing eval cap. */
+exports.DEFAULT_MAX_OUTPUT_BYTES = 256 * 1024;
+/** Floor/ceiling for a caller-supplied `maxBytes`. */
+exports.MIN_OUTPUT_BYTES = 1024;
+exports.MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
+/**
+ * Cut `text` to at most `maxBytes` UTF-8 bytes.
+ *
+ * `Buffer.subarray` slices bytes, which can land mid-codepoint; decoding back to
+ * a string would leave a replacement character at the seam. So the slice is taken
+ * and then trimmed back to the last complete character.
+ */
+function sliceUtf8(text, maxBytes) {
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.byteLength <= maxBytes)
+        return text;
+    let end = maxBytes;
+    // A UTF-8 continuation byte is 10xxxxxx; walk back off the middle of a
+    // multi-byte sequence so the decode is clean.
+    while (end > 0 && (buf[end] & 0b1100_0000) === 0b1000_0000)
+        end--;
+    return buf.subarray(0, end).toString('utf8');
+}
+/** Truncate plain text (or markdown) to a byte budget. */
+function capText(text, maxBytes = exports.DEFAULT_MAX_OUTPUT_BYTES) {
+    const totalBytes = Buffer.byteLength(text, 'utf8');
+    if (totalBytes <= maxBytes) {
+        return { text, truncated: false, totalBytes, returnedBytes: totalBytes };
+    }
+    const cut = sliceUtf8(text, maxBytes);
+    return { text: cut, truncated: true, totalBytes, returnedBytes: Buffer.byteLength(cut, 'utf8') };
+}
+/**
+ * Truncate HTML to a byte budget, backing up to the last tag boundary.
+ *
+ * Cutting mid-tag (`<div class="fo`) hands the caller markup that no parser will
+ * accept and that an LLM will happily hallucinate the rest of. Ending on a `>`
+ * keeps every returned tag complete — the document is still truncated, but every
+ * element in it is well-formed up to the cut.
+ */
+function capHtml(html, maxBytes = exports.DEFAULT_MAX_OUTPUT_BYTES) {
+    const capped = capText(html, maxBytes);
+    if (!capped.truncated)
+        return capped;
+    const lastClose = capped.text.lastIndexOf('>');
+    // Only back up when a boundary exists reasonably near the cut; a single
+    // enormous text node has no tag to align to and is better returned as-is.
+    if (lastClose > 0) {
+        const aligned = capped.text.slice(0, lastClose + 1);
+        return { ...capped, text: aligned, returnedBytes: Buffer.byteLength(aligned, 'utf8') };
+    }
+    return capped;
+}
+/** The metadata fields appended to a truncated read's envelope. */
+function truncationMeta(t) {
+    if (!t.truncated)
+        return {};
+    return {
+        truncated: true,
+        totalBytes: t.totalBytes,
+        returnedBytes: t.returnedBytes,
+        truncationNote: `output capped at ${t.returnedBytes} of ${t.totalBytes} bytes; ` +
+            'raise `maxBytes` for more, or narrow the read with `selector`',
+    };
+}
+//# sourceMappingURL=limits.js.map

package/dist/src/mcp/log.d.ts

@@ -0,0 +1,17 @@
+/**
+ * src/mcp/log.ts — stderr diagnostics, gated by `--log-level`.
+ *
+ * Lives apart from `server.ts` so the tool layer can log without importing the
+ * server module that imports it back. CRITICAL: in stdio mode NOTHING may be
+ * written to stdout except the JSON-RPC stream, so every diagnostic here goes to
+ * stderr.
+ */
+import type { LogLevel } from '../config';
+/** Apply the CLI's `--log-level`. Call before anything else logs. */
+export declare function setLogLevel(level: LogLevel): void;
+/** The level currently in force (for tests, and for callers gating expensive tracing). */
+export declare function getLogLevel(): LogLevel;
+/** stderr only — never stdout in stdio mode. Suppressed at `--log-level silent`. */
+export declare function logErr(message: string): void;
+/** Verbose tracing: emitted only at `--log-level debug`. */
+export declare function logDebug(message: string): void;

package/dist/src/mcp/log.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * src/mcp/log.ts — stderr diagnostics, gated by `--log-level`.
+ *
+ * Lives apart from `server.ts` so the tool layer can log without importing the
+ * server module that imports it back. CRITICAL: in stdio mode NOTHING may be
+ * written to stdout except the JSON-RPC stream, so every diagnostic here goes to
+ * stderr.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLogLevel = setLogLevel;
+exports.getLogLevel = getLogLevel;
+exports.logErr = logErr;
+exports.logDebug = logDebug;
+/**
+ * Active verbosity, set once from `--log-level` at startup.
+ *
+ * `silent` suppresses stderr entirely — an editor MCP config that asked for it
+ * was getting the noise anyway, because the parsed flag was never consumed.
+ * `debug` turns on the wire tracing that `logDebug` guards.
+ */
+let logLevel = 'info';
+/** Apply the CLI's `--log-level`. Call before anything else logs. */
+function setLogLevel(level) {
+    logLevel = level;
+}
+/** The level currently in force (for tests, and for callers gating expensive tracing). */
+function getLogLevel() {
+    return logLevel;
+}
+/** stderr only — never stdout in stdio mode. Suppressed at `--log-level silent`. */
+function logErr(message) {
+    if (logLevel === 'silent')
+        return;
+    process.stderr.write(`[chrome-mcp] ${message}\n`);
+}
+/** Verbose tracing: emitted only at `--log-level debug`. */
+function logDebug(message) {
+    if (logLevel !== 'debug')
+        return;
+    process.stderr.write(`[chrome-mcp] [debug] ${message}\n`);
+}
+//# sourceMappingURL=log.js.map

package/dist/src/mcp/server.d.ts

@@ -7,8 +7,7 @@
  * go to stderr via `logErr`.
  */
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-/** stderr only — never stdout in stdio mode. */
-export declare function logErr(message: string): void;
+export { getLogLevel, logDebug, logErr, setLogLevel } from './log';
 /** Build a fresh `Server` with the full tool surface registered (no transport). */
 export declare function createServer(version?: string): McpServer;
 /** Start over stdio. Idempotent. */

package/dist/src/mcp/server.js

@@ -8,38 +8,42 @@
  * go to stderr via `logErr`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logErr = logErr;
+exports.setLogLevel = exports.logErr = exports.logDebug = exports.getLogLevel = void 0;
 exports.createServer = createServer;
 exports.startMcpServer = startMcpServer;
 exports.stopMcpServer = stopMcpServer;
 exports.isMcpServerRunning = isMcpServerRunning;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const log_1 = require("./log");
 const tools_1 = require("./tools");
+// Re-exported so existing callers (and the CLI) keep importing the logger from
+// here; the implementation lives in ./log to avoid a server↔tools import cycle.
+var log_2 = require("./log");
+Object.defineProperty(exports, "getLogLevel", { enumerable: true, get: function () { return log_2.getLogLevel; } });
+Object.defineProperty(exports, "logDebug", { enumerable: true, get: function () { return log_2.logDebug; } });
+Object.defineProperty(exports, "logErr", { enumerable: true, get: function () { return log_2.logErr; } });
+Object.defineProperty(exports, "setLogLevel", { enumerable: true, get: function () { return log_2.setLogLevel; } });
 const SERVER_NAME = 'chrome-mcp';
 const SERVER_VERSION = '0.1.0';
 /** Default version reported when no explicit version is passed in (legacy callers/tests). */
 const DEFAULT_VERSION = SERVER_VERSION;
 let server = null;
 let transport = null;
-/** stderr only — never stdout in stdio mode. */
-function logErr(message) {
-    process.stderr.write(`[chrome-mcp] ${message}\n`);
-}
 /** Build a fresh `Server` with the full tool surface registered (no transport). */
 function createServer(version = DEFAULT_VERSION) {
     const srv = new mcp_js_1.McpServer({ name: SERVER_NAME, version }, { capabilities: { tools: {} } });
     (0, tools_1.registerTools)(srv);
     // `McpServer` wraps the low-level `Server`, which owns the `onerror` hook.
     srv.server.onerror = (err) => {
-        logErr(`server error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+        (0, log_1.logErr)(`server error: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
     };
     return srv;
 }
 /** Start over stdio. Idempotent. */
 async function startMcpServer(version = DEFAULT_VERSION) {
     if (server) {
-        logErr('startMcpServer called but already running; ignoring.');
+        (0, log_1.logErr)('startMcpServer called but already running; ignoring.');
         return;
     }
     const srv = createServer(version);
@@ -48,14 +52,14 @@ async function startMcpServer(version = DEFAULT_VERSION) {
         await srv.connect(tx);
     }
     catch (err) {
-        logErr(`failed to connect stdio transport: ${String(err)}`);
+        (0, log_1.logErr)(`failed to connect stdio transport: ${String(err)}`);
         server = null;
         transport = null;
         throw err;
     }
     server = srv;
     transport = tx;
-    logErr(`${SERVER_NAME} v${version} connected over stdio.`);
+    (0, log_1.logErr)(`${SERVER_NAME} v${version} connected over stdio.`);
 }
 /** Stop and release the transport. Idempotent, best-effort. */
 async function stopMcpServer() {
@@ -69,15 +73,15 @@ async function stopMcpServer() {
         await srv.close();
     }
     catch (err) {
-        logErr(`error closing server: ${String(err)}`);
+        (0, log_1.logErr)(`error closing server: ${String(err)}`);
     }
     try {
         await tx?.close();
     }
     catch (err) {
-        logErr(`error closing transport: ${String(err)}`);
+        (0, log_1.logErr)(`error closing transport: ${String(err)}`);
     }
-    logErr('MCP server stopped.');
+    (0, log_1.logErr)('MCP server stopped.');
 }
 function isMcpServerRunning() {
     return server !== null;

package/dist/src/mcp/tools.js

@@ -23,8 +23,10 @@ const types_1 = require("../executor/types");
 const manager_1 = require("../executor/manager");
 const policy_1 = require("../security/policy");
 const envelopes_1 = require("./envelopes");
+const limits_1 = require("./limits");
 const batch_1 = require("./batch");
 const helpers_1 = require("./helpers");
+const log_1 = require("./log");
 const tasks_1 = require("../bridge/tasks");
 const workspace_1 = require("../bridge/workspace");
 const validators_1 = require("./validators");
@@ -34,6 +36,10 @@ const TARGET_PROPS = {
     ref: zod_1.z.string().describe('Element ref from a prior read (exactly one of selector|ref)').optional(),
 };
 const tabIdField = zod_1.z.string().describe('Target tab id (defaults to the active tab)').optional();
+const maxBytesField = zod_1.z
+    .number()
+    .describe(`Cap the returned content at this many UTF-8 bytes (default ${limits_1.DEFAULT_MAX_OUTPUT_BYTES}). A truncated result reports truncated/totalBytes/returnedBytes. The full payload is still written to the task's results/ dir.`)
+    .optional();
 const waitUntilField = zod_1.z.enum(['load', 'domcontentloaded', 'networkidle']).describe('When to consider navigation done').optional();
 exports.TOOL_DEFINITIONS = [
     { name: 'tabs_list', description: 'List open browser tabs.', inputSchema: {} },
@@ -51,15 +57,15 @@ exports.TOOL_DEFINITIONS = [
     { name: 'hover', description: 'Hover over an element.', inputSchema: { ...TARGET_PROPS, tabId: tabIdField } },
     { name: 'scroll', description: 'Scroll the page or to an element.', inputSchema: { ...TARGET_PROPS, x: zod_1.z.number().optional(), y: zod_1.z.number().optional(), deltaX: zod_1.z.number().optional(), deltaY: zod_1.z.number().optional(), tabId: tabIdField } },
     { name: 'screenshot', description: 'Capture a PNG screenshot (page or element).', inputSchema: { ...TARGET_PROPS, fullPage: zod_1.z.boolean().optional(), tabId: tabIdField } },
-    { name: 'get_text', description: 'Get visible text of the page or an element.', inputSchema: { ...TARGET_PROPS, tabId: tabIdField } },
-    { name: 'get_html', description: 'Get HTML of the page or an element.', inputSchema: { ...TARGET_PROPS, outer: zod_1.z.boolean().optional(), tabId: tabIdField } },
+    { name: 'get_text', description: 'Get visible text of the page or an element.', inputSchema: { ...TARGET_PROPS, tabId: tabIdField, maxBytes: maxBytesField } },
+    { name: 'get_html', description: 'Get HTML of the page or an element. Output is capped (see maxBytes) and cut at a tag boundary; narrow it with `selector` rather than raising the cap when you can.', inputSchema: { ...TARGET_PROPS, outer: zod_1.z.boolean().optional(), tabId: tabIdField, maxBytes: maxBytesField } },
     { name: 'snapshot', description: 'Accessibility snapshot: interactive elements with stable refs to target by `ref` (more reliable than guessing CSS selectors).', inputSchema: { interactiveOnly: zod_1.z.boolean().optional(), max: zod_1.z.number().optional(), tabId: tabIdField } },
     { name: 'get_cookies', description: "Read cookies visible to the tab's URL (or a given url).", inputSchema: { url: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'storage', description: 'Read/write localStorage (or sessionStorage). op: get|set|remove|clear.', inputSchema: { op: zod_1.z.enum(['get', 'set', 'remove', 'clear']), key: zod_1.z.string().optional(), value: zod_1.z.string().optional(), session: zod_1.z.boolean().optional(), tabId: tabIdField } },
     { name: 'eval', description: 'Evaluate JavaScript in the page (disabled in safe-mode).', inputSchema: { expression: zod_1.z.string(), awaitPromise: zod_1.z.boolean().optional(), tabId: tabIdField } },
     { name: 'wait_for', description: 'Wait for a selector or text to appear/disappear.', inputSchema: { selector: zod_1.z.string().optional(), textContains: zod_1.z.string().optional(), gone: zod_1.z.boolean().optional(), timeoutMs: zod_1.z.number().optional(), tabId: tabIdField } },
     { name: 'extract_links', description: 'Extract anchors from the page or a subtree. dedupe=true collapses links sharing an href (nav/footer noise); limit caps the count.', inputSchema: { selector: zod_1.z.string().optional(), sameOriginOnly: zod_1.z.boolean().optional(), dedupe: zod_1.z.boolean().optional(), limit: zod_1.z.number().optional(), tabId: tabIdField } },
-    { name: 'read_as_markdown', description: 'Read the page (or subtree) as readable markdown.', inputSchema: { selector: zod_1.z.string().optional(), tabId: tabIdField } },
+    { name: 'read_as_markdown', description: 'Read the page (or subtree) as readable markdown.', inputSchema: { selector: zod_1.z.string().optional(), tabId: tabIdField, maxBytes: maxBytesField } },
     { name: 'fill_form', description: 'Fill multiple fields (keyed by selector) and optionally submit.', inputSchema: { fields: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()])), submitSelector: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'download_file', description: 'Download a file by URL or from a link element.', inputSchema: { url: zod_1.z.string().optional(), ...TARGET_PROPS, suggestedName: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'upload_file', description: 'Set local file(s) on a file <input> (target by selector or ref) — uploads without the OS dialog. Requires --enable-uploads. `files` are absolute local paths.', inputSchema: { ...TARGET_PROPS, files: zod_1.z.array(zod_1.z.string()), tabId: tabIdField } },
@@ -78,27 +84,38 @@ exports.TOOL_DEFINITIONS = [
             mode: zod_1.z.enum(['parallel', 'serial']).describe('Default "parallel".').optional(),
             stopOnError: zod_1.z.boolean().describe('Serial mode only: stop after the first failing op (the rest are skipped).').optional(),
             maxConcurrency: zod_1.z.number().describe('Parallel mode: max ops in flight at once (default 6).').optional(),
+            maxResultBytes: zod_1.z.number().describe('Total payload budget across all ops (default 1048576). Ops past the budget are replaced by a one-line summary instead of their content, so a 50-op screenshot/get_html batch cannot flood the caller.').optional(),
         },
     },
 ];
-const GATE_CONTEXT = 'cannot resolve the active tab URL for the policy gate';
+const GATE_CONTEXT = 'cannot resolve the target tab URL for the policy gate';
 /**
- * Resolve the URL the policy should be evaluated against (the active tab).
+ * Resolve the URL the policy should be evaluated against: the URL of the tab
+ * this very call will act on — the explicit `tabId` when the caller gave one,
+ * the active tab only when they didn't.
  *
- * NEVER substitutes a placeholder URL. If the tab list can't be read, the real
- * origin is unknown, and evaluating the policy against a fabricated URL would
- * silently allow or deny against the wrong origin with no signal to the caller.
- * So a `tabsList` failure (or a browser reporting no tabs at all) propagates —
- * the dispatch firewall renders it as a structured error carrying the code.
+ * Gating on the ACTIVE tab regardless of `tabId` is an authorization bypass:
+ * park an allowlisted page as active and every `tabId`-addressed read (get_text,
+ * get_html, screenshot, eval, …) sails through against a tab whose origin was
+ * never checked. The tab that gets touched is the tab that must be authorized.
+ *
+ * NEVER substitutes a placeholder URL, and never falls back to some *other*
+ * tab. If the real origin is unknown, evaluating the policy against a stand-in
+ * would silently allow or deny against the wrong origin with no signal to the
+ * caller. So a `tabsList` failure (or a browser reporting no tabs at all)
+ * propagates — the dispatch firewall renders it as an error carrying the code.
  *
  * Prefers a URL the backend already reported over asking again: the extension
  * rides the tab's landing URL home on every result frame, which is what keeps a
- * gated call to ONE round-trip instead of two.
+ * gated call to ONE round-trip instead of two. That cache only ever describes
+ * the active tab, so it is bypassed whenever an explicit `tabId` is in play.
  */
-async function activeUrl(ex) {
-    const known = ex.cachedActiveUrl?.();
-    if (known)
-        return known;
+async function gatedUrl(ex, tabId) {
+    if (!tabId) {
+        const known = ex.cachedActiveUrl?.();
+        if (known)
+            return known;
+    }
     let tabs;
     try {
         tabs = await ex.tabsList();
@@ -111,33 +128,44 @@ async function activeUrl(ex) {
             throw new types_1.ExecutorError(err.code, `${GATE_CONTEXT}: ${err.message}`);
         throw err; // an internal fault, not a browser one — don't relabel it
     }
-    const active = tabs.find((t) => t.active) ?? tabs[0];
-    if (!active)
+    if (tabs.length === 0) {
         throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the browser reports no open tabs`);
+    }
+    const target = tabId ? tabs.find((t) => t.tabId === tabId) : tabs.find((t) => t.active);
+    if (!target) {
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', tabId
+            ? `${GATE_CONTEXT}: no open tab has id ${tabId} — call tabs_list for the current ids`
+            : `${GATE_CONTEXT}: the browser reports open tabs but none active — pass an explicit tabId`);
+    }
     // An empty URL is Chrome declining to reveal one (a chrome:// page, or a tab
     // the extension has no host access to) — NOT an origin. Gating on '' would
     // produce a baffling "blocked on " denial that reads like a policy decision.
-    if (!active.url) {
-        throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the active tab (id ${active.tabId}) reports no URL. Chrome hides it for ` +
+    if (!target.url) {
+        throw new types_1.ExecutorError('TAB_NOT_FOUND', `${GATE_CONTEXT}: the target tab (id ${target.tabId}) reports no URL. Chrome hides it for ` +
             `internal pages (chrome://, the Web Store) and until the extension has access to that site — ` +
             `switch to a normal page, or open the target site in a new tab.`);
     }
-    return active.url;
+    return target.url;
 }
 /**
- * Policy chokepoint. `urlOverride` is the destination for navigation.
+ * Policy chokepoint. `opts.url` is the destination for navigation (it governs
+ * instead of any current tab URL); `opts.tabId` is the tab the call will act on,
+ * and MUST be threaded through by every URL-gated handler that accepts one —
+ * omitting it silently authorizes the call against the active tab instead.
  *
- * Only resolves the active URL for methods whose verdict actually depends on one
+ * Only resolves a tab URL for methods whose verdict actually depends on one
  * (`isUrlGated`). Tab management and the capability gates — eval, downloads,
  * uploads, mutations — are decided without any URL, so making them wait on the
  * tab list bought nothing and, worse, made `tab_new` fail exactly when the tab
  * list was unreadable: the one call that could dig you out.
  */
-async function gate(ctx, method, urlOverride) {
-    const url = urlOverride ?? ((0, policy_1.isUrlGated)(method) ? await activeUrl(ctx.ex) : '');
+async function gate(ctx, method, opts = {}) {
+    const url = opts.url ?? ((0, policy_1.isUrlGated)(method) ? await gatedUrl(ctx.ex, opts.tabId) : '');
     (0, policy_1.assertUrlAllowed)(url, method, ctx.policy);
 }
 const tabId = (args) => (0, validators_1.optionalString)(args, 'tabId');
+/** The caller's output cap for a content read, or the default. */
+const maxBytes = (args) => (0, validators_1.optionalNumber)(args, 'maxBytes', { min: limits_1.MIN_OUTPUT_BYTES, max: limits_1.MAX_OUTPUT_BYTES }) ?? limits_1.DEFAULT_MAX_OUTPUT_BYTES;
 const waitUntil = (args) => (0, validators_1.optionalString)(args, 'waitUntil');
 /** Tools that don't act on a single tab (so `tabId` is irrelevant) — exempt from
  *  the parallel-batch explicit-tabId requirement. Everything else falls back to
@@ -180,24 +208,24 @@ exports.TOOL_HANDLERS = {
     },
     navigate: async (a, ctx) => {
         const url = (0, validators_1.requireString)(a, 'url');
-        await gate(ctx, 'navigate', url);
+        await gate(ctx, 'navigate', { url });
         return (0, envelopes_1.jsonResult)(await ctx.ex.navigate({ url, tabId: tabId(a), waitUntil: waitUntil(a) }));
     },
     back: async (a, ctx) => {
-        await gate(ctx, 'back');
+        await gate(ctx, 'back', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.back(tabId(a)));
     },
     forward: async (a, ctx) => {
-        await gate(ctx, 'forward');
+        await gate(ctx, 'forward', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.forward(tabId(a)));
     },
     reload: async (a, ctx) => {
-        await gate(ctx, 'reload');
+        await gate(ctx, 'reload', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) }));
     },
     click: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'click');
+        await gate(ctx, 'click', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.click(t, {
             tabId: tabId(a),
             button: (0, validators_1.optionalString)(a, 'button'),
@@ -207,7 +235,7 @@ exports.TOOL_HANDLERS = {
     },
     type: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'type');
+        await gate(ctx, 'type', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.type(t, (0, validators_1.requireWithinLength)((0, validators_1.requireString)(a, 'text'), 'text', validators_1.MAX_TEXT_LEN), {
             tabId: tabId(a),
             clear: (0, validators_1.optionalBoolean)(a, 'clear'),
@@ -218,14 +246,14 @@ exports.TOOL_HANDLERS = {
     },
     select_option: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'type'); // mutating
+        await gate(ctx, 'type', { tabId: tabId(a) }); // mutating
         const values = (0, validators_1.optionalStringArray)(a, 'values');
         if (!values || values.length === 0)
             throw new validators_1.McpToolError('"values" must be a non-empty array of strings');
         return (0, envelopes_1.jsonResult)(await ctx.ex.selectOption(t, values, { tabId: tabId(a) }));
     },
     press: async (a, ctx) => {
-        await gate(ctx, 'press');
+        await gate(ctx, 'press', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
             tabId: tabId(a),
             modifiers: (0, validators_1.optionalStringArray)(a, 'modifiers'),
@@ -233,11 +261,11 @@ exports.TOOL_HANDLERS = {
     },
     hover: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'hover');
+        await gate(ctx, 'hover', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.hover(t, { tabId: tabId(a) }));
     },
     scroll: async (a, ctx) => {
-        await gate(ctx, 'scroll');
+        await gate(ctx, 'scroll', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.scroll({
             tabId: tabId(a),
             x: (0, validators_1.optionalNumber)(a, 'x'),
@@ -248,7 +276,7 @@ exports.TOOL_HANDLERS = {
         }));
     },
     screenshot: async (a, ctx) => {
-        await gate(ctx, 'screenshot');
+        await gate(ctx, 'screenshot', { tabId: tabId(a) });
         const shot = await ctx.ex.screenshot({
             tabId: tabId(a),
             fullPage: (0, validators_1.optionalBoolean)(a, 'fullPage'),
@@ -259,17 +287,22 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.imageResult)(shot.dataBase64, shot.mimeType, caption);
     },
     get_text: async (a, ctx) => {
-        await gate(ctx, 'get_text');
+        await gate(ctx, 'get_text', { tabId: tabId(a) });
         const res = await ctx.ex.getText((0, validators_1.optionalTarget)(a), { tabId: tabId(a) });
+        // Save the FULL read before capping — the artifact on disk stays lossless;
+        // only what crosses into the caller's context is bounded.
         (0, workspace_1.saveResult)('get_text', 'json', JSON.stringify(res, null, 2));
-        return (0, envelopes_1.jsonResult)(res);
+        const capped = (0, limits_1.capText)(res.text, maxBytes(a));
+        return (0, envelopes_1.jsonResult)({ ...res, text: capped.text, ...(0, limits_1.truncationMeta)(capped) });
     },
     get_html: async (a, ctx) => {
-        await gate(ctx, 'get_html');
-        return (0, envelopes_1.jsonResult)(await ctx.ex.getHtml((0, validators_1.optionalTarget)(a), { tabId: tabId(a), outer: (0, validators_1.optionalBoolean)(a, 'outer') }));
+        await gate(ctx, 'get_html', { tabId: tabId(a) });
+        const res = await ctx.ex.getHtml((0, validators_1.optionalTarget)(a), { tabId: tabId(a), outer: (0, validators_1.optionalBoolean)(a, 'outer') });
+        const capped = (0, limits_1.capHtml)(res.html, maxBytes(a));
+        return (0, envelopes_1.jsonResult)({ ...res, html: capped.text, ...(0, limits_1.truncationMeta)(capped) });
     },
     snapshot: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // read of page structure
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page structure
         return (0, envelopes_1.jsonResult)(await ctx.ex.snapshot({
             tabId: tabId(a),
             interactiveOnly: (0, validators_1.optionalBoolean)(a, 'interactiveOnly'),
@@ -277,13 +310,13 @@ exports.TOOL_HANDLERS = {
         }));
     },
     get_cookies: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // reads tab-scoped secrets; same domain gate as content reads
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // reads tab-scoped secrets; same domain gate as content reads
         return (0, envelopes_1.jsonResult)(await ctx.ex.getCookies({ tabId: tabId(a), url: (0, validators_1.optionalString)(a, 'url') }));
     },
     storage: async (a, ctx) => {
         const op = (0, validators_1.requireString)(a, 'op');
         // get is a read; set/remove/clear mutate.
-        await gate(ctx, op === 'get' ? 'get_text' : 'type');
+        await gate(ctx, op === 'get' ? 'get_text' : 'type', { tabId: tabId(a) });
         if ((op === 'set' || op === 'remove') && !(0, validators_1.optionalString)(a, 'key')) {
             throw new validators_1.McpToolError(`storage "${op}" requires a "key"`);
         }
@@ -296,14 +329,14 @@ exports.TOOL_HANDLERS = {
         }));
     },
     eval: async (a, ctx) => {
-        await gate(ctx, 'eval');
+        await gate(ctx, 'eval', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.eval((0, validators_1.requireString)(a, 'expression'), {
             tabId: tabId(a),
             awaitPromise: (0, validators_1.optionalBoolean)(a, 'awaitPromise'),
         }));
     },
     wait_for: async (a, ctx) => {
-        await gate(ctx, 'wait_for');
+        await gate(ctx, 'wait_for', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.waitFor({
             tabId: tabId(a),
             selector: (0, validators_1.optionalString)(a, 'selector'),
@@ -313,7 +346,7 @@ exports.TOOL_HANDLERS = {
         }));
     },
     extract_links: async (a, ctx) => {
-        await gate(ctx, 'get_text'); // read of page content
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page content
         const res = await (0, helpers_1.extractLinks)(ctx.ex, {
             selector: (0, validators_1.optionalString)(a, 'selector'),
             sameOriginOnly: (0, validators_1.optionalBoolean)(a, 'sameOriginOnly'),
@@ -325,13 +358,18 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.jsonResult)(res);
     },
     read_as_markdown: async (a, ctx) => {
-        await gate(ctx, 'get_text');
+        await gate(ctx, 'get_text', { tabId: tabId(a) });
         const md = await (0, helpers_1.readAsMarkdown)(ctx.ex, { selector: (0, validators_1.optionalString)(a, 'selector'), tabId: tabId(a) });
         (0, workspace_1.saveResult)('read_as_markdown', 'md', md);
-        return (0, envelopes_1.textResult)(md);
+        const capped = (0, limits_1.capText)(md, maxBytes(a));
+        // Markdown is returned as plain text, so the truncation notice has to ride in
+        // the body rather than as sibling JSON fields.
+        return (0, envelopes_1.textResult)(capped.truncated
+            ? `${capped.text}\n\n[truncated: ${capped.returnedBytes} of ${capped.totalBytes} bytes — raise maxBytes or narrow with selector; the full document was saved to the task's results/ dir]`
+            : capped.text);
     },
     fill_form: async (a, ctx) => {
-        await gate(ctx, 'type'); // mutating
+        await gate(ctx, 'type', { tabId: tabId(a) }); // mutating
         const fields = a.fields;
         if (typeof fields !== 'object' || fields === null || Array.isArray(fields)) {
             throw new validators_1.McpToolError('"fields" must be an object mapping selector -> string|boolean');
@@ -356,7 +394,7 @@ exports.TOOL_HANDLERS = {
     },
     upload_file: async (a, ctx) => {
         const t = (0, validators_1.requireTarget)(a);
-        await gate(ctx, 'upload_file');
+        await gate(ctx, 'upload_file', { tabId: tabId(a) });
         const files = (0, validators_1.optionalStringArray)(a, 'files');
         if (!files || files.length === 0)
             throw new validators_1.McpToolError('"files" must be a non-empty array of absolute local paths');
@@ -448,6 +486,27 @@ function summarizeArgs(rawArgs) {
 function recordHistory(tool, rawArgs, ok, error) {
     (0, workspace_1.appendHistory)({ ts: new Date().toISOString(), tool, args: summarizeArgs(rawArgs), ok, ...(error ? { error } : {}) });
 }
+/**
+ * Tools it is safe to re-issue after the extension drops mid-flight.
+ *
+ * MV3 recycles the extension's service worker on its own schedule, so a command
+ * can be in flight when the socket goes away — a fault that has nothing to do
+ * with the call and that the user currently fixes by re-issuing the identical
+ * request by hand. Only idempotent calls are eligible: repeating a `click` or a
+ * `type` could submit a form twice, which is not a cost worth paying to avoid one
+ * error message. `navigate` is included because landing on the same URL twice is
+ * the same end state.
+ */
+const RETRY_SAFE_TOOLS = new Set([
+    'tabs_list', 'chrome_status',
+    'get_text', 'get_html', 'snapshot', 'get_cookies',
+    'extract_links', 'read_as_markdown', 'screenshot',
+    'wait_for', 'navigate', 'reload',
+]);
+/** Whether `err` is the transient bridge fault that a single retry can clear. */
+function isRetryableFault(name, err) {
+    return err instanceof types_1.ExecutorError && err.code === 'EXTENSION_DISCONNECTED' && RETRY_SAFE_TOOLS.has(name);
+}
 async function dispatchToolCall(name, rawArgs) {
     const handler = exports.TOOL_HANDLERS[name];
     if (!handler)
@@ -459,7 +518,21 @@ async function dispatchToolCall(name, rawArgs) {
         // Workspace-management tools run server-side and must work even with no
         // browser paired, so they skip the executor readiness check.
         const ex = NO_BACKEND_TOOLS.has(name) ? null : await mgr.ensureReady();
-        const result = await handler((0, validators_1.asArgs)(rawArgs), { ex, policy: mgr.policy });
+        let result;
+        try {
+            result = await handler((0, validators_1.asArgs)(rawArgs), { ex, policy: mgr.policy });
+        }
+        catch (err) {
+            if (!isRetryableFault(name, err))
+                throw err;
+            // Re-pair (ensureReady resolves the new connection) and try once more. A
+            // second failure propagates untouched, so a genuinely unpaired browser
+            // still reports EXTENSION_DISCONNECTED rather than retrying forever.
+            (0, log_1.logDebug)(`${name}: extension disconnected mid-call; re-pairing and retrying once`);
+            const reconnected = await mgr.ensureReady();
+            result = await handler((0, validators_1.asArgs)(rawArgs), { ex: reconnected, policy: mgr.policy });
+            (0, log_1.logDebug)(`${name}: retry after reconnect succeeded`);
+        }
         recordHistory(name, rawArgs, !result.isError);
         return result;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "Drive your real Chrome browser over MCP — real logins, real cookies. A stdio MCP server (CLI) plus an MV3 extension, driving Chrome via chrome.scripting/chrome.tabs. Multi-tab batch automation, accessibility snapshots, deny-all security by default.",
   "author": "Mehmood Ur Rehman Qureshi",
   "license": "MIT",