@mehmoodqureshi/chrome-mcp 0.6.7 → 0.7.0

package/dist/src/mcp/tools.js

@@ -26,6 +26,10 @@ const envelopes_1 = require("./envelopes");
 const limits_1 = require("./limits");
 const batch_1 = require("./batch");
 const helpers_1 = require("./helpers");
+const redact_1 = require("./redact");
+const locate_1 = require("./locate");
+const snapdiff_1 = require("./snapdiff");
+const audit_1 = require("./audit");
 const log_1 = require("./log");
 const tasks_1 = require("../bridge/tasks");
 const workspace_1 = require("../bridge/workspace");
@@ -36,6 +40,35 @@ const TARGET_PROPS = {
     ref: zod_1.z.string().describe('Element ref from a prior read (exactly one of selector|ref)').optional(),
 };
 const tabIdField = zod_1.z.string().describe('Target tab id (defaults to the active tab)').optional();
+/**
+ * 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.
+ */
+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(),
+};
+/**
+ * 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.
+ */
+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(),
+};
+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')
+    .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.`)
@@ -50,25 +83,83 @@ exports.TOOL_DEFINITIONS = [
     { name: 'back', description: 'Go back in history.', inputSchema: { tabId: tabIdField } },
     { name: 'forward', description: 'Go forward in history.', inputSchema: { tabId: tabIdField } },
     { name: 'reload', description: 'Reload the active (or given) tab.', inputSchema: { tabId: tabIdField, waitUntil: waitUntilField } },
-    { name: 'click', description: 'Click an element (target by selector or a snapshot ref). trusted=true uses real OS-level input.', inputSchema: { ...TARGET_PROPS, tabId: tabIdField, button: zod_1.z.enum(['left', 'right', 'middle']).optional(), clickCount: zod_1.z.number().optional(), trusted: zod_1.z.boolean().optional() } },
-    { name: 'type', description: 'Type text into an element. trusted=true sends real keystrokes (works on React/Vue controlled inputs).', inputSchema: { ...TARGET_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() } },
-    { name: 'select_option', description: 'Select option(s) of a <select> by value or visible label.', inputSchema: { ...TARGET_PROPS, values: zod_1.z.array(zod_1.z.string()), tabId: tabIdField } },
+    { 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 } },
+    { 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 } },
+    { 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 } },
     { 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 } },
-    { name: 'hover', description: 'Hover over an element.', inputSchema: { ...TARGET_PROPS, tabId: tabIdField } },
-    { name: 'scroll', description: 'Scroll the page or to an element.', inputSchema: { ...TARGET_PROPS, x: zod_1.z.number().optional(), y: zod_1.z.number().optional(), deltaX: zod_1.z.number().optional(), deltaY: zod_1.z.number().optional(), tabId: tabIdField } },
-    { name: 'screenshot', description: 'Capture a PNG screenshot (page or element).', inputSchema: { ...TARGET_PROPS, fullPage: zod_1.z.boolean().optional(), tabId: tabIdField } },
-    { name: 'get_text', description: 'Get visible text of the page or an element.', inputSchema: { ...TARGET_PROPS, tabId: tabIdField, maxBytes: maxBytesField } },
-    { name: 'get_html', description: 'Get HTML of the page or an element. Output is capped (see maxBytes) and cut at a tag boundary; narrow it with `selector` rather than raising the cap when you can.', inputSchema: { ...TARGET_PROPS, outer: zod_1.z.boolean().optional(), tabId: tabIdField, maxBytes: maxBytesField } },
-    { name: 'snapshot', description: 'Accessibility snapshot: interactive elements with stable refs to target by `ref` (more reliable than guessing CSS selectors).', inputSchema: { interactiveOnly: zod_1.z.boolean().optional(), max: zod_1.z.number().optional(), tabId: tabIdField } },
+    { name: 'hover', description: 'Hover over an element.', inputSchema: { ...TARGET_PROPS, ...LOCATOR_PROPS, ...FRAME_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: '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(), ...FRAME_PROPS, tabId: tabIdField } },
     { name: 'get_cookies', description: "Read cookies visible to the tab's URL (or a given url).", inputSchema: { url: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'storage', description: 'Read/write localStorage (or sessionStorage). op: get|set|remove|clear.', inputSchema: { op: zod_1.z.enum(['get', 'set', 'remove', 'clear']), key: zod_1.z.string().optional(), value: zod_1.z.string().optional(), session: zod_1.z.boolean().optional(), tabId: tabIdField } },
-    { name: 'eval', description: 'Evaluate JavaScript in the page (disabled in safe-mode).', inputSchema: { expression: zod_1.z.string(), awaitPromise: zod_1.z.boolean().optional(), tabId: tabIdField } },
-    { name: 'wait_for', description: 'Wait for a selector or text to appear/disappear.', inputSchema: { selector: zod_1.z.string().optional(), textContains: zod_1.z.string().optional(), gone: zod_1.z.boolean().optional(), timeoutMs: zod_1.z.number().optional(), tabId: tabIdField } },
-    { name: 'extract_links', description: 'Extract anchors from the page or a subtree. dedupe=true collapses links sharing an href (nav/footer noise); limit caps the count.', inputSchema: { selector: zod_1.z.string().optional(), sameOriginOnly: zod_1.z.boolean().optional(), dedupe: zod_1.z.boolean().optional(), limit: zod_1.z.number().optional(), tabId: tabIdField } },
-    { name: 'read_as_markdown', description: 'Read the page (or subtree) as readable markdown.', inputSchema: { selector: zod_1.z.string().optional(), tabId: tabIdField, maxBytes: maxBytesField } },
-    { name: 'fill_form', description: 'Fill multiple fields (keyed by selector) and optionally submit.', inputSchema: { fields: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()])), submitSelector: zod_1.z.string().optional(), tabId: tabIdField } },
+    { name: 'eval', description: 'Evaluate JavaScript in the page (disabled in safe-mode).', inputSchema: { expression: zod_1.z.string(), awaitPromise: zod_1.z.boolean().optional(), ...FRAME_PROPS, tabId: tabIdField } },
+    { name: 'wait_for', description: 'Wait for a selector or text to appear/disappear.', inputSchema: { selector: zod_1.z.string().optional(), textContains: zod_1.z.string().optional(), gone: zod_1.z.boolean().optional(), timeoutMs: zod_1.z.number().optional(), ...FRAME_PROPS, tabId: tabIdField } },
+    { name: 'extract_links', description: 'Extract anchors from the page or a subtree. dedupe=true collapses links sharing an href (nav/footer noise); limit caps the count.', inputSchema: { selector: zod_1.z.string().optional(), sameOriginOnly: zod_1.z.boolean().optional(), dedupe: zod_1.z.boolean().optional(), limit: zod_1.z.number().optional(), ...FRAME_PROPS, tabId: tabIdField } },
+    { name: 'read_as_markdown', description: 'Read the page (or subtree) as readable markdown.', inputSchema: { selector: zod_1.z.string().optional(), ...FRAME_PROPS, tabId: tabIdField, maxBytes: maxBytesField } },
+    { name: 'fill_form', description: 'Fill multiple fields (keyed by selector) and optionally submit.', inputSchema: { fields: zod_1.z.record(zod_1.z.string(), zod_1.z.union([zod_1.z.string(), zod_1.z.boolean()])), submitSelector: zod_1.z.string().optional(), ...FRAME_PROPS, tabId: tabIdField } },
     { name: 'download_file', description: 'Download a file by URL or from a link element.', inputSchema: { url: zod_1.z.string().optional(), ...TARGET_PROPS, suggestedName: zod_1.z.string().optional(), tabId: tabIdField } },
     { name: 'upload_file', description: 'Set local file(s) on a file <input> (target by selector or ref) — uploads without the OS dialog. Requires --enable-uploads. `files` are absolute local paths.', inputSchema: { ...TARGET_PROPS, files: zod_1.z.array(zod_1.z.string()), tabId: tabIdField } },
+    {
+        name: 'frames_list',
+        description: "List the tab's frames (the top document plus every iframe the extension can reach), with each frame's id and URL. Use it when a selector that should match does not: the element is probably in one of these frames, and you can then pass frameId (or allFrames:true) to act inside it.",
+        inputSchema: { tabId: tabIdField },
+    },
+    {
+        name: 'console_logs',
+        description: 'Console output and uncaught errors recorded on the page (requires --enable-observers). This is how you find out WHY a page misbehaved rather than only what it looks like afterwards. Pass sinceSeq to poll for what is new, clear:true to drain.',
+        inputSchema: {
+            level: zod_1.z.enum(['log', 'info', 'warn', 'error', 'debug', 'exception']).describe('Only entries at this level').optional(),
+            ...FRAME_PROPS,
+            sinceSeq: zod_1.z.number().describe('Only entries newer than this seq (from a previous call)').optional(),
+            limit: zod_1.z.number().describe('Max entries to return (default 200)').optional(),
+            clear: zod_1.z.boolean().describe('Empty the buffer after reading').optional(),
+            tabId: tabIdField,
+        },
+    },
+    {
+        name: 'network_log',
+        description: "Requests the page made - fetch and XMLHttpRequest with method, URL, status and duration (requires --enable-observers). Set includeResources:true to also list scripts/images/styles from Resource Timing (those carry timing and size but no status). Does not include the document request or headers.",
+        inputSchema: {
+            urlContains: zod_1.z.string().describe('Only requests whose URL contains this substring').optional(),
+            ...FRAME_PROPS,
+            failedOnly: zod_1.z.boolean().describe('Only requests that errored or returned status >= 400').optional(),
+            includeResources: zod_1.z.boolean().describe('Also include Resource Timing entries (scripts, images, styles)').optional(),
+            sinceSeq: zod_1.z.number().optional(),
+            limit: zod_1.z.number().optional(),
+            clear: zod_1.z.boolean().optional(),
+            tabId: tabIdField,
+        },
+    },
+    {
+        name: 'dialogs',
+        description: "Native dialogs (alert/confirm/prompt/beforeunload) the page raised, and how they were answered (requires --enable-observers). With observers on, dialogs are intercepted rather than left to block the renderer - which is what otherwise turns a click that opens a confirm() into a mystery TIMEOUT. Set policy:'accept' to answer confirms with true.",
+        inputSchema: {
+            policy: zod_1.z.enum(['dismiss', 'accept']).describe("How to answer future dialogs (default dismiss: confirm->false, prompt->null)").optional(),
+            ...FRAME_PROPS,
+            promptText: zod_1.z.string().describe("Text to answer prompt() with when policy is 'accept'").optional(),
+            sinceSeq: zod_1.z.number().optional(),
+            limit: zod_1.z.number().optional(),
+            clear: zod_1.z.boolean().optional(),
+            tabId: tabIdField,
+        },
+    },
+    {
+        name: 'print_pdf',
+        description: "Render the page to PDF through Chrome's own print pipeline and save it to the task's results/ dir. Returns the path and size, not the bytes - a PDF is not something to spend context on.",
+        inputSchema: {
+            landscape: zod_1.z.boolean().optional(),
+            printBackground: zod_1.z.boolean().describe('Include background graphics (default true)').optional(),
+            scale: zod_1.z.number().describe('0.1 - 2.0').optional(),
+            paperWidth: zod_1.z.number().describe('Inches').optional(),
+            paperHeight: zod_1.z.number().describe('Inches').optional(),
+            pageRanges: zod_1.z.string().describe("e.g. '1-3, 5'").optional(),
+            preferCSSPageSize: zod_1.z.boolean().optional(),
+            tabId: tabIdField,
+        },
+    },
     { name: 'chrome_status', description: 'Report backend/session status.', inputSchema: {} },
     { name: 'profile_use', description: 'Switch the active browser profile (identity). Subsequent downloads, results, screenshots, and the action log are stored under profiles/<name>/. Resets the active task to "default" unless you then call task_new.', inputSchema: { name: zod_1.z.string().describe('Profile name (becomes a folder; sanitized to a safe path segment).') } },
     { name: 'task_new', description: 'Start a new task (run) under the active profile. Creates profiles/<profile>/tasks/<name>/ with downloads/, results/, screenshots/ and makes it the active task so all captured artifacts land there.', inputSchema: { name: zod_1.z.string().describe('Task name (becomes a folder; sanitized to a safe path segment).') } },
@@ -161,9 +252,112 @@ async function gatedUrl(ex, tabId) {
  */
 async function gate(ctx, method, opts = {}) {
     const url = opts.url ?? ((0, policy_1.isUrlGated)(method) ? await gatedUrl(ctx.ex, opts.tabId) : '');
-    (0, policy_1.assertUrlAllowed)(url, method, ctx.policy);
+    try {
+        (0, policy_1.assertUrlAllowed)(url, method, ctx.policy);
+    }
+    catch (err) {
+        (0, audit_1.noteGate)(url, false);
+        throw err;
+    }
+    (0, audit_1.noteGate)(url, true);
 }
 const tabId = (args) => (0, validators_1.optionalString)(args, 'tabId');
+/** Frame targeting pulled off the raw args. */
+const frameOpts = (args) => ({
+    frameId: (0, validators_1.optionalNumber)(args, 'frameId', { min: 0 }),
+    allFrames: (0, validators_1.optionalBoolean)(args, 'allFrames'),
+});
+const locatorOf = (args) => ({
+    role: (0, validators_1.optionalString)(args, 'role'),
+    name: (0, validators_1.optionalString)(args, 'name'),
+    nth: (0, validators_1.optionalNumber)(args, 'nth', { min: 0, max: 999 }),
+});
+/**
+ * Resolve whatever the caller used to point at an element: a CSS selector, a
+ * snapshot ref, or a role+name locator. Exactly one of the three — mixing them
+ * is a mistake worth reporting rather than silently preferring one.
+ */
+async function resolveTargetArg(ctx, a) {
+    const direct = (0, validators_1.optionalString)(a, 'selector') !== undefined || (0, validators_1.optionalString)(a, 'ref') !== undefined;
+    const loc = locatorOf(a);
+    if (direct && (0, locate_1.hasLocator)(loc)) {
+        throw new validators_1.McpToolError('give exactly one of selector | ref | role+name — not several at once');
+    }
+    if (!direct && (0, locate_1.hasLocator)(loc)) {
+        const found = await (0, locate_1.resolveLocator)(ctx.ex, loc, { tabId: tabId(a), ...frameOpts(a) });
+        return found.target;
+    }
+    // No locator: keep the original exactly-one-of validation and its message.
+    return (0, validators_1.requireTarget)(a);
+}
+/** Re-parse a redacted JSON string, falling back to the string when the
+ *  substitution broke its syntax (a marker inside a string literal never does,
+ *  but a caller is better served by the scrubbed text than by a throw). */
+function safeParse(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch {
+        return json;
+    }
+}
+/** Compiled redaction config per policy object (compiling per call is waste). */
+const redactionCache = new WeakMap();
+function redaction(policy) {
+    if (!policy.redact)
+        return redact_1.NO_REDACTION;
+    const hit = redactionCache.get(policy);
+    if (hit)
+        return hit;
+    const cfg = {
+        enabled: true,
+        extra: (policy.redactPatterns ?? []).map(redact_1.compileRedactionPattern),
+    };
+    redactionCache.set(policy, cfg);
+    return cfg;
+}
+/** The scope a tab's remembered snapshot lives under. */
+const snapScope = (a) => (0, snapdiff_1.scopeOf)((0, workspace_1.peekActiveWorkspace)()?.profile ?? 'default', tabId(a));
+/**
+ * Render an action's result, optionally with what the action CHANGED on the
+ * page. One extra round-trip buys the caller the delta instead of a full
+ * re-read, which is the expensive half of every click-then-look loop.
+ */
+async function actionResult(ctx, a, payload) {
+    if ((0, validators_1.optionalBoolean)(a, 'snapshotAfter') !== true)
+        return (0, envelopes_1.jsonResult)(payload);
+    const scope = snapScope(a);
+    const previous = (0, snapdiff_1.lastSnapshot)(scope);
+    const snap = await ctx.ex.snapshot({ tabId: tabId(a), max: 200, ...frameOpts(a) });
+    const diff = (0, snapdiff_1.diffSnapshots)(previous, snap);
+    const stored = (0, snapdiff_1.rememberSnapshot)(scope, snap);
+    return (0, envelopes_1.jsonResult)({ ...payload, changed: { ...diff, snapshotId: stored.id, url: snap.url } });
+}
+/**
+ * Shared body of console_logs / network_log / dialogs: one gate, one read, and
+ * a straight answer when the hook is not there rather than an empty list that
+ * reads like "nothing happened".
+ */
+async function readObservers(ctx, a, which, extra = {}) {
+    await gate(ctx, 'observers', { tabId: tabId(a) });
+    if (!ctx.ex.observers) {
+        throw new types_1.ExecutorError('UNSUPPORTED', 'this backend cannot read in-page observers');
+    }
+    const res = await ctx.ex.observers({
+        tabId: tabId(a),
+        ...frameOpts(a),
+        ...which,
+        ...extra,
+        sinceSeq: (0, validators_1.optionalNumber)(a, 'sinceSeq', { min: 0 }),
+        limit: (0, validators_1.optionalNumber)(a, 'limit', { min: 1, max: 1000 }),
+        clear: (0, validators_1.optionalBoolean)(a, 'clear'),
+    });
+    if (!res.installed) {
+        throw new validators_1.McpToolError('the observer hook is not present on this page. It is registered for allowlisted sites when the ' +
+            'server runs with --enable-observers; if it is on, reload the page so the hook is installed at load.');
+    }
+    return res;
+}
 /** The caller's output cap for a content read, or the default. */
 const maxBytes = (args) => (0, validators_1.optionalNumber)(args, 'maxBytes', { min: limits_1.MIN_OUTPUT_BYTES, max: limits_1.MAX_OUTPUT_BYTES }) ?? limits_1.DEFAULT_MAX_OUTPUT_BYTES;
 const waitUntil = (args) => (0, validators_1.optionalString)(args, 'waitUntil');
@@ -224,33 +418,38 @@ exports.TOOL_HANDLERS = {
         return (0, envelopes_1.jsonResult)(await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) }));
     },
     click: async (a, ctx) => {
-        const t = (0, validators_1.requireTarget)(a);
         await gate(ctx, 'click', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.click(t, {
+        const t = await resolveTargetArg(ctx, a);
+        const res = await ctx.ex.click(t, {
             tabId: tabId(a),
+            ...frameOpts(a),
             button: (0, validators_1.optionalString)(a, 'button'),
             clickCount: (0, validators_1.optionalNumber)(a, 'clickCount', { min: 1, max: 3 }),
             trusted: (0, validators_1.optionalBoolean)(a, 'trusted'),
-        }));
+        });
+        return actionResult(ctx, a, res);
     },
     type: async (a, ctx) => {
-        const t = (0, validators_1.requireTarget)(a);
         await gate(ctx, 'type', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.type(t, (0, validators_1.requireWithinLength)((0, validators_1.requireString)(a, 'text'), 'text', validators_1.MAX_TEXT_LEN), {
+        const t = await resolveTargetArg(ctx, a);
+        const res = await ctx.ex.type(t, (0, validators_1.requireWithinLength)((0, validators_1.requireString)(a, 'text'), 'text', validators_1.MAX_TEXT_LEN), {
             tabId: tabId(a),
+            ...frameOpts(a),
             clear: (0, validators_1.optionalBoolean)(a, 'clear'),
             pressEnter: (0, validators_1.optionalBoolean)(a, 'pressEnter'),
             keyEvents: (0, validators_1.optionalBoolean)(a, 'keyEvents'),
             trusted: (0, validators_1.optionalBoolean)(a, 'trusted'),
-        }));
+        });
+        return actionResult(ctx, a, res);
     },
     select_option: async (a, ctx) => {
-        const t = (0, validators_1.requireTarget)(a);
         await gate(ctx, 'type', { tabId: tabId(a) }); // mutating
+        const t = await resolveTargetArg(ctx, a);
         const values = (0, validators_1.optionalStringArray)(a, 'values');
         if (!values || values.length === 0)
             throw new validators_1.McpToolError('"values" must be a non-empty array of strings');
-        return (0, envelopes_1.jsonResult)(await ctx.ex.selectOption(t, values, { tabId: tabId(a) }));
+        const res = await ctx.ex.selectOption(t, values, { tabId: tabId(a), ...frameOpts(a) });
+        return actionResult(ctx, a, res);
     },
     press: async (a, ctx) => {
         await gate(ctx, 'press', { tabId: tabId(a) });
@@ -260,14 +459,16 @@ exports.TOOL_HANDLERS = {
         }));
     },
     hover: async (a, ctx) => {
-        const t = (0, validators_1.requireTarget)(a);
         await gate(ctx, 'hover', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.hover(t, { tabId: tabId(a) }));
+        const t = await resolveTargetArg(ctx, a);
+        const res = await ctx.ex.hover(t, { tabId: tabId(a), ...frameOpts(a) });
+        return actionResult(ctx, a, res);
     },
     scroll: async (a, ctx) => {
         await gate(ctx, 'scroll', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.scroll({
             tabId: tabId(a),
+            ...frameOpts(a),
             x: (0, validators_1.optionalNumber)(a, 'x'),
             y: (0, validators_1.optionalNumber)(a, 'y'),
             deltaX: (0, validators_1.optionalNumber)(a, 'deltaX'),
@@ -279,6 +480,7 @@ exports.TOOL_HANDLERS = {
         await gate(ctx, 'screenshot', { tabId: tabId(a) });
         const shot = await ctx.ex.screenshot({
             tabId: tabId(a),
+            ...frameOpts(a),
             fullPage: (0, validators_1.optionalBoolean)(a, 'fullPage'),
             target: (0, validators_1.optionalTarget)(a),
         });
@@ -288,26 +490,65 @@ exports.TOOL_HANDLERS = {
     },
     get_text: async (a, ctx) => {
         await gate(ctx, 'get_text', { tabId: tabId(a) });
-        const res = await ctx.ex.getText((0, validators_1.optionalTarget)(a), { tabId: tabId(a) });
+        const res = await ctx.ex.getText((0, validators_1.optionalTarget)(a), { tabId: tabId(a), ...frameOpts(a) });
         // Save the FULL read before capping — the artifact on disk stays lossless;
         // only what crosses into the caller's context is bounded.
         (0, workspace_1.saveResult)('get_text', 'json', JSON.stringify(res, null, 2));
-        const capped = (0, limits_1.capText)(res.text, maxBytes(a));
-        return (0, envelopes_1.jsonResult)({ ...res, text: capped.text, ...(0, limits_1.truncationMeta)(capped) });
+        const clean = (0, redact_1.redactText)(res.text, redaction(ctx.policy));
+        (0, audit_1.noteRedactions)(clean.redactions);
+        const capped = (0, limits_1.capText)(clean.value, maxBytes(a));
+        (0, audit_1.noteBytes)(capped.returnedBytes);
+        return (0, envelopes_1.jsonResult)({
+            ...res,
+            text: capped.text,
+            ...(0, limits_1.truncationMeta)(capped),
+            ...(clean.redactions ? { redactions: clean.redactions } : {}),
+        });
     },
     get_html: async (a, ctx) => {
         await gate(ctx, 'get_html', { tabId: tabId(a) });
-        const res = await ctx.ex.getHtml((0, validators_1.optionalTarget)(a), { tabId: tabId(a), outer: (0, validators_1.optionalBoolean)(a, 'outer') });
-        const capped = (0, limits_1.capHtml)(res.html, maxBytes(a));
-        return (0, envelopes_1.jsonResult)({ ...res, html: capped.text, ...(0, limits_1.truncationMeta)(capped) });
+        const res = await ctx.ex.getHtml((0, validators_1.optionalTarget)(a), {
+            tabId: tabId(a),
+            ...frameOpts(a),
+            outer: (0, validators_1.optionalBoolean)(a, 'outer'),
+        });
+        // Password values go before the cap, so a truncated read cannot leak what a
+        // full one would have hidden.
+        const clean = (0, redact_1.redactHtml)(res.html, redaction(ctx.policy));
+        (0, audit_1.noteRedactions)(clean.redactions);
+        const capped = (0, limits_1.capHtml)(clean.value, maxBytes(a));
+        (0, audit_1.noteBytes)(capped.returnedBytes);
+        return (0, envelopes_1.jsonResult)({
+            ...res,
+            html: capped.text,
+            ...(0, limits_1.truncationMeta)(capped),
+            ...(clean.redactions ? { redactions: clean.redactions } : {}),
+        });
     },
     snapshot: async (a, ctx) => {
         await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page structure
-        return (0, envelopes_1.jsonResult)(await ctx.ex.snapshot({
+        const snap = await ctx.ex.snapshot({
             tabId: tabId(a),
+            ...frameOpts(a),
             interactiveOnly: (0, validators_1.optionalBoolean)(a, 'interactiveOnly'),
             max: (0, validators_1.optionalNumber)(a, 'max', { min: 1, max: 1000 }),
-        }));
+        });
+        const scope = snapScope(a);
+        const previous = (0, snapdiff_1.lastSnapshot)(scope);
+        const stored = (0, snapdiff_1.rememberSnapshot)(scope, snap);
+        if ((0, validators_1.optionalBoolean)(a, 'diff') !== true) {
+            return (0, envelopes_1.jsonResult)({ ...snap, snapshotId: stored.id });
+        }
+        const diff = (0, snapdiff_1.diffSnapshots)(previous, snap);
+        return (0, envelopes_1.jsonResult)({
+            url: snap.url,
+            title: snap.title,
+            snapshotId: stored.id,
+            ...diff,
+            ...(diff.since === null
+                ? { note: 'no previous snapshot for this tab, so everything is reported as added' }
+                : {}),
+        });
     },
     get_cookies: async (a, ctx) => {
         await gate(ctx, 'get_text', { tabId: tabId(a) }); // reads tab-scoped secrets; same domain gate as content reads
@@ -330,15 +571,31 @@ exports.TOOL_HANDLERS = {
     },
     eval: async (a, ctx) => {
         await gate(ctx, 'eval', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.eval((0, validators_1.requireString)(a, 'expression'), {
+        const res = await ctx.ex.eval((0, validators_1.requireString)(a, 'expression'), {
             tabId: tabId(a),
+            ...frameOpts(a),
             awaitPromise: (0, validators_1.optionalBoolean)(a, 'awaitPromise'),
-        }));
+        });
+        // eval returns arbitrary page data — the widest read there is, so it gets
+        // the same scrub as the content reads.
+        const cfg = redaction(ctx.policy);
+        if (!cfg.enabled || res.value === undefined)
+            return (0, envelopes_1.jsonResult)(res);
+        const asText = typeof res.value === 'string' ? res.value : JSON.stringify(res.value);
+        if (asText === undefined)
+            return (0, envelopes_1.jsonResult)(res);
+        const clean = (0, redact_1.redactText)(asText, cfg);
+        if (clean.redactions === 0)
+            return (0, envelopes_1.jsonResult)(res);
+        (0, audit_1.noteRedactions)(clean.redactions);
+        const value = typeof res.value === 'string' ? clean.value : safeParse(clean.value);
+        return (0, envelopes_1.jsonResult)({ ...res, value, redactions: clean.redactions });
     },
     wait_for: async (a, ctx) => {
         await gate(ctx, 'wait_for', { tabId: tabId(a) });
         return (0, envelopes_1.jsonResult)(await ctx.ex.waitFor({
             tabId: tabId(a),
+            ...frameOpts(a),
             selector: (0, validators_1.optionalString)(a, 'selector'),
             textContains: (0, validators_1.optionalString)(a, 'textContains'),
             gone: (0, validators_1.optionalBoolean)(a, 'gone'),
@@ -348,6 +605,7 @@ exports.TOOL_HANDLERS = {
     extract_links: async (a, ctx) => {
         await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page content
         const res = await (0, helpers_1.extractLinks)(ctx.ex, {
+            ...frameOpts(a),
             selector: (0, validators_1.optionalString)(a, 'selector'),
             sameOriginOnly: (0, validators_1.optionalBoolean)(a, 'sameOriginOnly'),
             dedupe: (0, validators_1.optionalBoolean)(a, 'dedupe'),
@@ -359,9 +617,16 @@ exports.TOOL_HANDLERS = {
     },
     read_as_markdown: async (a, ctx) => {
         await gate(ctx, 'get_text', { tabId: tabId(a) });
-        const md = await (0, helpers_1.readAsMarkdown)(ctx.ex, { selector: (0, validators_1.optionalString)(a, 'selector'), tabId: tabId(a) });
+        const md = await (0, helpers_1.readAsMarkdown)(ctx.ex, {
+            selector: (0, validators_1.optionalString)(a, 'selector'),
+            tabId: tabId(a),
+            ...frameOpts(a),
+        });
         (0, workspace_1.saveResult)('read_as_markdown', 'md', md);
-        const capped = (0, limits_1.capText)(md, maxBytes(a));
+        const clean = (0, redact_1.redactText)(md, redaction(ctx.policy));
+        (0, audit_1.noteRedactions)(clean.redactions);
+        const capped = (0, limits_1.capText)(clean.value, maxBytes(a));
+        (0, audit_1.noteBytes)(capped.returnedBytes);
         // Markdown is returned as plain text, so the truncation notice has to ride in
         // the body rather than as sibling JSON fields.
         return (0, envelopes_1.textResult)(capped.truncated
@@ -379,6 +644,7 @@ exports.TOOL_HANDLERS = {
                 (0, validators_1.requireWithinLength)(val, `fields["${sel}"]`, validators_1.MAX_TEXT_LEN);
         }
         return (0, envelopes_1.jsonResult)(await (0, helpers_1.fillForm)(ctx.ex, {
+            ...frameOpts(a),
             fields: fields,
             submitSelector: (0, validators_1.optionalString)(a, 'submitSelector'),
             tabId: tabId(a),
@@ -414,9 +680,102 @@ exports.TOOL_HANDLERS = {
         }
         return (0, envelopes_1.jsonResult)(await ctx.ex.uploadFile(t, files, { tabId: tabId(a) }));
     },
+    frames_list: async (a, ctx) => {
+        await gate(ctx, 'frames_list', { tabId: tabId(a) });
+        if (!ctx.ex.framesList)
+            throw new types_1.ExecutorError('UNSUPPORTED', 'this backend cannot enumerate frames');
+        const frames = await ctx.ex.framesList({ tabId: tabId(a) });
+        return (0, envelopes_1.jsonResult)({
+            frames,
+            count: frames.length,
+            ...(frames.length > 1
+                ? { hint: 'pass frameId (or allFrames:true) on a click/type/get_text to act inside one of these' }
+                : {}),
+        });
+    },
+    console_logs: async (a, ctx) => {
+        const res = await readObservers(ctx, a, { console: true });
+        const level = (0, validators_1.optionalString)(a, 'level');
+        const entries = (res.console ?? []).filter((e) => !level || e.level === level);
+        return (0, envelopes_1.jsonResult)({
+            entries,
+            count: entries.length,
+            ...(res.dropped ? { dropped: true, dropNote: 'older entries were dropped from the in-page ring buffer' } : {}),
+            ...(res.justInstalled ? { note: res.note } : {}),
+        });
+    },
+    network_log: async (a, ctx) => {
+        const res = await readObservers(ctx, a, { network: true }, {
+            includeResources: (0, validators_1.optionalBoolean)(a, 'includeResources'),
+        });
+        const contains = (0, validators_1.optionalString)(a, 'urlContains');
+        const failedOnly = (0, validators_1.optionalBoolean)(a, 'failedOnly') === true;
+        const entries = (res.network ?? []).filter((e) => {
+            if (contains && !e.url.includes(contains))
+                return false;
+            if (failedOnly && !e.error && (e.status ?? 0) < 400)
+                return false;
+            return true;
+        });
+        return (0, envelopes_1.jsonResult)({
+            entries,
+            count: entries.length,
+            ...(res.dropped ? { dropped: true } : {}),
+            ...(res.justInstalled ? { note: res.note } : {}),
+        });
+    },
+    dialogs: async (a, ctx) => {
+        const policy = (0, validators_1.optionalString)(a, 'policy');
+        if (policy && policy !== 'dismiss' && policy !== 'accept') {
+            throw new validators_1.McpToolError('"policy" must be "dismiss" or "accept"');
+        }
+        const res = await readObservers(ctx, a, { dialogs: true }, {
+            setPolicy: policy,
+            promptText: (0, validators_1.optionalString)(a, 'promptText'),
+        });
+        return (0, envelopes_1.jsonResult)({
+            entries: res.dialogs ?? [],
+            count: (res.dialogs ?? []).length,
+            policy: res.dialogPolicy,
+            ...(res.justInstalled ? { note: res.note } : {}),
+        });
+    },
+    print_pdf: async (a, ctx) => {
+        await gate(ctx, 'print_pdf', { tabId: tabId(a) });
+        if (!ctx.ex.printPdf)
+            throw new types_1.ExecutorError('UNSUPPORTED', 'this backend cannot print to PDF');
+        const pdf = await ctx.ex.printPdf({
+            tabId: tabId(a),
+            landscape: (0, validators_1.optionalBoolean)(a, 'landscape'),
+            printBackground: (0, validators_1.optionalBoolean)(a, 'printBackground'),
+            scale: (0, validators_1.optionalNumber)(a, 'scale', { min: 0.1, max: 2 }),
+            paperWidth: (0, validators_1.optionalNumber)(a, 'paperWidth', { min: 0.1, max: 200 }),
+            paperHeight: (0, validators_1.optionalNumber)(a, 'paperHeight', { min: 0.1, max: 200 }),
+            pageRanges: (0, validators_1.optionalString)(a, 'pageRanges'),
+            preferCSSPageSize: (0, validators_1.optionalBoolean)(a, 'preferCSSPageSize'),
+        });
+        const bytes = Buffer.from(pdf.dataBase64, 'base64');
+        const path = (0, workspace_1.saveBinary)('print_pdf', 'pdf', bytes);
+        (0, audit_1.noteBytes)(bytes.byteLength);
+        // The bytes themselves are deliberately NOT returned: a PDF is megabytes of
+        // base64 that no model can read, and the file on disk is the useful artifact.
+        return (0, envelopes_1.jsonResult)({
+            path,
+            bytes: bytes.byteLength,
+            url: pdf.url,
+            title: pdf.title,
+            ...(path ? {} : { note: 'no active task workspace, so the PDF was not saved to disk' }),
+        });
+    },
     chrome_status: async (_a, ctx) => (0, envelopes_1.jsonResult)(ctx.ex.status()),
     // --- task workspace management (server-side; no browser needed) ---
-    profile_use: async (a) => (0, envelopes_1.jsonResult)(workspaceView((0, workspace_1.switchWorkspace)({ profile: (0, validators_1.requireString)(a, 'name') }))),
+    profile_use: async (a) => {
+        // Snapshots are keyed by profile+tab, and a profile switch routes to a
+        // different browser entirely — keeping the old tree would diff a page
+        // against one from another machine.
+        (0, snapdiff_1.resetSnapshots)();
+        return (0, envelopes_1.jsonResult)(workspaceView((0, workspace_1.switchWorkspace)({ profile: (0, validators_1.requireString)(a, 'name') })));
+    },
     task_new: async (a) => (0, envelopes_1.jsonResult)(workspaceView((0, workspace_1.switchWorkspace)({ task: (0, validators_1.requireString)(a, 'name') }))),
     task_status: async () => (0, envelopes_1.jsonResult)(workspaceView((0, workspace_1.getActiveWorkspace)())),
     tasks_list: async () => (0, envelopes_1.jsonResult)((0, tasks_1.listTasks)((0, workspace_1.getActiveWorkspace)().dataDir)),
@@ -482,9 +841,28 @@ function summarizeArgs(rawArgs) {
     }
     return Object.keys(out).length ? out : undefined;
 }
-/** Append one action record to the active task's history.jsonl (best-effort). */
-function recordHistory(tool, rawArgs, ok, error) {
-    (0, workspace_1.appendHistory)({ ts: new Date().toISOString(), tool, args: summarizeArgs(rawArgs), ok, ...(error ? { error } : {}) });
+/**
+ * Append one action record to the active task's history.jsonl (best-effort).
+ *
+ * The audit fields — which URL the policy was evaluated against, whether it
+ * denied, how many bytes came back, how many secrets were scrubbed — are the
+ * ones someone actually wants when reviewing what an agent did in their real
+ * browser, and they exist only inside the call.
+ */
+function recordHistory(tool, rawArgs, ok, extra = {}) {
+    const a = extra.audit ?? {};
+    (0, workspace_1.appendHistory)({
+        ts: new Date().toISOString(),
+        tool,
+        args: summarizeArgs(rawArgs),
+        ok,
+        ...(extra.ms !== undefined ? { ms: extra.ms } : {}),
+        ...(a.url ? { url: a.url } : {}),
+        ...(a.denied ? { policy: 'denied' } : a.url ? { policy: 'allowed' } : {}),
+        ...(a.bytes !== undefined ? { bytes: a.bytes } : {}),
+        ...(a.redactions ? { redactions: a.redactions } : {}),
+        ...(extra.error ? { error: extra.error } : {}),
+    });
 }
 /**
  * Tools it is safe to re-issue after the extension drops mid-flight.
@@ -502,6 +880,7 @@ const RETRY_SAFE_TOOLS = new Set([
     'get_text', 'get_html', 'snapshot', 'get_cookies',
     'extract_links', 'read_as_markdown', 'screenshot',
     'wait_for', 'navigate', 'reload',
+    'frames_list', 'print_pdf',
 ]);
 /** Whether `err` is the transient bridge fault that a single retry can clear. */
 function isRetryableFault(name, err) {
@@ -513,6 +892,13 @@ async function dispatchToolCall(name, rawArgs) {
         return (0, envelopes_1.errorResult)(`unknown tool: ${name}`);
     if (!allowCall(Date.now()))
         return (0, envelopes_1.errorResult)('rate limit exceeded; slow down');
+    const started = Date.now();
+    // One audit record per call, carried through async hops so a parallel `batch`
+    // cannot cross-attribute one op's target URL to another's log line.
+    const { result: outcome } = await (0, audit_1.withAudit)(async (audit) => dispatchInner(name, handler, rawArgs, audit, started));
+    return outcome;
+}
+async function dispatchInner(name, handler, rawArgs, audit, started) {
     try {
         const mgr = (0, manager_1.getManager)();
         // Workspace-management tools run server-side and must work even with no
@@ -533,12 +919,12 @@ async function dispatchToolCall(name, rawArgs) {
             result = await handler((0, validators_1.asArgs)(rawArgs), { ex: reconnected, policy: mgr.policy });
             (0, log_1.logDebug)(`${name}: retry after reconnect succeeded`);
         }
-        recordHistory(name, rawArgs, !result.isError);
+        recordHistory(name, rawArgs, !result.isError, { ms: Date.now() - started, audit });
         return result;
     }
     catch (err) {
         const message = errMessage(err);
-        recordHistory(name, rawArgs, false, message);
+        recordHistory(name, rawArgs, false, { error: message, ms: Date.now() - started, audit });
         return (0, envelopes_1.errorResult)(message);
     }
 }