@mehmoodqureshi/chrome-mcp 0.9.1 → 0.9.3

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/stub-executor.d.ts

@@ -54,6 +54,15 @@ export interface StubOptions {
     snapshotNodes?: SnapshotNode[];
     /** Frames the stub reports for `frames_list`. */
     frames?: FrameInfo[];
+    /** Applied after any action or history move: models a click/submit/back that
+     *  lands the tab on a different page (e.g. a redirect to a sign-in wall). */
+    afterAction?: {
+        url?: string;
+        nodes?: SnapshotNode[];
+    };
+    /** When true, `waitFor` rejects with TIMEOUT - the error a wait on a page
+     *  that silently became a login form used to surface. */
+    waitForTimesOut?: boolean;
     /** What the in-page observers return. Absent = the hook is not installed,
      *  which is the case the tools must report clearly rather than as an empty list. */
     observers?: ObserverReadResult;
@@ -76,6 +85,10 @@ export declare class StubExecutor implements Executor {
     snapshotNodes: SnapshotNode[];
     private readonly frames;
     private readonly observerState?;
+    private readonly afterAction?;
+    private readonly waitForTimesOut;
+    /** How many snapshots were taken - the auth guard must cost none when off. */
+    snapshotCalls: number;
     /** The last observer args received, so a test can assert what was requested. */
     lastObserverArgs?: ObserverArgs;
     /** How many times the gate actually asked for the tab list — the round-trip
@@ -110,6 +123,8 @@ export declare class StubExecutor implements Executor {
     back(): Promise<NavResult>;
     forward(): Promise<NavResult>;
     reload(): Promise<NavResult>;
+    /** Move the stub tab to the configured post-action page, if any. */
+    private landed;
     click(): Promise<ActionOk>;
     type(): Promise<ActionOk>;
     fill(): Promise<ActionOk>;

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

@@ -32,6 +32,10 @@ class StubExecutor {
     snapshotNodes;
     frames;
     observerState;
+    afterAction;
+    waitForTimesOut;
+    /** How many snapshots were taken - the auth guard must cost none when off. */
+    snapshotCalls = 0;
     /** The last observer args received, so a test can assert what was requested. */
     lastObserverArgs;
     /** How many times the gate actually asked for the tab list — the round-trip
@@ -40,6 +44,8 @@ class StubExecutor {
     ready = false;
     constructor(opts = {}) {
         this.url = opts.activeUrl ?? 'about:blank';
+        this.afterAction = opts.afterAction;
+        this.waitForTimesOut = opts.waitForTimesOut ?? false;
         this.evalThrows = opts.evalThrows ?? false;
         this.tabsListThrows = opts.tabsListThrows ?? false;
         this.noTabs = opts.noTabs ?? false;
@@ -133,15 +139,28 @@ class StubExecutor {
         return { url: args.url, title: 'Stub Page', httpStatus: 200 };
     }
     async back() {
+        this.landed();
         return { url: this.url, title: 'Stub Page' };
     }
     async forward() {
+        this.landed();
         return { url: this.url, title: 'Stub Page' };
     }
     async reload() {
+        this.landed();
         return { url: this.url, title: 'Stub Page' };
     }
+    /** Move the stub tab to the configured post-action page, if any. */
+    landed() {
+        if (!this.afterAction)
+            return;
+        if (this.afterAction.url !== undefined)
+            this.url = this.afterAction.url;
+        if (this.afterAction.nodes !== undefined)
+            this.snapshotNodes = this.afterAction.nodes;
+    }
     async click() {
+        this.landed();
         return ok;
     }
     async type() {
@@ -149,18 +168,22 @@ class StubExecutor {
             this.remainingWriteDisconnects--;
             throw new types_1.ExecutorError('EXTENSION_DISCONNECTED', 'stub: service worker recycled mid-command');
         }
+        this.landed();
         return ok;
     }
     async fill() {
+        this.landed();
         return ok;
     }
     async press() {
+        this.landed();
         return ok;
     }
     async hover() {
         return ok;
     }
     async selectOption() {
+        this.landed();
         return ok;
     }
     async scroll() {
@@ -175,6 +198,7 @@ class StubExecutor {
         return { html: this.htmlPayload };
     }
     async snapshot() {
+        this.snapshotCalls++;
         return { url: this.url, title: 'Stub Page', nodes: this.snapshotNodes, truncated: false };
     }
     async getCookies() {
@@ -195,6 +219,8 @@ class StubExecutor {
         return { ok: true, value: 'stub-value', type: 'string' };
     }
     async waitFor() {
+        if (this.waitForTimesOut)
+            throw new types_1.ExecutorError('TIMEOUT', 'stub: wait_for timed out');
         return { matched: true, waitedMs: 0 };
     }
     async download(args) {

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;
@@ -349,7 +372,9 @@ export interface Executor {
  * (which only carries codes that originate inside the extension); these extra
  * codes describe failures on the server half (no backend, launch failed, etc.).
  */
-export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'UPLOAD_FAILED' | 'FRAME_NOT_FOUND' | 'OBSERVERS_DISABLED' | 'UNSUPPORTED' | 'BACKPRESSURE';
+export type ExecutorErrorCodeLocal = 'NO_BACKEND' | 'EXTENSION_DISCONNECTED' | 'TIMEOUT' | 'TAB_NOT_FOUND' | 'STALE_TAB' | 'SELECTOR_NOT_FOUND' | 'REF_EXPIRED' | 'EVAL_FAILED' | 'LAUNCH_FAILED' | 'DETACHED' | 'TARGET_GONE' | 'POLICY_DENIED' | 'DEVTOOLS_OPEN' | 'DOWNLOAD_FAILED' | 'UPLOAD_FAILED' | 'FRAME_NOT_FOUND' | 'OBSERVERS_DISABLED' | 'UNSUPPORTED' | 'BACKPRESSURE'
+/** The page is a sign-in wall (session expired mid-run). Raised only when the caller opts in via `failOnAuthWall`. */
+ | 'AUTH_REQUIRED';
 export declare class ExecutorError extends Error {
     readonly code: ExecutorErrorCodeLocal;
     constructor(code: ExecutorErrorCodeLocal, message: string);

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(', ')}. `