@mehmoodqureshi/chrome-mcp 0.4.2 → 0.5.0

package/README.md

@@ -84,14 +84,52 @@ OS dialog (requires `--enable-uploads`).
 `click`/`type` accept `trusted: true` for real OS-level input (works on
 React/Vue controlled inputs); interactions auto-wait for the target to appear.
 
+### Driving several tabs at once — `batch`
+
+`batch` runs many tool calls in **one** request — `parallel` (default) or
+`serial` (with optional `stopOnError`). Each sub-op goes through the **same**
+policy gate, rate limit, and error handling as a direct call (no bypass,
+no nesting). Use it to fan work out across tabs:
+
+```jsonc
+// open three product pages (background, so they don't fight for focus)…
+{ "name": "batch", "arguments": { "ops": [
+  { "tool": "tab_new", "args": { "url": "https://a.example/p" } },
+  { "tool": "tab_new", "args": { "url": "https://b.example/p" } },
+  { "tool": "tab_new", "args": { "url": "https://c.example/p" } }
+]}}
+
+// …then read them all at once (wall-clock ≈ the slowest one, not the sum)
+{ "name": "batch", "arguments": { "ops": [
+  { "tool": "get_text", "args": { "tabId": "<a tabId>" } },
+  { "tool": "get_text", "args": { "tabId": "<b tabId>" } },
+  { "tool": "get_text", "args": { "tabId": "<c tabId>" } }
+]}}
+```
+
+In `parallel` mode, tab-scoped ops **must** pass an explicit `tabId` — the
+active-tab default is unsafe under concurrency, so it's rejected rather than
+silently mis-routed. (`tab_new`, `tabs_list`, `chrome_status` are exempt.)
+
+> **`tab_new` focuses the new tab by default** (so "open X" behaves like opening
+> a link, instead of replacing your current page — use `tab_new`, not
+> `navigate`, to open without losing the current tab). Pass `active: false` to
+> open in the background; parallel batches do this automatically.
+
 ## Status
 
-v0.2.0 — all six build phases complete and green (57 automated tests + a gated
-headed extension smoke). End-to-end working: `npx chrome-mcp` ⇄ bridge ⇄
-extension ⇄ your real Chrome, with a Playwright CDP fallback. v0.2 adds the
-accessibility `snapshot` + element refs, auto-wait, cookies/storage/`select_option`,
-trusted input (`chrome.debugger`), a toolbar status badge, and a stable pairing
-token (`--persist-token`).
+v0.5.0 — **safe multi-tab concurrency.** Adds the `batch` fan-out tool, makes
+parallel tab automation race-free (explicit-`tabId` guard; per-tab
+`chrome.debugger` serialization; collision-free `tab_new`), captures screenshots
+via `chrome.debugger` (a specific tab without stealing focus — plus true
+full-page and element capture), and focuses newly opened tabs by default. 111
+automated tests + a gated headed extension smoke.
+
+v0.2.0 — all six build phases complete and green. End-to-end working:
+`npx chrome-mcp` ⇄ bridge ⇄ extension ⇄ your real Chrome, with a Playwright CDP
+fallback. v0.2 adds the accessibility `snapshot` + element refs, auto-wait,
+cookies/storage/`select_option`, trusted input (`chrome.debugger`), a toolbar
+status badge, and a stable pairing token (`--persist-token`).
 
 - [x] **Phase 0 — Contracts & skeleton:** `shared/protocol.ts` (wire contract),
       `src/executor/types.ts` (Executor interface), `src/security/policy.ts`
@@ -162,8 +200,10 @@ from the extension's **Options** page using the `port` + `token` from
 `~/.chrome-mcp/handshake.json` (run `npx chrome-mcp --print-pairing` to get the
 path).
 
-> **v1 uses `chrome.scripting`/`chrome.tabs`, not `chrome.debugger`.** No
-> "is being debugged" banner, CSP-safe reads (isolated world), and it's testable
-> under Playwright. Trade-off: clicks/typing are synthetic DOM events, not
-> OS-level trusted input, and `screenshot` is visible-tab only. A trusted-input
-> `chrome.debugger` backend is a documented future upgrade (BLUEPRINT §10).
+> **Reads/interaction use `chrome.scripting`/`chrome.tabs`** — no "is being
+> debugged" banner, CSP-safe reads (isolated world), testable under Playwright.
+> `chrome.debugger` is used only where it's needed and worth it: `trusted: true`
+> input (real OS-level events on React/Vue inputs) and `screenshot` (captures a
+> specific tab **without** activating it — safe under parallel `batch` — with
+> true full-page and element capture). Those ops briefly show the debug banner
+> while attached.

package/dist/shared/mutex.d.ts

@@ -0,0 +1,18 @@
+/**
+ * shared/mutex.ts — a tiny per-key async lock.
+ *
+ * Calls sharing a key run one-at-a-time in FIFO order; different keys run
+ * concurrently. Pure promises, no platform deps, so it's reusable by the
+ * extension service worker and unit-testable without Chrome.
+ *
+ * Used in the SW to serialize chrome.debugger attach→work→detach per tab (a
+ * second attach on the same tab throws, and one op's detach would yank the
+ * debugger from a concurrent op) while keeping different tabs parallel.
+ */
+export declare class KeyedMutex {
+    private readonly tails;
+    /** Run `fn` after all earlier holders of `key` settle. Resolves/rejects with fn's outcome. */
+    run<T>(key: string, fn: () => Promise<T> | T): Promise<T>;
+    /** Number of keys with an outstanding or queued holder (for tests/inspection). */
+    get size(): number;
+}

package/dist/shared/mutex.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * shared/mutex.ts — a tiny per-key async lock.
+ *
+ * Calls sharing a key run one-at-a-time in FIFO order; different keys run
+ * concurrently. Pure promises, no platform deps, so it's reusable by the
+ * extension service worker and unit-testable without Chrome.
+ *
+ * Used in the SW to serialize chrome.debugger attach→work→detach per tab (a
+ * second attach on the same tab throws, and one op's detach would yank the
+ * debugger from a concurrent op) while keeping different tabs parallel.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyedMutex = void 0;
+function noop() {
+    /* swallow — the tracker must never reject so the queue keeps flowing */
+}
+class KeyedMutex {
+    tails = new Map();
+    /** Run `fn` after all earlier holders of `key` settle. Resolves/rejects with fn's outcome. */
+    run(key, fn) {
+        const prev = this.tails.get(key) ?? Promise.resolve();
+        // Run fn whether the previous holder resolved or rejected (its failure must
+        // not poison this one).
+        const result = prev.then(fn, fn);
+        // A non-rejecting tracker the next waiter chains on.
+        const tail = result.then(noop, noop);
+        this.tails.set(key, tail);
+        void tail.then(() => {
+            // Only drop the entry if no newer waiter has replaced it.
+            if (this.tails.get(key) === tail)
+                this.tails.delete(key);
+        });
+        return result;
+    }
+    /** Number of keys with an outstanding or queued holder (for tests/inspection). */
+    get size() {
+        return this.tails.size;
+    }
+}
+exports.KeyedMutex = KeyedMutex;
+//# sourceMappingURL=mutex.js.map

package/dist/shared/screenshot.d.ts

@@ -0,0 +1,58 @@
+/**
+ * shared/screenshot.ts — pure screenshot-planning logic, shared so it can be
+ * unit-tested without Chrome and reused by the extension SW.
+ *
+ * Turns measured page dimensions (and an optional element rect) into the
+ * `Page.captureScreenshot` clip + the logical dimensions/truncation flags the
+ * `ScreenshotResult` reports. No chrome.* calls — just arithmetic.
+ */
+/** Measured page geometry, in CSS pixels. */
+export interface PageDims {
+    /** Viewport width/height. */
+    w: number;
+    h: number;
+    /** Full content box (document) width/height. */
+    fullW: number;
+    fullH: number;
+}
+/** An element's box in DOCUMENT coordinates (viewport rect + scroll offset), CSS px. */
+export interface ElementRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A CDP `Page.captureScreenshot` clip (CSS px; `scale` multiplies output). */
+export interface CaptureClip {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    scale: number;
+}
+export interface ScreenshotPlan {
+    /** Omitted for a plain viewport capture (capture whatever is visible). */
+    clip?: CaptureClip;
+    /** Must be true whenever a clip reaches outside the current viewport. */
+    captureBeyondViewport: boolean;
+    /** Logical (CSS px) dimensions to report back in ScreenshotResult. */
+    width: number;
+    height: number;
+    /** The capture was clamped below the real content/element height. */
+    truncated: boolean;
+    /** The true height when `truncated` (or for any fullPage/element capture). */
+    fullHeight?: number;
+}
+/**
+ * Practical single-capture height ceiling. Skia/CDP cannot encode arbitrarily
+ * tall images; beyond this we clamp the clip and flag `truncated`.
+ */
+export declare const MAX_CAPTURE_PX = 16384;
+/**
+ * Plan a capture. Element clip wins over fullPage; fullPage wins over the plain
+ * viewport capture. Heights are clamped to MAX_CAPTURE_PX with `truncated` set.
+ */
+export declare function planScreenshot(dims: PageDims, opts?: {
+    fullPage?: boolean;
+    element?: ElementRect | null;
+}): ScreenshotPlan;

package/dist/shared/screenshot.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * shared/screenshot.ts — pure screenshot-planning logic, shared so it can be
+ * unit-tested without Chrome and reused by the extension SW.
+ *
+ * Turns measured page dimensions (and an optional element rect) into the
+ * `Page.captureScreenshot` clip + the logical dimensions/truncation flags the
+ * `ScreenshotResult` reports. No chrome.* calls — just arithmetic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CAPTURE_PX = void 0;
+exports.planScreenshot = planScreenshot;
+/**
+ * Practical single-capture height ceiling. Skia/CDP cannot encode arbitrarily
+ * tall images; beyond this we clamp the clip and flag `truncated`.
+ */
+exports.MAX_CAPTURE_PX = 16384;
+/**
+ * Plan a capture. Element clip wins over fullPage; fullPage wins over the plain
+ * viewport capture. Heights are clamped to MAX_CAPTURE_PX with `truncated` set.
+ */
+function planScreenshot(dims, opts = {}) {
+    if (opts.element) {
+        const realH = Math.max(1, Math.round(opts.element.h));
+        const clipH = Math.min(opts.element.h, exports.MAX_CAPTURE_PX);
+        return {
+            clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale: 1 },
+            captureBeyondViewport: true,
+            width: Math.max(1, Math.round(opts.element.w)),
+            height: Math.min(realH, exports.MAX_CAPTURE_PX),
+            truncated: realH > exports.MAX_CAPTURE_PX,
+            fullHeight: realH,
+        };
+    }
+    if (opts.fullPage) {
+        const clipH = Math.min(dims.fullH, exports.MAX_CAPTURE_PX);
+        return {
+            clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale: 1 },
+            captureBeyondViewport: true,
+            width: dims.fullW,
+            height: clipH,
+            truncated: dims.fullH > clipH,
+            fullHeight: dims.fullH,
+        };
+    }
+    // Plain viewport: no clip, capture what's visible.
+    return {
+        captureBeyondViewport: false,
+        width: dims.w,
+        height: dims.h,
+        truncated: false,
+    };
+}
+//# sourceMappingURL=screenshot.js.map

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

@@ -54,7 +54,9 @@ export declare class CdpExecutor implements Executor {
     private guard;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
-    tabNew(url?: string): Promise<TabInfo>;
+    tabNew(url?: string, opts?: {
+        active?: boolean;
+    }): Promise<TabInfo>;
     tabClose(tabId: TabId): Promise<{
         closed: true;
         tabId: TabId;

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

@@ -288,11 +288,13 @@ class CdpExecutor {
         await p.bringToFront().catch(() => undefined);
         return { tabId, url: p.url(), title: await p.title().catch(() => ''), active: true, index: 0 };
     }
-    async tabNew(url) {
+    async tabNew(url, opts) {
         const ctx = await this.getContext();
         const p = await ctx.newPage();
         if (url)
             await p.goto(url, { waitUntil: 'load' }).catch(() => undefined);
+        if (opts?.active !== false)
+            await p.bringToFront().catch(() => undefined);
         return { tabId: this.idFor(p), url: p.url(), title: await p.title().catch(() => ''), active: true, index: 0 };
     }
     async tabClose(tabId) {

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

@@ -20,7 +20,9 @@ export declare class ExtensionExecutor implements Executor {
     dispose(): Promise<void>;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
-    tabNew(url?: string): Promise<TabInfo>;
+    tabNew(url?: string, opts?: {
+        active?: boolean;
+    }): Promise<TabInfo>;
     tabClose(tabId: TabId): Promise<{
         closed: true;
         tabId: TabId;

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

@@ -61,8 +61,8 @@ class ExtensionExecutor {
     async tabSelect(tabId) {
         return (await this.send('tab_select', {}, { tabId }));
     }
-    async tabNew(url) {
-        return (await this.send('tab_new', { url }));
+    async tabNew(url, opts) {
+        return (await this.send('tab_new', { url, active: opts?.active }));
     }
     async tabClose(tabId) {
         return (await this.send('tab_close', {}, { tabId }));

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

@@ -27,7 +27,9 @@ export declare class StubExecutor implements Executor {
     dispose(): Promise<void>;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
-    tabNew(url?: string): Promise<TabInfo>;
+    tabNew(url?: string, _opts?: {
+        active?: boolean;
+    }): Promise<TabInfo>;
     tabClose(tabId: TabId): Promise<{
         closed: true;
         tabId: TabId;

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

@@ -49,7 +49,7 @@ class StubExecutor {
     async tabSelect(tabId) {
         return { ...this.tab(), tabId };
     }
-    async tabNew(url) {
+    async tabNew(url, _opts) {
         if (url)
             this.url = url;
         return this.tab();

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

@@ -144,7 +144,10 @@ export interface Executor {
     dispose(): Promise<void>;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
-    tabNew(url?: string): Promise<TabInfo>;
+    /** Open a tab. `active` (default true) focuses it; pass false to open in the background. */
+    tabNew(url?: string, opts?: {
+        active?: boolean;
+    }): Promise<TabInfo>;
     tabClose(tabId: TabId): Promise<{
         closed: true;
         tabId: TabId;

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

@@ -0,0 +1,26 @@
+/**
+ * src/mcp/batch.ts — the `batch` fan-out tool: run many tool calls in one
+ * request, in parallel (default) or serially.
+ *
+ * Pure server-side composition: every sub-op is routed back through the same
+ * `dispatchToolCall` firewall, so it inherits the policy gate (server AND
+ * extension), the rate limiter, the executor-ready guard, and never-throw error
+ * rendering. There is no security bypass — a batch of N tool calls is exactly N
+ * ordinary tool calls that happen to be issued together.
+ *
+ * Concurrency safety: in parallel mode a tab-scoped sub-op that omits `tabId`
+ * would fall back to the shared "active tab" pointer, which races under
+ * concurrency (see docs/BLUEPRINT.md and the SW executor's active-tab default).
+ * So parallel mode REQUIRES an explicit `tabId` on tab-scoped ops; the op is
+ * rejected (as its own isError result) rather than silently mis-routed.
+ */
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/** Routes a single tool call through the never-throw firewall. */
+export type DispatchFn = (name: string, args: unknown) => Promise<CallToolResult>;
+export interface BatchDeps {
+    dispatch: DispatchFn;
+    /** True for tools that act on a specific tab and default to the active tab
+     *  when `tabId` is omitted — those need an explicit `tabId` in parallel mode. */
+    requiresExplicitTab: (tool: string) => boolean;
+}
+export declare function runBatch(rawArgs: unknown, deps: BatchDeps): Promise<CallToolResult>;

package/dist/src/mcp/batch.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * src/mcp/batch.ts — the `batch` fan-out tool: run many tool calls in one
+ * request, in parallel (default) or serially.
+ *
+ * Pure server-side composition: every sub-op is routed back through the same
+ * `dispatchToolCall` firewall, so it inherits the policy gate (server AND
+ * extension), the rate limiter, the executor-ready guard, and never-throw error
+ * rendering. There is no security bypass — a batch of N tool calls is exactly N
+ * ordinary tool calls that happen to be issued together.
+ *
+ * Concurrency safety: in parallel mode a tab-scoped sub-op that omits `tabId`
+ * would fall back to the shared "active tab" pointer, which races under
+ * concurrency (see docs/BLUEPRINT.md and the SW executor's active-tab default).
+ * So parallel mode REQUIRES an explicit `tabId` on tab-scoped ops; the op is
+ * rejected (as its own isError result) rather than silently mis-routed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBatch = runBatch;
+const envelopes_1 = require("./envelopes");
+const validators_1 = require("./validators");
+/** Hard cap on operations per batch — bounds memory (results accumulate) and blast radius. */
+const MAX_OPS = 50;
+const DEFAULT_CONCURRENCY = 6;
+const MAX_CONCURRENCY = 16;
+/** 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) {
+    if (!Array.isArray(raw))
+        throw new validators_1.McpToolError('"ops" must be an array of { tool, args } objects');
+    if (raw.length === 0)
+        throw new validators_1.McpToolError('"ops" must contain at least one operation');
+    if (raw.length > MAX_OPS)
+        throw new validators_1.McpToolError(`"ops" has ${raw.length} operations; the max is ${MAX_OPS}`);
+    return raw.map((o, i) => {
+        if (typeof o !== 'object' || o === null || Array.isArray(o)) {
+            throw new validators_1.McpToolError(`ops[${i}] must be an object with a "tool" and optional "args"`);
+        }
+        const rec = o;
+        if (typeof rec.tool !== 'string' || rec.tool.length === 0) {
+            throw new validators_1.McpToolError(`ops[${i}].tool must be a non-empty string`);
+        }
+        if (rec.args !== undefined && (typeof rec.args !== 'object' || rec.args === null || Array.isArray(rec.args))) {
+            throw new validators_1.McpToolError(`ops[${i}].args must be an object`);
+        }
+        return { tool: rec.tool, args: rec.args ?? {} };
+    });
+}
+/** Map with bounded concurrency. `fn` never throws (dispatch is the firewall). */
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        for (;;) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            out[i] = await fn(items[i], i);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
+async function runBatch(rawArgs, deps) {
+    const a = (0, validators_1.asArgs)(rawArgs);
+    const ops = parseOps(a.ops);
+    const mode = ((0, validators_1.optionalString)(a, 'mode') ?? 'parallel');
+    if (mode !== 'parallel' && mode !== 'serial') {
+        throw new validators_1.McpToolError('"mode" must be "parallel" or "serial"');
+    }
+    const stopOnError = (0, validators_1.optionalBoolean)(a, 'stopOnError') ?? false;
+    const concurrency = (0, validators_1.optionalNumber)(a, 'maxConcurrency', { min: 1, max: MAX_CONCURRENCY }) ?? DEFAULT_CONCURRENCY;
+    /** Run one op through the firewall, after the per-op guards. Never throws. */
+    const runOne = async (op) => {
+        if (op.tool === 'batch')
+            return (0, envelopes_1.errorResult)('batch cannot be nested inside batch');
+        if (mode === 'parallel' && deps.requiresExplicitTab(op.tool) && op.args.tabId == null) {
+            return (0, envelopes_1.errorResult)(`"${op.tool}" needs an explicit "tabId" in a parallel batch — the active-tab default is unsafe under concurrency (use serial mode, or pass tabId)`);
+        }
+        // In a parallel batch, default new tabs to the background so N concurrent
+        // opens don't fight over window focus (a single tab_new still focuses).
+        let args = op.args;
+        if (mode === 'parallel' && op.tool === 'tab_new' && args.active === undefined) {
+            args = { ...args, active: false };
+        }
+        return deps.dispatch(op.tool, args);
+    };
+    let outcomes;
+    if (mode === 'serial') {
+        outcomes = ops.map(() => ({ status: 'skipped' }));
+        for (let i = 0; i < ops.length; i++) {
+            const result = await runOne(ops[i]);
+            outcomes[i] = { status: result.isError ? 'error' : 'ok', result };
+            if (stopOnError && result.isError)
+                break; // leave the rest 'skipped'
+        }
+    }
+    else {
+        const results = await mapLimit(ops, concurrency, (op) => runOne(op));
+        outcomes = results.map((result) => ({ status: result.isError ? 'error' : 'ok', result }));
+    }
+    return renderBatch(ops, outcomes, mode);
+}
+/** 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) {
+    const summary = outcomes.map((o, i) => ({ index: i, tool: ops[i].tool, status: o.status }));
+    const counts = {
+        total: ops.length,
+        ok: summary.filter((s) => s.status === 'ok').length,
+        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) },
+    ];
+    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);
+    }
+    // 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;
+    return isError ? { content, isError: true } : { content };
+}
+//# sourceMappingURL=batch.js.map

package/dist/src/mcp/tools.js

@@ -22,6 +22,7 @@ const types_1 = require("../executor/types");
 const manager_1 = require("../executor/manager");
 const policy_1 = require("../security/policy");
 const envelopes_1 = require("./envelopes");
+const batch_1 = require("./batch");
 const helpers_1 = require("./helpers");
 const validators_1 = require("./validators");
 const TARGET_PROPS = {
@@ -37,9 +38,9 @@ const obj = (properties, required = []) => ({
 exports.TOOL_DEFINITIONS = [
     { name: 'tabs_list', description: 'List open browser tabs.', inputSchema: obj({}) },
     { name: 'tab_select', description: 'Make a tab active by tabId.', inputSchema: obj({ tabId: { type: 'string' } }, ['tabId']) },
-    { name: 'tab_new', description: 'Open a new tab, optionally at a URL.', inputSchema: obj({ url: { type: 'string' } }) },
+    { name: 'tab_new', description: 'Open a NEW tab (optionally at a URL) and focus it. Prefer this over `navigate` when the user says "open"/"go to" a site — `navigate` REPLACES the current tab. Pass active:false to open in the background (used by parallel batches).', inputSchema: obj({ url: { type: 'string' }, active: { type: 'boolean' } }) },
     { name: 'tab_close', description: 'Close a tab by tabId.', inputSchema: obj({ tabId: { type: 'string' } }, ['tabId']) },
-    { name: 'navigate', description: 'Navigate the active (or given) tab to a URL.', inputSchema: obj({ url: { type: 'string' }, tabId: { type: 'string' }, waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] } }, ['url']) },
+    { name: 'navigate', description: 'Navigate a tab to a URL, REPLACING its current page. Acts on the active tab unless tabId is given — to open a site without losing the current page, use `tab_new` instead.', inputSchema: obj({ url: { type: 'string' }, tabId: { type: 'string' }, waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] } }, ['url']) },
     { name: 'back', description: 'Go back in history.', inputSchema: obj({ tabId: { type: 'string' } }) },
     { name: 'forward', description: 'Go forward in history.', inputSchema: obj({ tabId: { type: 'string' } }) },
     { name: 'reload', description: 'Reload the active (or given) tab.', inputSchema: obj({ tabId: { type: 'string' }, waitUntil: { type: 'string', enum: ['load', 'domcontentloaded', 'networkidle'] } }) },
@@ -63,6 +64,20 @@ exports.TOOL_DEFINITIONS = [
     { name: 'download_file', description: 'Download a file by URL or from a link element.', inputSchema: obj({ url: { type: 'string' }, ...TARGET_PROPS, suggestedName: { type: 'string' }, tabId: { type: 'string' } }) },
     { 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: obj({ ...TARGET_PROPS, files: { type: 'array', items: { type: 'string' } }, tabId: { type: 'string' } }, ['files']) },
     { name: 'chrome_status', description: 'Report backend/session status.', inputSchema: obj({}) },
+    {
+        name: 'batch',
+        description: 'Run multiple tool calls in one request — parallel (default) or serial. Each op is { tool, args } and goes through the same policy gate, rate limit, and error handling as a direct call. In parallel mode, tab-scoped ops MUST pass an explicit tabId (the active-tab default is unsafe under concurrency). Use to drive several tabs at once (e.g. open tabs, then batch get_text across them). Cannot be nested.',
+        inputSchema: obj({
+            ops: {
+                type: 'array',
+                description: 'Operations to run; each is a tool name + its args.',
+                items: obj({ tool: { type: 'string' }, args: { type: 'object' } }, ['tool']),
+            },
+            mode: { type: 'string', enum: ['parallel', 'serial'], description: 'Default "parallel".' },
+            stopOnError: { type: 'boolean', description: 'Serial mode only: stop after the first failing op (the rest are skipped).' },
+            maxConcurrency: { type: 'number', description: 'Parallel mode: max ops in flight at once (default 6).' },
+        }, ['ops']),
+    },
 ];
 /** Resolve the URL the policy should be evaluated against (the active tab). */
 async function activeUrl(ex) {
@@ -81,6 +96,14 @@ async function gate(ctx, method, urlOverride) {
 }
 const tabId = (args) => (0, validators_1.optionalString)(args, 'tabId');
 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
+ *  the active tab when `tabId` is omitted, which races under concurrency. */
+const PARALLEL_TAB_EXEMPT = new Set(['tabs_list', 'tab_new', 'chrome_status', 'batch']);
+/** A known tool that operates on a specific tab — needs an explicit tabId in a parallel batch. */
+function requiresExplicitTab(tool) {
+    return tool in exports.TOOL_HANDLERS && !PARALLEL_TAB_EXEMPT.has(tool);
+}
 exports.TOOL_HANDLERS = {
     tabs_list: async (_a, ctx) => (0, envelopes_1.jsonResult)(await ctx.ex.tabsList()),
     tab_select: async (a, ctx) => {
@@ -89,7 +112,7 @@ exports.TOOL_HANDLERS = {
     },
     tab_new: async (a, ctx) => {
         await gate(ctx, 'tab_new');
-        return (0, envelopes_1.jsonResult)(await ctx.ex.tabNew((0, validators_1.optionalString)(a, 'url')));
+        return (0, envelopes_1.jsonResult)(await ctx.ex.tabNew((0, validators_1.optionalString)(a, 'url'), { active: (0, validators_1.optionalBoolean)(a, 'active') }));
     },
     tab_close: async (a, ctx) => {
         await gate(ctx, 'tab_close');
@@ -285,6 +308,9 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.jsonResult)(await ctx.ex.uploadFile(t, files, { tabId: tabId(a) }));
     },
     chrome_status: async (_a, ctx) => (0, envelopes_1.jsonResult)(ctx.ex.status()),
+    // Fan-out: each sub-op is routed back through `dispatchToolCall`, so it gets
+    // the same policy gate, rate limit, and never-throw handling as a direct call.
+    batch: async (a) => (0, batch_1.runBatch)(a, { dispatch: dispatchToolCall, requiresExplicitTab }),
 };
 // ---------------------------------------------------------------------------
 // Dispatch (never-throw firewall)

package/docs/BLUEPRINT.md

@@ -588,9 +588,14 @@ Build: `files` whitelist incl. `extension-dist/`, `--print-pairing`/`--print-ext
 - **Native-messaging trampoline install step** is the one manual setup beyond `npx`; the manual file-path paste is the no-native fallback. Smoother one-click pairing is a v1.1 polish.
 - **`networkidle`** is approximated by a bounded idle-window poll (no native CDP event); documented as best-effort, never able to wedge a call.
 - **Local-code-execution attacker** who can already read the user's 0600 files has root-equivalent access to the user session; the token cannot defend against an attacker who already owns the filesystem. The policy allowlist still blocks blind exfil to arbitrary domains.
-- **`captureBeyondViewport` very-tall pages**: capped + `truncated` flag; scroll-stitch is the v1.1 upgrade if full fidelity is needed.
+- **`captureBeyondViewport` very-tall pages**: full-page capture now ships (extension `screenshot` uses `chrome.debugger Page.captureScreenshot` with a content-box clip); only pages taller than the ~16384px skia ceiling are clamped + `truncated`-flagged. [RESOLVED — v0.5.0]
+
+**Resolved in v0.5.0 (safe multi-tab concurrency):**
+- **Screenshot active-tab race (H1):** the extension captured via `captureVisibleTab`, which had to activate the target tab — concurrent captures stole focus and could grab the wrong tab. Now `chrome.debugger Page.captureScreenshot` captures a specific tab without activating it.
+- **Active-tab default under concurrency (H2):** the `batch` fan-out tool requires an explicit `tabId` on tab-scoped ops in `parallel` mode (rejected rather than mis-routed to whatever tab is frontmost).
+- **Per-tab debugger collisions + `tab_new` race (H3/H4):** a `KeyedMutex` serializes `chrome.debugger` attach/detach per tab and the `tab_new` blank-tab claim; different tabs still run in parallel.
+- Per-cmd `tabId` addressing is on every wire method, so multi-tab works without a backend pool. A true multi-*session* `Executor` pool remains out of scope.
 
 **Genuinely open (decide before v1.1):**
-- Multi-tab/multi-session concurrency (single global Executor + single attached tab today): does an agent need N tabs driven simultaneously? That breaks the singleton and requires per-cmd `tabId` everywhere on the wire.
 - Web Store path: requires a `chrome.scripting`-only mode (no `chrome.debugger`) — a second executor backend behind the same interface.
 - Whether `download` should ever use the extension `chrome.downloads` path (user Downloads dir) as an explicit opt-in, or remain server-fetch-only forever.

package/extension-dist/background.js

@@ -359,6 +359,62 @@
     return { url: location.href, title: document.title, nodes, truncated: els.length > nodes.length };
   }
 
+  // shared/screenshot.ts
+  var MAX_CAPTURE_PX = 16384;
+  function planScreenshot(dims, opts = {}) {
+    if (opts.element) {
+      const realH = Math.max(1, Math.round(opts.element.h));
+      const clipH = Math.min(opts.element.h, MAX_CAPTURE_PX);
+      return {
+        clip: { x: opts.element.x, y: opts.element.y, width: opts.element.w, height: clipH, scale: 1 },
+        captureBeyondViewport: true,
+        width: Math.max(1, Math.round(opts.element.w)),
+        height: Math.min(realH, MAX_CAPTURE_PX),
+        truncated: realH > MAX_CAPTURE_PX,
+        fullHeight: realH
+      };
+    }
+    if (opts.fullPage) {
+      const clipH = Math.min(dims.fullH, MAX_CAPTURE_PX);
+      return {
+        clip: { x: 0, y: 0, width: dims.fullW, height: clipH, scale: 1 },
+        captureBeyondViewport: true,
+        width: dims.fullW,
+        height: clipH,
+        truncated: dims.fullH > clipH,
+        fullHeight: dims.fullH
+      };
+    }
+    return {
+      captureBeyondViewport: false,
+      width: dims.w,
+      height: dims.h,
+      truncated: false
+    };
+  }
+
+  // shared/mutex.ts
+  function noop() {
+  }
+  var KeyedMutex = class {
+    tails = /* @__PURE__ */ new Map();
+    /** Run `fn` after all earlier holders of `key` settle. Resolves/rejects with fn's outcome. */
+    run(key, fn) {
+      const prev = this.tails.get(key) ?? Promise.resolve();
+      const result = prev.then(fn, fn);
+      const tail = result.then(noop, noop);
+      this.tails.set(key, tail);
+      void tail.then(() => {
+        if (this.tails.get(key) === tail) this.tails.delete(key);
+      });
+      return result;
+    }
+    /** Number of keys with an outstanding or queued holder (for tests/inspection). */
+    get size() {
+      return this.tails.size;
+    }
+  };
+
   // extension/src/sw/executor.ts
   var CmdError = class extends Error {
     constructor(code, message) {
@@ -369,6 +425,8 @@
   var SESSION = crypto.randomUUID();
   var CONTENT_SCHEME = /^(https?|file):/i;
   var delay = (ms) => new Promise((r) => setTimeout(r, ms));
+  var locks = new KeyedMutex();
+  var claimedTabs = /* @__PURE__ */ new Set();
   function mint(tabId) {
     return `ext:${SESSION}:${tabId}`;
   }
@@ -441,13 +499,15 @@
     }
   }
   async function withDebugger(tabId, fn) {
-    const target = { tabId };
-    await chrome.debugger.attach(target, "1.3");
-    try {
-      return await fn(target);
-    } finally {
-      await chrome.debugger.detach(target).catch(() => void 0);
-    }
+    return locks.run(`dbg:${tabId}`, async () => {
+      const target = { tabId };
+      await chrome.debugger.attach(target, "1.3");
+      try {
+        return await fn(target);
+      } finally {
+        await chrome.debugger.detach(target).catch(() => void 0);
+      }
+    });
   }
   async function trustedType(tabId, selector, text, clear) {
     const focused = await execInTab(
@@ -489,6 +549,72 @@
     });
     return true;
   }
+  async function measurePage(tabId, selector) {
+    return execInTab(
+      tabId,
+      (sel) => {
+        const d = document.documentElement;
+        const dims = {
+          w: window.innerWidth,
+          h: window.innerHeight,
+          fullW: Math.max(d.scrollWidth, d.clientWidth),
+          fullH: Math.max(d.scrollHeight, d.clientHeight)
+        };
+        if (!sel) return { dims, element: null, missing: false };
+        const el = document.querySelector(sel);
+        if (!el) return { dims, element: null, missing: true };
+        el.scrollIntoView({ block: "center", inline: "center" });
+        const r = el.getBoundingClientRect();
+        return { dims, element: { x: r.left + window.scrollX, y: r.top + window.scrollY, w: r.width, h: r.height }, missing: false };
+      },
+      [selector ?? null]
+    );
+  }
+  async function screenshotViaDebugger(tabId, fullPage, selector) {
+    const measured = await measurePage(tabId, selector);
+    if (!measured) throw new CmdError("CDP_ERROR", "could not read page dimensions");
+    if (selector && measured.missing) throw new CmdError("SELECTOR_NOT_FOUND", `no element for selector: ${selector}`);
+    const plan = planScreenshot(measured.dims, { fullPage, element: measured.element });
+    const params = { format: "png", captureBeyondViewport: plan.captureBeyondViewport };
+    if (plan.clip) params.clip = plan.clip;
+    const data = await withDebugger(tabId, async (target) => {
+      const res = await chrome.debugger.sendCommand(target, "Page.captureScreenshot", params);
+      return res.data ?? "";
+    });
+    return {
+      dataBase64: data,
+      mimeType: "image/png",
+      width: plan.width,
+      height: plan.height,
+      truncated: plan.truncated,
+      fullHeight: plan.fullHeight
+    };
+  }
+  async function screenshotViaVisibleTab(tabId, fullPage) {
+    let t = await chrome.tabs.get(tabId);
+    if (!t.active) {
+      await chrome.tabs.update(tabId, { active: true });
+      await chrome.windows.update(t.windowId, { focused: true }).catch(() => void 0);
+      await delay(150);
+      t = await chrome.tabs.get(tabId);
+    }
+    const dims = await execInTab(
+      tabId,
+      () => ({ w: window.innerWidth, h: window.innerHeight, full: document.documentElement.scrollHeight }),
+      []
+    );
+    const dataUrl = await chrome.tabs.captureVisibleTab(t.windowId, { format: "png" });
+    const viewportH = dims?.h ?? 0;
+    const fullH = dims?.full ?? viewportH;
+    return {
+      dataBase64: dataUrl.split(",")[1] ?? "",
+      mimeType: "image/png",
+      width: dims?.w ?? 0,
+      height: viewportH,
+      truncated: fullPage && fullH > viewportH,
+      fullHeight: fullPage ? fullH : void 0
+    };
+  }
   async function tabInfo(tab, index = 0) {
     return {
       tabId: mint(tab.id ?? -1),
@@ -542,19 +668,34 @@
         }
         case "tab_new": {
           const url = typeof cmd.params.url === "string" ? cmd.params.url : void 0;
+          const active = cmd.params.active !== false;
           const BLANK = /^(about:blank|chrome:\/\/newtab|chrome:\/\/new-tab-page|edge:\/\/newtab)/i;
-          const blank = (await chrome.tabs.query({})).find(
-            (t2) => t2.id !== void 0 && (BLANK.test(t2.url ?? "") || (t2.url ?? "") === "" || t2.pendingUrl === "about:blank")
-          );
-          if (blank?.id !== void 0) {
-            if (url) {
-              await chrome.tabs.update(blank.id, { url });
-              await waitComplete(blank.id);
+          const claim = await locks.run("tab_new", async () => {
+            const tabs = await chrome.tabs.query({});
+            const present = new Set(tabs.map((t) => t.id).filter((id) => id !== void 0));
+            for (const id of claimedTabs) if (!present.has(id)) claimedTabs.delete(id);
+            const blank = tabs.find(
+              (t) => t.id !== void 0 && !claimedTabs.has(t.id) && (BLANK.test(t.url ?? "") || (t.url ?? "") === "" || t.pendingUrl === "about:blank")
+            );
+            if (blank?.id !== void 0) {
+              claimedTabs.add(blank.id);
+              return { id: blank.id, reused: true, needsNav: url !== void 0 };
             }
-            return { ...await tabInfo(await chrome.tabs.get(blank.id)), reused: true };
+            const created = await chrome.tabs.create({ url, active: false });
+            if (created.id === void 0) throw new CmdError("TARGET_GONE", "failed to create a tab");
+            claimedTabs.add(created.id);
+            return { id: created.id, reused: false, needsNav: false };
+          });
+          if (claim.needsNav) {
+            await chrome.tabs.update(claim.id, { url });
+            await waitComplete(claim.id);
+          }
+          if (active) {
+            const t = await chrome.tabs.get(claim.id);
+            await chrome.tabs.update(claim.id, { active: true }).catch(() => void 0);
+            await chrome.windows.update(t.windowId, { focused: true }).catch(() => void 0);
           }
-          const t = await chrome.tabs.create({ url, active: false });
-          return { ...await tabInfo(t), reused: false };
+          return { ...await tabInfo(await chrome.tabs.get(claim.id)), reused: claim.reused };
         }
         case "tab_close": {
           const id = parseTabId(String(cmd.tabId));
@@ -809,34 +950,21 @@
           );
           return { ok: true };
         }
-        // -- screenshot (captureVisibleTab grabs the ACTIVE visible tab, so activate the target first) --
+        // -- screenshot --
+        // Primary path: chrome.debugger Page.captureScreenshot, which captures a
+        // SPECIFIC tab WITHOUT activating it (no focus-stealing → safe under
+        // concurrent batches) and supports true full-page + element capture.
+        // Falls back to captureVisibleTab only if the debugger can't attach.
         case "screenshot": {
           const id = await targetTab(cmd);
-          let t = await chrome.tabs.get(id);
-          if (!t.active) {
-            await chrome.tabs.update(id, { active: true });
-            await chrome.windows.update(t.windowId, { focused: true }).catch(() => void 0);
-            await delay(150);
-            t = await chrome.tabs.get(id);
-          }
-          const dims = await execInTab(
-            id,
-            () => ({ w: window.innerWidth, h: window.innerHeight, full: document.documentElement.scrollHeight }),
-            []
-          );
-          const dataUrl = await chrome.tabs.captureVisibleTab(t.windowId, { format: "png" });
           const fullPage = cmd.params.fullPage === true;
-          const viewportH = dims?.h ?? 0;
-          const fullH = dims?.full ?? viewportH;
-          return {
-            dataBase64: dataUrl.split(",")[1] ?? "",
-            mimeType: "image/png",
-            width: dims?.w ?? 0,
-            height: viewportH,
-            // The scripting backend can only capture the viewport; flag when a fullPage was asked but clipped.
-            truncated: fullPage && fullH > viewportH,
-            fullHeight: fullPage ? fullH : void 0
-          };
+          const selector = selectorOf(cmd);
+          try {
+            return await screenshotViaDebugger(id, fullPage, selector);
+          } catch (err) {
+            if (err instanceof CmdError && err.code === "SELECTOR_NOT_FOUND") throw err;
+            return await screenshotViaVisibleTab(id, fullPage);
+          }
         }
         // -- eval (MAIN world; may be blocked by strict page CSP) --
         case "eval": {

package/extension-dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Chrome MCP Bridge",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Lets a local chrome-mcp server drive this browser. Pair it with the server's handshake token.",
   "minimum_chrome_version": "116",
   "background": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehmoodqureshi/chrome-mcp",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Drive a real Chrome browser over MCP. A stdio MCP server (CLI) plus an MV3 extension, behind one pluggable Executor (extension via chrome.scripting, or a Playwright CDP fallback).",
   "author": "Mehmood Ur Rehman Qureshi",
   "license": "MIT",