@geometra/mcp 1.19.10 → 1.19.12

package/dist/server.js

@@ -21,6 +21,7 @@ function nodeFilterShape() {
         role: z.string().optional().describe('ARIA role to match'),
         name: z.string().optional().describe('Accessible name to match (exact or substring)'),
         text: z.string().optional().describe('Text content to search for (substring match)'),
+        contextText: z.string().optional().describe('Ancestor / prompt text to disambiguate repeated controls with the same visible name'),
         value: z.string().optional().describe('Displayed / current field value to match (substring match)'),
         checked: checkedStateInput(),
         disabled: z.boolean().optional().describe('Match disabled state'),
@@ -145,7 +146,7 @@ const batchActionSchema = z.discriminatedUnion('type', [
     }),
 ]);
 export function createServer() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.10' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.11' }, { capabilities: { tools: {} } });
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
 
@@ -213,7 +214,7 @@ Chromium opens **visible** by default unless \`headless: true\`. File upload / w
     // ── query ────────────────────────────────────────────────────
     server.tool('geometra_query', `Find elements in the current Geometra UI by stable id, role, name, text content, current value, or semantic state. Returns matching elements with their exact pixel bounds {x, y, width, height}, visible in-viewport bounds, an on-screen center point, visibility / scroll-reveal hints, role, name, value, state, and tree path.
 
-This is the Geometra equivalent of Playwright's locator — but instant, structured, and with no browser. Use the returned bounds to click elements or assert on layout.`, nodeFilterShape(), async ({ id, role, name, text, value, checked, disabled, focused, selected, expanded, invalid, required, busy }) => {
+This is the Geometra equivalent of Playwright's locator — but instant, structured, and with no browser. Use the returned bounds to click elements or assert on layout.`, nodeFilterShape(), async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -223,6 +224,7 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
             role,
             name,
             text,
+            contextText,
             value,
             checked,
             disabled,
@@ -234,12 +236,12 @@ This is the Geometra equivalent of Playwright's locator — but instant, structu
             busy,
         };
         if (!hasNodeFilter(filter))
-            return err('Provide at least one query filter (id, role, name, text, value, or state)');
+            return err('Provide at least one query filter (id, role, name, text, contextText, value, or state)');
         const matches = findNodes(a11y, filter);
         if (matches.length === 0) {
             return ok(`No elements found matching ${JSON.stringify(filter)}`);
         }
-        const result = matches.map(node => formatNode(node, a11y.bounds));
+        const result = sortA11yNodes(matches).map(node => formatNode(node, a11y, a11y.bounds));
         return ok(JSON.stringify(result, null, 2));
     });
     server.tool('geometra_wait_for', `Wait for a semantic UI condition without guessing sleep durations. Use this for slow SPA transitions, resume parsing, custom validation alerts, disabled submit buttons, and value/state confirmation before submit.
@@ -255,7 +257,7 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
             .optional()
             .default(10_000)
             .describe('Maximum time to wait before returning an error (default 10000ms)'),
-    }, async ({ id, role, name, text, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs }) => {
+    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, present, timeoutMs }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -264,6 +266,7 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
             role,
             name,
             text,
+            contextText,
             value,
             checked,
             disabled,
@@ -275,7 +278,7 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
             busy,
         };
         if (!hasNodeFilter(filter))
-            return err('Provide at least one wait filter (id, role, name, text, value, or state)');
+            return err('Provide at least one wait filter (id, role, name, text, contextText, value, or state)');
         const matchesCondition = () => {
             if (!session.tree || !session.layout)
                 return false;
@@ -296,7 +299,7 @@ The filter matches the same fields as geometra_query. Set \`present: false\` to
         if (!after)
             return ok(`Condition satisfied after ${elapsedMs}ms for ${JSON.stringify(filter)}.`);
         const matches = findNodes(after, filter);
-        const result = matches.slice(0, 8).map(node => formatNode(node, after.bounds));
+        const result = sortA11yNodes(matches).slice(0, 8).map(node => formatNode(node, after, after.bounds));
         return ok(JSON.stringify(result, null, 2));
     });
     server.tool('geometra_fill_fields', `Fill several labeled form fields in one MCP call. This is the preferred high-level primitive for long forms.
@@ -309,8 +312,13 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
             .optional()
             .default(false)
             .describe('Return an error if invalid fields remain after filling'),
+        includeSteps: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Include per-field step results in the JSON payload (default true). Set false for the smallest batch response.'),
         detail: detailInput(),
-    }, async ({ fields, stopOnError, failOnInvalid, detail }) => {
+    }, async ({ fields, stopOnError, failOnInvalid, includeSteps, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -319,8 +327,10 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         for (let index = 0; index < fields.length; index++) {
             const field = fields[index];
             try {
-                const summary = await executeFillField(session, field, detail);
-                steps.push({ index, kind: field.kind, ok: true, summary });
+                const result = await executeFillField(session, field, detail);
+                steps.push(detail === 'verbose'
+                    ? { index, kind: field.kind, ok: true, summary: result.summary }
+                    : { index, kind: field.kind, ok: true, ...result.compact });
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
@@ -334,12 +344,16 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
         const after = sessionA11y(session);
         const signals = after ? collectSessionSignals(after) : undefined;
         const invalidRemaining = signals?.invalidFields.length ?? 0;
+        const successCount = steps.filter(step => step.ok === true).length;
+        const errorCount = steps.length - successCount;
         const payload = {
             completed: stoppedAt === undefined && steps.length === fields.length,
             fieldCount: fields.length,
-            steps,
+            successCount,
+            errorCount,
+            ...(includeSteps ? { steps } : {}),
             ...(stoppedAt !== undefined ? { stoppedAt } : {}),
-            ...(signals ? { final: sessionSignalsPayload(signals) } : {}),
+            ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
         };
         if (failOnInvalid && invalidRemaining > 0) {
             return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
@@ -351,8 +365,13 @@ Use \`kind: "text"\` for textboxes / textareas, \`"choice"\` for selects / combo
 Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_listbox_option\`, \`select_option\`, \`set_checked\`, \`wheel\`, \`wait_for\`, and \`fill_fields\`.`, {
         actions: z.array(batchActionSchema).min(1).max(80).describe('Ordered high-level action steps to run sequentially'),
         stopOnError: z.boolean().optional().default(true).describe('Stop at the first failing step (default true)'),
+        includeSteps: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Include per-action step results in the JSON payload (default true). Set false for the smallest batch response.'),
         detail: detailInput(),
-    }, async ({ actions, stopOnError, detail }) => {
+    }, async ({ actions, stopOnError, includeSteps, detail }) => {
         const session = getSession();
         if (!session)
             return err('Not connected. Call geometra_connect first.');
@@ -361,8 +380,10 @@ Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_lis
         for (let index = 0; index < actions.length; index++) {
             const action = actions[index];
             try {
-                const summary = await executeBatchAction(session, action, detail);
-                steps.push({ index, type: action.type, ok: true, summary });
+                const result = await executeBatchAction(session, action, detail, includeSteps);
+                steps.push(detail === 'verbose'
+                    ? { index, type: action.type, ok: true, summary: result.summary }
+                    : { index, type: action.type, ok: true, ...result.compact });
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
@@ -374,12 +395,16 @@ 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 payload = {
             completed: stoppedAt === undefined && steps.length === actions.length,
             stepCount: actions.length,
-            steps,
+            successCount,
+            errorCount,
+            ...(includeSteps ? { steps } : {}),
             ...(stoppedAt !== undefined ? { stoppedAt } : {}),
-            ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after)) } : {}),
+            ...(after ? { final: sessionSignalsPayload(collectSessionSignals(after), detail) } : {}),
         };
         return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
     });
@@ -417,12 +442,18 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
         id: z.string().describe('Section id from geometra_page_model, e.g. fm:1.0 or ls:2.1'),
         maxHeadings: z.number().int().min(1).max(20).optional().default(6).describe('Cap heading rows'),
         maxFields: z.number().int().min(1).max(40).optional().default(18).describe('Cap field rows'),
+        fieldOffset: z.number().int().min(0).optional().default(0).describe('Field row offset for long forms'),
+        onlyRequiredFields: z.boolean().optional().default(false).describe('Only include required fields'),
+        onlyInvalidFields: z.boolean().optional().default(false).describe('Only include invalid fields'),
         maxActions: z.number().int().min(1).max(30).optional().default(12).describe('Cap action rows'),
+        actionOffset: z.number().int().min(0).optional().default(0).describe('Action row offset'),
         maxLists: z.number().int().min(0).max(20).optional().default(8).describe('Cap nested lists'),
+        listOffset: z.number().int().min(0).optional().default(0).describe('Nested-list offset'),
         maxItems: z.number().int().min(0).max(50).optional().default(20).describe('Cap list items'),
+        itemOffset: z.number().int().min(0).optional().default(0).describe('List-item offset'),
         maxTextPreview: z.number().int().min(0).max(20).optional().default(6).describe('Cap text preview lines'),
         includeBounds: z.boolean().optional().default(false).describe('Include bounds for fields/actions/headings/items'),
-    }, async ({ id, maxHeadings, maxFields, maxActions, maxLists, maxItems, maxTextPreview, includeBounds }) => {
+    }, async ({ id, maxHeadings, maxFields, fieldOffset, onlyRequiredFields, onlyInvalidFields, maxActions, actionOffset, maxLists, listOffset, maxItems, itemOffset, maxTextPreview, includeBounds, }) => {
         const session = getSession();
         if (!session?.tree || !session?.layout)
             return err('Not connected. Call geometra_connect first.');
@@ -430,9 +461,15 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
         const detail = expandPageSection(a11y, id, {
             maxHeadings,
             maxFields,
+            fieldOffset,
+            onlyRequiredFields,
+            onlyInvalidFields,
             maxActions,
+            actionOffset,
             maxLists,
+            listOffset,
             maxItems,
+            itemOffset,
             maxTextPreview,
             includeBounds,
         });
@@ -440,6 +477,90 @@ Use this after geometra_page_model when you know which form/dialog/list/landmark
             return err(`No expandable section found for id ${id}`);
         return ok(JSON.stringify(detail));
     });
+    server.tool('geometra_reveal', `Scroll until a matching node is revealed. This is the generic alternative to trial-and-error wheel calls on long forms.
+
+Use the same filters as geometra_query, plus an optional match index when repeated controls share the same visible label.`, {
+        ...nodeFilterShape(),
+        index: z.number().int().min(0).optional().default(0).describe('Which matching node to reveal after sorting top-to-bottom'),
+        fullyVisible: z.boolean().optional().default(true).describe('Require the target to become fully visible (default true)'),
+        maxSteps: z.number().int().min(1).max(12).optional().default(6).describe('Maximum reveal attempts before returning an error'),
+        timeoutMs: z
+            .number()
+            .int()
+            .min(50)
+            .max(60_000)
+            .optional()
+            .default(2_500)
+            .describe('Per-scroll wait timeout (default 2500ms)'),
+    }, async ({ id, role, name, text, contextText, value, checked, disabled, focused, selected, expanded, invalid, required, busy, index, fullyVisible, maxSteps, timeoutMs }) => {
+        const session = getSession();
+        if (!session)
+            return err('Not connected. Call geometra_connect first.');
+        const matchIndex = index ?? 0;
+        const requireFullyVisible = fullyVisible ?? true;
+        const revealSteps = maxSteps ?? 6;
+        const waitTimeout = timeoutMs ?? 2_500;
+        const filter = {
+            id,
+            role,
+            name,
+            text,
+            contextText,
+            value,
+            checked,
+            disabled,
+            focused,
+            selected,
+            expanded,
+            invalid,
+            required,
+            busy,
+        };
+        if (!hasNodeFilter(filter))
+            return err('Provide at least one reveal filter (id, role, name, text, contextText, value, or state)');
+        let attempts = 0;
+        while (attempts <= revealSteps) {
+            const a11y = sessionA11y(session);
+            if (!a11y)
+                return err('No UI tree available to reveal from');
+            const matches = sortA11yNodes(findNodes(a11y, filter));
+            if (matches.length === 0) {
+                return err(`No elements found matching ${JSON.stringify(filter)}`);
+            }
+            if (matchIndex >= matches.length) {
+                return err(`Requested reveal index ${matchIndex} but only ${matches.length} matching element(s) were found`);
+            }
+            const target = matches[matchIndex];
+            const formatted = formatNode(target, a11y, a11y.bounds);
+            const visible = requireFullyVisible ? formatted.visibility.fullyVisible : formatted.visibility.intersectsViewport;
+            if (visible) {
+                return ok(JSON.stringify({
+                    revealed: true,
+                    attempts,
+                    target: formatted,
+                }, null, 2));
+            }
+            if (attempts === revealSteps) {
+                return err(JSON.stringify({
+                    revealed: false,
+                    attempts,
+                    target: formatted,
+                }, null, 2));
+            }
+            const deltaX = clamp(formatted.scrollHint.revealDeltaX, -Math.round(a11y.bounds.width * 0.75), Math.round(a11y.bounds.width * 0.75));
+            let deltaY = clamp(formatted.scrollHint.revealDeltaY, -Math.round(a11y.bounds.height * 0.85), Math.round(a11y.bounds.height * 0.85));
+            if (deltaY === 0 && !formatted.visibility.fullyVisible) {
+                deltaY = formatted.visibility.offscreenAbove ? -Math.round(a11y.bounds.height * 0.4) : Math.round(a11y.bounds.height * 0.4);
+            }
+            await sendWheel(session, deltaY, {
+                deltaX,
+                x: formatted.center.x,
+                y: formatted.center.y,
+            }, waitTimeout);
+            attempts++;
+        }
+        return err(`Failed to reveal ${JSON.stringify(filter)}`);
+    });
     // ── click ────────────────────────────────────────────────────
     server.tool('geometra_click', `Click an element in the Geometra UI. Provide either the element's bounds (from geometra_query) or raw x,y coordinates. The click is dispatched server-side via the geometry protocol — no browser, no simulated DOM events.
 
@@ -897,7 +1018,7 @@ function truncateInlineText(text, max) {
         return undefined;
     return normalized.length > max ? `${normalized.slice(0, max - 1)}…` : normalized;
 }
-function sessionSignalsPayload(signals) {
+function sessionSignalsPayload(signals, detail = 'minimal') {
     return {
         ...(signals.pageUrl ? { pageUrl: signals.pageUrl } : {}),
         ...(signals.scrollX !== undefined || signals.scrollY !== undefined
@@ -906,26 +1027,85 @@ function sessionSignalsPayload(signals) {
         ...(signals.focus ? { focus: signals.focus } : {}),
         dialogCount: signals.dialogCount,
         busyCount: signals.busyCount,
-        alerts: signals.alerts,
-        invalidFields: signals.invalidFields,
+        alertCount: signals.alerts.length,
+        invalidCount: signals.invalidFields.length,
+        alerts: detail === 'verbose' ? signals.alerts : signals.alerts.slice(0, 2),
+        invalidFields: detail === 'verbose' ? signals.invalidFields : signals.invalidFields.slice(0, 4),
+    };
+}
+function compactTextValue(value, inlineLimit = 48) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    if (!normalized)
+        return { valueLength: value.length };
+    return normalized.length <= inlineLimit
+        ? { value: normalized }
+        : { valueLength: value.length };
+}
+function fieldStatePayload(session, fieldLabel) {
+    const a11y = sessionA11y(session);
+    if (!a11y)
+        return undefined;
+    const matches = findNodes(a11y, {
+        name: fieldLabel,
+        role: 'combobox',
+    });
+    if (matches.length === 0) {
+        matches.push(...findNodes(a11y, { name: fieldLabel, role: 'textbox' }));
+    }
+    if (matches.length === 0) {
+        matches.push(...findNodes(a11y, { name: fieldLabel, role: 'button' }));
+    }
+    const match = matches[0];
+    if (!match)
+        return undefined;
+    const valuePayload = match.value ? compactTextValue(match.value, 64) : {};
+    return {
+        role: match.role,
+        ...valuePayload,
+        ...(match.state && Object.keys(match.state).length > 0 ? { state: match.state } : {}),
+        ...(match.validation?.error ? { error: truncateInlineText(match.validation.error, 120) } : {}),
     };
 }
-async function executeBatchAction(session, action, detail) {
+function waitStatusPayload(wait) {
+    return wait ? { wait: wait.status } : {};
+}
+function compactFilterPayload(filter) {
+    return Object.fromEntries(Object.entries(filter).filter(([, value]) => value !== undefined));
+}
+async function executeBatchAction(session, action, detail, includeSteps) {
     switch (action.type) {
         case 'click': {
             const before = sessionA11y(session);
             const wait = await sendClick(session, action.x, action.y, action.timeoutMs);
-            return `Clicked at (${action.x}, ${action.y}).\n${postActionSummary(session, before, wait, detail)}`;
+            return {
+                summary: `Clicked at (${action.x}, ${action.y}).\n${postActionSummary(session, before, wait, detail)}`,
+                compact: {
+                    at: { x: action.x, y: action.y },
+                    ...waitStatusPayload(wait),
+                },
+            };
         }
         case 'type': {
             const before = sessionA11y(session);
             const wait = await sendType(session, action.text, action.timeoutMs);
-            return `Typed "${action.text}".\n${postActionSummary(session, before, wait, detail)}`;
+            return {
+                summary: `Typed "${action.text}".\n${postActionSummary(session, before, wait, detail)}`,
+                compact: {
+                    ...compactTextValue(action.text),
+                    ...waitStatusPayload(wait),
+                },
+            };
         }
         case 'key': {
             const before = sessionA11y(session);
             const wait = await sendKey(session, action.key, { shift: action.shift, ctrl: action.ctrl, meta: action.meta, alt: action.alt }, action.timeoutMs);
-            return `Pressed ${formatKeyCombo(action.key, action)}.\n${postActionSummary(session, before, wait, detail)}`;
+            return {
+                summary: `Pressed ${formatKeyCombo(action.key, action)}.\n${postActionSummary(session, before, wait, detail)}`,
+                compact: {
+                    key: formatKeyCombo(action.key, action),
+                    ...waitStatusPayload(wait),
+                },
+            };
         }
         case 'upload_files': {
             const before = sessionA11y(session);
@@ -936,7 +1116,16 @@ async function executeBatchAction(session, action, detail) {
                 strategy: action.strategy,
                 drop: action.dropX !== undefined && action.dropY !== undefined ? { x: action.dropX, y: action.dropY } : undefined,
             }, action.timeoutMs ?? 8_000);
-            return `Uploaded ${action.paths.length} file(s).\n${postActionSummary(session, before, wait, detail)}`;
+            return {
+                summary: `Uploaded ${action.paths.length} file(s).\n${postActionSummary(session, before, wait, detail)}`,
+                compact: {
+                    fileCount: action.paths.length,
+                    ...(action.fieldLabel ? { fieldLabel: action.fieldLabel } : {}),
+                    ...(action.strategy ? { strategy: action.strategy } : {}),
+                    ...waitStatusPayload(wait),
+                    ...(action.fieldLabel ? { readback: fieldStatePayload(session, action.fieldLabel) } : {}),
+                },
+            };
         }
         case 'pick_listbox_option': {
             const before = sessionA11y(session);
@@ -948,7 +1137,15 @@ async function executeBatchAction(session, action, detail) {
             }, action.timeoutMs);
             const summary = postActionSummary(session, before, wait, detail);
             const fieldSummary = action.fieldLabel ? summarizeFieldLabelState(session, action.fieldLabel) : undefined;
-            return [`Picked listbox option "${action.label}".`, fieldSummary, summary].filter(Boolean).join('\n');
+            return {
+                summary: [`Picked listbox option "${action.label}".`, fieldSummary, summary].filter(Boolean).join('\n'),
+                compact: {
+                    label: action.label,
+                    ...(action.fieldLabel ? { fieldLabel: action.fieldLabel } : {}),
+                    ...waitStatusPayload(wait),
+                    ...(action.fieldLabel ? { readback: fieldStatePayload(session, action.fieldLabel) } : {}),
+                },
+            };
         }
         case 'select_option': {
             if (action.value === undefined && action.label === undefined && action.index === undefined) {
@@ -960,7 +1157,16 @@ async function executeBatchAction(session, action, detail) {
                 label: action.label,
                 index: action.index,
             }, action.timeoutMs);
-            return `Selected option.\n${postActionSummary(session, before, wait, detail)}`;
+            return {
+                summary: `Selected option.\n${postActionSummary(session, before, wait, detail)}`,
+                compact: {
+                    at: { x: action.x, y: action.y },
+                    ...(action.value !== undefined ? { value: action.value } : {}),
+                    ...(action.label !== undefined ? { label: action.label } : {}),
+                    ...(action.index !== undefined ? { index: action.index } : {}),
+                    ...waitStatusPayload(wait),
+                },
+            };
         }
         case 'set_checked': {
             const before = sessionA11y(session);
@@ -969,7 +1175,15 @@ async function executeBatchAction(session, action, detail) {
                 exact: action.exact,
                 controlType: action.controlType,
             }, action.timeoutMs);
-            return `Set ${action.controlType ?? 'checkbox/radio'} "${action.label}" to ${String(action.checked ?? true)}.\n${postActionSummary(session, before, wait, detail)}`;
+            return {
+                summary: `Set ${action.controlType ?? 'checkbox/radio'} "${action.label}" to ${String(action.checked ?? true)}.\n${postActionSummary(session, before, wait, detail)}`,
+                compact: {
+                    label: action.label,
+                    checked: action.checked ?? true,
+                    ...(action.controlType ? { controlType: action.controlType } : {}),
+                    ...waitStatusPayload(wait),
+                },
+            };
         }
         case 'wheel': {
             const before = sessionA11y(session);
@@ -978,7 +1192,15 @@ async function executeBatchAction(session, action, detail) {
                 x: action.x,
                 y: action.y,
             }, action.timeoutMs);
-            return `Wheel delta (${action.deltaX ?? 0}, ${action.deltaY}).\n${postActionSummary(session, before, wait, detail)}`;
+            return {
+                summary: `Wheel delta (${action.deltaX ?? 0}, ${action.deltaY}).\n${postActionSummary(session, before, wait, detail)}`,
+                compact: {
+                    deltaY: action.deltaY,
+                    ...(action.deltaX !== undefined ? { deltaX: action.deltaX } : {}),
+                    ...(action.x !== undefined && action.y !== undefined ? { at: { x: action.x, y: action.y } } : {}),
+                    ...waitStatusPayload(wait),
+                },
+            };
         }
         case 'wait_for': {
             if (!session.tree || !session.layout)
@@ -988,6 +1210,7 @@ async function executeBatchAction(session, action, detail) {
                 role: action.role,
                 name: action.name,
                 text: action.text,
+                contextText: action.contextText,
                 value: action.value,
                 checked: action.checked,
                 disabled: action.disabled,
@@ -1016,24 +1239,64 @@ async function executeBatchAction(session, action, detail) {
                 throw new Error(`Timed out after ${timeoutMs}ms waiting for ${present ? 'presence' : 'absence'} of ${JSON.stringify(filter)}`);
             }
             if (!present) {
-                return `Condition satisfied after ${elapsedMs}ms: no nodes matched ${JSON.stringify(filter)}.`;
+                return {
+                    summary: `Condition satisfied after ${elapsedMs}ms: no nodes matched ${JSON.stringify(filter)}.`,
+                    compact: {
+                        present,
+                        elapsedMs,
+                        filter: compactFilterPayload(filter),
+                    },
+                };
             }
             const after = sessionA11y(session);
             if (!after) {
-                return `Condition satisfied after ${elapsedMs}ms for ${JSON.stringify(filter)}.`;
+                return {
+                    summary: `Condition satisfied after ${elapsedMs}ms for ${JSON.stringify(filter)}.`,
+                    compact: {
+                        present,
+                        elapsedMs,
+                        filter: compactFilterPayload(filter),
+                    },
+                };
             }
             const matches = findNodes(after, filter);
             if (detail === 'verbose') {
-                return JSON.stringify(matches.slice(0, 8).map(node => formatNode(node, after.bounds)), null, 2);
+                return {
+                    summary: JSON.stringify(sortA11yNodes(matches).slice(0, 8).map(node => formatNode(node, after, after.bounds)), null, 2),
+                    compact: {
+                        present,
+                        elapsedMs,
+                        matchCount: matches.length,
+                        filter: compactFilterPayload(filter),
+                    },
+                };
             }
-            return `Condition satisfied after ${elapsedMs}ms with ${matches.length} matching node(s).`;
+            return {
+                summary: `Condition satisfied after ${elapsedMs}ms with ${matches.length} matching node(s).`,
+                compact: {
+                    present,
+                    elapsedMs,
+                    matchCount: matches.length,
+                    filter: compactFilterPayload(filter),
+                },
+            };
         }
         case 'fill_fields': {
-            const lines = [];
-            for (const field of action.fields) {
-                lines.push(await executeFillField(session, field, detail));
+            const steps = [];
+            for (let index = 0; index < action.fields.length; index++) {
+                const field = action.fields[index];
+                const result = await executeFillField(session, field, detail);
+                steps.push(detail === 'verbose'
+                    ? { index, kind: field.kind, ok: true, summary: result.summary }
+                    : { index, kind: field.kind, ok: true, ...result.compact });
             }
-            return lines.join('\n');
+            return {
+                summary: steps.map(step => String(step.summary ?? '')).filter(Boolean).join('\n'),
+                compact: {
+                    fieldCount: action.fields.length,
+                    ...(includeSteps ? { steps } : {}),
+                },
+            };
         }
     }
 }
@@ -1043,36 +1306,68 @@ async function executeFillField(session, field, detail) {
             const before = sessionA11y(session);
             const wait = await sendFieldText(session, field.fieldLabel, field.value, { exact: field.exact }, field.timeoutMs);
             const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
-            return [
-                `Filled text field "${field.fieldLabel}".`,
-                fieldSummary,
-                postActionSummary(session, before, wait, detail),
-            ].filter(Boolean).join('\n');
+            return {
+                summary: [
+                    `Filled text field "${field.fieldLabel}".`,
+                    fieldSummary,
+                    postActionSummary(session, before, wait, detail),
+                ].filter(Boolean).join('\n'),
+                compact: {
+                    fieldLabel: field.fieldLabel,
+                    ...compactTextValue(field.value),
+                    ...waitStatusPayload(wait),
+                    readback: fieldStatePayload(session, field.fieldLabel),
+                },
+            };
         }
         case 'choice': {
             const before = sessionA11y(session);
             const wait = await sendFieldChoice(session, field.fieldLabel, field.value, { exact: field.exact, query: field.query }, field.timeoutMs);
             const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
-            return [
-                `Set choice field "${field.fieldLabel}" to "${field.value}".`,
-                fieldSummary,
-                postActionSummary(session, before, wait, detail),
-            ].filter(Boolean).join('\n');
+            return {
+                summary: [
+                    `Set choice field "${field.fieldLabel}" to "${field.value}".`,
+                    fieldSummary,
+                    postActionSummary(session, before, wait, detail),
+                ].filter(Boolean).join('\n'),
+                compact: {
+                    fieldLabel: field.fieldLabel,
+                    value: field.value,
+                    ...waitStatusPayload(wait),
+                    readback: fieldStatePayload(session, field.fieldLabel),
+                },
+            };
         }
         case 'toggle': {
             const before = sessionA11y(session);
             const wait = await sendSetChecked(session, field.label, { checked: field.checked, exact: field.exact, controlType: field.controlType }, field.timeoutMs);
-            return `Set ${field.controlType ?? 'checkbox/radio'} "${field.label}" to ${String(field.checked ?? true)}.\n${postActionSummary(session, before, wait, detail)}`;
+            return {
+                summary: `Set ${field.controlType ?? 'checkbox/radio'} "${field.label}" to ${String(field.checked ?? true)}.\n${postActionSummary(session, before, wait, detail)}`,
+                compact: {
+                    label: field.label,
+                    checked: field.checked ?? true,
+                    ...(field.controlType ? { controlType: field.controlType } : {}),
+                    ...waitStatusPayload(wait),
+                },
+            };
         }
         case 'file': {
             const before = sessionA11y(session);
             const wait = await sendFileUpload(session, field.paths, { fieldLabel: field.fieldLabel, exact: field.exact }, field.timeoutMs ?? 8_000);
             const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
-            return [
-                `Uploaded ${field.paths.length} file(s) to "${field.fieldLabel}".`,
-                fieldSummary,
-                postActionSummary(session, before, wait, detail),
-            ].filter(Boolean).join('\n');
+            return {
+                summary: [
+                    `Uploaded ${field.paths.length} file(s) to "${field.fieldLabel}".`,
+                    fieldSummary,
+                    postActionSummary(session, before, wait, detail),
+                ].filter(Boolean).join('\n'),
+                compact: {
+                    fieldLabel: field.fieldLabel,
+                    fileCount: field.paths.length,
+                    ...waitStatusPayload(wait),
+                    readback: fieldStatePayload(session, field.fieldLabel),
+                },
+            };
         }
     }
 }
@@ -1092,7 +1387,96 @@ function textMatches(haystack, needle) {
         return false;
     return haystack.toLowerCase().includes(needle.toLowerCase());
 }
-function nodeMatchesFilter(node, filter) {
+function sortA11yNodes(nodes) {
+    return [...nodes].sort((a, b) => {
+        if (a.bounds.y !== b.bounds.y)
+            return a.bounds.y - b.bounds.y;
+        if (a.bounds.x !== b.bounds.x)
+            return a.bounds.x - b.bounds.x;
+        return a.path.length - b.path.length;
+    });
+}
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+function pathStartsWith(path, prefix) {
+    if (prefix.length > path.length)
+        return false;
+    for (let index = 0; index < prefix.length; index++) {
+        if (path[index] !== prefix[index])
+            return false;
+    }
+    return true;
+}
+function namedAncestors(root, path) {
+    const out = [];
+    let current = root;
+    for (const index of path) {
+        out.push(current);
+        if (!current.children[index])
+            break;
+        current = current.children[index];
+    }
+    return out;
+}
+function collectDescendants(node, predicate) {
+    const out = [];
+    function walk(current) {
+        for (const child of current.children) {
+            if (predicate(child))
+                out.push(child);
+            walk(child);
+        }
+    }
+    walk(node);
+    return out;
+}
+function promptContext(root, node) {
+    const ancestors = namedAncestors(root, node.path);
+    const normalizedName = (node.name ?? '').replace(/\s+/g, ' ').trim().toLowerCase();
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        const grouped = collectDescendants(ancestor, candidate => candidate.role === 'button' || candidate.role === 'radio' || candidate.role === 'checkbox').length >= 2;
+        if (!grouped && ancestor.role !== 'group' && ancestor.role !== 'form' && ancestor.role !== 'dialog')
+            continue;
+        const best = collectDescendants(ancestor, candidate => (candidate.role === 'heading' || candidate.role === 'text') &&
+            !!truncateInlineText(candidate.name, 120) &&
+            !pathStartsWith(candidate.path, node.path))
+            .filter(candidate => candidate.bounds.y <= node.bounds.y + 8)
+            .map(candidate => {
+            const text = truncateInlineText(candidate.name, 120);
+            if (!text)
+                return null;
+            if (text.toLowerCase() === normalizedName)
+                return null;
+            const dy = Math.max(0, node.bounds.y - candidate.bounds.y);
+            const dx = Math.abs(node.bounds.x - candidate.bounds.x);
+            const headingBonus = candidate.role === 'heading' ? -32 : 0;
+            return { text, score: dy * 4 + dx + headingBonus };
+        })
+            .filter((candidate) => !!candidate)
+            .sort((a, b) => a.score - b.score)[0];
+        if (best?.text)
+            return best.text;
+    }
+    return undefined;
+}
+function sectionContext(root, node) {
+    const ancestors = namedAncestors(root, node.path);
+    for (let index = ancestors.length - 1; index >= 0; index--) {
+        const ancestor = ancestors[index];
+        if (ancestor.role === 'form' || ancestor.role === 'dialog' || ancestor.role === 'main' || ancestor.role === 'navigation' || ancestor.role === 'region') {
+            const name = truncateInlineText(ancestor.name, 80);
+            if (name)
+                return name;
+        }
+    }
+    return undefined;
+}
+function nodeContextText(root, node) {
+    return [promptContext(root, node), sectionContext(root, node)].filter(Boolean).join(' | ') || undefined;
+}
+function nodeMatchesFilter(node, filter, contextText) {
     if (filter.id && nodeIdForPath(node.path) !== filter.id)
         return false;
     if (filter.role && node.role !== filter.role)
@@ -1104,6 +1488,8 @@ function nodeMatchesFilter(node, filter) {
     if (filter.text &&
         !textMatches(`${node.name ?? ''} ${node.value ?? ''} ${node.validation?.error ?? ''} ${node.validation?.description ?? ''}`.trim(), filter.text))
         return false;
+    if (!textMatches(contextText, filter.contextText))
+        return false;
     if (filter.checked !== undefined && node.state?.checked !== filter.checked)
         return false;
     if (filter.disabled !== undefined && (node.state?.disabled ?? false) !== filter.disabled)
@@ -1125,7 +1511,8 @@ function nodeMatchesFilter(node, filter) {
 export function findNodes(node, filter) {
     const matches = [];
     function walk(n) {
-        if (nodeMatchesFilter(n, filter) && hasNodeFilter(filter))
+        const contextText = filter.contextText ? nodeContextText(node, n) : undefined;
+        if (nodeMatchesFilter(n, filter, contextText) && hasNodeFilter(filter))
             matches.push(n);
         for (const child of n.children)
             walk(child);
@@ -1134,32 +1521,23 @@ export function findNodes(node, filter) {
     return matches;
 }
 function summarizeFieldLabelState(session, fieldLabel) {
-    const a11y = sessionA11y(session);
-    if (!a11y)
-        return undefined;
-    const matches = findNodes(a11y, {
-        name: fieldLabel,
-        role: 'combobox',
-    });
-    if (matches.length === 0) {
-        matches.push(...findNodes(a11y, { name: fieldLabel, role: 'textbox' }));
-    }
-    if (matches.length === 0) {
-        matches.push(...findNodes(a11y, { name: fieldLabel, role: 'button' }));
-    }
-    const match = matches[0];
-    if (!match)
+    const payload = fieldStatePayload(session, fieldLabel);
+    if (!payload)
         return undefined;
     const parts = [`Field "${fieldLabel}"`];
-    if (match.value)
-        parts.push(`value=${JSON.stringify(match.value)}`);
-    if (match.state && Object.keys(match.state).length > 0)
-        parts.push(`state=${JSON.stringify(match.state)}`);
-    if (match.validation?.error)
-        parts.push(`error=${JSON.stringify(match.validation.error)}`);
+    if (payload.role)
+        parts.push(`role=${String(payload.role)}`);
+    if (payload.value)
+        parts.push(`value=${JSON.stringify(payload.value)}`);
+    if (payload.valueLength)
+        parts.push(`valueLength=${String(payload.valueLength)}`);
+    if (payload.state)
+        parts.push(`state=${JSON.stringify(payload.state)}`);
+    if (payload.error)
+        parts.push(`error=${JSON.stringify(payload.error)}`);
     return parts.join(' ');
 }
-function formatNode(node, viewport) {
+function formatNode(node, root, viewport) {
     const visibleLeft = Math.max(0, node.bounds.x);
     const visibleTop = Math.max(0, node.bounds.y);
     const visibleRight = Math.min(viewport.width, node.bounds.x + node.bounds.width);
@@ -1177,11 +1555,14 @@ function formatNode(node, viewport) {
         : Math.round(Math.min(Math.max(node.bounds.y + node.bounds.height / 2, 0), viewport.height));
     const revealDeltaX = Math.round(node.bounds.x + node.bounds.width / 2 - viewport.width / 2);
     const revealDeltaY = Math.round(node.bounds.y + node.bounds.height / 2 - viewport.height / 2);
+    const prompt = promptContext(root, node);
+    const section = sectionContext(root, node);
     return {
         id: nodeIdForPath(node.path),
         role: node.role,
         name: node.name,
         ...(node.value ? { value: node.value } : {}),
+        ...(prompt || section ? { context: { ...(prompt ? { prompt } : {}), ...(section ? { section } : {}) } } : {}),
         bounds: node.bounds,
         visibleBounds: {
             x: visibleLeft,