@geometra/mcp 1.62.2 → 1.63.0

package/README.md

@@ -24,7 +24,7 @@ Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a sm
 
 | Tool | Description |
 |---|---|
-| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; pass `stealth: true` for CloakBrowser's patched Chromium; can inline `formSchema` and/or `pageModel`, or defer the page model for a faster first connect response |
+| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; pass `browserMode: "stock" | "cloakbrowser"` for explicit authorized testing modes; can inline `formSchema` and/or `pageModel`, or defer the page model for a faster first connect response |
 | `geometra_prepare_browser` | Pre-launch and pre-navigate a reusable proxy/browser for `pageUrl` without creating an active session; supports the same headed/headless/stealth browser settings as `geometra_connect` |
 | `geometra_query` | Find elements by stable id, role, name, text content, prompt/section/item context, current value, or semantic state such as `invalid`, `required`, or `busy` |
 | `geometra_wait_for` | Wait for a semantic condition instead of guessing sleeps (`busy`, `disabled`, alerts, values, etc.). **Strict parameters** — use `text` plus `present: false` to wait until a substring disappears (e.g. “Parsing your resume”); there is no `textGone` field |
@@ -33,7 +33,7 @@ Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a sm
 | `geometra_fill_form` | Fill a form from `valuesById` / `valuesByLabel` in one MCP call; can auto-connect from `pageUrl` / `url` for the lowest-token known-form path |
 | `geometra_fill_fields` | Fill text/choice/toggle/file fields in one MCP call; text-only batches now use the proxy fast path when step output is omitted, and text/choice/toggle entries can use `fieldId` from `geometra_form_schema` without repeating the label |
 | `geometra_run_actions` | Execute a batch of high-level actions in one MCP round trip; can auto-connect from `pageUrl` / `url` and return a final-only payload for the smallest multi-step responses |
-| `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, and primary actions with nearby section/item context when available |
+| `geometra_page_model` | Summary-first webpage model: archetypes, stable section ids, counts, top-level sections, primary actions, and `blockedSite` metadata for CAPTCHA/challenge/access-denied states |
 | `geometra_find_action` | Resolve a repeated button/link by action label plus optional `sectionText`, `promptText`, or `itemText` before clicking |
 | `geometra_expand_section` | Expand one form/dialog/list/landmark from `geometra_page_model` on demand, with paging/filtering for long sections |
 | `geometra_reveal` | Scroll until a matching node is visible instead of guessing wheel deltas; auto-scales reveal steps for tall forms when omitted |
@@ -252,10 +252,12 @@ In another terminal (from repo root after `npm install` / `bun install` and `bun
 ```bash
 npx geometra-proxy http://localhost:8080 --port 3200
 # Requires Chromium: npx playwright install chromium
-# Optional stealth prefetch: npx cloakbrowser install
+# Optional authorized stealth-testing prefetch: npx cloakbrowser install
 ```
 
-`geometra-proxy` opens a **visible Chromium window by default**. For servers or CI, pass **`--headless`** or set **`GEOMETRA_HEADLESS=1`**. Pass **`--stealth`**, **`stealth: true`** on MCP tools, or **`GEOMETRA_STEALTH=1`** to use CloakBrowser's patched Chromium through the same proxy protocol. Optional **`--slow-mo <ms>`** slows Playwright actions so they are easier to watch. Headed vs headless usually does **not** materially change token usage, since token usage is driven by MCP tool output rather than whether Chromium is visible.
+`geometra-proxy` runs **headless by default**. Pass **`--headed`** or **`headless: false`** on MCP tools when you need a visible Chromium window. Pass **`--stealth`**, **`stealth: true`** on MCP tools, or **`GEOMETRA_STEALTH=1`** to use CloakBrowser's Chromium through the same proxy protocol for authorized testing. Optional **`--slow-mo <ms>`** slows Playwright actions so they are easier to watch. Headed vs headless usually does **not** materially change token usage, since token usage is driven by MCP tool output rather than whether Chromium is visible.
+
+For blocked/challenge pages, keep `blockDetection: true` (default). Set `blockedSitePolicy` to `"continue"` (default), `"manual-handoff"` to return retry guidance for a visible user handoff, or `"error"` to stop immediately with structured `blockedSite` details.
 
 Point MCP at `ws://127.0.0.1:3200` instead of a native Geometra server. The proxy translates clicks and keyboard messages into Playwright actions and streams updated geometry.
 

package/dist/proxy-spawn.d.ts

@@ -12,11 +12,9 @@ export declare function resolveProxyScriptPathWith(customRequire: NodeRequire, m
 export declare function resolveProxyRuntimePath(): string;
 export declare function resolveProxyRuntimePathWith(customRequire: NodeRequire, moduleDir?: string): string;
 /**
- * BYO outbound proxy for the spawned Chromium. JobForge sets this when the
- * user configures a residential / mobile / SOCKS proxy in `profile.yml` to
- * bypass datacenter-IP fingerprinting on apply portals (Ashby class B,
- * Lever Mapbox geocoder, Cloudflare Bot Management, etc.). Geometra is the
- * wire — the user supplies the proxy.
+ * BYO outbound proxy for the spawned Chromium. Geometra only passes the
+ * caller-provided network route through to Playwright; callers are responsible
+ * for using proxies with authorization and in line with the target site's rules.
  */
 export interface SpawnProxyConfig {
     server: string;

package/dist/proxy-spawn.js

@@ -127,7 +127,26 @@ function buildLocalProxyDistIfPossible(packageDir, entryFile, errors) {
     return undefined;
 }
 export function resolveStealthMode(stealth) {
-    return stealth ?? true;
+    if (stealth !== undefined)
+        return stealth;
+    const explicit = process.env.GEOMETRA_STEALTH;
+    if (truthyEnv(explicit))
+        return true;
+    if (falseyEnv(explicit))
+        return false;
+    const browser = process.env.GEOMETRA_BROWSER?.trim().toLowerCase();
+    if (browser === 'stealth' || browser === 'cloakbrowser' || browser === 'cloak')
+        return true;
+    if (browser === 'chromium' || browser === 'chrome' || browser === 'stock' || browser === 'playwright') {
+        return false;
+    }
+    return false;
+}
+function truthyEnv(value) {
+    return value != null && /^(1|true|yes|on)$/i.test(value);
+}
+function falseyEnv(value) {
+    return value != null && /^(0|false|no|off)$/i.test(value);
 }
 export async function startEmbeddedGeometraProxy(opts) {
     const runtimePath = resolveProxyRuntimePath();
@@ -176,7 +195,7 @@ export function formatProxyStartupFailure(message, opts) {
         hints.push(PLAYWRIGHT_INSTALL_HINT);
     }
     if (/cloakbrowser|CLOAKBROWSER|ERR_MODULE_NOT_FOUND|Cannot find package/i.test(message)) {
-        hints.push('Stealth mode uses CloakBrowser. Install dependencies with npm install, or disable stealth with stealth=false / GEOMETRA_STEALTH=0. To prefetch the patched Chromium binary, run: npx cloakbrowser install');
+        hints.push('Stealth mode uses CloakBrowser. Install dependencies with npm install, or disable stealth with stealth=false / GEOMETRA_STEALTH=0. To prefetch the browser binary for authorized testing, run: npx cloakbrowser install');
     }
     if (opts.port > 0 && /EADDRINUSE|address already in use/i.test(message)) {
         hints.push(`Requested port ${opts.port} is unavailable. Omit the port to use an ephemeral OS-assigned port, or choose another local port.`);

package/dist/server.js

@@ -21,7 +21,34 @@ function stealthInput() {
     return z
         .boolean()
         .optional()
-        .describe('Launch CloakBrowser stealth Chromium for proxy-backed pageUrl sessions. Default false unless GEOMETRA_STEALTH=1 or GEOMETRA_BROWSER=stealth is set.');
+        .describe('Launch CloakBrowser Chromium for authorized proxy-backed pageUrl testing. Default false unless GEOMETRA_STEALTH=1 or GEOMETRA_BROWSER=stealth is set.');
+}
+function browserModeInput() {
+    return z
+        .enum(['stock', 'cloakbrowser'])
+        .optional()
+        .describe('Explicit browser engine for proxy-backed sessions. `stock` forces Playwright Chromium; `cloakbrowser` opts into CloakBrowser for authorized testing. Conflicts with a contradictory stealth value.');
+}
+function blockDetectionInput() {
+    return z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe('Detect CAPTCHA/challenge/blocked/unsupported-browser pages and surface `blockedSite` metadata (default true).');
+}
+function blockedSitePolicyInput() {
+    return z
+        .enum(['continue', 'manual-handoff', 'error'])
+        .optional()
+        .default('continue')
+        .describe('How to respond when blockDetection finds a blocked/challenge page: continue (default), manual-handoff (return handoff metadata), or error.');
+}
+function manualHandoffInput() {
+    return z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Shortcut for blockedSitePolicy="manual-handoff" when a blocked/challenge page is detected.');
 }
 function formSchemaFormatInput() {
     return z
@@ -37,6 +64,76 @@ function pageModelModeInput() {
         .default('inline')
         .describe('When returnPageModel=true, `inline` includes the full page model in the connect response. `deferred` returns connect as soon as the transport is ready and lets the caller fetch geometra_page_model separately.');
 }
+function resolveBrowserStealth(input) {
+    const modeStealth = input.browserMode === 'cloakbrowser'
+        ? true
+        : input.browserMode === 'stock'
+            ? false
+            : undefined;
+    if (modeStealth !== undefined && input.stealth !== undefined && input.stealth !== modeStealth) {
+        return {
+            ok: false,
+            error: `Conflicting browser settings: browserMode="${input.browserMode}" implies stealth=${modeStealth}, but stealth=${input.stealth} was also provided.`,
+        };
+    }
+    const stealth = input.stealth ?? modeStealth;
+    return stealth === undefined ? { ok: true } : { ok: true, stealth };
+}
+function effectiveBlockedSitePolicy(policy, manualHandoff) {
+    return manualHandoff ? 'manual-handoff' : policy;
+}
+function blockedSiteManualHandoffPayload(blockedSite, options) {
+    return {
+        required: true,
+        reason: blockedSite.hint ?? 'Blocked or challenge page detected',
+        recommendedAction: blockedSite.recommendedAction ?? 'manual-handoff',
+        message: 'Pause automation and let a user complete the challenge or review access in a normal visible browser session.',
+        retry: {
+            ...(options?.pageUrl ? { pageUrl: options.pageUrl } : {}),
+            headless: false,
+            blockDetection: true,
+            blockedSitePolicy: 'continue',
+        },
+    };
+}
+function blockedSitePolicyErrorPayload(blockedSite, policy) {
+    return {
+        blocked: true,
+        blockedSite,
+        blockedSitePolicy: policy,
+        message: blockedSite.hint ?? 'Blocked or challenge page detected',
+    };
+}
+function applyBlockedSitePolicyPayload(payload, blockedSite, options) {
+    if (!blockedSite?.detected)
+        return payload;
+    const policy = effectiveBlockedSitePolicy(options.policy, options.manualHandoff);
+    const next = {
+        ...payload,
+        blockedSite,
+        blockedSitePolicy: policy,
+    };
+    if (policy === 'manual-handoff') {
+        next.manualHandoff = blockedSiteManualHandoffPayload(blockedSite, options);
+    }
+    return next;
+}
+function blockedSiteFromPayload(payload) {
+    const value = payload.blockedSite;
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const candidate = value;
+    return candidate.detected ? candidate : undefined;
+}
+function blockedSiteErrorIfNeeded(payload, policy, manualHandoff) {
+    const effectivePolicy = effectiveBlockedSitePolicy(policy, manualHandoff);
+    if (effectivePolicy !== 'error')
+        return undefined;
+    const blockedSite = blockedSiteFromPayload(payload);
+    if (!blockedSite)
+        return undefined;
+    return err(JSON.stringify(blockedSitePolicyErrorPayload(blockedSite, effectivePolicy)));
+}
 function formSchemaContextInput() {
     return z
         .enum(['auto', 'always', 'none'])
@@ -407,7 +504,7 @@ export function createServer() {
 
 Use \`url\` (ws://…) only when a Geometra/native server or an already-running proxy is listening. If you accidentally pass \`https://…\` in \`url\`, MCP treats it like \`pageUrl\` and starts the proxy for you.
 
-Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth: true\` (or set \`GEOMETRA_STEALTH=1\`) to launch CloakBrowser's patched Chromium instead of stock Playwright Chromium. File upload / wheel / native \`<select>\` need the proxy path (\`pageUrl\` or ws to proxy). Set \`returnForms: true\` and/or \`returnPageModel: true\` when you want a lower-turn startup response. When connect first-response latency matters more than inlining the page model, pair \`returnPageModel: true\` with \`pageModelMode: "deferred"\` and call \`geometra_page_model\` next.
+Chromium runs **headless** by default unless \`headless: false\`. Pass \`stealth: true\` (or set \`GEOMETRA_STEALTH=1\`) to opt into CloakBrowser's Chromium for authorized testing instead of stock Playwright Chromium. File upload / wheel / native \`<select>\` need the proxy path (\`pageUrl\` or ws to proxy). Set \`returnForms: true\` and/or \`returnPageModel: true\` when you want a lower-turn startup response. When connect first-response latency matters more than inlining the page model, pair \`returnPageModel: true\` with \`pageModelMode: "deferred"\` and call \`geometra_page_model\` next.
 
 **Parallelism:** by default, geometra MCP pools and reuses Chromium instances across sessions for speed. That pooling is safe for read-only exploration, but it shares localStorage / cookies / page state across whichever sessions land on the same proxy — which means **two parallel form-submission flows can contaminate each other** (one job's email/autocomplete state leaks into another, or worse, two agents end up driving the same browser tab). For parallel apply / form submission, pass \`isolated: true\`. Each isolated session gets its own brand-new Chromium that is destroyed on disconnect, never enters the pool, and is guaranteed independent of every other session. The cost is ~1–2s of extra startup vs the ~50ms reusable-proxy attach.`, {
         url: z
@@ -430,7 +527,7 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
         headless: z
             .boolean()
             .optional()
-            .describe('Run Chromium headless (default false = visible window).'),
+            .describe('Run Chromium headless (default true). Set false for a visible window.'),
         width: z.number().int().positive().optional().describe('Viewport width for spawned proxy.'),
         height: z.number().int().positive().optional().describe('Viewport height for spawned proxy.'),
         slowMo: z
@@ -440,6 +537,7 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
             .optional()
             .describe('Playwright slowMo (ms) on spawned proxy for easier visual following.'),
         stealth: stealthInput(),
+        browserMode: browserModeInput(),
         isolated: z
             .boolean()
             .optional()
@@ -458,7 +556,7 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
                 .describe('Comma-separated host patterns to bypass (e.g. "*.internal,localhost").'),
         })
             .optional()
-            .describe('BYO outbound proxy for the spawned Chromium. Routes all browser traffic through the supplied residential / mobile / SOCKS proxy — useful for apply portals (Ashby, Lever, Cloudflare-fronted ATSes) that fingerprint datacenter IPs and flag headless sessions as bots. The reusable proxy pool is partitioned by proxy identity so callers with different proxy configs never share a Chromium instance.'),
+            .describe('BYO outbound proxy for the spawned Chromium. Routes browser traffic through the supplied HTTP/SOCKS proxy. Use only proxies you are authorized to use and in line with the target site rules. The reusable proxy pool is partitioned by proxy identity so callers with different proxy configs never share a Chromium instance.'),
         returnForms: z
             .boolean()
             .optional()
@@ -470,6 +568,9 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
             .default(false)
             .describe('Include geometra_page_model output in the connect response so exploration can start in one turn.'),
         pageModelMode: pageModelModeInput(),
+        blockDetection: blockDetectionInput(),
+        blockedSitePolicy: blockedSitePolicyInput(),
+        manualHandoff: manualHandoffInput(),
         formId: z.string().optional().describe('Optional form id filter when returnForms=true'),
         maxFields: z.number().int().min(1).max(120).optional().default(80).describe('Cap returned fields per form when returnForms=true'),
         onlyRequiredFields: z.boolean().optional().default(false).describe('Only include required fields when returnForms=true'),
@@ -485,6 +586,9 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
         const normalized = normalizeConnectTarget({ url: input.url, pageUrl: input.pageUrl });
         if (!normalized.ok)
             return err(normalized.error);
+        const browser = resolveBrowserStealth({ stealth: input.stealth, browserMode: input.browserMode });
+        if (!browser.ok)
+            return err(browser.error);
         const target = normalized.value;
         const formSchema = {
             formId: input.formId,
@@ -513,7 +617,7 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
                     width: input.width,
                     height: input.height,
                     slowMo: input.slowMo,
-                    ...(input.stealth !== undefined && { stealth: input.stealth }),
+                    ...(browser.stealth !== undefined && { stealth: browser.stealth }),
                     isolated: input.isolated,
                     proxy: input.proxy,
                     awaitInitialFrame: deferInlinePageModel ? false : undefined,
@@ -522,7 +626,7 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
                 if (input.returnForms) {
                     await stabilizeInlineFormSchemas(session, formSchema);
                 }
-                return ok(JSON.stringify(connectResponsePayload(session, {
+                const payload = connectResponsePayload(session, {
                     transport: 'proxy',
                     requestedPageUrl: target.pageUrl,
                     autoCoercedFromUrl: target.autoCoercedFromUrl,
@@ -530,9 +634,17 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
                     returnForms: input.returnForms,
                     returnPageModel: input.returnPageModel,
                     pageModelMode: input.pageModelMode,
+                    blockDetection: input.blockDetection,
+                    blockedSitePolicy: input.blockedSitePolicy,
+                    manualHandoff: input.manualHandoff,
                     formSchema,
                     pageModelOptions,
-                }), null, input.detail === 'verbose' ? 2 : undefined));
+                    headless: input.headless,
+                });
+                const blockedError = blockedSiteErrorIfNeeded(payload, input.blockedSitePolicy, input.manualHandoff);
+                if (blockedError)
+                    return blockedError;
+                return ok(JSON.stringify(payload, null, input.detail === 'verbose' ? 2 : undefined));
             }
             const session = await connect(target.wsUrl, {
                 width: input.width,
@@ -542,7 +654,7 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
             if (input.returnForms) {
                 await stabilizeInlineFormSchemas(session, formSchema);
             }
-            return ok(JSON.stringify(connectResponsePayload(session, {
+            const payload = connectResponsePayload(session, {
                 transport: 'ws',
                 requestedWsUrl: target.wsUrl,
                 autoCoercedFromUrl: false,
@@ -550,9 +662,17 @@ Chromium opens **visible** by default unless \`headless: true\`. Pass \`stealth:
                 returnForms: input.returnForms,
                 returnPageModel: input.returnPageModel,
                 pageModelMode: input.pageModelMode,
+                blockDetection: input.blockDetection,
+                blockedSitePolicy: input.blockedSitePolicy,
+                manualHandoff: input.manualHandoff,
                 formSchema,
                 pageModelOptions,
-            }), null, input.detail === 'verbose' ? 2 : undefined));
+                headless: input.headless,
+            });
+            const blockedError = blockedSiteErrorIfNeeded(payload, input.blockedSitePolicy, input.manualHandoff);
+            if (blockedError)
+                return blockedError;
+            return ok(JSON.stringify(payload, null, input.detail === 'verbose' ? 2 : undefined));
         }
         catch (e) {
             return err(`Failed to connect: ${formatConnectFailureMessage(e, target)}`);
@@ -577,7 +697,7 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
         headless: z
             .boolean()
             .optional()
-            .describe('Run Chromium headless (default false = visible window).'),
+            .describe('Run Chromium headless (default true). Set false for a visible window.'),
         width: z.number().int().positive().optional().describe('Viewport width for the warmed browser.'),
         height: z.number().int().positive().optional().describe('Viewport height for the warmed browser.'),
         slowMo: z
@@ -587,6 +707,7 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
             .optional()
             .describe('Playwright slowMo (ms) for the warmed browser.'),
         stealth: stealthInput(),
+        browserMode: browserModeInput(),
         proxy: z
             .object({
             server: z
@@ -601,8 +722,11 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
         })
             .optional()
             .describe('BYO outbound proxy for the warmed Chromium. The pool entry is partitioned by proxy identity, so a later geometra_connect with the same proxy config will reuse this warmed browser; a different proxy config (or no proxy) will not.'),
-    }, async ({ pageUrl, port, headless, width, height, slowMo, stealth, proxy }) => {
+    }, async ({ pageUrl, port, headless, width, height, slowMo, stealth, browserMode, proxy }) => {
         try {
+            const browser = resolveBrowserStealth({ stealth, browserMode });
+            if (!browser.ok)
+                return err(browser.error);
             const prepared = await prewarmProxy({
                 pageUrl,
                 port,
@@ -610,7 +734,7 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
                 width,
                 height,
                 slowMo,
-                ...(stealth !== undefined && { stealth }),
+                ...(browser.stealth !== undefined && { stealth: browser.stealth }),
                 proxy,
             });
             return ok(JSON.stringify(prepared));
@@ -975,11 +1099,12 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         url: z.string().optional().describe('Optional target URL. Use a ws:// Geometra server URL or an http(s) page URL to auto-connect before filling.'),
         pageUrl: z.string().optional().describe('Optional http(s) page URL to auto-connect before filling. Prefer this over url for browser pages.'),
         port: z.number().int().min(0).max(65535).optional().describe('Preferred local port for an auto-spawned proxy (default: ephemeral OS-assigned port).'),
-        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default false = visible window).'),
+        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default true). Set false for a visible window.'),
         width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
         height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
         stealth: stealthInput(),
+        browserMode: browserModeInput(),
         formId: z.string().optional().describe('Optional form id from geometra_form_schema or geometra_page_model'),
         valuesById: formValuesRecordSchema.optional().describe('Form values keyed by stable field id from geometra_form_schema'),
         valuesByLabel: formValuesRecordSchema.optional().describe('Form values keyed by schema field label'),
@@ -1017,7 +1142,10 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             .describe('When auto-connecting via pageUrl/url, request an isolated proxy (own brand-new Chromium, destroyed on disconnect). Required for safe parallel form submission. See geometra_connect for details. Ignored when reusing an existing sessionId — set isolated on the original geometra_connect for that case.'),
         detail: detailInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, isolated, detail, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, browserMode, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, isolated, detail, sessionId }) => {
+        const browser = resolveBrowserStealth({ stealth, browserMode });
+        if (!browser.ok)
+            return err(browser.error);
         const directFields = !includeSteps && !formId && Object.keys(valuesById ?? {}).length === 0
             ? directLabelBatchFields(valuesByLabel)
             : null;
@@ -1030,7 +1158,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             width,
             height,
             slowMo,
-            stealth,
+            stealth: browser.stealth,
             isolated,
             awaitInitialFrame: directFields ? false : undefined,
         }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_fill_form.');
@@ -1286,11 +1414,12 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         url: z.string().optional().describe('Optional target URL. Use a ws:// Geometra server URL or an http(s) page URL to auto-connect before submitting.'),
         pageUrl: z.string().optional().describe('Optional http(s) page URL to auto-connect before submitting. Prefer this over url for browser pages.'),
         port: z.number().int().min(0).max(65535).optional().describe('Preferred local port for an auto-spawned proxy (default: ephemeral OS-assigned port).'),
-        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default false = visible window).'),
+        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default true). Set false for a visible window.'),
         width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
         height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
         stealth: stealthInput(),
+        browserMode: browserModeInput(),
         isolated: z.boolean().optional().default(false).describe('When auto-connecting via pageUrl/url, request an isolated proxy. Required for safe parallel form submission.'),
         formId: z.string().optional().describe('Optional form id from geometra_form_schema or geometra_page_model'),
         valuesById: formValuesRecordSchema.optional().describe('Form values keyed by stable field id from geometra_form_schema'),
@@ -1304,11 +1433,14 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         failOnInvalid: z.boolean().optional().default(false).describe('Return an error if invalid fields remain after the submit wait resolves.'),
         detail: detailInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, isolated, formId, valuesById, valuesByLabel, submit, submitIndex, submitTimeoutMs, waitFor, skipFill, softTimeoutMs, failOnInvalid, detail, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, browserMode, isolated, formId, valuesById, valuesByLabel, submit, submitIndex, submitTimeoutMs, waitFor, skipFill, softTimeoutMs, failOnInvalid, detail, sessionId }) => {
+        const browser = resolveBrowserStealth({ stealth, browserMode });
+        if (!browser.ok)
+            return err(browser.error);
         const toolStartedAt = performance.now();
         const effectiveSoftTimeoutMs = softTimeoutMs ?? HOST_SAFE_TOOL_TIMEOUT_MS;
         const deadlineAt = toolStartedAt + effectiveSoftTimeoutMs;
-        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, stealth, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_submit_form.');
+        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, stealth: browser.stealth, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_submit_form.');
         if (!resolved.ok)
             return err(resolved.error);
         const session = resolved.session;
@@ -1589,11 +1721,12 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         url: z.string().optional().describe('Optional target URL. Use a ws:// Geometra server URL or an http(s) page URL to auto-connect before running actions.'),
         pageUrl: z.string().optional().describe('Optional http(s) page URL to auto-connect before running actions. Prefer this over url for browser pages.'),
         port: z.number().int().min(0).max(65535).optional().describe('Preferred local port for an auto-spawned proxy (default: ephemeral OS-assigned port).'),
-        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default false = visible window).'),
+        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default true). Set false for a visible window.'),
         width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
         height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
         stealth: stealthInput(),
+        browserMode: browserModeInput(),
         isolated: z
             .boolean()
             .optional()
@@ -1617,7 +1750,10 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         output: z.enum(['full', 'final']).optional().default('full').describe('`full` (default) returns counts and optional step listings. `final` keeps only completion state plus final semantic signals.'),
         detail: detailInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, isolated, actions, resumeFromIndex, softTimeoutMs, stopOnError, includeSteps, output, detail, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, browserMode, isolated, actions, resumeFromIndex, softTimeoutMs, stopOnError, includeSteps, output, detail, sessionId }) => {
+        const browser = resolveBrowserStealth({ stealth, browserMode });
+        if (!browser.ok)
+            return err(browser.error);
         const toolStartedAt = performance.now();
         const effectiveSoftTimeoutMs = softTimeoutMs ?? HOST_SAFE_TOOL_TIMEOUT_MS;
         const deadlineAt = toolStartedAt + effectiveSoftTimeoutMs;
@@ -1630,7 +1766,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
             width,
             height,
             slowMo,
-            stealth,
+            stealth: browser.stealth,
             isolated,
             awaitInitialFrame: canDeferInitialFrameForRunActions(actions) ? false : undefined,
         }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_run_actions.');
@@ -1800,8 +1936,11 @@ Use this first on normal HTML pages when you want to understand the page shape w
             .optional()
             .default(false)
             .describe('Attach a base64 PNG viewport screenshot. Requires @geometra/proxy. Use when geometry alone is ambiguous (icon-only buttons, visual styling cues).'),
+        blockDetection: blockDetectionInput(),
+        blockedSitePolicy: blockedSitePolicyInput(),
+        manualHandoff: manualHandoffInput(),
         sessionId: sessionIdInput,
-    }, async ({ maxPrimaryActions, maxSectionsPerKind, includeScreenshot, sessionId }) => {
+    }, async ({ maxPrimaryActions, maxSectionsPerKind, includeScreenshot, blockDetection, blockedSitePolicy, manualHandoff, sessionId }) => {
         const sessionResult = resolveToolSession(sessionId);
         if ('error' in sessionResult)
             return sessionResult.error;
@@ -1809,9 +1948,14 @@ Use this first on normal HTML pages when you want to understand the page shape w
         const a11y = await sessionA11yWhenReady(session);
         if (!a11y)
             return err('No UI tree available');
-        const model = buildPageModel(a11y, { maxPrimaryActions, maxSectionsPerKind });
+        const model = buildPageModel(a11y, { maxPrimaryActions, maxSectionsPerKind, blockDetection });
+        const policy = effectiveBlockedSitePolicy(blockedSitePolicy, manualHandoff);
+        if (policy === 'error' && model.blockedSite?.detected) {
+            return err(JSON.stringify(blockedSitePolicyErrorPayload(model.blockedSite, policy)));
+        }
+        const payload = applyBlockedSitePolicyPayload(model, model.blockedSite, { policy: blockedSitePolicy, manualHandoff, pageUrl: a11y.meta?.pageUrl });
         const screenshot = includeScreenshot ? await captureScreenshotBase64(session) : undefined;
-        return ok(JSON.stringify(model), screenshot);
+        return ok(JSON.stringify(payload), screenshot);
     });
     server.tool('geometra_form_schema', `Get a compact, fill-oriented schema for forms on the page. This is the preferred discovery step before geometra_fill_form.
 
@@ -1819,11 +1963,12 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
         url: z.string().optional().describe('Optional target URL. Use a ws:// Geometra server URL or an http(s) page URL to auto-connect before discovery.'),
         pageUrl: z.string().optional().describe('Optional http(s) page URL to auto-connect before discovery. Prefer this over url for browser pages.'),
         port: z.number().int().min(0).max(65535).optional().describe('Preferred local port for an auto-spawned proxy (default: ephemeral OS-assigned port).'),
-        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default false = visible window).'),
+        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default true). Set false for a visible window.'),
         width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
         height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
         slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
         stealth: stealthInput(),
+        browserMode: browserModeInput(),
         isolated: z
             .boolean()
             .optional()
@@ -1838,8 +1983,11 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
         sinceSchemaId: z.string().optional().describe('If the current schema matches this id, return changed=false without resending forms'),
         format: formSchemaFormatInput(),
         sessionId: sessionIdInput,
-    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, isolated, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeContext, sinceSchemaId, format, sessionId }) => {
-        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, stealth, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_form_schema.');
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, browserMode, isolated, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeContext, sinceSchemaId, format, sessionId }) => {
+        const browser = resolveBrowserStealth({ stealth, browserMode });
+        if (!browser.ok)
+            return err(browser.error);
+        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, stealth: browser.stealth, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_form_schema.');
         if (!resolved.ok)
             return err(resolved.error);
         const session = resolved.session;
@@ -2811,16 +2959,27 @@ async function stabilizeInlineFormSchemas(session, options, opts) {
 }
 function connectResponsePayload(session, opts) {
     const payload = connectPayload(session, opts);
+    const policy = opts.blockedSitePolicy ?? 'continue';
+    const pageModelOptions = {
+        ...opts.pageModelOptions,
+        blockDetection: opts.blockDetection,
+    };
+    const model = opts.blockDetection === false ? undefined : pageModelFromSession(session, pageModelOptions);
+    const nextPayload = applyBlockedSitePolicyPayload({ ...payload }, model?.blockedSite, {
+        policy,
+        manualHandoff: opts.manualHandoff,
+        pageUrl: opts.requestedPageUrl,
+        headless: opts.headless,
+    });
     if (!opts.returnForms && !opts.returnPageModel)
-        return payload;
-    const nextPayload = { ...payload };
+        return nextPayload;
     if (opts.returnForms) {
         nextPayload.formSchema = formSchemaResponsePayload(session, opts.formSchema ?? {});
     }
     if (opts.returnPageModel) {
         nextPayload.pageModel = opts.pageModelMode === 'deferred'
-            ? deferredPageModelConnectPayload(session, opts.pageModelOptions)
-            : pageModelResponsePayload(session, opts.pageModelOptions);
+            ? deferredPageModelConnectPayload(session, pageModelOptions)
+            : (model ?? pageModelResponsePayload(session, pageModelOptions));
     }
     return nextPayload;
 }
@@ -2832,14 +2991,17 @@ function deferredPageModelConnectPayload(session, options) {
         options: {
             maxPrimaryActions: options?.maxPrimaryActions ?? 6,
             maxSectionsPerKind: options?.maxSectionsPerKind ?? 8,
+            blockDetection: options?.blockDetection !== false,
         },
     };
 }
 function pageModelResponsePayload(session, options) {
+    return pageModelFromSession(session, options) ?? { available: false };
+}
+function pageModelFromSession(session, options) {
     const a11y = sessionA11y(session);
-    if (!a11y) {
-        return { available: false };
-    }
+    if (!a11y)
+        return undefined;
     return buildPageModel(a11y, options);
 }
 async function ensureToolSession(target, missingConnectionMessage = 'Not connected. Call geometra_connect first.') {

package/dist/session.d.ts

@@ -142,6 +142,13 @@ export interface CaptchaDetection {
     type?: 'recaptcha' | 'hcaptcha' | 'turnstile' | 'cloudflare-challenge' | 'unknown';
     hint?: string;
 }
+export interface BlockedSiteDetection {
+    detected: boolean;
+    type?: 'captcha' | 'cloudflare-challenge' | 'automation-detected' | 'access-denied' | 'unsupported-browser' | 'rate-limited' | 'unknown';
+    hint?: string;
+    evidence?: string[];
+    recommendedAction?: 'manual-handoff' | 'retry-later' | 'review-site-rules';
+}
 export interface VerificationDetection {
     detected: boolean;
     type?: 'email_code' | 'sms_code' | 'security_question' | 'unknown';
@@ -160,6 +167,7 @@ export interface PageModel {
         listCount: number;
         focusableCount: number;
     };
+    blockedSite?: BlockedSiteDetection;
     captcha?: CaptchaDetection;
     verification?: VerificationDetection;
     primaryActions: PagePrimaryAction[];
@@ -539,10 +547,9 @@ export declare function connectThroughProxy(options: {
      */
     isolated?: boolean;
     /**
-     * BYO outbound proxy for the Chromium. Routes all browser traffic through
-     * the supplied residential / mobile / SOCKS proxy. The reusable pool is
-     * partitioned by proxy identity so two callers with different proxy
-     * configs never share a Chromium instance.
+     * BYO outbound proxy for Chromium. The reusable pool is partitioned by proxy
+     * identity so two callers with different proxy configs never share a
+     * Chromium instance.
      */
     proxy?: SpawnProxyConfig;
 }): Promise<Session>;
@@ -722,6 +729,7 @@ export declare function nodeContextForNode(root: A11yNode, node: A11yNode): Node
 export declare function buildPageModel(root: A11yNode, options?: {
     maxPrimaryActions?: number;
     maxSectionsPerKind?: number;
+    blockDetection?: boolean;
 }): PageModel;
 export declare function buildFormSchemas(root: A11yNode, options?: FormSchemaBuildOptions): FormSchemaModel[];
 /**

package/dist/session.js

@@ -441,8 +441,8 @@ function findReusableProxy(options) {
         .filter(entry => entry.headless === desiredHeadless
         && entry.stealth === desiredStealth
         && entry.slowMo === desiredSlowMo
-        // Proxy partition is hard — a session with residential proxy MUST NOT
-        // attach to a pooled direct-connection Chromium (and vice versa).
+        // Proxy partition is hard: a session with a caller-provided proxy MUST
+        // NOT attach to a pooled direct-connection Chromium (and vice versa).
         // Different proxy credentials also get separate pool entries.
         && entry.proxyKey === desiredProxyKey)
         .sort((a, b) => {
@@ -2529,6 +2529,90 @@ function detectCaptcha(root) {
     }
     return found ?? { detected: false };
 }
+const BLOCKED_SITE_PATTERNS = [
+    {
+        pattern: /cloudflare.*challenge|challenge-platform|just a moment|checking your browser|cdn-cgi\/challenge/i,
+        type: 'cloudflare-challenge',
+        hint: 'Cloudflare challenge page detected',
+        recommendedAction: 'manual-handoff',
+    },
+    {
+        pattern: /verify (you are|that you are|you're|you.re) human|are you human|human verification|i.m not a robot|not a robot/i,
+        type: 'captcha',
+        hint: 'Human verification challenge detected',
+        recommendedAction: 'manual-handoff',
+    },
+    {
+        pattern: /automated access|automation detected|bot detected|bot activity|unusual traffic|suspicious traffic|browser automation/i,
+        type: 'automation-detected',
+        hint: 'Automation block detected',
+        recommendedAction: 'manual-handoff',
+    },
+    {
+        pattern: /access denied|forbidden|blocked from accessing|temporarily blocked|request blocked|not authorized/i,
+        type: 'access-denied',
+        hint: 'Access denied or request blocked page detected',
+        recommendedAction: 'review-site-rules',
+    },
+    {
+        pattern: /unsupported browser|browser is not supported|please update your browser|enable javascript/i,
+        type: 'unsupported-browser',
+        hint: 'Unsupported browser or JavaScript requirement detected',
+        recommendedAction: 'manual-handoff',
+    },
+    {
+        pattern: /too many requests|rate limit|temporarily unavailable|try again later/i,
+        type: 'rate-limited',
+        hint: 'Rate limit or temporary block detected',
+        recommendedAction: 'retry-later',
+    },
+];
+function detectBlockedSite(root, captcha) {
+    if (captcha.detected) {
+        return {
+            detected: true,
+            type: captcha.type === 'cloudflare-challenge' ? 'cloudflare-challenge' : 'captcha',
+            ...(captcha.hint ? { hint: captcha.hint } : {}),
+            recommendedAction: 'manual-handoff',
+        };
+    }
+    let found;
+    const evidence = [];
+    const checkText = (raw) => {
+        if (!raw || found)
+            return;
+        const text = raw.replace(/\s+/g, ' ').trim();
+        if (!text)
+            return;
+        for (const candidate of BLOCKED_SITE_PATTERNS) {
+            if (!candidate.pattern.test(text))
+                continue;
+            found = {
+                detected: true,
+                type: candidate.type,
+                hint: candidate.hint,
+                recommendedAction: candidate.recommendedAction,
+            };
+            evidence.push(truncateUiText(text, 140));
+            return;
+        }
+    };
+    checkText(root.meta?.pageUrl);
+    function walk(node) {
+        if (found)
+            return;
+        checkText([node.name, node.value, node.validation?.error, node.validation?.description].filter(Boolean).join(' '));
+        for (const child of node.children)
+            walk(child);
+    }
+    walk(root);
+    if (!found)
+        return { detected: false };
+    return {
+        ...found,
+        ...(evidence.length > 0 ? { evidence: evidence.slice(0, 3) } : {}),
+    };
+}
 const VERIFICATION_FIELD_PATTERN = /verif|security.?code|confirm.*(code|email)|one.?time|otp|2fa|mfa|passcode/i;
 const VERIFICATION_CONTEXT_PATTERN = /sent.*(code|email|sms|text)|enter.*code|check.your.(email|phone|inbox)|we.sent|verification/i;
 function detectVerification(root) {
@@ -2643,9 +2727,11 @@ export function buildPageModel(root, options) {
         lists: sortByBounds(lists).slice(0, maxSectionsPerKind),
     };
     const captcha = detectCaptcha(root);
+    const blockedSite = options?.blockDetection === false ? { detected: false } : detectBlockedSite(root, captcha);
     const verification = detectVerification(root);
     return {
         ...baseModel,
+        ...(blockedSite.detected ? { blockedSite } : {}),
         ...(captcha.detected ? { captcha } : {}),
         ...(verification.detected ? { verification } : {}),
         archetypes: inferPageArchetypes(baseModel),
@@ -2844,6 +2930,9 @@ export function summarizePageModel(model, maxLines = 10) {
     if (model.archetypes.length > 0) {
         lines.push(`archetypes: ${model.archetypes.join(', ')}`);
     }
+    if (model.blockedSite?.detected) {
+        lines.push(`blocked: ${model.blockedSite.type ?? 'unknown'}${model.blockedSite.hint ? ` - ${model.blockedSite.hint}` : ''}`);
+    }
     lines.push(`summary: ${model.summary.landmarkCount} landmarks, ${model.summary.formCount} forms, ${model.summary.dialogCount} dialogs, ${model.summary.listCount} lists, ${model.summary.focusableCount} focusable`);
     for (const landmark of model.landmarks.slice(0, 3)) {
         const name = landmark.name ? ` "${truncateUiText(landmark.name, 32)}"` : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.62.2",
+  "version": "1.63.0",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,7 @@
     "ui-testing"
   ],
   "dependencies": {
-    "@geometra/proxy": "^1.62.2",
+    "@geometra/proxy": "^1.63.0",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@razroo/parallel-mcp": "^0.1.0",
     "ws": "^8.18.0",