@mehmoodqureshi/chrome-mcp 0.6.6 → 0.7.0

package/README.md

@@ -201,6 +201,99 @@ silently mis-routed. (`tab_new`, `tabs_list`, `chrome_status` are exempt.)
 > `navigate`, to open without losing the current tab). Pass `active: false` to
 > open in the background; parallel batches do this automatically.
 
+### Reaching into iframes and shadow roots
+
+A selector that "should" match but doesn't almost always means the element is
+somewhere your selector cannot reach: inside an `<iframe>` (checkout widgets,
+OAuth consent screens, embedded editors) or inside a web component's shadow root.
+
+Shadow roots are handled for you — every selector and every `ref` now resolves
+through open shadow roots, so anything `snapshot` shows you is something you can
+click. (It used to show you elements no click could reach: the snapshot walked
+shadow roots, the actions did not.)
+
+Frames are opt-in, because reaching into one is a decision:
+
+```jsonc
+frames_list {}                                  // what frames exist, and their URLs
+click { "selector": "#pay", "allFrames": true } // find it in whichever frame has it
+get_text { "frameId": 7 }                       // pin one frame
+```
+
+Every frame is authorized against **its own** URL before anything runs in it, so
+an allowlisted page embedding a third-party iframe does not become a way to read
+that third party. Frames whose origin isn't on your allowlist are skipped.
+
+### Seeing why a page broke — `console_logs`, `network_log`, `dialogs`
+
+Reading the DOM tells you what a page looks like after it failed, not why. With
+`--enable-observers`, an in-page hook records console output, uncaught errors,
+and `fetch`/`XMLHttpRequest` traffic, and intercepts native dialogs:
+
+```jsonc
+console_logs { "level": "error" }        // the exception the page swallowed
+network_log  { "failedOnly": true }      // the 500 behind the blank screen
+dialogs      { "policy": "accept" }      // answer confirm() with true from here on
+```
+
+It is **off by default and deliberately so**: the hook patches `console`,
+`fetch`, `XMLHttpRequest` and the dialog functions on every allowlisted page in
+your real browser. When it's on, it is registered only for the domains on your
+allowlist, at document_start (so it catches load-time failures), and nothing it
+records leaves the page until a tool call reads it — through the same gate as any
+other page read.
+
+Dialog interception is also a fix, not just an observation: `alert`/`confirm`/
+`beforeunload` block the renderer, so a click that opened one used to hang every
+injected script until the command timed out and reported `TIMEOUT` with nothing
+to point at. With observers on, the dialog is answered (`dismiss` by default:
+confirm → false, prompt → null) and recorded.
+
+> **What `network_log` sees:** the requests page code makes — `fetch` and
+> `XMLHttpRequest`, with method, URL, status and duration — plus Resource Timing
+> entries (scripts, images, styles) when you ask for them. Not the document
+> request, redirects, or headers. That is the cost of not holding a debugger
+> session open on your browser.
+
+### Only what changed — `snapshot { diff: true }`
+
+A snapshot is the most expensive read in the tool surface, and the loop that uses
+it most (snapshot → click → snapshot) re-sends a page that is mostly identical
+every time. Ask for the delta instead:
+
+```jsonc
+snapshot { "diff": true }                       // added / removed / changed only
+click { "selector": "#save", "snapshotAfter": true }   // what the click changed
+```
+
+Nodes are matched across snapshots by role + accessible name, not by `ref` —
+refs renumber in document order on every snapshot, so diffing on them would
+report an unchanged button as removed-and-re-added the moment anything above it
+appears.
+
+### Targeting by role and name
+
+Actions accept a locator instead of a CSS selector, so you don't need a snapshot
+first just to learn a ref:
+
+```jsonc
+click { "role": "button", "name": "Sign in" }
+type  { "role": "textbox", "name": "Email", "text": "a@b.com" }
+```
+
+Resolution is server-side and refuses to guess: an ambiguous locator fails with
+the candidates listed rather than acting on the first one (pass `nth` to pick).
+
+### Printing — `print_pdf`
+
+```jsonc
+print_pdf { "landscape": true }
+```
+
+Renders through Chrome's own print pipeline and saves to the task's `results/`
+dir, returning the path and size. The bytes themselves are never returned — a
+PDF is megabytes of base64 no model can read.
+
 ## Status
 
 v0.5.0 — **safe multi-tab concurrency.** Adds the `batch` fan-out tool, makes
@@ -261,8 +354,31 @@ status badge, and a stable pairing token (`--persist-token`).
 chrome-mcp --allow-domain example.com --enable-mutations
 chrome-mcp --policy ./policy.json          # see policy.example.json
 chrome-mcp --unsafe-all-domains            # loud footgun
+chrome-mcp --enable-observers              # console/network/dialog capture (patches page globals)
+chrome-mcp --redact                        # scrub secret-shaped strings out of page reads
 ```
 
+**What comes back is gated too.** The allowlist decides which pages may be read;
+it says nothing about what is on them. A logged-in page routinely renders a
+session token into a script tag or an API key onto a settings screen.
+
+- **Password field values are always suppressed** — in `get_html`, and in
+  `snapshot`, where the field still appears (so you can type into it) flagged
+  `secret: true` with no value. No flag, no opt-in: nobody wants those characters.
+- `--redact` additionally scrubs secret-shaped strings — JWTs, AWS/GitHub/Slack/
+  Google keys, `Bearer` headers, private-key blocks — out of `get_text`,
+  `get_html`, `read_as_markdown` and `eval`. It is opt-in because a pattern will
+  eventually fire on something you actually wanted. `--redact-pattern <regex>`
+  adds your own (and implies `--redact`); an invalid one fails at startup rather
+  than silently never matching.
+- Redaction runs **before** the output cap, so a truncated read cannot leak what
+  a full one would have hidden.
+
+Every call is recorded to the task's `history.jsonl` with the URL it touched, the
+policy verdict (`allowed`/`denied`), how long it took, how many bytes came back,
+and how many secrets were scrubbed — so "what did the agent do in my browser" has
+an answer after the fact.
+
 The per-boot 256-bit token in `~/.chrome-mcp/handshake.json` (mode 0600) is the
 only trust boundary; it is never written to stdout/stderr. On POSIX the mode is
 re-verified after every write and the server **fails closed** if the file ends up

package/dist/shared/observers.d.ts

@@ -0,0 +1,110 @@
+/**
+ * shared/observers.ts — the record shapes produced by the in-page observer hook
+ * (`extension/src/page/hook.ts`) and consumed by the `console_logs`,
+ * `network_log` and `dialogs` tools.
+ *
+ * Why an in-page hook rather than the CDP `Log`/`Console`/`Network` domains: the
+ * executor attaches `chrome.debugger` for the duration of ONE op and detaches in
+ * `finally` (that is what keeps the "being debugged" banner off the user's
+ * browser and keeps other CDP clients working). Observing console and network
+ * needs a session that spans commands, which that model cannot provide. A
+ * MAIN-world hook installed at document_start costs no attach, survives the
+ * service worker being recycled (the buffers live in the page), and captures
+ * exactly what page code did — which is what an agent debugging a page is
+ * asking about.
+ *
+ * The trade-off, stated plainly: `network_log` sees `fetch` and
+ * `XMLHttpRequest` — the calls page code makes — plus whatever the Resource
+ * Timing API reports for everything else. It does not see the document request,
+ * redirects, or request/response headers.
+ */
+import type { WirePolicy } from './protocol';
+/** Bumped when the hook's on-page state shape changes. */
+export declare const OBSERVER_HOOK_VERSION: 1;
+/** The MAIN-world global the hook installs its state on. */
+export declare const OBSERVER_GLOBAL: "__chromeMcpObservers";
+/** Ring-buffer ceilings, enforced in-page so a chatty site cannot grow unbounded. */
+export declare const MAX_CONSOLE_ENTRIES = 500;
+export declare const MAX_NETWORK_ENTRIES = 300;
+export declare const MAX_DIALOG_ENTRIES = 50;
+export type ConsoleLevel = 'log' | 'info' | 'warn' | 'error' | 'debug' | 'exception';
+export interface ConsoleEntry {
+    /** Monotonic per-page sequence, so a caller can poll for "what is new". */
+    seq: number;
+    ts: number;
+    level: ConsoleLevel;
+    text: string;
+    /** Present for `exception`: the error's stack, trimmed. */
+    stack?: string;
+    url?: string;
+}
+export interface NetworkEntry {
+    seq: number;
+    ts: number;
+    /** 'fetch' | 'xhr' | 'resource' (the Resource Timing fallback). */
+    via: 'fetch' | 'xhr' | 'resource';
+    method: string;
+    url: string;
+    status?: number;
+    ok?: boolean;
+    durationMs?: number;
+    /** Set when the request rejected (network error, CORS, abort). */
+    error?: string;
+    /** Resource Timing only: the initiator type Chrome reports (script, img, css…). */
+    initiator?: string;
+    bytes?: number;
+}
+export type DialogKind = 'alert' | 'confirm' | 'prompt' | 'beforeunload';
+export interface DialogEntry {
+    seq: number;
+    ts: number;
+    kind: DialogKind;
+    message: string;
+    /** What the hook answered on the page's behalf. */
+    answered: string;
+}
+/**
+ * How the hook answers a native dialog. `dismiss` is the default: it is what a
+ * blocked renderer would eventually be told anyway, and it never confirms a
+ * destructive action the agent did not ask for. `accept` is opt-in per tab.
+ */
+export type DialogPolicy = 'dismiss' | 'accept';
+export interface ObserverReadResult {
+    /** Absent hook (observers disabled, or the page loaded before it registered). */
+    installed: boolean;
+    hookVersion?: number;
+    console?: ConsoleEntry[];
+    network?: NetworkEntry[];
+    dialogs?: DialogEntry[];
+    dialogPolicy?: DialogPolicy;
+    /** True when the ring buffer dropped older entries before this read. */
+    dropped?: boolean;
+}
+/**
+ * Runs IN THE PAGE (MAIN world), serialized to source — so it must be
+ * self-contained and takes the global's name rather than importing the constant.
+ *
+ * Draining is explicit: `clear` empties the buffers it returned, and `sinceSeq`
+ * lets a caller poll for only what is new. Nothing here reaches out; it reads
+ * what the hook already recorded on this page.
+ */
+export declare function readObservers(globalName: string, opts: {
+    console?: boolean;
+    network?: boolean;
+    dialogs?: boolean;
+    sinceSeq?: number;
+    limit?: number;
+    clear?: boolean;
+    setPolicy?: string | null;
+    promptText?: string | null;
+    includeResources?: boolean;
+}): unknown;
+/**
+ * Translate the domain allowlist into Chrome match patterns for registering the
+ * hook as a content script. A bare host becomes `*://host/*`; `*.host` becomes
+ * `*://*.host/*` (which Chrome reads as the host AND its subdomains, matching
+ * how the allowlist itself behaves); `*` becomes `<all_urls>`. Entries carrying
+ * no host are dropped rather than widened — the page the tool may not read is
+ * also the page it must not instrument.
+ */
+export declare function observerMatches(policy: WirePolicy): string[];

package/dist/shared/observers.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * shared/observers.ts — the record shapes produced by the in-page observer hook
+ * (`extension/src/page/hook.ts`) and consumed by the `console_logs`,
+ * `network_log` and `dialogs` tools.
+ *
+ * Why an in-page hook rather than the CDP `Log`/`Console`/`Network` domains: the
+ * executor attaches `chrome.debugger` for the duration of ONE op and detaches in
+ * `finally` (that is what keeps the "being debugged" banner off the user's
+ * browser and keeps other CDP clients working). Observing console and network
+ * needs a session that spans commands, which that model cannot provide. A
+ * MAIN-world hook installed at document_start costs no attach, survives the
+ * service worker being recycled (the buffers live in the page), and captures
+ * exactly what page code did — which is what an agent debugging a page is
+ * asking about.
+ *
+ * The trade-off, stated plainly: `network_log` sees `fetch` and
+ * `XMLHttpRequest` — the calls page code makes — plus whatever the Resource
+ * Timing API reports for everything else. It does not see the document request,
+ * redirects, or request/response headers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DIALOG_ENTRIES = exports.MAX_NETWORK_ENTRIES = exports.MAX_CONSOLE_ENTRIES = exports.OBSERVER_GLOBAL = exports.OBSERVER_HOOK_VERSION = void 0;
+exports.readObservers = readObservers;
+exports.observerMatches = observerMatches;
+const policy_1 = require("./policy");
+/** Bumped when the hook's on-page state shape changes. */
+exports.OBSERVER_HOOK_VERSION = 1;
+/** The MAIN-world global the hook installs its state on. */
+exports.OBSERVER_GLOBAL = '__chromeMcpObservers';
+/** Ring-buffer ceilings, enforced in-page so a chatty site cannot grow unbounded. */
+exports.MAX_CONSOLE_ENTRIES = 500;
+exports.MAX_NETWORK_ENTRIES = 300;
+exports.MAX_DIALOG_ENTRIES = 50;
+/**
+ * Runs IN THE PAGE (MAIN world), serialized to source — so it must be
+ * self-contained and takes the global's name rather than importing the constant.
+ *
+ * Draining is explicit: `clear` empties the buffers it returned, and `sinceSeq`
+ * lets a caller poll for only what is new. Nothing here reaches out; it reads
+ * what the hook already recorded on this page.
+ */
+function readObservers(globalName, opts) {
+    const state = window[globalName];
+    if (!state)
+        return { installed: false };
+    if (opts.setPolicy === 'dismiss' || opts.setPolicy === 'accept')
+        state.dialogPolicy = opts.setPolicy;
+    if (typeof opts.promptText === 'string')
+        state.promptText = opts.promptText;
+    const since = typeof opts.sinceSeq === 'number' ? opts.sinceSeq : 0;
+    const limit = typeof opts.limit === 'number' && opts.limit > 0 ? opts.limit : 200;
+    const take = (buf) => {
+        const picked = buf.filter((e) => e.seq > since);
+        return picked.length > limit ? picked.slice(picked.length - limit) : picked;
+    };
+    // Resource Timing covers what the fetch/XHR patches structurally cannot see
+    // (documents, scripts, images, styles). It carries no status code, so those
+    // entries report timing and size only — stated, not implied.
+    if (opts.network && opts.includeResources) {
+        try {
+            const entries = performance.getEntriesByType('resource');
+            for (let i = state.resourceCursor; i < entries.length; i++) {
+                const r = entries[i];
+                state.network.push({
+                    seq: ++state.seq,
+                    ts: Math.round(performance.timeOrigin + r.startTime),
+                    via: 'resource',
+                    method: 'GET',
+                    url: r.name.length > 2000 ? `${r.name.slice(0, 2000)}…` : r.name,
+                    durationMs: Math.round(r.duration),
+                    initiator: r.initiatorType,
+                    bytes: r.transferSize || undefined,
+                });
+            }
+            state.resourceCursor = entries.length;
+        }
+        catch {
+            /* Resource Timing unavailable — the fetch/XHR records still stand */
+        }
+    }
+    const out = {
+        installed: true,
+        hookVersion: state.v,
+        dialogPolicy: state.dialogPolicy,
+        dropped: state.dropped,
+    };
+    if (opts.console)
+        out.console = take(state.console);
+    if (opts.network)
+        out.network = take(state.network);
+    if (opts.dialogs)
+        out.dialogs = take(state.dialogs);
+    if (opts.clear) {
+        if (opts.console)
+            state.console.length = 0;
+        if (opts.network)
+            state.network.length = 0;
+        if (opts.dialogs)
+            state.dialogs.length = 0;
+        state.dropped = false;
+    }
+    return out;
+}
+/**
+ * Translate the domain allowlist into Chrome match patterns for registering the
+ * hook as a content script. A bare host becomes `*://host/*`; `*.host` becomes
+ * `*://*.host/*` (which Chrome reads as the host AND its subdomains, matching
+ * how the allowlist itself behaves); `*` becomes `<all_urls>`. Entries carrying
+ * no host are dropped rather than widened — the page the tool may not read is
+ * also the page it must not instrument.
+ */
+function observerMatches(policy) {
+    if (policy.allowObservers !== true)
+        return [];
+    const out = new Set();
+    for (const raw of policy.allowDomains ?? []) {
+        const p = (0, policy_1.normalizeDomainPattern)(raw);
+        if (!p)
+            continue;
+        if (p === '*')
+            return ['<all_urls>'];
+        out.add(`*://${p}/*`);
+    }
+    return [...out];
+}
+//# sourceMappingURL=observers.js.map

package/dist/shared/page-fns.d.ts

@@ -0,0 +1,46 @@
+/**
+ * shared/page-fns.ts — the ONE function that runs inside a page for every
+ * DOM-touching command.
+ *
+ * MUST be self-contained: `chrome.scripting.executeScript` serializes it to
+ * source, so it may not close over anything from this module. That constraint is
+ * exactly why every op lives in one function instead of ten — the shared
+ * helpers below (`deepQuery` above all) can then be written once and are
+ * automatically used by every op.
+ *
+ * `deepQuery` is the reason this file exists. `snapshot` deliberately walks open
+ * shadow roots and stamps `data-mcp-ref` on what it finds there, but every
+ * action used to resolve that ref with a plain `document.querySelector`, which
+ * cannot cross a shadow boundary. So the snapshot advertised elements that no
+ * click could ever reach — a structural dead end on every web-component site.
+ * One resolver, used by every op, is what closes it.
+ */
+/** Ops the page-side dispatcher understands. */
+export type PageOpName = 'probe' | 'text' | 'html' | 'click' | 'type' | 'focus' | 'point' | 'hover' | 'select' | 'measure' | 'scroll' | 'storage' | 'waitSelector' | 'waitFor';
+export interface PageOpArgs {
+    op: PageOpName;
+    selector?: string | null;
+    text?: string;
+    clear?: boolean;
+    outer?: boolean;
+    values?: string[];
+    x?: number | null;
+    y?: number | null;
+    deltaX?: number | null;
+    deltaY?: number | null;
+    storageOp?: string;
+    key?: string | null;
+    value?: string | null;
+    session?: boolean;
+    textContains?: string | null;
+    gone?: boolean;
+    timeoutMs?: number;
+    interval?: number;
+}
+/**
+ * Runs IN THE PAGE (or in one frame of it). Returns a plain JSON-able object;
+ * `found: false` means the selector matched nothing, which the caller renders as
+ * SELECTOR_NOT_FOUND. Never throws across the boundary — a page that blows up
+ * inside an op is reported as `{ ok: false, error }`.
+ */
+export declare function pageOp(a: PageOpArgs): unknown;