@geometra/mcp 1.53.0 → 1.54.0

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

@@ -1087,11 +1087,138 @@ describe('submit_form tool', () => {
         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
@@ -1124,7 +1251,7 @@ describe('click transparent fallback', () => {
         const payload = JSON.parse(result.content[0].text);
         expect(payload).toMatchObject({
             target: { role: 'button', name: 'Submit' },
-            fallback: { used: true, reason: 'relaxed-visibility' },
+            fallback: { attempted: true, used: true, reason: 'relaxed-visibility' },
         });
     });
 });

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.22' }, { 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) } : {}),
         };
@@ -1359,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();
@@ -1370,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 ? (() => {
@@ -1428,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) } : {}),
             }
             : {
@@ -1438,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));
@@ -1694,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
@@ -2988,22 +3015,25 @@ async function resolveClickLocationWithFallback(session, options) {
         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: { used: true, reason: 'revision-retry', attempts },
+                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,
@@ -3013,11 +3043,32 @@ async function resolveClickLocationWithFallback(session, options) {
             return {
                 ok: true,
                 value: relaxed.value,
-                fallback: { used: true, reason: 'relaxed-visibility', attempts },
+                fallback: { attempted: true, used: true, reason: 'relaxed-visibility', attempts },
             };
         }
     }
-    return first;
+    // 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})`;
@@ -3516,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}).`
@@ -3762,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) {
@@ -3777,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++) {
@@ -3805,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.53.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",