@mehmoodqureshi/chrome-mcp 0.4.1 → 0.5.0

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/dist/src/security/policy.d.ts

@@ -6,54 +6,36 @@
  * threat, so the policy:
  *   - is ON by default with a SAFE default (empty allowlist, no eval, no
  *     downloads, mutations disabled),
- *   - gates READS as well as writes (reads are the exfil payload).
- *
- * SCOPE OF ENFORCEMENT: this policy is enforced SERVER-SIDE ONLY, at the executor
- * dispatch chokepoint (`assertUrlAllowed` in src/mcp/tools.ts). The extension does
- * NOT independently re-check the policy, so the bridge token is the sole trust
- * boundary for the WebSocket: any client holding the token can issue commands the
- * extension will execute, regardless of this policy. The policy constrains the
- * official MCP server (and thus the LLM driving it); it is not a second line of
- * defense against a rogue token-holding client. (A future hardening would mirror
- * this gate inside the extension router via a policy delivered in the welcome frame.)
+ *   - gates READS as well as writes (reads are the exfil payload),
+ *   - is enforced at BOTH ends. The decision lives in `shared/policy.ts`
+ *     (`evaluatePolicy`); the server wraps it here (`assertUrlAllowed`) and the
+ *     extension router runs the SAME function against the policy delivered in the
+ *     `welcome` frame. Because both ends call one shared function, they cannot
+ *     drift, and a client that bypasses the server still hits the extension gate.
+ *     (The bridge token remains the PRIMARY trust boundary for the WebSocket;
+ *     the extension gate is defense-in-depth on top of it.)
  *
  * `assertUrlAllowed(url, method, policy)` is the single chokepoint. It throws an
  * `ExecutorError('POLICY_DENIED', …)` which the never-throw dispatch firewall
  * renders as a structured MCP error.
  */
-import type { WireMethod } from '../../shared/protocol';
-export interface Policy {
-    /** Glob domain allowlist, e.g. ['example.com', '*.example.com', '*']. Empty = deny all. */
-    allowDomains: string[];
-    /** Allow the `eval` primitive at all. */
-    allowEval: boolean;
-    /** Allow `download_file`. */
-    allowDownloads: boolean;
-    /** Allow `upload_file` (sends local files to the page — exfiltration risk). */
-    allowUploads: boolean;
+import type { WireMethod, WirePolicy } from '../../shared/protocol';
+import { isReadMethod, isMutatingMethod, isUrlGated, hostOf, isDomainAllowed } from '../../shared/policy';
+export { isReadMethod, isMutatingMethod, isUrlGated, hostOf, isDomainAllowed };
+/** The full server-side policy: the wire-serializable {@link WirePolicy} plus the
+ *  server-only `uploadsDir` (a local path, never sent to the extension). */
+export interface Policy extends WirePolicy {
     /** If set, `upload_file` may only read files inside this directory (absolute path). */
     uploadsDir?: string;
-    /** Allow acting on / reading tabs whose URL is not in `allowDomains` is governed
-     *  by `allowDomains`; this flag instead relaxes tab *management* (list/select)
-     *  to all tabs regardless of their URL. Default false. */
-    allowAllTabs: boolean;
-    /** Safe-mode master switch for the mutating tool set (click/type/navigate/…). */
-    enableMutations: boolean;
 }
 /** The SAFE default: deny everything until the user opts in. */
 export declare const DEFAULT_POLICY: Readonly<Policy>;
 /** Merge a partial (from a policy file and/or CLI flags) over the safe default. */
 export declare function resolvePolicy(partial?: Partial<Policy>): Policy;
-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;
-/** 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: Policy): boolean;
 /**
  * Throw `POLICY_DENIED` unless `method` against `url` is permitted by `policy`.
  * `url` is the DESTINATION for navigation, otherwise the current tab URL.
- * Pure and side-effect-free so it can run identically on server and extension.
+ * Thin server-side wrapper over the shared, pure `evaluatePolicy` — the SAME
+ * function the extension router runs, so the two ends cannot drift.
  */
 export declare function assertUrlAllowed(url: string, method: WireMethod, policy: Policy): void;

package/dist/src/security/policy.js

@@ -7,30 +7,30 @@
  * threat, so the policy:
  *   - is ON by default with a SAFE default (empty allowlist, no eval, no
  *     downloads, mutations disabled),
- *   - gates READS as well as writes (reads are the exfil payload).
- *
- * SCOPE OF ENFORCEMENT: this policy is enforced SERVER-SIDE ONLY, at the executor
- * dispatch chokepoint (`assertUrlAllowed` in src/mcp/tools.ts). The extension does
- * NOT independently re-check the policy, so the bridge token is the sole trust
- * boundary for the WebSocket: any client holding the token can issue commands the
- * extension will execute, regardless of this policy. The policy constrains the
- * official MCP server (and thus the LLM driving it); it is not a second line of
- * defense against a rogue token-holding client. (A future hardening would mirror
- * this gate inside the extension router via a policy delivered in the welcome frame.)
+ *   - gates READS as well as writes (reads are the exfil payload),
+ *   - is enforced at BOTH ends. The decision lives in `shared/policy.ts`
+ *     (`evaluatePolicy`); the server wraps it here (`assertUrlAllowed`) and the
+ *     extension router runs the SAME function against the policy delivered in the
+ *     `welcome` frame. Because both ends call one shared function, they cannot
+ *     drift, and a client that bypasses the server still hits the extension gate.
+ *     (The bridge token remains the PRIMARY trust boundary for the WebSocket;
+ *     the extension gate is defense-in-depth on top of it.)
  *
  * `assertUrlAllowed(url, method, policy)` is the single chokepoint. It throws an
  * `ExecutorError('POLICY_DENIED', …)` which the never-throw dispatch firewall
  * renders as a structured MCP error.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_POLICY = void 0;
+exports.DEFAULT_POLICY = exports.isDomainAllowed = exports.hostOf = exports.isUrlGated = exports.isMutatingMethod = exports.isReadMethod = void 0;
 exports.resolvePolicy = resolvePolicy;
-exports.isReadMethod = isReadMethod;
-exports.isMutatingMethod = isMutatingMethod;
-exports.hostOf = hostOf;
-exports.isDomainAllowed = isDomainAllowed;
 exports.assertUrlAllowed = assertUrlAllowed;
 const types_1 = require("../executor/types");
+const policy_1 = require("../../shared/policy");
+Object.defineProperty(exports, "isReadMethod", { enumerable: true, get: function () { return policy_1.isReadMethod; } });
+Object.defineProperty(exports, "isMutatingMethod", { enumerable: true, get: function () { return policy_1.isMutatingMethod; } });
+Object.defineProperty(exports, "isUrlGated", { enumerable: true, get: function () { return policy_1.isUrlGated; } });
+Object.defineProperty(exports, "hostOf", { enumerable: true, get: function () { return policy_1.hostOf; } });
+Object.defineProperty(exports, "isDomainAllowed", { enumerable: true, get: function () { return policy_1.isDomainAllowed; } });
 /** The SAFE default: deny everything until the user opts in. */
 exports.DEFAULT_POLICY = Object.freeze({
     allowDomains: [],
@@ -54,121 +54,17 @@ function resolvePolicy(partial) {
     };
 }
 // ---------------------------------------------------------------------------
-// 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 (unless allowAllTabs is off). */
-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));
-}
-// ---------------------------------------------------------------------------
 // The gate
 // ---------------------------------------------------------------------------
 /**
  * Throw `POLICY_DENIED` unless `method` against `url` is permitted by `policy`.
  * `url` is the DESTINATION for navigation, otherwise the current tab URL.
- * Pure and side-effect-free so it can run identically on server and extension.
+ * Thin server-side wrapper over the shared, pure `evaluatePolicy` — the SAME
+ * function the extension router runs, so the two ends cannot drift.
  */
 function assertUrlAllowed(url, method, policy) {
-    // -- capability gates (independent of URL) --
-    if (method === 'eval' && !policy.allowEval) {
-        throw new types_1.ExecutorError('POLICY_DENIED', 'eval is disabled (safe-mode). Pass --unsafe-enable-eval to allow it.');
-    }
-    if (method === 'download_file' && !policy.allowDownloads) {
-        throw new types_1.ExecutorError('POLICY_DENIED', 'downloads are disabled. Pass --enable-downloads or set allowDownloads.');
-    }
-    if (method === 'upload_file' && !policy.allowUploads) {
-        throw new types_1.ExecutorError('POLICY_DENIED', 'uploads are disabled (sending local files to a page is an exfiltration risk). ' +
-            'Pass --enable-uploads or set allowUploads.');
-    }
-    if (isMutatingMethod(method) && !policy.enableMutations) {
-        throw new types_1.ExecutorError('POLICY_DENIED', `mutating tool "${method}" is disabled (safe-mode). Pass --enable-mutations to allow it.`);
-    }
-    // -- tab management without allowAllTabs still needs the target tab's URL allowlisted,
-    //    but list/select/close don't carry a content URL here; treat them as allowed once
-    //    the mutation gate above has passed (URL-gating of their effect happens on the
-    //    subsequent content op). --
-    if (!isUrlGated(method))
-        return;
-    // Navigating to a blank page is always fine.
-    if (isAboutBlank(url) && NAVIGATION.has(method))
-        return;
-    if (!isDomainAllowed(url, policy)) {
-        const host = hostOf(url) || url;
-        throw new types_1.ExecutorError('POLICY_DENIED', `"${method}" denied: ${host} is not in the domain allowlist. ` +
-            `Add it to allowDomains, or pass --unsafe-all-domains.`);
-    }
+    const verdict = (0, policy_1.evaluatePolicy)(url, method, policy);
+    if (!verdict.ok)
+        throw new types_1.ExecutorError('POLICY_DENIED', verdict.reason);
 }
 //# sourceMappingURL=policy.js.map

package/docs/BLUEPRINT.md

@@ -64,7 +64,7 @@ takes over from CDP and vice-versa on disconnect.
 - **The 256-bit per-boot token is the ONLY security boundary.** Origin checks and the loopback bind are defense-in-depth against *browser-page* attackers, not native processes. [RESOLVED — security blockers 2 & 3]
 - **One canonical `protocol.ts`** imported by both server and extension. Four conflicting wire/port/token designs are collapsed into this single contract. [RESOLVED — integration blocker 1]
 - **Helpers (`extract_links`, `read_as_markdown`, `fill_form`) are composed server-side** from primitives. Only `download_file` is an executor/wire method. [RESOLVED — integration blocker 2]
-- **Default-deny domain policy is ON by default and gates reads too**, enforced SERVER-SIDE inside the executor dispatch (both backends). NOTE: the extension router does NOT independently re-check the policy — the bridge token is the sole trust boundary for the WebSocket. Mirroring the gate into the extension router is a planned hardening. [RESOLVED — security major 4 & eval]
+- **Default-deny domain policy is ON by default and gates reads too**, enforced at BOTH ends via the shared `evaluatePolicy` (`shared/policy.ts`): the server wraps it in the executor dispatch, and the extension router runs the same function against the policy delivered in the `welcome` frame. The bridge token remains the primary trust boundary; the extension gate is defense-in-depth. [RESOLVED — security major 4 & eval]
 
 ---
 
@@ -540,7 +540,7 @@ threat** (this tool feeds untrusted page text to an LLM that can call `eval`).
 3. **Origin is NOT a security layer.** Documented as defense-in-depth against *browser-page* attackers only (a web page cannot forge a `chrome-extension://` Origin; a native process can). The token holds independently. We never relax token strength on Origin's account. Never reject a valid-token dev connection solely on Origin mismatch. [RESOLVED — blocker 2, mv3 major Origin]
 4. **No `/connect` HTTP endpoint.** Token bootstrap is the **native-messaging trampoline** reading the 0600 file (the model/attacker can't read it), with a manual file-path-pairing fallback. No race-able network token vendor exists. [RESOLVED — blocker 3]
 5. **Token never logged.** Never on stdout or stderr; only in the 0600 file (mode verified post-write, fail-closed). Any human-readable pairing artifact is also 0600 and short-lived. `policy.test.ts` asserts the token appears on neither stream. `logErr` redacts. [RESOLVED — major 5]
-6. **Default-deny domain policy, ON by default, gating READS too.** `Policy { allowDomains: glob[]; allowEval; allowDownloads; allowAllTabs }`. Absent config → **SAFE DEFAULT**: navigate only to `about:blank` + already-open allowlisted tabs, **eval denied cross-domain, reads (`get_text`/`get_html`/`screenshot`/`eval`) denied outside the allowlist**, downloads off. `assertUrlAllowed(currentTabUrl, method)` runs SERVER-SIDE in **the executor dispatch (both backends)** before any attach/navigate/eval/read. The extension router does NOT re-check the policy (token is the sole bridge boundary); a mirrored extension-side gate is a planned hardening. `--unsafe-all-domains` (= `allowDomains:['*']`) is the loud-logged escape hatch. [RESOLVED — major 4]
+6. **Default-deny domain policy, ON by default, gating READS too.** `Policy { allowDomains: glob[]; allowEval; allowDownloads; allowAllTabs }`. Absent config → **SAFE DEFAULT**: navigate only to `about:blank` + already-open allowlisted tabs, **eval denied cross-domain, reads (`get_text`/`get_html`/`screenshot`/`eval`) denied outside the allowlist**, downloads off. The shared `evaluatePolicy(url, method, policy)` runs at **both ends** — wrapped server-side as `assertUrlAllowed` in the executor dispatch (both backends), and re-run by the extension router against the policy delivered in `welcome` — before any attach/navigate/eval/read. `--unsafe-all-domains` (= `allowDomains:['*']`) is the loud-logged escape hatch. [RESOLVED — major 4]
 7. **Safe-mode shipped in v1 (not "future").** Default disables `eval` and the entire mutating tool set; `--enable-mutations` / `--unsafe-enable-eval` opt in. `eval`'s effective target origin (the tab's current URL) is allowlist-checked before dispatch. [RESOLVED — major eval]
 8. **Narrowed manifest:** no `<all_urls>`; `host_permissions:[]` + `optional_host_permissions` requested on demand after an explicit user action-click grant before first attach. [RESOLVED — major 4]
 9. **Displacement is a security event:** superseding connects are logged loudly + surfaced in `chrome_status`; the active connection is pinned to the first `hello` ext id and won't be displaced by a different id without re-pair. [RESOLVED — minor 9]
@@ -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.