@geometra/mcp 1.52.0 → 1.54.0

package/dist/__tests__/server-batch-results.test.js

@@ -982,6 +982,279 @@ describe('batch MCP result shaping', () => {
         });
     });
 });
+describe('submit_form tool', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        resetMockSessionCaches();
+        mockState.formSchemas = [];
+    });
+    it('combines fill + submit-click + post-submit wait in one call', async () => {
+        const handler = getToolHandler('geometra_submit_form');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('textbox', 'Full name', { value: '', path: [0] }),
+                node('textbox', 'Email', { value: '', path: [1] }),
+                node('button', 'Submit application', {
+                    bounds: { x: 60, y: 480, width: 180, height: 40 },
+                    path: [2],
+                }),
+            ],
+        });
+        mockState.formSchemas = [{
+                formId: 'fm:0',
+                name: 'Application',
+                fieldCount: 2,
+                requiredCount: 2,
+                invalidCount: 2,
+                fields: [
+                    { id: 'ff:0.0', kind: 'text', label: 'Full name' },
+                    { id: 'ff:0.1', kind: 'text', label: 'Email' },
+                ],
+            }];
+        mockState.sendFillFields.mockImplementationOnce(async () => ({
+            status: 'acknowledged',
+            timeoutMs: 6000,
+            result: { invalidCount: 0, alertCount: 0, dialogCount: 0, busyCount: 0, pageUrl: 'https://jobs.example.com/application' },
+        }));
+        mockState.sendClick.mockImplementationOnce(async () => {
+            mockState.currentA11yRoot = node('group', undefined, {
+                bounds: { x: 0, y: 0, width: 1280, height: 800 },
+                meta: { pageUrl: 'https://jobs.example.com/confirm', scrollX: 0, scrollY: 0 },
+                children: [
+                    node('dialog', 'Application submitted', {
+                        bounds: { x: 240, y: 140, width: 420, height: 260 },
+                        path: [0],
+                    }),
+                ],
+            });
+            bumpMockUiRevision();
+            return { status: 'updated', timeoutMs: 2000 };
+        });
+        const result = await handler({
+            valuesByLabel: { 'Full name': 'Taylor Applicant', Email: 'taylor@example.com' },
+            submit: { role: 'button', name: 'Submit application' },
+            waitFor: { role: 'dialog', name: 'Application submitted', timeoutMs: 5000 },
+            detail: 'minimal',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            completed: true,
+            fill: { fieldCount: 2, formId: 'fm:0' },
+            submit: { target: { role: 'button', name: 'Submit application' } },
+            waitFor: { present: true, matchCount: 1 },
+            navigated: true,
+            afterUrl: 'https://jobs.example.com/confirm',
+        });
+        expect(mockState.sendFillFields).toHaveBeenCalledTimes(1);
+        expect(mockState.sendClick).toHaveBeenCalledTimes(1);
+    });
+    it('rejects missing values when skipFill is false', async () => {
+        const handler = getToolHandler('geometra_submit_form');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('button', 'Submit', { bounds: { x: 60, y: 480, width: 100, height: 40 }, path: [0] }),
+            ],
+        });
+        const result = await handler({ detail: 'minimal' });
+        expect(result.content[0].text).toContain('Provide at least one value');
+    });
+    it('skipFill: true goes straight to submit + wait', async () => {
+        const handler = getToolHandler('geometra_submit_form');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('button', 'Submit', { bounds: { x: 60, y: 480, width: 100, height: 40 }, path: [0] }),
+            ],
+        });
+        mockState.sendClick.mockImplementationOnce(async () => {
+            bumpMockUiRevision();
+            return { status: 'updated', timeoutMs: 2000 };
+        });
+        const result = await handler({
+            skipFill: true,
+            submit: { role: 'button', name: 'Submit' },
+            detail: 'minimal',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({ completed: true });
+        expect(payload).not.toHaveProperty('fill');
+        expect(mockState.sendFillFields).not.toHaveBeenCalled();
+        expect(mockState.sendClick).toHaveBeenCalledTimes(1);
+    });
+});
+describe('fill transparent fallback', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        resetMockSessionCaches();
+    });
+    it('geometra_run_actions aggregates step-level fill fallback metadata into top-level fallbacks', async () => {
+        const handler = getToolHandler('geometra_run_actions');
+        mockState.currentA11yRoot = node('group', undefined, {
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('textbox', 'Full name', { value: '', path: [0] }),
+            ],
+        });
+        // Force the batched path to reject with a recoverable error so the
+        // fill_fields step falls through to the sequential loop and tags the step.
+        mockState.sendFillFields.mockRejectedValue(new Error('Unsupported client message type "fillFields"'));
+        // includeSteps:false makes the fill_fields step handler prefer the batched
+        // fast-path. When that path is unavailable, the step flips to sequential
+        // and emits fallback metadata that run_actions lifts into the top-level
+        // `fallbacks` array.
+        const result = await handler({
+            actions: [
+                {
+                    type: 'fill_fields',
+                    fields: [{ kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' }],
+                },
+            ],
+            stopOnError: true,
+            includeSteps: false,
+            detail: 'minimal',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            completed: true,
+            stepCount: 1,
+            successCount: 1,
+            fallbacks: [
+                { stepIndex: 0, type: 'fill_fields', attempted: true, used: true, reason: 'batched-unavailable', attempts: 2 },
+            ],
+        });
+    });
+    it('geometra_fill_fields surfaces fallback metadata when the batched path is unavailable', async () => {
+        const handler = getToolHandler('geometra_fill_fields');
+        mockState.currentA11yRoot = node('group', undefined, {
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('textbox', 'Full name', { value: '', path: [0] }),
+            ],
+        });
+        // Force the batched path to throw a recoverable error so the handler
+        // falls through to the sequential loop and tags the fallback.
+        mockState.sendFillFields.mockRejectedValueOnce(new Error('Unsupported client message type "fillFields"'));
+        const result = await handler({
+            fields: [{ kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' }],
+            stopOnError: true,
+            failOnInvalid: false,
+            includeSteps: false,
+            detail: 'minimal',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            completed: true,
+            fieldCount: 1,
+            successCount: 1,
+            errorCount: 0,
+            fallback: { attempted: true, used: true, reason: 'batched-unavailable', attempts: 2 },
+        });
+    });
+    it('geometra_fill_form surfaces fallback metadata when batched throws recoverable error', async () => {
+        const handler = getToolHandler('geometra_fill_form');
+        mockState.currentA11yRoot = node('group', undefined, {
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('textbox', 'Full name', { value: '', path: [0] }),
+            ],
+        });
+        mockState.formSchemas = [{
+                formId: 'fm:0',
+                name: 'Application',
+                fieldCount: 1,
+                requiredCount: 1,
+                invalidCount: 1,
+                fields: [
+                    { id: 'ff:0.0', kind: 'text', label: 'Full name' },
+                ],
+            }];
+        // Both the batched-direct path and the schema-backed batched path call
+        // sendFillFields. Reject all calls so both hit the recoverable-error
+        // branch and the handler lands in the sequential loop.
+        mockState.sendFillFields.mockRejectedValue(new Error('Unsupported client message type "fillFields"'));
+        const result = await handler({
+            valuesByLabel: { 'Full name': 'Taylor Applicant' },
+            includeSteps: false,
+            detail: 'minimal',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            execution: 'sequential',
+            fallback: { attempted: true, used: true, reason: 'batched-threw', attempts: 2 },
+        });
+    });
+});
+describe('click transparent fallback', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        resetMockSessionCaches();
+    });
+    it('surfaces fallback.attempted:false when click fallback attempted and failed', async () => {
+        const handler = getToolHandler('geometra_click');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [],
+        });
+        const result = await handler({
+            role: 'button',
+            name: 'Does not exist',
+            fullyVisible: true,
+            maxRevealSteps: 1,
+            revealTimeoutMs: 50,
+            detail: 'terse',
+        });
+        // Fallback was attempted (both revision-retry — if mockWaitForUiCondition
+        // returns true — and relaxed-visibility) but neither phase recovered the
+        // missing target, so the handler returns a structured error carrying the
+        // attempted-but-failed telemetry.
+        const errorText = result.content[0].text;
+        expect(errorText).toContain('"fallback"');
+        const parsed = JSON.parse(errorText);
+        expect(parsed.fallback).toMatchObject({ attempted: true, used: false });
+        expect(parsed.fallback.reasonsTried.length).toBeGreaterThan(0);
+    });
+    it('surfaces fallback.used when relaxed-visibility lets an offscreen submit resolve', async () => {
+        const handler = getToolHandler('geometra_click');
+        // First tree: target exists but is offscreen below the viewport, so a
+        // fullyVisible requirement cannot be satisfied before the reveal budget runs out.
+        // The relaxed-visibility fallback drops the fullyVisible requirement and tries
+        // once more with a larger reveal budget.
+        const offscreenTree = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('button', 'Submit', {
+                    // Starts fully offscreen-below and wheel stubs don't move it in tests,
+                    // so the fullyVisible attempt will fail. Relaxed-visibility sees it
+                    // intersect enough to count as revealed.
+                    bounds: { x: 60, y: 780, width: 180, height: 60 },
+                    path: [0],
+                }),
+            ],
+        });
+        mockState.currentA11yRoot = offscreenTree;
+        mockState.sendClick.mockResolvedValueOnce({ status: 'updated', timeoutMs: 2000 });
+        const result = await handler({
+            role: 'button',
+            name: 'Submit',
+            fullyVisible: true,
+            maxRevealSteps: 1,
+            revealTimeoutMs: 100,
+            detail: 'terse',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            target: { role: 'button', name: 'Submit' },
+            fallback: { attempted: true, used: true, reason: 'relaxed-visibility' },
+        });
+    });
+});
 describe('query and reveal tools', () => {
     beforeEach(() => {
         vi.clearAllMocks();

package/dist/server.js

@@ -330,7 +330,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
     }),
 ]);
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.21' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.23' }, { capabilities: { tools: {} } });
     const sessionIdInput = z.string().optional().describe('Session identifier returned by geometra_connect. Omit to use the most recent session.');
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
@@ -774,6 +774,7 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         const resolvedFields = resolveFillFieldInputs(session, fields);
         if (!resolvedFields.ok)
             return err(resolvedFields.error);
+        let fallbackFromBatch;
         if (!includeSteps) {
             try {
                 const batched = await tryBatchedResolvedFields(session, resolvedFields.fields, detail);
@@ -792,6 +793,10 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
                     }
                     return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
                 }
+                // Batched path returned {ok: false} — this is the transparent fallback
+                // case. Continue into the sequential loop and mark the result so
+                // operators can aggregate how often it fires.
+                fallbackFromBatch = { attempted: true, used: true, reason: 'batched-unavailable', attempts: 2 };
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
@@ -847,6 +852,7 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
             errorCount,
             ...(includeSteps ? { steps } : {}),
             ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+            ...(fallbackFromBatch ? { fallback: fallbackFromBatch } : {}),
             ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
         };
         if (failOnInvalid && invalidRemaining > 0) {
@@ -1017,6 +1023,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                 planned.fields = planned.planned.map(p => p.field);
             }
         }
+        let fallbackFromBatch;
         if (!includeSteps) {
             let usedBatch = false;
             let batchAckResult;
@@ -1050,6 +1057,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                     const message = e instanceof Error ? e.message : String(e);
                     return err(message);
                 }
+                fallbackFromBatch = { attempted: true, used: true, reason: 'batched-threw', attempts: 2 };
             }
             if (usedBatch) {
                 const after = sessionA11y(session);
@@ -1057,6 +1065,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
                 const invalidRemaining = signals?.invalidFields.length ?? 0;
                 if ((!batchAckResult || batchAckResult.invalidCount > 0) && invalidRemaining > 0) {
                     usedBatch = false;
+                    fallbackFromBatch = { attempted: true, used: true, reason: 'batched-invalid-readback', attempts: 2 };
                 }
             }
             if (usedBatch) {
@@ -1131,6 +1140,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
             ...(startIndex > 0 ? { resumedFromIndex: startIndex } : {}),
             ...(includeSteps ? { steps } : {}),
             ...(stoppedAt !== undefined ? { stoppedAt, resumeFromIndex: stoppedAt + 1 } : {}),
+            ...(fallbackFromBatch ? { fallback: fallbackFromBatch } : {}),
             ...(verification ? { verification } : {}),
             ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
         };
@@ -1156,6 +1166,164 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         }
         return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
     });
+    // ── fill + submit + wait ──────────────────────────────────────
+    server.tool('geometra_submit_form', `Fill a form, click its submit button, and optionally wait for the post-submit UI state — all in one MCP call. This is the preferred path for the canonical ATS / sign-in flow when the whole sequence should run server-side.
+
+Pass \`valuesById\` or \`valuesByLabel\` to populate fields, \`submit\` to target the submit button (default: semantic \`{ role: 'button', name: 'Submit' }\`), and \`waitFor\` to block on the post-submit state (success banner, navigation, submit button gone, etc.). Navigation is detected automatically and surfaced as \`navigated: true\` with \`afterUrl\`.
+
+Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: true\` for safe parallel submissions.`, {
+        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).'),
+        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.'),
+        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'),
+        valuesByLabel: formValuesRecordSchema.optional().describe('Form values keyed by schema field label'),
+        submit: z.object(nodeFilterShape()).optional().describe('Semantic target for the submit button. Defaults to {role: "button", name: "Submit"}.'),
+        submitIndex: z.number().int().min(0).optional().default(0).describe('Which matching submit target to click after sorting top-to-bottom (default 0)'),
+        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.'),
+        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.');
+        if (!resolved.ok)
+            return err(resolved.error);
+        const session = resolved.session;
+        const connection = autoConnectionPayload(resolved);
+        if (!session.tree || !session.layout) {
+            await waitForUiCondition(session, () => Boolean(session.tree && session.layout), 2_000);
+        }
+        const entryA11y = sessionA11y(session);
+        if (!entryA11y)
+            return err('No UI tree available for form submission');
+        const entryUrl = entryA11y.meta?.pageUrl;
+        let fillSummary;
+        if (!skipFill) {
+            const entryCount = Object.keys(valuesById ?? {}).length + Object.keys(valuesByLabel ?? {}).length;
+            if (entryCount === 0) {
+                return err('Provide at least one value in valuesById or valuesByLabel, or set skipFill: true to submit already-filled values.');
+            }
+            const schemas = getSessionFormSchemas(session, { includeOptions: true, includeContext: 'auto' });
+            if (schemas.length === 0)
+                return err('No forms found in the current UI');
+            const resolution = resolveTargetFormSchema(schemas, { formId, valuesById, valuesByLabel });
+            if (!resolution.ok)
+                return err(resolution.error);
+            const schema = resolution.schema;
+            const planned = planFormFill(schema, { valuesById, valuesByLabel });
+            if (!planned.ok)
+                return err(planned.error);
+            try {
+                const startRevision = session.updateRevision;
+                const wait = await sendFillFields(session, planned.fields);
+                const ack = parseProxyFillAckResult(wait.result);
+                await waitForDeferredBatchUpdate(session, startRevision, wait);
+                fillSummary = {
+                    formId: schema.formId,
+                    fieldCount: planned.fields.length,
+                    ...(ack ? { invalidCount: ack.invalidCount, alertCount: ack.alertCount } : {}),
+                    ...(entryCount !== planned.fields.length ? { requestedValueCount: entryCount } : {}),
+                };
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return err(`Failed to fill form before submit: ${message}`);
+            }
+        }
+        const submitFilter = submit ?? { role: 'button', name: 'Submit' };
+        const resolvedClick = await resolveClickLocation(session, {
+            filter: submitFilter,
+            index: submitIndex,
+            fullyVisible: true,
+            revealTimeoutMs: 2_500,
+        });
+        if (!resolvedClick.ok)
+            return err(`Submit target not found: ${resolvedClick.error}`);
+        const beforeSubmit = sessionA11y(session);
+        const clickWait = await sendClick(session, resolvedClick.value.x, resolvedClick.value.y, submitTimeoutMs);
+        let waitResult;
+        if (waitFor) {
+            const postWait = await waitForSemanticCondition(session, {
+                filter: {
+                    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,
+                timeoutMs: waitFor.timeoutMs ?? 15_000,
+            });
+            if (!postWait.ok) {
+                const payload = {
+                    ...connection,
+                    completed: false,
+                    ...(fillSummary ? { fill: fillSummary } : {}),
+                    submit: {
+                        at: { x: resolvedClick.value.x, y: resolvedClick.value.y },
+                        ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target) } : {}),
+                        ...waitStatusPayload(clickWait),
+                    },
+                    waitFor: { ok: false, error: postWait.error },
+                };
+                return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+            }
+            waitResult = postWait.value;
+        }
+        const after = sessionA11y(session);
+        const signals = after ? collectSessionSignals(after) : undefined;
+        const afterUrl = after?.meta?.pageUrl;
+        const navigated = Boolean(afterUrl && entryUrl && afterUrl !== entryUrl);
+        const payload = {
+            ...connection,
+            completed: true,
+            ...(fillSummary ? { fill: fillSummary } : {}),
+            submit: {
+                at: { x: resolvedClick.value.x, y: resolvedClick.value.y },
+                ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target), revealSteps: resolvedClick.value.revealAttempts ?? 0 } : {}),
+                ...waitStatusPayload(clickWait),
+            },
+            ...(waitResult ? { waitFor: waitConditionCompact(waitResult) } : {}),
+            ...(navigated ? { navigated: true, afterUrl } : {}),
+            ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
+        };
+        // Pull in page model hints on navigation to mirror fill_form behavior.
+        if (navigated && after) {
+            const model = buildPageModel(after);
+            if (model.captcha)
+                payload.captcha = model.captcha;
+            if (model.verification)
+                payload.verification = model.verification;
+        }
+        if (failOnInvalid && signals && signals.invalidFields.length > 0) {
+            return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+        }
+        // Swallow the unused `beforeSubmit` binding; it anchors that the a11y tree was
+        // captured pre-click and keeps the pattern consistent with other tools that
+        // diff before/after for summaries (we rely on the waitFor / final signals
+        // for the actual comparison here).
+        void beforeSubmit;
+        return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+    });
     server.tool('geometra_run_actions', `Execute several Geometra actions in one MCP round trip and return one consolidated result. This is the preferred path for long, multi-step form fills where one-tool-per-field would otherwise create too much chatter.
 
 Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_listbox_option\`, \`select_option\`, \`set_checked\`, \`wheel\`, \`wait_for\`, \`expand_section\`, and \`fill_fields\`. \`click\` steps can also carry a nested \`waitFor\` condition. \`fill_fields\` steps can carry \`verifyFills: true\` to batch fill + read-back verification in one step (same semantics as \`geometra_fill_form\`'s \`verifyFills\`). \`expand_section\` takes a stable section id from \`geometra_page_model\` and returns the same payload as \`geometra_expand_section\`, eliminating a round-trip when drilling into a form/dialog before acting on it. Pass \`pageUrl\` / \`url\` to auto-connect so an entire flow can run in one MCP call.`, {
@@ -1201,6 +1369,10 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         const steps = [];
         let stoppedAt;
         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];
             const startedAt = performance.now();
@@ -1212,6 +1384,17 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
                     uiTreeWaitMs = performance.now() - uiTreeWaitStartedAt;
                 }
                 const result = await executeBatchAction(session, action, detail, includeSteps);
+                const stepFallback = result.compact.fallback;
+                if (stepFallback?.used) {
+                    fallbackRecords.push({
+                        stepIndex: index,
+                        type: action.type,
+                        attempted: true,
+                        used: true,
+                        reason: stepFallback.reason,
+                        attempts: stepFallback.attempts,
+                    });
+                }
                 const elapsedMs = Number((performance.now() - startedAt).toFixed(1));
                 const cumulativeMs = Number((performance.now() - batchStartedAt).toFixed(1));
                 const stepSignals = includeSteps ? (() => {
@@ -1270,6 +1453,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
                 ...connection,
                 completed: stoppedAt === undefined && steps.length === actions.length,
                 ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+                ...(fallbackRecords.length > 0 ? { fallbacks: fallbackRecords } : {}),
                 ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after), detail) } : {}),
             }
             : {
@@ -1280,6 +1464,7 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
                 errorCount,
                 ...(includeSteps ? { steps } : {}),
                 ...(stoppedAt !== undefined ? { stoppedAt } : {}),
+                ...(fallbackRecords.length > 0 ? { fallbacks: fallbackRecords } : {}),
                 ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after), detail) } : {}),
             };
         return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
@@ -1508,7 +1693,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             return sessionResult.error;
         const session = sessionResult.session;
         const before = sessionA11y(session);
-        const resolved = await resolveClickLocation(session, {
+        const resolved = await resolveClickLocationWithFallback(session, {
             x,
             y,
             filter: {
@@ -1536,7 +1721,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             revealTimeoutMs,
         });
         if (!resolved.ok)
-            return err(resolved.error);
+            return err(clickFallbackErrorMessage(resolved));
         const wait = await sendClick(session, resolved.value.x, resolved.value.y, timeoutMs);
         const summary = postActionSummary(session, before, wait, detail);
         const clickLine = !resolved.value.target
@@ -1574,6 +1759,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
                 at: { x: resolved.value.x, y: resolved.value.y },
                 ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
                 ...waitStatusPayload(wait),
+                ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
                 postWait: waitConditionCompact(postWait.value),
             };
             return ok(detailText(lines.filter(Boolean).join('\n'), compact, detail));
@@ -1582,6 +1768,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             at: { x: resolved.value.x, y: resolved.value.y },
             ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
             ...waitStatusPayload(wait),
+            ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
         };
         return ok(detailText(lines.filter(Boolean).join('\n'), compact, detail));
     });
@@ -2817,6 +3004,72 @@ async function resolveClickLocation(session, options) {
         },
     };
 }
+async function resolveClickLocationWithFallback(session, options) {
+    const first = await resolveClickLocation(session, options);
+    if (first.ok)
+        return first;
+    // Fallback only applies to semantic resolves. Explicit coordinates never enter
+    // the reveal path, so there is nothing to retry.
+    const hasExplicitCoordinates = options.x !== undefined || options.y !== undefined;
+    if (hasExplicitCoordinates)
+        return first;
+    if (!hasNodeFilter(options.filter))
+        return first;
+    const reasonsTried = [];
+    let attempts = 1;
+    const startRevision = session.updateRevision;
+    const revisionAdvanced = await waitForUiCondition(session, () => session.updateRevision > startRevision, 600);
+    if (revisionAdvanced) {
+        attempts += 1;
+        reasonsTried.push('revision-retry');
+        const retry = await resolveClickLocation(session, options);
+        if (retry.ok) {
+            return {
+                ok: true,
+                value: retry.value,
+                fallback: { attempted: true, used: true, reason: 'revision-retry', attempts },
+            };
+        }
+    }
+    if (options.fullyVisible !== false) {
+        attempts += 1;
+        reasonsTried.push('relaxed-visibility');
+        const relaxed = await resolveClickLocation(session, {
+            ...options,
+            fullyVisible: false,
+            maxRevealSteps: Math.max(options.maxRevealSteps ?? 0, 24),
+        });
+        if (relaxed.ok) {
+            return {
+                ok: true,
+                value: relaxed.value,
+                fallback: { attempted: true, used: true, reason: 'relaxed-visibility', attempts },
+            };
+        }
+    }
+    // All fallback phases tried and none recovered. Carry the trace of what we
+    // tried so operators see the attempted-but-failed signal alongside the
+    // successful-recovery signal.
+    if (reasonsTried.length === 0)
+        return first;
+    return {
+        ok: false,
+        error: first.error,
+        fallback: { attempted: true, used: false, reasonsTried, attempts },
+    };
+}
+/**
+ * Expose the attempted-but-failed fallback telemetry on error responses. When
+ * `resolved.fallback` is present on a failure, return a structured JSON error
+ * so operators can aggregate recovery failures the same way they aggregate
+ * successful recoveries. Plain-text errors are preserved for the no-fallback
+ * case to avoid churning that error contract.
+ */
+function clickFallbackErrorMessage(resolved) {
+    if (!resolved.fallback)
+        return resolved.error;
+    return JSON.stringify({ error: resolved.error, fallback: resolved.fallback });
+}
 function describeFormattedNode(node) {
     return `${node.role}${node.name ? ` ${JSON.stringify(node.name)}` : ''} (${node.id})`;
 }
@@ -3286,7 +3539,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
     switch (action.type) {
         case 'click': {
             const before = sessionA11y(session);
-            const resolved = await resolveClickLocation(session, {
+            const resolved = await resolveClickLocationWithFallback(session, {
                 x: action.x,
                 y: action.y,
                 filter: {
@@ -3314,7 +3567,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                 revealTimeoutMs: action.revealTimeoutMs,
             });
             if (!resolved.ok)
-                throw new Error(resolved.error);
+                throw new Error(clickFallbackErrorMessage(resolved));
             const wait = await sendClick(session, resolved.value.x, resolved.value.y, action.timeoutMs);
             const targetSummary = resolved.value.target
                 ? `Clicked ${describeFormattedNode(resolved.value.target)} at (${resolved.value.x}, ${resolved.value.y}).`
@@ -3357,6 +3610,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                     at: { x: resolved.value.x, y: resolved.value.y },
                     ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
                     ...waitStatusPayload(wait),
+                    ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
                     ...(postWaitCompact ? { postWait: postWaitCompact } : {}),
                 },
             };
@@ -3559,6 +3813,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
             const verifyFillsFn = action.verifyFills
                 ? () => verifyFormFills(session, resolvedFields.fields.map(field => ({ field, confidence: 1.0, matchMethod: 'label-exact' })))
                 : undefined;
+            let fallbackFromBatch;
             if (!includeSteps) {
                 const batched = await tryBatchedResolvedFields(session, resolvedFields.fields, detail);
                 if (batched.ok) {
@@ -3574,6 +3829,10 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                         },
                     };
                 }
+                // Batched path unavailable — fall through into sequential and tag the
+                // step so `geometra_run_actions` result aggregation matches the shape
+                // emitted by standalone `geometra_fill_fields` / `geometra_fill_form`.
+                fallbackFromBatch = { attempted: true, used: true, reason: 'batched-unavailable', attempts: 2 };
             }
             const steps = [];
             for (let index = 0; index < resolvedFields.fields.length; index++) {
@@ -3602,6 +3861,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                 compact: {
                     fieldCount: resolvedFields.fields.length,
                     ...(includeSteps ? { steps } : {}),
+                    ...(fallbackFromBatch ? { fallback: fallbackFromBatch } : {}),
                     ...(verification ? { verification } : {}),
                 },
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geometra/mcp",
-  "version": "1.52.0",
+  "version": "1.54.0",
   "description": "MCP server for Geometra — interact with running Geometra apps via the geometry protocol, no browser needed",
   "license": "MIT",
   "type": "module",