@mehmoodqureshi/chrome-mcp 0.9.1 → 0.9.3

package/dist/src/mcp/tools.js

@@ -29,6 +29,7 @@ const helpers_1 = require("./helpers");
 const redact_1 = require("./redact");
 const locate_1 = require("./locate");
 const snapdiff_1 = require("./snapdiff");
+const auth_wall_1 = require("../../shared/auth-wall");
 const audit_1 = require("./audit");
 const log_1 = require("./log");
 const tasks_1 = require("../bridge/tasks");
@@ -40,6 +41,7 @@ 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();
+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
@@ -79,27 +81,27 @@ exports.TOOL_DEFINITIONS = [
     { name: 'tab_select', description: 'Make a tab active by tabId.', inputSchema: { tabId: zod_1.z.string() } },
     { name: 'tab_new', description: 'Open a NEW tab (optionally at a URL) and focus it. Prefer this over `navigate` when the user says "open"/"go to" a site — `navigate` REPLACES the current tab. Pass active:false to open in the background (used by parallel batches).', inputSchema: { url: zod_1.z.string().optional(), active: zod_1.z.boolean().optional() } },
     { name: 'tab_close', description: 'Close a tab by tabId.', inputSchema: { tabId: zod_1.z.string() } },
-    { name: 'navigate', description: 'Navigate a tab to a URL, REPLACING its current page. Acts on the active tab unless tabId is given — to open a site without losing the current page, use `tab_new` instead.', inputSchema: { url: zod_1.z.string(), tabId: tabIdField, waitUntil: waitUntilField } },
-    { 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, 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: 'navigate', description: 'Navigate a tab to a URL, REPLACING its current page. Acts on the active tab unless tabId is given — to open a site without losing the current page, use `tab_new` instead.', inputSchema: { url: zod_1.z.string(), tabId: tabIdField, waitUntil: waitUntilField, failOnAuthWall: authWallField } },
+    { 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: '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: '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(), ...FRAME_PROPS, tabId: tabIdField } },
+    { 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 } },
     { 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(), ...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: '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, failOnAuthWall: authWallField } },
     { 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: '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, failOnAuthWall: authWallField } },
     { 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 } },
     {
@@ -161,6 +163,7 @@ exports.TOOL_DEFINITIONS = [
         },
     },
     { name: 'chrome_status', description: 'Report backend/session status.', inputSchema: {} },
+    { name: 'auth_check', description: 'Is the tab sitting on a sign-in wall? Reads the page (URL, title, password fields, sign-in controls) and returns { authRequired, confidence, signals }. Use it after a navigate, or whenever a step fails unexpectedly, to tell "the session expired" apart from "the agent got lost". Pass failOnAuthWall:true to get an [AUTH_REQUIRED] error instead of a verdict, so a harness can bucket the run as an auth failure.', inputSchema: { failOnAuthWall: authWallField, ...FRAME_PROPS, tabId: tabIdField } },
     { 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).') } },
     { name: 'tasks_list', description: 'List every task across all profiles under the data dir, with sizes and download counts.', inputSchema: {} },
@@ -198,15 +201,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();
@@ -317,6 +320,51 @@ function redaction(policy) {
     return cfg;
 }
 /** The scope a tab's remembered snapshot lives under. */
+/**
+ * Throw `[AUTH_REQUIRED]` when the caller asked for it and the page is a
+ * high-confidence sign-in wall. Medium-confidence verdicts never fail a call: a
+ * lone password field on an otherwise ordinary page is not worth aborting over.
+ */
+function failIfAuthWall(wall, url, a, policy) {
+    if (!wall || wall.confidence !== 'high')
+        return;
+    if (!authGuardOn(a, policy))
+        return;
+    throw new types_1.ExecutorError('AUTH_REQUIRED', (0, auth_wall_1.describeAuthWall)(wall, url));
+}
+/** The guard is on for this call when the caller asked, or the server runs with `--fail-on-auth-wall`. */
+function authGuardOn(a, policy) {
+    return (0, validators_1.optionalBoolean)(a, 'failOnAuthWall') === true || policy.failOnAuthWall === true;
+}
+/**
+ * After an action or history move: when the guard is on, look at the page the
+ * tab landed on and fail with `AUTH_REQUIRED` if it is a sign-in wall. Costs
+ * one snapshot round-trip, and only when the guard is on. The snapshot is
+ * remembered for this tab so a later `snapshot { diff: true }` stays coherent.
+ */
+async function guardAuthWall(ctx, a) {
+    if (!authGuardOn(a, ctx.policy))
+        return;
+    const snap = await ctx.ex.snapshot({ tabId: tabId(a), interactiveOnly: true, max: 200 });
+    (0, snapdiff_1.rememberSnapshot)(snapScope(a), snap);
+    failIfAuthWall((0, auth_wall_1.detectAuthWall)(snap), snap.url, a, ctx.policy);
+}
+/**
+ * A wait that timed out on a page that has become a sign-in wall is an auth
+ * failure, not a slow page. With the guard on, reclassify it.
+ */
+async function reclassifyTimeout(ctx, a, err) {
+    if (err instanceof types_1.ExecutorError && err.code === 'TIMEOUT' && authGuardOn(a, ctx.policy)) {
+        await guardAuthWall(ctx, a);
+    }
+    throw err;
+}
+/** The `authWall` field to spread onto a page-read result: present only when detected. */
+function authWallOf(ctx, snap, a) {
+    const wall = (0, auth_wall_1.detectAuthWall)(snap);
+    failIfAuthWall(wall, snap.url, a, ctx.policy);
+    return wall ? { authWall: wall } : {};
+}
 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
@@ -324,13 +372,20 @@ const snapScope = (a) => (0, snapdiff_1.scopeOf)((0, workspace_1.peekActiveWorks
  * 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)
+    const wantDiff = (0, validators_1.optionalBoolean)(a, 'snapshotAfter') === true;
+    const guard = authGuardOn(a, ctx.policy);
+    if (!wantDiff && !guard)
         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);
+    // One snapshot serves both: the auth guard reads it first (and aborts the
+    // call if the action landed on a sign-in wall), then the diff is built.
+    failIfAuthWall((0, auth_wall_1.detectAuthWall)(snap), snap.url, a, ctx.policy);
     const stored = (0, snapdiff_1.rememberSnapshot)(scope, snap);
+    if (!wantDiff)
+        return (0, envelopes_1.jsonResult)(payload);
+    const diff = (0, snapdiff_1.diffSnapshots)(previous, snap);
     return (0, envelopes_1.jsonResult)({ ...payload, changed: { ...diff, snapshotId: stored.id, url: snap.url } });
 }
 /**
@@ -403,19 +458,31 @@ exports.TOOL_HANDLERS = {
     navigate: async (a, ctx) => {
         const url = (0, validators_1.requireString)(a, 'url');
         await gate(ctx, 'navigate', { url });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.navigate({ url, tabId: tabId(a), waitUntil: waitUntil(a) }));
+        const nav = await ctx.ex.navigate({ url, tabId: tabId(a), waitUntil: waitUntil(a) });
+        if (!authGuardOn(a, ctx.policy))
+            return (0, envelopes_1.jsonResult)(nav);
+        // Guard on: the check costs one snapshot round-trip after the navigation.
+        const snap = await ctx.ex.snapshot({ tabId: tabId(a), interactiveOnly: true, max: 200 });
+        (0, snapdiff_1.rememberSnapshot)(snapScope(a), snap);
+        return (0, envelopes_1.jsonResult)({ ...nav, ...authWallOf(ctx, snap, a) });
     },
     back: async (a, ctx) => {
         await gate(ctx, 'back', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.back(tabId(a)));
+        const res = await ctx.ex.back(tabId(a));
+        await guardAuthWall(ctx, a);
+        return (0, envelopes_1.jsonResult)(res);
     },
     forward: async (a, ctx) => {
         await gate(ctx, 'forward', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.forward(tabId(a)));
+        const res = await ctx.ex.forward(tabId(a));
+        await guardAuthWall(ctx, a);
+        return (0, envelopes_1.jsonResult)(res);
     },
     reload: async (a, ctx) => {
         await gate(ctx, 'reload', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) }));
+        const res = await ctx.ex.reload({ tabId: tabId(a), waitUntil: waitUntil(a) });
+        await guardAuthWall(ctx, a);
+        return (0, envelopes_1.jsonResult)(res);
     },
     click: async (a, ctx) => {
         await gate(ctx, 'click', { tabId: tabId(a) });
@@ -453,10 +520,12 @@ exports.TOOL_HANDLERS = {
     },
     press: async (a, ctx) => {
         await gate(ctx, 'press', { tabId: tabId(a) });
-        return (0, envelopes_1.jsonResult)(await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
+        const res = await ctx.ex.press((0, validators_1.requireString)(a, 'key'), {
             tabId: tabId(a),
             modifiers: (0, validators_1.optionalStringArray)(a, 'modifiers'),
-        }));
+        });
+        await guardAuthWall(ctx, a); // Enter on a form is the classic way to land on a wall
+        return (0, envelopes_1.jsonResult)(res);
     },
     hover: async (a, ctx) => {
         await gate(ctx, 'hover', { tabId: tabId(a) });
@@ -478,13 +547,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);
     },
@@ -536,14 +612,16 @@ exports.TOOL_HANDLERS = {
         const scope = snapScope(a);
         const previous = (0, snapdiff_1.lastSnapshot)(scope);
         const stored = (0, snapdiff_1.rememberSnapshot)(scope, snap);
+        const authWall = authWallOf(ctx, snap, a);
         if ((0, validators_1.optionalBoolean)(a, 'diff') !== true) {
-            return (0, envelopes_1.jsonResult)({ ...snap, snapshotId: stored.id });
+            return (0, envelopes_1.jsonResult)({ ...snap, snapshotId: stored.id, ...authWall });
         }
         const diff = (0, snapdiff_1.diffSnapshots)(previous, snap);
         return (0, envelopes_1.jsonResult)({
             url: snap.url,
             title: snap.title,
             snapshotId: stored.id,
+            ...authWall,
             ...diff,
             ...(diff.since === null
                 ? { note: 'no previous snapshot for this tab, so everything is reported as added' }
@@ -593,14 +671,19 @@ exports.TOOL_HANDLERS = {
     },
     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'),
-            timeoutMs: (0, validators_1.optionalNumber)(a, 'timeoutMs', { min: 0, max: 120_000 }),
-        }));
+        try {
+            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'),
+                timeoutMs: (0, validators_1.optionalNumber)(a, 'timeoutMs', { min: 0, max: 120_000 }),
+            }));
+        }
+        catch (err) {
+            return reclassifyTimeout(ctx, a, err);
+        }
     },
     extract_links: async (a, ctx) => {
         await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page content
@@ -643,12 +726,14 @@ exports.TOOL_HANDLERS = {
             if (typeof val === 'string')
                 (0, validators_1.requireWithinLength)(val, `fields["${sel}"]`, validators_1.MAX_TEXT_LEN);
         }
-        return (0, envelopes_1.jsonResult)(await (0, helpers_1.fillForm)(ctx.ex, {
+        const res = await (0, helpers_1.fillForm)(ctx.ex, {
             ...frameOpts(a),
             fields: fields,
             submitSelector: (0, validators_1.optionalString)(a, 'submitSelector'),
             tabId: tabId(a),
-        }));
+        });
+        await guardAuthWall(ctx, a);
+        return (0, envelopes_1.jsonResult)(res);
     },
     download_file: async (a, ctx) => {
         await gate(ctx, 'download_file');
@@ -768,6 +853,18 @@ exports.TOOL_HANDLERS = {
         });
     },
     chrome_status: async (_a, ctx) => (0, envelopes_1.jsonResult)(ctx.ex.status()),
+    auth_check: async (a, ctx) => {
+        await gate(ctx, 'get_text', { tabId: tabId(a) }); // read of page structure
+        const snap = await ctx.ex.snapshot({ tabId: tabId(a), ...frameOpts(a), interactiveOnly: true, max: 200 });
+        const wall = (0, auth_wall_1.detectAuthWall)(snap);
+        failIfAuthWall(wall, snap.url, a, ctx.policy);
+        return (0, envelopes_1.jsonResult)({
+            url: snap.url,
+            title: snap.title,
+            authRequired: wall !== null,
+            ...(wall ? { confidence: wall.confidence, signals: wall.signals } : {}),
+        });
+    },
     // --- task workspace management (server-side; no browser needed) ---
     profile_use: async (a) => {
         // Snapshots are keyed by profile+tab, and a profile switch routes to a
@@ -877,7 +974,7 @@ function recordHistory(tool, rawArgs, ok, extra = {}) {
  */
 const RETRY_SAFE_TOOLS = new Set([
     'tabs_list', 'chrome_status',
-    'get_text', 'get_html', 'snapshot', 'get_cookies',
+    'get_text', 'get_html', 'snapshot', 'get_cookies', 'auth_check',
     'extract_links', 'read_as_markdown', 'screenshot',
     'wait_for', 'navigate', 'reload',
     'frames_list', 'print_pdf',

package/dist/src/security/policy.d.ts

@@ -32,6 +32,10 @@ export interface Policy extends WirePolicy {
     redact?: boolean;
     /** Extra redaction patterns (regex sources) supplied by the operator. */
     redactPatterns?: string[];
+    /** `--fail-on-auth-wall`: every navigating tool and action fails with
+     *  `AUTH_REQUIRED` when the page it lands on is a high-confidence sign-in
+     *  wall, so an expired session is never scored as some other failure. */
+    failOnAuthWall?: boolean;
 }
 /** The SAFE default: deny everything until the user opts in. */
 export declare const DEFAULT_POLICY: Readonly<Policy>;

package/dist/src/security/policy.js

@@ -43,6 +43,7 @@ exports.DEFAULT_POLICY = Object.freeze({
     allowObservers: false,
     redact: false,
     redactPatterns: [],
+    failOnAuthWall: false,
 });
 /** Merge a partial (from a policy file and/or CLI flags) over the safe default. */
 function resolvePolicy(partial) {
@@ -57,6 +58,7 @@ function resolvePolicy(partial) {
         allowObservers: partial?.allowObservers ?? exports.DEFAULT_POLICY.allowObservers,
         redact: partial?.redact ?? exports.DEFAULT_POLICY.redact,
         redactPatterns: partial?.redactPatterns ?? [...(exports.DEFAULT_POLICY.redactPatterns ?? [])],
+        failOnAuthWall: partial?.failOnAuthWall ?? exports.DEFAULT_POLICY.failOnAuthWall,
     };
 }
 // ---------------------------------------------------------------------------

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; }
@@ -350,7 +350,7 @@ export type ExecutorErrorCode =
 
 ## 5. The Complete MCP Tool Surface
 
-38 tools. `readOnly` is metadata (not a JSON-Schema field) consumed by the host
+39 tools. `readOnly` is metadata (not a JSON-Schema field) consumed by the host
 and by **safe-mode** (shipped in v1, default ON). Every handler:
 `withReadyExecutor()` → validate args (`requireTarget` for selector|ref) →
 **`policy.assertUrlAllowed(currentTabUrl, method)`** → call executor/helper →