@mehmoodqureshi/chrome-mcp 0.4.1 → 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/policy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * shared/policy.ts — the PURE policy decision, imported VERBATIM by both the
+ * server (src/security/policy.ts wraps it to throw ExecutorError) and the
+ * extension (router mirrors it to throw CmdError). Keeping the decision in one
+ * shared module is what makes the two ends provably agree — the gate is then
+ * genuinely enforced "at both ends" (server dispatch AND extension router).
+ *
+ * No throwing, no Node/Chrome deps: returns a verdict the caller renders into
+ * whatever error type it uses.
+ */
+import type { WireMethod, WirePolicy } from './protocol';
+export declare function isReadMethod(method: WireMethod): boolean;
+/** Everything in the mutating tool set that safe-mode disables. `eval` is gated
+ *  separately via `allowEval`; `download_file` separately via `allowDownloads`. */
+export declare function isMutatingMethod(method: WireMethod): boolean;
+/** Whether the method touches a specific URL that must be allowlisted. */
+export declare function isUrlGated(method: WireMethod): boolean;
+/** Parse a host out of a URL string; '' if it has none (about:blank, data:, …). */
+export declare function hostOf(url: string): string;
+export declare function isDomainAllowed(url: string, policy: WirePolicy): boolean;
+export type PolicyVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Decide whether `method` against `url` is permitted by `policy`. `url` is the
+ * DESTINATION for navigation, otherwise the current tab URL. Pure: returns a
+ * verdict; the caller throws its own error type on `{ ok: false }`.
+ */
+export declare function evaluatePolicy(url: string, method: WireMethod, policy: WirePolicy): PolicyVerdict;
+/** A wire policy that allows nothing — the safe default when none was delivered. */
+export declare const DENY_ALL_WIRE_POLICY: WirePolicy;

package/dist/shared/policy.js

@@ -0,0 +1,151 @@
+"use strict";
+/**
+ * shared/policy.ts — the PURE policy decision, imported VERBATIM by both the
+ * server (src/security/policy.ts wraps it to throw ExecutorError) and the
+ * extension (router mirrors it to throw CmdError). Keeping the decision in one
+ * shared module is what makes the two ends provably agree — the gate is then
+ * genuinely enforced "at both ends" (server dispatch AND extension router).
+ *
+ * No throwing, no Node/Chrome deps: returns a verdict the caller renders into
+ * whatever error type it uses.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DENY_ALL_WIRE_POLICY = void 0;
+exports.isReadMethod = isReadMethod;
+exports.isMutatingMethod = isMutatingMethod;
+exports.isUrlGated = isUrlGated;
+exports.hostOf = hostOf;
+exports.isDomainAllowed = isDomainAllowed;
+exports.evaluatePolicy = evaluatePolicy;
+// ---------------------------------------------------------------------------
+// Method classification
+// ---------------------------------------------------------------------------
+/** Methods that read page CONTENT (the exfil payload) — URL-gated. */
+const READ_CONTENT = new Set([
+    'get_text',
+    'get_html',
+    'screenshot',
+    'wait_for',
+]);
+/** Content-mutating actions — URL-gated AND mutation-gated. */
+const MUTATE_CONTENT = new Set([
+    'click',
+    'type',
+    'press',
+    'hover',
+    'scroll',
+]);
+/** Navigation — URL-gated by the DESTINATION url, and mutation-gated. */
+const NAVIGATION = new Set([
+    'navigate',
+    'back',
+    'forward',
+    'reload',
+]);
+/** Tab management — mutation-gated, but not content-URL-gated. */
+const TAB_MUTATE = new Set([
+    'tab_select',
+    'tab_new',
+    'tab_close',
+]);
+function isReadMethod(method) {
+    return READ_CONTENT.has(method) || method === 'tabs_list';
+}
+/** Everything in the mutating tool set that safe-mode disables. `eval` is gated
+ *  separately via `allowEval`; `download_file` separately via `allowDownloads`. */
+function isMutatingMethod(method) {
+    return MUTATE_CONTENT.has(method) || NAVIGATION.has(method) || TAB_MUTATE.has(method);
+}
+/** Whether the method touches a specific URL that must be allowlisted. */
+function isUrlGated(method) {
+    return (READ_CONTENT.has(method) ||
+        MUTATE_CONTENT.has(method) ||
+        NAVIGATION.has(method) ||
+        method === 'eval' ||
+        method === 'upload_file');
+}
+// ---------------------------------------------------------------------------
+// Domain matching
+// ---------------------------------------------------------------------------
+/** Parse a host out of a URL string; '' if it has none (about:blank, data:, …). */
+function hostOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return '';
+    }
+}
+function isAboutBlank(url) {
+    return url === 'about:blank' || url === '' || url.startsWith('about:');
+}
+/** Convert a single domain glob to a predicate. '*' matches everything;
+ *  '*.example.com' matches example.com and any subdomain; otherwise exact host. */
+function globMatches(host, pattern) {
+    const p = pattern.trim().toLowerCase();
+    if (p === '*' || p === '*://*/*')
+        return true;
+    if (p.startsWith('*.')) {
+        const base = p.slice(2);
+        return host === base || host.endsWith('.' + base);
+    }
+    return host === p;
+}
+function isDomainAllowed(url, policy) {
+    const host = hostOf(url);
+    if (!host)
+        return false;
+    return policy.allowDomains.some((pat) => globMatches(host, pat));
+}
+/**
+ * Decide whether `method` against `url` is permitted by `policy`. `url` is the
+ * DESTINATION for navigation, otherwise the current tab URL. Pure: returns a
+ * verdict; the caller throws its own error type on `{ ok: false }`.
+ */
+function evaluatePolicy(url, method, policy) {
+    // -- capability gates (independent of URL) --
+    if (method === 'eval' && !policy.allowEval) {
+        return { ok: false, reason: 'eval is disabled (safe-mode). Pass --unsafe-enable-eval to allow it.' };
+    }
+    if (method === 'download_file' && !policy.allowDownloads) {
+        return { ok: false, reason: 'downloads are disabled. Pass --enable-downloads or set allowDownloads.' };
+    }
+    if (method === 'upload_file' && !policy.allowUploads) {
+        return {
+            ok: false,
+            reason: 'uploads are disabled (sending local files to a page is an exfiltration risk). ' +
+                'Pass --enable-uploads or set allowUploads.',
+        };
+    }
+    if (isMutatingMethod(method) && !policy.enableMutations) {
+        return {
+            ok: false,
+            reason: `mutating tool "${method}" is disabled (safe-mode). Pass --enable-mutations to allow it.`,
+        };
+    }
+    // Methods that don't carry a content URL pass once the gates above are clear.
+    if (!isUrlGated(method))
+        return { ok: true };
+    // Navigating to a blank page is always fine.
+    if (isAboutBlank(url) && NAVIGATION.has(method))
+        return { ok: true };
+    if (!isDomainAllowed(url, policy)) {
+        const host = hostOf(url) || url;
+        return {
+            ok: false,
+            reason: `"${method}" denied: ${host} is not in the domain allowlist. ` +
+                `Add it to allowDomains, or pass --unsafe-all-domains.`,
+        };
+    }
+    return { ok: true };
+}
+/** A wire policy that allows nothing — the safe default when none was delivered. */
+exports.DENY_ALL_WIRE_POLICY = {
+    allowDomains: [],
+    allowEval: false,
+    allowDownloads: false,
+    allowUploads: false,
+    allowAllTabs: false,
+    enableMutations: false,
+};
+//# sourceMappingURL=policy.js.map

package/dist/shared/protocol.d.ts

@@ -49,11 +49,26 @@ export interface HelloFrame extends BaseFrame {
         chrome: string;
     };
 }
+/**
+ * The wire-serializable subset of the server's policy, delivered in `welcome` so
+ * the extension can enforce the SAME gate the server does (defense-in-depth). The
+ * server-only `uploadsDir` (a local filesystem path) is intentionally NOT sent.
+ */
+export interface WirePolicy {
+    allowDomains: string[];
+    allowEval: boolean;
+    allowDownloads: boolean;
+    allowUploads: boolean;
+    allowAllTabs: boolean;
+    enableMutations: boolean;
+}
 export interface WelcomeFrame extends BaseFrame {
     type: 'welcome';
     serverVersion: string;
     sessionId: string;
     heartbeatMs: number;
+    /** The active policy, so the extension can mirror the server-side gate. */
+    policy: WirePolicy;
 }
 export interface UnauthFrame extends BaseFrame {
     type: 'unauthorized';

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/bridge/server.d.ts

@@ -10,7 +10,7 @@
  *   3. On success, send `welcome`, promote to the single ACTIVE connection
  *      (superseding any prior one — a security-relevant displacement event).
  */
-import { type WireEvent, type WireMethod } from '../../shared/protocol';
+import { type WireEvent, type WireMethod, type WirePolicy } from '../../shared/protocol';
 export interface DisplacementInfo {
     oldExtId: string;
     newExtId: string;
@@ -20,6 +20,9 @@ export interface DisplacementInfo {
 export interface BridgeOptions {
     token: string;
     serverVersion: string;
+    /** Active policy, sent to the extension in `welcome` so it mirrors the gate.
+     *  Defaults to deny-all if omitted. */
+    policy?: WirePolicy;
     port?: number;
     host?: string;
     heartbeatMs?: number;

package/dist/src/bridge/server.js

@@ -16,6 +16,7 @@ exports.BridgeServer = void 0;
 const ws_1 = require("ws");
 const node_crypto_1 = require("node:crypto");
 const protocol_1 = require("../../shared/protocol");
+const policy_1 = require("../../shared/policy");
 const types_1 = require("../executor/types");
 const connection_1 = require("./connection");
 const auth_1 = require("./auth");
@@ -174,6 +175,7 @@ class BridgeServer {
             serverVersion: this.opts.serverVersion,
             sessionId,
             heartbeatMs: this.heartbeatMs,
+            policy: this.opts.policy ?? policy_1.DENY_ALL_WIRE_POLICY,
         };
         this.send(ws, welcome);
         this.log(`extension paired (session ${sessionId}, id "${ext.id}")`);

package/dist/src/cli.js

@@ -61,9 +61,12 @@ async function main() {
     }
     const dataDir = (0, datadir_1.ensureDataDir)(cfg.dataDir);
     const token = (0, auth_1.resolveToken)(dataDir, { persist: cfg.persistToken });
+    const { allowDomains, allowEval, allowDownloads, allowUploads, allowAllTabs, enableMutations } = cfg.policy;
     const bridge = new server_1.BridgeServer({
         token,
         serverVersion: version(),
+        // Wire-serializable policy subset (no local uploadsDir) so the extension mirrors the gate.
+        policy: { allowDomains, allowEval, allowDownloads, allowUploads, allowAllTabs, enableMutations },
         port: cfg.wsPort,
         onLog: (m) => (0, server_2.logErr)(m),
         onDisplacement: (d) => (0, server_2.logErr)(`SECURITY: extension connection displaced (different id: ${d.differentId})`),

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>;