@mehmoodqureshi/chrome-mcp 0.9.2 → 0.9.4

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

@@ -18,10 +18,11 @@ const workspace_1 = require("../bridge/workspace");
  * Deliberately short. It exists to cover back-to-back calls (a `batch`, or an
  * agent's read → click → read), where the tab demonstrably has not changed
  * between them. Past that, pay the round-trip. Note the extension re-gates every
- * command against the tab's live URL regardless, so this window trades a little
- * pre-check precision for half the traffic — never enforcement itself.
+ * command against the tab's live URL regardless (fail-closed, authoritative), so
+ * this window trades a little pre-check precision for half the traffic — never
+ * enforcement itself.
  */
-const ACTIVE_URL_TTL_MS = 1_000;
+const ACTIVE_URL_TTL_MS = 2_000;
 /** Flatten frame options into the params a wire command carries. */
 function frameParams(o) {
     if (!o)
@@ -88,6 +89,11 @@ class ExtensionExecutor {
     cachedActiveUrl() {
         return this.bridge.lastActiveUrl(this.activeProfile(), ACTIVE_URL_TTL_MS);
     }
+    /** A specific tab's URL as last reported (by a result for that tab, or by a
+     *  `tabs_list`), if fresh enough to gate against. */
+    cachedTabUrl(tabId) {
+        return this.bridge.lastTabUrl(this.activeProfile(), tabId, ACTIVE_URL_TTL_MS);
+    }
     // -- tabs ---------------------------------------------------------------
     async tabsList() {
         return (await this.send('tabs_list', {}));
@@ -145,7 +151,7 @@ class ExtensionExecutor {
         return (await this.send('get_html', { ...targetParams(t), ...frameParams(opts), outer: opts?.outer }, { tabId: opts?.tabId }));
     }
     async snapshot(opts) {
-        return (await this.send('snapshot', { interactiveOnly: opts?.interactiveOnly, max: opts?.max, ...frameParams(opts) }, { tabId: opts?.tabId }));
+        return (await this.send('snapshot', { interactiveOnly: opts?.interactiveOnly, max: opts?.max, locator: opts?.locator, ...frameParams(opts) }, { tabId: opts?.tabId }));
     }
     async getCookies(opts) {
         return (await this.send('get_cookies', { url: opts?.url }, { tabId: opts?.tabId }));
@@ -154,7 +160,14 @@ class ExtensionExecutor {
         return (await this.send('storage', { op: args.op, key: args.key, value: args.value, session: args.session }, { tabId: args.tabId }));
     }
     async screenshot(opts) {
-        return (await this.send('screenshot', { fullPage: opts?.fullPage, ...targetParams(opts?.target), ...frameParams(opts) }, { tabId: opts?.tabId }));
+        return (await this.send('screenshot', {
+            fullPage: opts?.fullPage,
+            format: opts?.format,
+            quality: opts?.quality,
+            scale: opts?.scale,
+            ...targetParams(opts?.target),
+            ...frameParams(opts),
+        }, { tabId: opts?.tabId }));
     }
     async eval(expression, opts) {
         const result = (await this.send('eval', { expression, awaitPromise: opts?.awaitPromise, ...frameParams(opts) }, { tabId: opts?.tabId }));

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

@@ -111,9 +111,18 @@ export interface WaitResult {
 export interface ActionOk {
     ok: true;
 }
+export type ScreenshotFormat = 'png' | 'jpeg';
+/** Encoding knobs every backend accepts. All optional; see shared/screenshot.ts for defaults. */
+export interface ScreenshotEncoding {
+    format?: ScreenshotFormat;
+    /** JPEG only, 1-100. */
+    quality?: number;
+    /** Output pixels per CSS pixel (1 = CSS size, 2 = device pixels on a Retina display). */
+    scale?: number;
+}
 export interface ScreenshotResult {
     dataBase64: string;
-    mimeType: 'image/png';
+    mimeType: 'image/png' | 'image/jpeg';
     width: number;
     height: number;
     /** fullPage capture exceeded the height cap; `fullHeight` reports the real size. */
@@ -153,6 +162,13 @@ export interface SnapshotResult {
     title: string;
     nodes: SnapshotNode[];
     truncated: boolean;
+    /** Locator mode, no match: what the page had of that role (for the error message). */
+    nearby?: string[];
+}
+/** A role/name query the page resolves itself (see shared/snapshot.ts). */
+export interface SnapshotLocator {
+    role?: string;
+    name?: string;
 }
 export interface CookieItem {
     name: string;
@@ -205,6 +221,12 @@ export interface Executor {
      * report cheaply simply omit it.
      */
     cachedActiveUrl?(): string | null;
+    /**
+     * Same idea for an explicitly-targeted tab: its URL if the backend already
+     * knows it recently enough (the extension reports it on every result for that
+     * tab, and a `tabsList` reports it for every tab). Null → resolve properly.
+     */
+    cachedTabUrl?(tabId: TabId): string | null;
     tabsList(): Promise<TabInfo[]>;
     tabSelect(tabId: TabId): Promise<TabInfo>;
     /** Open a tab. `active` (default true) focuses it; pass false to open in the background. */
@@ -279,6 +301,7 @@ export interface Executor {
         tabId?: TabId;
         interactiveOnly?: boolean;
         max?: number;
+        locator?: SnapshotLocator;
     } & FrameOpts): Promise<SnapshotResult>;
     /** Read cookies visible to the active tab's URL (or a given url). */
     getCookies(opts?: {
@@ -299,7 +322,7 @@ export interface Executor {
         tabId?: TabId;
         fullPage?: boolean;
         target?: Target;
-    } & FrameOpts): Promise<ScreenshotResult>;
+    } & ScreenshotEncoding & FrameOpts): Promise<ScreenshotResult>;
     eval(expression: string, opts?: {
         tabId?: TabId;
         awaitPromise?: boolean;

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

@@ -9,10 +9,13 @@
  * redeploy.
  *
  * A locator closes that: `{ role: 'button', name: 'Sign in' }` resolves through
- * one snapshot, server-side, and the caller never sees the tree. Matching runs
- * strongest-first (exact, then case-insensitive, then contains) so an
- * unambiguous name wins outright, and an ambiguous one fails loudly with the
- * candidates rather than silently clicking the first row.
+ * one snapshot and the caller never sees the tree. The page does the matching
+ * itself (`collectSnapshot` with a locator returns only the strongest-tier
+ * hits, and stamps refs on those alone), so what crosses the bridge is a
+ * handful of nodes rather than 400; this module re-scores them — same tiers:
+ * exact, then case-insensitive, then prefix, then contains — so an unambiguous
+ * name wins outright and an ambiguous one fails loudly with the candidates
+ * rather than silently clicking the first row.
  */
 import type { Executor, SnapshotNode, Target } from '../executor/types';
 export interface Locator {

package/dist/src/mcp/locate.js

@@ -10,10 +10,13 @@
  * redeploy.
  *
  * A locator closes that: `{ role: 'button', name: 'Sign in' }` resolves through
- * one snapshot, server-side, and the caller never sees the tree. Matching runs
- * strongest-first (exact, then case-insensitive, then contains) so an
- * unambiguous name wins outright, and an ambiguous one fails loudly with the
- * candidates rather than silently clicking the first row.
+ * one snapshot and the caller never sees the tree. The page does the matching
+ * itself (`collectSnapshot` with a locator returns only the strongest-tier
+ * hits, and stamps refs on those alone), so what crosses the bridge is a
+ * handful of nodes rather than 400; this module re-scores them — same tiers:
+ * exact, then case-insensitive, then prefix, then contains — so an unambiguous
+ * name wins outright and an ambiguous one fails loudly with the candidates
+ * rather than silently clicking the first row.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasLocator = hasLocator;
@@ -60,6 +63,7 @@ async function resolveLocator(ex, loc, opts = {}) {
         tabId: opts.tabId,
         interactiveOnly: false,
         max: 400,
+        locator: want,
         frameId: opts.frameId,
         allFrames: opts.allFrames,
     });
@@ -79,10 +83,13 @@ async function resolveLocator(ex, loc, opts = {}) {
     }
     const describe = (n) => `${n.role} "${n.name}"`;
     if (winners.length === 0) {
-        const sample = snap.nodes
-            .filter((n) => !want.role || norm(n.role) === norm(want.role))
-            .slice(0, 8)
-            .map(describe);
+        // A page that scored in place reports what it had of that role as `nearby`;
+        // a backend that returned the full tree leaves it to us.
+        const sample = snap.nearby ??
+            snap.nodes
+                .filter((n) => !want.role || norm(n.role) === norm(want.role))
+                .slice(0, 8)
+                .map(describe);
         throw new validators_1.McpToolError(`no element matches ${JSON.stringify(want)}. ` +
             (sample.length
                 ? `Closest by role: ${sample.join(', ')}. `

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

@@ -22,6 +22,27 @@ export interface ToolDefinition {
     inputSchema: z.ZodRawShape;
 }
 export declare const TOOL_DEFINITIONS: ToolDefinition[];
+/** Every advertised tool name, in catalog order. */
+export declare const TOOL_NAMES: readonly string[];
+/**
+ * Restrict the tool surface to `names` (`--tools`). The catalog is the single
+ * largest fixed cost of having this server connected: every tool's JSON Schema
+ * is re-sent to the model on EVERY turn. A run that only reads pages has no use
+ * for uploads, PDFs or task management, and should not pay for their schemas.
+ *
+ * Excluded tools are neither advertised in `tools/list` nor callable — a
+ * `batch` op naming one is refused exactly like an unknown tool, so hiding a
+ * tool is a real restriction and not just a display filter.
+ *
+ * Passing `null`/`undefined`/`[]` restores the full catalog. Unknown names
+ * throw rather than being ignored: a typo that silently drops `click` from the
+ * surface is far more expensive to debug than a startup error.
+ */
+export declare function setToolAllowlist(names: readonly string[] | null | undefined): void;
+/** Is `name` on the surface? True for every catalog tool when no allowlist is set. */
+export declare function isToolEnabled(name: string): boolean;
+/** The names actually advertised, in catalog order. */
+export declare function enabledToolNames(): readonly string[];
 interface ToolCtx {
     ex: Executor;
     policy: Policy;

package/dist/src/mcp/tools.js

@@ -12,7 +12,10 @@
  * `Error` as an `isError` result.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TOOL_HANDLERS = exports.TOOL_DEFINITIONS = void 0;
+exports.TOOL_HANDLERS = exports.TOOL_NAMES = exports.TOOL_DEFINITIONS = void 0;
+exports.setToolAllowlist = setToolAllowlist;
+exports.isToolEnabled = isToolEnabled;
+exports.enabledToolNames = enabledToolNames;
 exports.resetRateLimiter = resetRateLimiter;
 exports.dispatchToolCall = dispatchToolCall;
 exports.assertNoDrift = assertNoDrift;
@@ -35,45 +38,59 @@ const log_1 = require("./log");
 const tasks_1 = require("../bridge/tasks");
 const workspace_1 = require("../bridge/workspace");
 const validators_1 = require("./validators");
-/** Shared selector|ref target — both optional; a handler that needs one calls `requireTarget`. */
+/**
+ * Element targeting, defined ONCE and spread whole by every tool that acts on
+ * an element. `TARGET_PROPS` is the plain selector|ref pair (for tools whose
+ * handler resolves a node and nothing else); `LOCATOR_PROPS` is the full block
+ * — selector | ref | role+name, in any frame — and is what click/type/hover/
+ * select_option spread as a single object.
+ *
+ * Keeping the block in one place is also what keeps `tools/list` cheap: these
+ * seven fields repeat across a dozen tools, so every byte of prose here is paid
+ * a dozen times on EVERY turn. Detail an agent does not need on every call
+ * belongs in the owning tool's description (`frames_list`, `auth_check`) or the
+ * README, not here.
+ *
+ * A handler that needs a target calls `requireTarget`; ambiguity fails loudly
+ * rather than acting on the wrong element.
+ */
 const TARGET_PROPS = {
-    selector: zod_1.z.string().describe('CSS selector (exactly one of selector|ref)').optional(),
-    ref: zod_1.z.string().describe('Element ref from a prior read (exactly one of selector|ref)').optional(),
+    selector: zod_1.z.string().describe('CSS selector (or pass ref)').optional(),
+    ref: zod_1.z.string().describe('Element ref from a snapshot').optional(),
 };
-const tabIdField = zod_1.z.string().describe('Target tab id (defaults to the active tab)').optional();
-const authWallField = zod_1.z.boolean().describe('Fail with [AUTH_REQUIRED] when the page this call lands on is a high-confidence sign-in wall (session expired). Off by default unless the server runs with --fail-on-auth-wall; snapshot still reports the verdict as `authWall` either way.').optional();
 /**
- * Frame targeting. Omitted = the top frame, which is what every call did before
- * frames were addressable. `allFrames` is the one to reach for when a selector
- * "should" match but does not: the element is almost always inside an iframe
- * (checkout widgets, OAuth consent, embedded editors). Every frame is
- * authorized against its own URL, so a scan never reaches a site the allowlist
- * does not cover.
+ * Frame targeting. Omitted = the top frame. `allFrames` is the one to reach for
+ * when a selector "should" match but does not — the element is almost always
+ * inside an iframe. Every frame is authorized against its own URL, so a scan
+ * never reaches a site the allowlist does not cover.
  */
 const FRAME_PROPS = {
-    frameId: zod_1.z.number().describe('Act inside this frame (ids come from frames_list)').optional(),
-    allFrames: zod_1.z
-        .boolean()
-        .describe('Search every frame of the tab and act on the first that matches - use when a selector should match but does not (the element is in an iframe)')
-        .optional(),
+    frameId: zod_1.z.number().describe('Frame id from frames_list').optional(),
+    allFrames: zod_1.z.boolean().describe('Act on the first match in ANY frame (the element may be in an iframe)').optional(),
 };
 /**
- * Target an element by role + accessible name instead of a CSS selector, so an
- * action needs no snapshot first. Resolution is server-side and fails loudly on
- * ambiguity rather than acting on the wrong element.
+ * The full locator block. role+name targets an element the way a person reads
+ * the page, so an action needs no snapshot first; resolution is server-side.
  */
 const LOCATOR_PROPS = {
-    role: zod_1.z.string().describe('Target by ARIA role (e.g. button, link, textbox) - alternative to selector/ref').optional(),
-    name: zod_1.z.string().describe('Target by accessible name/visible label (pairs with role)').optional(),
-    nth: zod_1.z.number().describe('Pick the nth (0-based) match when a role+name locator is legitimately ambiguous').optional(),
+    ...TARGET_PROPS,
+    // These tools take role+name too, so their `selector` says so; the tools that
+    // only resolve a node keep the plain TARGET_PROPS wording.
+    selector: zod_1.z.string().describe('CSS selector (or ref, or role+name)').optional(),
+    role: zod_1.z.string().describe('ARIA role, e.g. button|link|textbox (pair with name)').optional(),
+    name: zod_1.z.string().describe('Accessible name / visible label (pair with role)').optional(),
+    nth: zod_1.z.number().describe('0-based index when role+name is ambiguous').optional(),
+    ...FRAME_PROPS,
 };
+const tabIdField = zod_1.z.string().describe('Tab id (default: active tab)').optional();
+const authWallField = zod_1.z.boolean().describe('Error with [AUTH_REQUIRED] if this lands on a sign-in wall (expired session)').optional();
 const snapshotAfterField = zod_1.z
     .boolean()
-    .describe('Return what CHANGED on the page after this action (added/removed/changed elements vs the last snapshot) instead of making you re-read the page')
+    .describe('Return what CHANGED on the page after this action instead of making you re-read it')
     .optional();
 const maxBytesField = zod_1.z
     .number()
-    .describe(`Cap the returned content at this many UTF-8 bytes (default ${limits_1.DEFAULT_MAX_OUTPUT_BYTES}). A truncated result reports truncated/totalBytes/returnedBytes. The full payload is still written to the task's results/ dir.`)
+    .describe(`Cap returned content at N UTF-8 bytes (default ${limits_1.DEFAULT_MAX_OUTPUT_BYTES}); the full payload still lands in results/`)
     .optional();
 const waitUntilField = zod_1.z.enum(['load', 'domcontentloaded', 'networkidle']).describe('When to consider navigation done').optional();
 exports.TOOL_DEFINITIONS = [
@@ -85,13 +102,13 @@ exports.TOOL_DEFINITIONS = [
     { name: 'back', description: 'Go back in history.', inputSchema: { tabId: tabIdField, failOnAuthWall: authWallField } },
     { name: 'forward', description: 'Go forward in history.', inputSchema: { tabId: tabIdField, failOnAuthWall: authWallField } },
     { name: 'reload', description: 'Reload the active (or given) tab.', inputSchema: { tabId: tabIdField, waitUntil: waitUntilField, failOnAuthWall: authWallField } },
-    { name: 'click', description: 'Click an element. Target by selector, a snapshot ref, or role+name (e.g. role:"button", name:"Sign in") - the locator needs no snapshot first. trusted=true uses real OS-level input.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, tabId: tabIdField, button: zod_1.z.enum(['left', 'right', 'middle']).optional(), clickCount: zod_1.z.number().optional(), trusted: zod_1.z.boolean().optional(), snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
-    { name: 'type', description: 'Type text into an element (target by selector, ref, or role+name). trusted=true sends real keystrokes (works on React/Vue controlled inputs).', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, text: zod_1.z.string(), tabId: tabIdField, clear: zod_1.z.boolean().optional(), pressEnter: zod_1.z.boolean().optional(), keyEvents: zod_1.z.boolean().optional(), trusted: zod_1.z.boolean().optional(), snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
-    { name: 'select_option', description: 'Select option(s) of a <select> by value or visible label.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, values: zod_1.z.array(zod_1.z.string()), tabId: tabIdField, snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
+    { name: 'click', description: 'Click an element. Target by selector, a snapshot ref, or role+name (e.g. role:"button", name:"Sign in") - the locator needs no snapshot first. trusted=true uses real OS-level input.', inputSchema: { ...LOCATOR_PROPS, tabId: tabIdField, button: zod_1.z.enum(['left', 'right', 'middle']).optional(), clickCount: zod_1.z.number().optional(), trusted: zod_1.z.boolean().optional(), snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
+    { name: 'type', description: 'Type text into an element (target by selector, ref, or role+name). trusted=true sends real keystrokes (works on React/Vue controlled inputs).', inputSchema: { ...LOCATOR_PROPS, text: zod_1.z.string(), tabId: tabIdField, clear: zod_1.z.boolean().optional(), pressEnter: zod_1.z.boolean().optional(), keyEvents: zod_1.z.boolean().optional(), trusted: zod_1.z.boolean().optional(), snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
+    { name: 'select_option', description: 'Select option(s) of a <select> by value or visible label.', inputSchema: { ...LOCATOR_PROPS, values: zod_1.z.array(zod_1.z.string()), tabId: tabIdField, snapshotAfter: snapshotAfterField, failOnAuthWall: authWallField } },
     { name: 'press', description: 'Press a key (with optional modifiers).', inputSchema: { key: zod_1.z.string(), modifiers: zod_1.z.array(zod_1.z.string()).optional(), tabId: tabIdField, failOnAuthWall: authWallField } },
-    { name: 'hover', description: 'Hover over an element.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_PROPS, tabId: tabIdField, snapshotAfter: snapshotAfterField } },
+    { name: 'hover', description: 'Hover over an element.', inputSchema: { ...LOCATOR_PROPS, tabId: tabIdField, snapshotAfter: snapshotAfterField } },
     { name: 'scroll', description: 'Scroll the page or to an element.', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, x: zod_1.z.number().optional(), y: zod_1.z.number().optional(), deltaX: zod_1.z.number().optional(), deltaY: zod_1.z.number().optional(), tabId: tabIdField } },
-    { name: 'screenshot', description: 'Capture a PNG screenshot (page or element).', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, fullPage: zod_1.z.boolean().optional(), tabId: tabIdField } },
+    { name: 'screenshot', description: 'Capture a screenshot (page or element). Default is JPEG (quality 70) at CSS-pixel size, which is several times smaller than PNG and reads fine. Pass format:"png" for lossless, quality 1-100 for JPEG, scale 2 for device pixels on a Retina display or 0.5 to shrink.', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, fullPage: zod_1.z.boolean().optional(), format: zod_1.z.enum(['jpeg', 'png']).optional(), quality: zod_1.z.number().optional(), scale: zod_1.z.number().optional(), tabId: tabIdField } },
     { name: 'get_text', description: 'Get visible text of the page or an element.', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, tabId: tabIdField, maxBytes: maxBytesField } },
     { name: 'get_html', description: 'Get HTML of the page or an element. Output is capped (see maxBytes) and cut at a tag boundary; narrow it with `selector` rather than raising the cap when you can. Password field values are always blanked.', inputSchema: { ...TARGET_PROPS, ...FRAME_PROPS, outer: zod_1.z.boolean().optional(), tabId: tabIdField, maxBytes: maxBytesField } },
     { name: 'snapshot', description: 'Accessibility snapshot: interactive elements with refs to target by `ref` (more reliable than guessing CSS selectors). Pass diff:true to get only what changed since the last snapshot of this tab - far cheaper in a click/read loop. Password fields appear as secret:true with no value.', inputSchema: { interactiveOnly: zod_1.z.boolean().optional(), max: zod_1.z.number().optional(), diff: zod_1.z.boolean().describe('Return added/removed/changed elements since the previous snapshot of this tab instead of the whole tree').optional(), failOnAuthWall: authWallField, ...FRAME_PROPS, tabId: tabIdField } },
@@ -182,6 +199,48 @@ exports.TOOL_DEFINITIONS = [
         },
     },
 ];
+// ---------------------------------------------------------------------------
+// Tool allowlist (--tools)
+// ---------------------------------------------------------------------------
+/** Every advertised tool name, in catalog order. */
+exports.TOOL_NAMES = exports.TOOL_DEFINITIONS.map((d) => d.name);
+/** `null` = the whole catalog (the default). */
+let toolAllowlist = null;
+/**
+ * Restrict the tool surface to `names` (`--tools`). The catalog is the single
+ * largest fixed cost of having this server connected: every tool's JSON Schema
+ * is re-sent to the model on EVERY turn. A run that only reads pages has no use
+ * for uploads, PDFs or task management, and should not pay for their schemas.
+ *
+ * Excluded tools are neither advertised in `tools/list` nor callable — a
+ * `batch` op naming one is refused exactly like an unknown tool, so hiding a
+ * tool is a real restriction and not just a display filter.
+ *
+ * Passing `null`/`undefined`/`[]` restores the full catalog. Unknown names
+ * throw rather than being ignored: a typo that silently drops `click` from the
+ * surface is far more expensive to debug than a startup error.
+ */
+function setToolAllowlist(names) {
+    if (!names || names.length === 0) {
+        toolAllowlist = null;
+        return;
+    }
+    const known = new Set(exports.TOOL_NAMES);
+    const unknown = names.filter((n) => !known.has(n));
+    if (unknown.length > 0) {
+        throw new Error(`--tools: unknown tool ${unknown.map((n) => JSON.stringify(n)).join(', ')}. ` +
+            `Known tools: ${exports.TOOL_NAMES.join(', ')}`);
+    }
+    toolAllowlist = new Set(names);
+}
+/** Is `name` on the surface? True for every catalog tool when no allowlist is set. */
+function isToolEnabled(name) {
+    return toolAllowlist === null || toolAllowlist.has(name);
+}
+/** The names actually advertised, in catalog order. */
+function enabledToolNames() {
+    return exports.TOOL_NAMES.filter(isToolEnabled);
+}
 const GATE_CONTEXT = 'cannot resolve the target tab URL for the policy gate';
 /**
  * Resolve the URL the policy should be evaluated against: the URL of the tab
@@ -201,15 +260,15 @@ const GATE_CONTEXT = 'cannot resolve the target tab URL for the policy gate';
  *
  * Prefers a URL the backend already reported over asking again: the extension
  * rides the tab's landing URL home on every result frame, which is what keeps a
- * gated call to ONE round-trip instead of two. That cache only ever describes
- * the active tab, so it is bypassed whenever an explicit `tabId` is in play.
+ * gated call to ONE round-trip instead of two. The active-tab cache serves calls
+ * without a `tabId`; the per-tab cache (fed by results for that tab and by any
+ * `tabs_list`) serves explicitly-targeted ones, so a parallel batch over N tabs
+ * gates on the one listing that opened it rather than N more.
  */
 async function gatedUrl(ex, tabId) {
-    if (!tabId) {
-        const known = ex.cachedActiveUrl?.();
-        if (known)
-            return known;
-    }
+    const known = tabId ? ex.cachedTabUrl?.(tabId) : ex.cachedActiveUrl?.();
+    if (known)
+        return known;
     let tabs;
     try {
         tabs = await ex.tabsList();
@@ -547,13 +606,20 @@ exports.TOOL_HANDLERS = {
     },
     screenshot: async (a, ctx) => {
         await gate(ctx, 'screenshot', { tabId: tabId(a) });
+        const format = (0, validators_1.optionalString)(a, 'format');
+        if (format !== undefined && format !== 'jpeg' && format !== 'png') {
+            throw new validators_1.McpToolError('"format" must be "jpeg" or "png"');
+        }
         const shot = await ctx.ex.screenshot({
             tabId: tabId(a),
             ...frameOpts(a),
             fullPage: (0, validators_1.optionalBoolean)(a, 'fullPage'),
             target: (0, validators_1.optionalTarget)(a),
+            format,
+            quality: (0, validators_1.optionalNumber)(a, 'quality', { min: 1, max: 100 }),
+            scale: (0, validators_1.optionalNumber)(a, 'scale', { min: 0.1, max: 4 }),
         });
-        (0, workspace_1.saveScreenshot)(shot.dataBase64);
+        (0, workspace_1.saveScreenshot)(shot.dataBase64, shot.mimeType === 'image/jpeg' ? 'jpg' : 'png');
         const caption = shot.truncated ? `(truncated; full height ${shot.fullHeight}px)` : undefined;
         return (0, envelopes_1.imageResult)(shot.dataBase64, shot.mimeType, caption);
     },
@@ -977,6 +1043,10 @@ function isRetryableFault(name, err) {
     return err instanceof types_1.ExecutorError && err.code === 'EXTENSION_DISCONNECTED' && RETRY_SAFE_TOOLS.has(name);
 }
 async function dispatchToolCall(name, rawArgs) {
+    // The allowlist is checked here, not only at registration, so a `batch` op
+    // cannot reach a tool the operator kept off the surface.
+    if (!isToolEnabled(name))
+        return (0, envelopes_1.errorResult)(`tool not enabled on this server (--tools): ${name}`);
     const handler = exports.TOOL_HANDLERS[name];
     if (!handler)
         return (0, envelopes_1.errorResult)(`unknown tool: ${name}`);
@@ -1039,7 +1109,13 @@ function registerTools(server) {
     // just routes back through `dispatchToolCall` — our never-throw firewall that
     // applies the rate limit, executor readiness, policy gate, and history log.
     for (const d of exports.TOOL_DEFINITIONS) {
+        if (!isToolEnabled(d.name))
+            continue;
         server.registerTool(d.name, { description: d.description, inputSchema: d.inputSchema }, async (args) => dispatchToolCall(d.name, args));
     }
+    const advertised = enabledToolNames();
+    if (advertised.length < exports.TOOL_NAMES.length) {
+        (0, log_1.logErr)(`--tools: advertising ${advertised.length} of ${exports.TOOL_NAMES.length} tools (${advertised.join(', ')})`);
+    }
 }
 //# sourceMappingURL=tools.js.map

package/docs/BLUEPRINT.md

@@ -173,7 +173,7 @@ export interface EvalResult { ok: boolean; value?: unknown; type?: string; error
 export interface WaitResult { matched: boolean; ref?: string; waitedMs: number; }
 export interface ActionOk   { ok: true; }
 export interface ScreenshotResult {
-  dataBase64: string; mimeType: 'image/png';
+  dataBase64: string; mimeType: 'image/png' | 'image/jpeg';  // jpeg q70 @ CSS px by default; format/quality/scale opt-in
   width: number; height: number; truncated: boolean; fullHeight?: number;  // fullPage cap metadata
 }
 export interface DownloadResult { path: string; backend: BackendKind; bytes: number; mimeType?: string; suggestedName?: string; }