@geometra/mcp 1.61.1 → 1.61.3

package/README.md

@@ -18,14 +18,14 @@ Geometra proxy:       Chromium → DOM geometry → same WebSocket as native →
 
 Use Geometra MCP when an LLM needs to explore, interpret, and operate a real UI with compact semantic state instead of repeatedly consuming large browser snapshots. Keep Playwright-style tooling for deterministic scripts, DOM-oriented test automation, and compatibility fallback paths while Geometra closes remaining live-site gaps.
 
-Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a small warm pool so compatible headed and headless workflows do not immediately evict each other.
+Proxy-backed sessions stay warm by default on disconnect, and MCP now keeps a small warm pool so compatible headed, headless, and stealth workflows do not immediately evict each other.
 
 ## Tools
 
 | Tool | Description |
 |---|---|
-| `geometra_connect` | Connect with `url` (ws://…) **or** `pageUrl` (https://…) to auto-start geometra-proxy; 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; best when the agent can prepare before the user-facing task starts |
+| `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_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 |
 | `geometra_wait_for_resume_parse` | Convenience wait until a parsing banner is gone (defaults: `text`: `"Parsing"`, `present` implied false). Same engine as `geometra_wait_for` |
@@ -252,9 +252,10 @@ 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
 ```
 
-`geometra-proxy` opens a **visible Chromium window by default**. For servers or CI, pass **`--headless`** or set **`GEOMETRA_HEADLESS=1`**. 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` 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.
 
 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.
 
@@ -341,7 +342,7 @@ For long application flows, prefer one of these patterns:
 4. `geometra_snapshot({ view: "form-required" })` when you need the remaining required fields including offscreen ones
 5. `geometra_reveal` for far-below-fold targets such as submit buttons (auto-scales reveal steps when you omit `maxSteps`)
 6. `geometra_click({ ..., waitFor: ... })` when one action should also wait for the next semantic state
-7. `geometra_prepare_browser({ pageUrl, headless, width, height })` when you can hide browser startup before the real task and want the next proxy-backed flow to attach warm
+7. `geometra_prepare_browser({ pageUrl, headless, stealth, width, height })` when you can hide browser startup before the real task and want the next proxy-backed flow to attach warm
 8. `geometra_run_actions` when you need mixed navigation + waits + field entry, especially with `pageUrl` / `url` for a one-call flow
 9. `geometra_connect({ pageUrl, returnPageModel: true })` when you want connect + summary-first exploration in one turn
 10. `geometra_connect({ pageUrl, returnPageModel: true, pageModelMode: "deferred" })` when first-response latency matters more than inlining the page model; follow with `geometra_page_model`

package/dist/proxy-spawn.d.ts

@@ -31,9 +31,11 @@ export interface SpawnProxyParams {
     width?: number;
     height?: number;
     slowMo?: number;
+    stealth?: boolean;
     eagerInitialExtract?: boolean;
     proxy?: SpawnProxyConfig;
 }
+export declare function resolveStealthMode(stealth?: boolean): boolean;
 export declare function startEmbeddedGeometraProxy(opts: SpawnProxyParams): Promise<{
     runtime: EmbeddedProxyRuntime;
     wsUrl: string;

package/dist/proxy-spawn.js

@@ -125,6 +125,18 @@ function buildLocalProxyDistIfPossible(packageDir, entryFile, errors) {
     }
     return undefined;
 }
+function envRequestsStealth() {
+    const explicit = process.env.GEOMETRA_STEALTH;
+    if (explicit !== undefined) {
+        const v = explicit.toLowerCase();
+        return v === '1' || v === 'true' || v === 'yes' || v === 'stealth' || v === 'cloak';
+    }
+    const browser = (process.env.GEOMETRA_BROWSER ?? '').toLowerCase();
+    return browser === 'stealth' || browser === 'cloak' || browser === 'cloakbrowser';
+}
+export function resolveStealthMode(stealth) {
+    return stealth ?? envRequestsStealth();
+}
 export async function startEmbeddedGeometraProxy(opts) {
     const runtimePath = resolveProxyRuntimePath();
     const runtimeModule = await import(pathToFileURL(runtimePath).href);
@@ -138,6 +150,7 @@ export async function startEmbeddedGeometraProxy(opts) {
         height: opts.height,
         headed: opts.headless !== true,
         slowMo: opts.slowMo,
+        ...(opts.stealth !== undefined && { stealth: opts.stealth }),
         eagerInitialExtract: opts.eagerInitialExtract,
         ...(opts.proxy && { proxy: opts.proxy }),
     });
@@ -168,6 +181,9 @@ export function formatProxyStartupFailure(message, opts) {
     if (/Executable doesn't exist|playwright install chromium|browserType\.launch/i.test(message)) {
         hints.push('Install Chromium with: npx playwright install chromium');
     }
+    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');
+    }
     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.`);
     }
@@ -191,6 +207,10 @@ export function spawnGeometraProxy(opts) {
         args.push('--headless');
     else if (opts.headless === false)
         args.push('--headed');
+    if (opts.stealth === true)
+        args.push('--stealth');
+    else if (opts.stealth === false)
+        args.push('--no-stealth');
     if (opts.eagerInitialExtract === false)
         args.push('--lazy-initial-extract');
     if (opts.proxy?.server) {

package/dist/server.js

@@ -17,6 +17,12 @@ function detailInput() {
         .default('minimal')
         .describe('`terse` returns compact machine-friendly JSON. `minimal` (default) returns short human-readable summaries. `verbose` adds fuller fallback context.');
 }
+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.');
+}
 function formSchemaFormatInput() {
     return z
         .enum(['compact', 'packed'])
@@ -117,6 +123,68 @@ const geometraWaitForResumeParseInputSchema = z
 })
     .strict();
 const timeoutMsInput = z.number().int().min(50).max(60_000).optional();
+const HOST_SAFE_TOOL_TIMEOUT_MS = 20_000;
+const HOST_SAFE_TIMEOUT_RESERVE_MS = 750;
+const HOST_SAFE_REVEAL_TIMEOUT_MS = 8_000;
+const MIN_ACTION_TIMEOUT_MS = 50;
+function softTimeoutMsInput() {
+    return z
+        .number()
+        .int()
+        .min(1_000)
+        .max(55_000)
+        .optional()
+        .default(HOST_SAFE_TOOL_TIMEOUT_MS)
+        .describe('Server-side soft deadline for this MCP call. When reached, the tool returns partial progress plus a resume hint before the MCP host request deadline can kill the call.');
+}
+function remainingUntil(deadlineAt) {
+    return Math.max(0, Math.floor(deadlineAt - performance.now()));
+}
+function hasSoftBudget(deadlineAt, reserveMs = HOST_SAFE_TIMEOUT_RESERVE_MS) {
+    return remainingUntil(deadlineAt) > reserveMs;
+}
+function timeoutCapFromDeadline(deadlineAt, reserveMs = HOST_SAFE_TIMEOUT_RESERVE_MS) {
+    return Math.max(MIN_ACTION_TIMEOUT_MS, remainingUntil(deadlineAt) - reserveMs);
+}
+function capTimeoutMs(timeoutMs, capMs, fallbackMs) {
+    return Math.max(MIN_ACTION_TIMEOUT_MS, Math.min(timeoutMs ?? fallbackMs, Math.max(MIN_ACTION_TIMEOUT_MS, Math.floor(capMs))));
+}
+function capFillFieldTimeout(field, capMs, fallbackMs = 5_000) {
+    return {
+        ...field,
+        timeoutMs: capTimeoutMs(field.timeoutMs, capMs, fallbackMs),
+    };
+}
+function capBatchActionTimeouts(action, capMs) {
+    switch (action.type) {
+        case 'click':
+            return {
+                ...action,
+                timeoutMs: capTimeoutMs(action.timeoutMs, capMs, 5_000),
+                revealTimeoutMs: capTimeoutMs(action.revealTimeoutMs, capMs, 2_500),
+                ...(action.waitFor ? { waitFor: { ...action.waitFor, timeoutMs: capTimeoutMs(action.waitFor.timeoutMs, capMs, 10_000) } } : {}),
+            };
+        case 'type':
+        case 'key':
+        case 'select_option':
+        case 'set_checked':
+        case 'wheel':
+            return { ...action, timeoutMs: capTimeoutMs(action.timeoutMs, capMs, 5_000) };
+        case 'upload_files':
+            return { ...action, timeoutMs: capTimeoutMs(action.timeoutMs, capMs, 8_000) };
+        case 'pick_listbox_option':
+            return { ...action, timeoutMs: capTimeoutMs(action.timeoutMs, capMs, 4_500) };
+        case 'wait_for':
+            return { ...action, timeoutMs: capTimeoutMs(action.timeoutMs, capMs, 10_000) };
+        case 'fill_fields':
+            return {
+                ...action,
+                fields: action.fields.map(field => capFillFieldTimeout(field, capMs)),
+            };
+        case 'expand_section':
+            return action;
+    }
+}
 const fillFieldSchema = z.union([
     z.object({
         kind: z.literal('text'),
@@ -339,7 +407,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\`. 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 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.
 
 **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
@@ -371,6 +439,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
             .nonnegative()
             .optional()
             .describe('Playwright slowMo (ms) on spawned proxy for easier visual following.'),
+        stealth: stealthInput(),
         isolated: z
             .boolean()
             .optional()
@@ -444,6 +513,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
                     width: input.width,
                     height: input.height,
                     slowMo: input.slowMo,
+                    ...(input.stealth !== undefined && { stealth: input.stealth }),
                     isolated: input.isolated,
                     proxy: input.proxy,
                     awaitInitialFrame: deferInlinePageModel ? false : undefined,
@@ -516,6 +586,7 @@ Use this when you can prepare ahead of the user-facing task so the next \`geomet
             .nonnegative()
             .optional()
             .describe('Playwright slowMo (ms) for the warmed browser.'),
+        stealth: stealthInput(),
         proxy: z
             .object({
             server: z
@@ -530,9 +601,18 @@ 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, proxy }) => {
+    }, async ({ pageUrl, port, headless, width, height, slowMo, stealth, proxy }) => {
         try {
-            const prepared = await prewarmProxy({ pageUrl, port, headless, width, height, slowMo, proxy });
+            const prepared = await prewarmProxy({
+                pageUrl,
+                port,
+                headless,
+                width,
+                height,
+                slowMo,
+                ...(stealth !== undefined && { stealth }),
+                proxy,
+            });
             return ok(JSON.stringify(prepared));
         }
         catch (e) {
@@ -899,6 +979,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         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(),
         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'),
@@ -936,7 +1017,7 @@ 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, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, isolated, detail, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, formId, valuesById, valuesByLabel, stopOnError, failOnInvalid, includeSteps, resumeFromIndex, verifyFills, skipPreFilled, isolated, detail, sessionId }) => {
         const directFields = !includeSteps && !formId && Object.keys(valuesById ?? {}).length === 0
             ? directLabelBatchFields(valuesByLabel)
             : null;
@@ -949,6 +1030,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             width,
             height,
             slowMo,
+            stealth,
             isolated,
             awaitInitialFrame: directFields ? false : undefined,
         }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_fill_form.');
@@ -1208,6 +1290,7 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         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(),
         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'),
@@ -1217,24 +1300,44 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
         submitTimeoutMs: z.number().int().min(50).max(60_000).optional().default(15_000).describe('Action wait timeout for the submit click (default 15000ms). Increase for slow backends.'),
         waitFor: z.object(waitConditionShape()).optional().describe('Optional semantic condition to wait for after the submit click (success banner, navigation, submit gone, etc.)'),
         skipFill: z.boolean().optional().default(false).describe('Skip the fill phase and go straight to submit+wait. Use when values have already been filled by a previous call.'),
+        softTimeoutMs: softTimeoutMsInput(),
         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, isolated, formId, valuesById, valuesByLabel, submit, submitIndex, submitTimeoutMs, waitFor, skipFill, failOnInvalid, detail, sessionId }) => {
-        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_submit_form.');
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, isolated, formId, valuesById, valuesByLabel, submit, submitIndex, submitTimeoutMs, waitFor, skipFill, softTimeoutMs, failOnInvalid, detail, sessionId }) => {
+        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.');
         if (!resolved.ok)
             return err(resolved.error);
         const session = resolved.session;
         const connection = autoConnectionPayload(resolved);
+        let fillSummary;
+        let fillFallback;
+        const pausedPayload = (phase, resumeHint, extra) => ({
+            ...connection,
+            completed: false,
+            paused: true,
+            phase,
+            pauseReason: 'soft-timeout',
+            softTimeoutMs: effectiveSoftTimeoutMs,
+            elapsedMs: Number((performance.now() - toolStartedAt).toFixed(1)),
+            ...(resumeHint ? { resumeHint } : {}),
+            ...(fillSummary ? { fill: fillSummary } : {}),
+            ...(fillFallback ? { fill_fallback: fillFallback } : {}),
+            ...(extra ?? {}),
+        });
         if (!session.tree || !session.layout) {
-            await waitForUiCondition(session, () => Boolean(session.tree && session.layout), 2_000);
+            await waitForUiCondition(session, () => Boolean(session.tree && session.layout), capTimeoutMs(2_000, timeoutCapFromDeadline(deadlineAt), 2_000));
         }
         const entryA11y = sessionA11y(session);
         if (!entryA11y)
             return err('No UI tree available for form submission');
         const entryUrl = entryA11y.meta?.pageUrl;
-        let fillSummary;
-        let fillFallback;
+        if (!hasSoftBudget(deadlineAt)) {
+            return ok(JSON.stringify(pausedPayload('before-fill', { retrySameCall: true }), null, detail === 'verbose' ? 2 : undefined));
+        }
         if (!skipFill) {
             const entryCount = Object.keys(valuesById ?? {}).length + Object.keys(valuesByLabel ?? {}).length;
             if (entryCount === 0) {
@@ -1253,16 +1356,26 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             let usedBatch = true;
             try {
                 const startRevision = session.updateRevision;
-                const wait = await sendFillFields(session, planned.fields);
+                const wait = await sendFillFields(session, planned.fields.map(field => capFillFieldTimeout(field, timeoutCapFromDeadline(deadlineAt))), capTimeoutMs(undefined, timeoutCapFromDeadline(deadlineAt), HOST_SAFE_TOOL_TIMEOUT_MS));
                 const ack = parseProxyFillAckResult(wait.result);
                 await waitForDeferredBatchUpdate(session, startRevision, wait);
                 fillSummary = {
                     formId: schema.formId,
                     execution: 'batched',
                     fieldCount: planned.fields.length,
+                    ...waitStatusPayload(wait),
                     ...(ack ? { invalidCount: ack.invalidCount, alertCount: ack.alertCount } : {}),
                     ...(entryCount !== planned.fields.length ? { requestedValueCount: entryCount } : {}),
                 };
+                if (wait.status === 'timed_out') {
+                    return ok(JSON.stringify(pausedPayload('fill', {
+                        tool: 'geometra_submit_form',
+                        skipFill: true,
+                        submit: submit ?? { role: 'button', name: 'Submit' },
+                        submitIndex,
+                        ...(waitFor ? { waitFor } : {}),
+                    }), null, detail === 'verbose' ? 2 : undefined));
+                }
             }
             catch (e) {
                 if (!canFallbackToSequentialFill(e)) {
@@ -1276,8 +1389,24 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                 let successCount = 0;
                 let firstErr;
                 for (const field of planned.fields) {
+                    if (!hasSoftBudget(deadlineAt)) {
+                        fillSummary = {
+                            formId: schema.formId,
+                            execution: 'sequential',
+                            fieldCount: planned.fields.length,
+                            successCount,
+                            ...(entryCount !== planned.fields.length ? { requestedValueCount: entryCount } : {}),
+                        };
+                        return ok(JSON.stringify(pausedPayload('fill', {
+                            tool: 'geometra_submit_form',
+                            skipFill: true,
+                            submit: submit ?? { role: 'button', name: 'Submit' },
+                            submitIndex,
+                            ...(waitFor ? { waitFor } : {}),
+                        }), null, detail === 'verbose' ? 2 : undefined));
+                    }
                     try {
-                        await executeFillField(session, field, detail);
+                        await executeFillField(session, capFillFieldTimeout(field, timeoutCapFromDeadline(deadlineAt)), detail);
                         successCount += 1;
                     }
                     catch (e) {
@@ -1297,12 +1426,22 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                 };
             }
         }
+        const submitResumeHint = {
+            tool: 'geometra_submit_form',
+            skipFill: true,
+            submit: submit ?? { role: 'button', name: 'Submit' },
+            submitIndex,
+            ...(waitFor ? { waitFor } : {}),
+        };
+        if (!hasSoftBudget(deadlineAt)) {
+            return ok(JSON.stringify(pausedPayload('submit', submitResumeHint), null, detail === 'verbose' ? 2 : undefined));
+        }
         const submitFilter = submit ?? { role: 'button', name: 'Submit' };
         const resolvedClick = await resolveClickLocationWithFallback(session, {
             filter: submitFilter,
             index: submitIndex,
             fullyVisible: true,
-            revealTimeoutMs: 2_500,
+            revealTimeoutMs: capTimeoutMs(2_500, timeoutCapFromDeadline(deadlineAt), 2_500),
         });
         if (!resolvedClick.ok) {
             const payload = {
@@ -1315,10 +1454,44 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
             };
             return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
         }
+        if (!hasSoftBudget(deadlineAt)) {
+            return ok(JSON.stringify(pausedPayload('submit', submitResumeHint), null, detail === 'verbose' ? 2 : undefined));
+        }
         const beforeSubmit = sessionA11y(session);
-        const clickWait = await sendClick(session, resolvedClick.value.x, resolvedClick.value.y, submitTimeoutMs);
+        const clickWait = await sendClick(session, resolvedClick.value.x, resolvedClick.value.y, capTimeoutMs(submitTimeoutMs, timeoutCapFromDeadline(deadlineAt), 15_000));
         let waitResult;
         if (waitFor) {
+            if (!hasSoftBudget(deadlineAt)) {
+                return ok(JSON.stringify(pausedPayload('wait_for', {
+                    tool: 'geometra_wait_for',
+                    filter: compactFilterPayload({
+                        id: waitFor.id,
+                        role: waitFor.role,
+                        name: waitFor.name,
+                        text: waitFor.text,
+                        contextText: waitFor.contextText,
+                        promptText: waitFor.promptText,
+                        sectionText: waitFor.sectionText,
+                        itemText: waitFor.itemText,
+                        value: waitFor.value,
+                        checked: waitFor.checked,
+                        disabled: waitFor.disabled,
+                        focused: waitFor.focused,
+                        selected: waitFor.selected,
+                        expanded: waitFor.expanded,
+                        invalid: waitFor.invalid,
+                        required: waitFor.required,
+                        busy: waitFor.busy,
+                    }),
+                    present: waitFor.present ?? true,
+                }, {
+                    submit: {
+                        at: { x: resolvedClick.value.x, y: resolvedClick.value.y },
+                        ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target) } : {}),
+                        ...waitStatusPayload(clickWait),
+                    },
+                }), null, detail === 'verbose' ? 2 : undefined));
+            }
             const postWait = await waitForSemanticCondition(session, {
                 filter: {
                     id: waitFor.id,
@@ -1340,7 +1513,7 @@ Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: tr
                     busy: waitFor.busy,
                 },
                 present: waitFor.present ?? true,
-                timeoutMs: waitFor.timeoutMs ?? 15_000,
+                timeoutMs: capTimeoutMs(waitFor.timeoutMs, timeoutCapFromDeadline(deadlineAt), 15_000),
             });
             if (!postWait.ok) {
                 const preErrFallbacks = [];
@@ -1420,12 +1593,21 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         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(),
         isolated: z
             .boolean()
             .optional()
             .default(false)
             .describe('When auto-connecting via pageUrl/url, request an isolated proxy. See geometra_connect for details.'),
         actions: z.array(batchActionSchema).min(1).max(80).describe('Ordered high-level action steps to run sequentially'),
+        resumeFromIndex: z
+            .number()
+            .int()
+            .min(0)
+            .optional()
+            .default(0)
+            .describe('Resume a previous partial geometra_run_actions result from this action index. Use the returned resumeFromIndex when a call pauses.'),
+        softTimeoutMs: softTimeoutMsInput(),
         stopOnError: z.boolean().optional().default(true).describe('Stop at the first failing step (default true)'),
         includeSteps: z
             .boolean()
@@ -1435,7 +1617,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, isolated, actions, stopOnError, includeSteps, output, detail, sessionId }) => {
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, stealth, isolated, actions, resumeFromIndex, softTimeoutMs, stopOnError, includeSteps, output, detail, sessionId }) => {
+        const toolStartedAt = performance.now();
+        const effectiveSoftTimeoutMs = softTimeoutMs ?? HOST_SAFE_TOOL_TIMEOUT_MS;
+        const deadlineAt = toolStartedAt + effectiveSoftTimeoutMs;
         const resolved = await ensureToolSession({
             sessionId,
             url,
@@ -1445,6 +1630,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
             width,
             height,
             slowMo,
+            stealth,
             isolated,
             awaitInitialFrame: canDeferInitialFrameForRunActions(actions) ? false : undefined,
         }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_run_actions.');
@@ -1452,23 +1638,36 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
             return err(resolved.error);
         const session = resolved.session;
         const connection = autoConnectionPayload(resolved);
+        const startIndex = resumeFromIndex ?? 0;
+        if (startIndex > actions.length) {
+            return err(`resumeFromIndex ${startIndex} exceeds actions length ${actions.length}`);
+        }
         const steps = [];
         let stoppedAt;
+        let pausedAt;
         const batchStartedAt = performance.now();
         // Collect transparent-fallback signals from each step so run_actions
         // surfaces them at top level regardless of `includeSteps` — otherwise
         // the telemetry is dead code when callers opt out of the steps listing.
         const fallbackRecords = [];
-        for (let index = 0; index < actions.length; index++) {
-            const action = actions[index];
+        for (let index = startIndex; index < actions.length; index++) {
+            if (!hasSoftBudget(deadlineAt)) {
+                pausedAt = index;
+                break;
+            }
+            const action = capBatchActionTimeouts(actions[index], timeoutCapFromDeadline(deadlineAt));
             const startedAt = performance.now();
             let uiTreeWaitMs = 0;
             try {
                 if (actionNeedsUiTree(action) && (!session.tree || !session.layout)) {
                     const uiTreeWaitStartedAt = performance.now();
-                    await waitForUiCondition(session, () => Boolean(session.tree && session.layout), 2_000);
+                    await waitForUiCondition(session, () => Boolean(session.tree && session.layout), capTimeoutMs(2_000, timeoutCapFromDeadline(deadlineAt), 2_000));
                     uiTreeWaitMs = performance.now() - uiTreeWaitStartedAt;
                 }
+                if (!hasSoftBudget(deadlineAt)) {
+                    pausedAt = index;
+                    break;
+                }
                 const result = await executeBatchAction(session, action, detail, includeSteps);
                 const stepFallback = result.compact.fallback;
                 if (stepFallback?.used) {
@@ -1511,6 +1710,10 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
                         ...result.compact,
                         ...(stepSignals ? { signals: stepSignals } : {}),
                     });
+                if (index + 1 < actions.length && !hasSoftBudget(deadlineAt)) {
+                    pausedAt = index + 1;
+                    break;
+                }
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
@@ -1534,20 +1737,37 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         const after = sessionA11y(session);
         const successCount = steps.filter(step => step.ok === true).length;
         const errorCount = steps.length - successCount;
+        const elapsedMs = Number((performance.now() - toolStartedAt).toFixed(1));
+        const completed = stoppedAt === undefined && pausedAt === undefined && startIndex + steps.length >= actions.length;
+        const resumePayload = {
+            ...(startIndex > 0 ? { resumedFromIndex: startIndex } : {}),
+            ...(pausedAt !== undefined
+                ? {
+                    paused: true,
+                    pausedAt,
+                    resumeFromIndex: pausedAt,
+                    pauseReason: 'soft-timeout',
+                    softTimeoutMs: effectiveSoftTimeoutMs,
+                    elapsedMs,
+                }
+                : {}),
+        };
         const payload = output === 'final'
             ? {
                 ...connection,
-                completed: stoppedAt === undefined && steps.length === actions.length,
+                completed,
+                ...resumePayload,
                 ...(stoppedAt !== undefined ? { stoppedAt } : {}),
                 ...(fallbackRecords.length > 0 ? { fallbacks: fallbackRecords } : {}),
                 ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after), detail) } : {}),
             }
             : {
                 ...connection,
-                completed: stoppedAt === undefined && steps.length === actions.length,
+                completed,
                 stepCount: actions.length,
                 successCount,
                 errorCount,
+                ...resumePayload,
                 ...(includeSteps ? { steps } : {}),
                 ...(stoppedAt !== undefined ? { stoppedAt } : {}),
                 ...(fallbackRecords.length > 0 ? { fallbacks: fallbackRecords } : {}),
@@ -1603,6 +1823,7 @@ Unlike geometra_expand_section, this collapses repeated radio/button groups into
         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(),
         isolated: z
             .boolean()
             .optional()
@@ -1617,8 +1838,8 @@ 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, isolated, formId, maxFields, onlyRequiredFields, onlyInvalidFields, includeOptions, includeContext, sinceSchemaId, format, sessionId }) => {
-        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_form_schema.');
+    }, 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.');
         if (!resolved.ok)
             return err(resolved.error);
         const session = resolved.session;
@@ -2655,6 +2876,7 @@ async function ensureToolSession(target, missingConnectionMessage = 'Not connect
                 width: target.width,
                 height: target.height,
                 slowMo: target.slowMo,
+                ...(target.stealth !== undefined && { stealth: target.stealth }),
                 awaitInitialFrame: target.awaitInitialFrame,
                 isolated: target.isolated,
             });
@@ -2994,13 +3216,21 @@ function inferRevealStepBudget(target, viewport) {
     return clamp(Math.max(6, Math.max(verticalSteps, horizontalSteps) + 1), 6, 48);
 }
 async function revealSemanticTarget(session, options) {
-    const initialTreeReady = await ensureSessionUiTree(session, Math.max(4_000, options.timeoutMs));
+    const revealStartedAt = performance.now();
+    const revealDeadlineAt = revealStartedAt + HOST_SAFE_REVEAL_TIMEOUT_MS;
+    const initialTreeReady = await ensureSessionUiTree(session, capTimeoutMs(Math.max(4_000, options.timeoutMs), timeoutCapFromDeadline(revealDeadlineAt, 100), HOST_SAFE_REVEAL_TIMEOUT_MS));
     if (!initialTreeReady) {
         return { ok: false, error: 'Timed out waiting for the initial UI tree after connect.' };
     }
     let attempts = 0;
     let stepBudget = options.maxSteps;
     while (attempts <= (stepBudget ?? 48)) {
+        if (!hasSoftBudget(revealDeadlineAt, 100)) {
+            return {
+                ok: false,
+                error: `Reveal exceeded the host-safe ${HOST_SAFE_REVEAL_TIMEOUT_MS}ms budget after ${attempts} step(s). Retry with a more specific filter/id or reveal the target in smaller geometra_scroll_to calls.`,
+            };
+        }
         const a11y = sessionA11y(session);
         if (!a11y)
             return { ok: false, error: 'No UI tree available to reveal from' };
@@ -3046,7 +3276,7 @@ async function revealSemanticTarget(session, options) {
             deltaX,
             x: formatted.center.x,
             y: formatted.center.y,
-        }, options.timeoutMs);
+        }, capTimeoutMs(options.timeoutMs, timeoutCapFromDeadline(revealDeadlineAt, 100), 2_500));
         attempts++;
     }
     return { ok: false, error: `Failed to reveal ${JSON.stringify(options.filter)}` };

package/dist/session.d.ts

@@ -488,6 +488,7 @@ export declare function prewarmProxy(options: {
     pageUrl: string;
     port?: number;
     headless?: boolean;
+    stealth?: boolean;
     width?: number;
     height?: number;
     slowMo?: number;
@@ -499,6 +500,7 @@ export declare function prewarmProxy(options: {
     pageUrl: string;
     wsUrl: string;
     headless: boolean;
+    stealth: boolean;
     width: number;
     height: number;
 }>;
@@ -524,6 +526,7 @@ export declare function connectThroughProxy(options: {
     width?: number;
     height?: number;
     slowMo?: number;
+    stealth?: boolean;
     awaitInitialFrame?: boolean;
     eagerInitialExtract?: boolean;
     /**

package/dist/session.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import WebSocket from 'ws';
-import { spawnGeometraProxy, startEmbeddedGeometraProxy } from './proxy-spawn.js';
+import { resolveStealthMode, spawnGeometraProxy, startEmbeddedGeometraProxy, } from './proxy-spawn.js';
 import { completeSessionLifecycle, failSessionLifecycle, heartbeatSessionLifecycle, initializeSessionLifecycle, recordSessionSnapshot, } from './session-state.js';
 /**
  * Stable identity for an outbound proxy config, used as the reusable-pool
@@ -143,10 +143,12 @@ function setReusableProxy(proxy, wsUrl, opts) {
     clearReusableProxiesIfExited();
     const now = Date.now();
     const proxyKey = proxyKeyFor(opts.proxy);
+    const stealth = resolveStealthMode(opts.stealth);
     const existing = reusableProxies.find(entry => sameReusableProxyEntry(entry, proxy));
     if (existing) {
         existing.wsUrl = wsUrl;
         existing.headless = opts.headless === true;
+        existing.stealth = stealth;
         existing.slowMo = opts.slowMo ?? 0;
         existing.width = opts.width ?? 1280;
         existing.height = opts.height ?? 720;
@@ -162,6 +164,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
             child,
             wsUrl,
             headless: opts.headless === true,
+            stealth,
             slowMo: opts.slowMo ?? 0,
             width: opts.width ?? 1280,
             height: opts.height ?? 720,
@@ -188,6 +191,7 @@ function setReusableProxy(proxy, wsUrl, opts) {
         runtime: proxy.runtime,
         wsUrl,
         headless: opts.headless === true,
+        stealth,
         slowMo: opts.slowMo ?? 0,
         width: opts.width ?? 1280,
         height: opts.height ?? 720,
@@ -405,6 +409,7 @@ function stopSessionHeartbeat(session) {
 function reusableProxyMatchesOptions(entry, options) {
     return (entry.pageUrl === options.pageUrl &&
         entry.headless === (options.headless === true) &&
+        entry.stealth === resolveStealthMode(options.stealth) &&
         entry.slowMo === (options.slowMo ?? 0) &&
         entry.width === (options.width ?? 1280) &&
         entry.height === (options.height ?? 720) &&
@@ -422,12 +427,14 @@ function findExactReusableProxy(options) {
 function findReusableProxy(options) {
     clearReusableProxiesIfExited();
     const desiredHeadless = options.headless === true;
+    const desiredStealth = resolveStealthMode(options.stealth);
     const desiredSlowMo = options.slowMo ?? 0;
     const desiredWidth = options.width ?? 1280;
     const desiredHeight = options.height ?? 720;
     const desiredProxyKey = proxyKeyFor(options.proxy);
     return reusableProxies
         .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).
@@ -459,6 +466,7 @@ export async function prewarmProxy(options) {
             pageUrl: options.pageUrl,
             wsUrl: existing.wsUrl,
             headless: options.headless === true,
+            stealth: resolveStealthMode(options.stealth),
             width: options.width ?? 1280,
             height: options.height ?? 720,
         };
@@ -472,6 +480,7 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             proxy: options.proxy,
         });
         try {
@@ -484,6 +493,7 @@ export async function prewarmProxy(options) {
         setReusableProxy({ runtime }, wsUrl, {
             headless: options.headless,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             width: options.width,
             height: options.height,
             pageUrl: options.pageUrl,
@@ -497,6 +507,7 @@ export async function prewarmProxy(options) {
             pageUrl: options.pageUrl,
             wsUrl,
             headless: options.headless === true,
+            stealth: resolveStealthMode(options.stealth),
             width: options.width ?? 1280,
             height: options.height ?? 720,
         };
@@ -512,11 +523,13 @@ export async function prewarmProxy(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             proxy: options.proxy,
         });
         setReusableProxy({ child }, wsUrl, {
             headless: options.headless,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             width: options.width,
             height: options.height,
             pageUrl: options.pageUrl,
@@ -529,6 +542,7 @@ export async function prewarmProxy(options) {
             pageUrl: options.pageUrl,
             wsUrl,
             headless: options.headless === true,
+            stealth: resolveStealthMode(options.stealth),
             width: options.width ?? 1280,
             height: options.height ?? 720,
         };
@@ -621,6 +635,7 @@ async function startFreshProxySession(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             eagerInitialExtract,
             proxy: options.proxy,
         });
@@ -649,6 +664,7 @@ async function startFreshProxySession(options) {
             setReusableProxy({ runtime }, wsUrl, {
                 headless: options.headless,
                 slowMo: options.slowMo,
+                stealth: options.stealth,
                 width: options.width,
                 height: options.height,
                 pageUrl: options.pageUrl,
@@ -695,6 +711,7 @@ async function startFreshProxySession(options) {
             width: options.width,
             height: options.height,
             slowMo: options.slowMo,
+            stealth: options.stealth,
             eagerInitialExtract,
             proxy: options.proxy,
         });
@@ -717,6 +734,7 @@ async function startFreshProxySession(options) {
                 setReusableProxy({ child }, wsUrl, {
                     headless: options.headless,
                     slowMo: options.slowMo,
+                    stealth: options.stealth,
                     width: options.width,
                     height: options.height,
                     pageUrl: options.pageUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.61.1",
+  "version": "1.61.3",
   "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.61.1",
+    "@geometra/proxy": "^1.61.3",
     "@modelcontextprotocol/sdk": "^1.12.1",
     "@razroo/parallel-mcp": "^0.1.0",
     "ws": "^8.18.0",