@geometra/mcp 1.49.0 → 1.52.0

package/dist/__tests__/ats-integration.test.js

@@ -70,6 +70,7 @@ vi.mock('../session.js', () => ({
     connectThroughProxy: mockState.connectThroughProxy,
     prewarmProxy: mockState.prewarmProxy,
     disconnect: vi.fn(),
+    pruneDisconnectedSessions: vi.fn(() => []),
     getSession: vi.fn(() => mockState.session),
     resolveSession: vi.fn((id) => ({ kind: 'ok', session: mockState.session, ...(id ? { id } : {}) })),
     listSessions: vi.fn(() => [{ id: 's1', url: 'https://jobs.example.com/application' }]),

package/dist/__tests__/connect-utils.test.js

@@ -3,7 +3,7 @@ import { createRequire } from 'node:module';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { describe, expect, it } from 'vitest';
-import { formatConnectFailureMessage, normalizeConnectTarget } from '../connect-utils.js';
+import { CONNECT_TARGET_EXACTLY_ONE_ERROR, formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget, } from '../connect-utils.js';
 import { formatProxyStartupFailure, parseProxyReadySignalLine, resolveProxyScriptPath, resolveProxyScriptPathWith, } from '../proxy-spawn.js';
 describe('normalizeConnectTarget', () => {
     it('accepts explicit pageUrl for http(s) pages', () => {
@@ -46,23 +46,102 @@ describe('normalizeConnectTarget', () => {
             },
         });
     });
+    it('accepts wss url input for already-running peers (TLS WebSocket)', () => {
+        const result = normalizeConnectTarget({ url: 'wss://example.com/socket' });
+        expect(result).toEqual({
+            ok: true,
+            value: {
+                kind: 'ws',
+                wsUrl: 'wss://example.com/socket',
+                autoCoercedFromUrl: false,
+            },
+        });
+    });
     it('rejects ambiguous and empty connect inputs', () => {
         expect(normalizeConnectTarget({})).toEqual({
             ok: false,
-            error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).',
+            error: CONNECT_TARGET_EXACTLY_ONE_ERROR,
         });
         expect(normalizeConnectTarget({ url: 'ws://127.0.0.1:3100', pageUrl: 'https://example.com' })).toEqual({
             ok: false,
-            error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).',
+            error: CONNECT_TARGET_EXACTLY_ONE_ERROR,
+        });
+    });
+    it('rejects invalid pageUrl strings (URL parser failure)', () => {
+        const result = normalizeConnectTarget({ pageUrl: 'https://exam ple.com' });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error.startsWith('Invalid pageUrl:')).toBe(true);
+        }
+    });
+    it('rejects non-http(s) url when using pageUrl (explicit)', () => {
+        expect(normalizeConnectTarget({ pageUrl: 'file:///tmp/x.html' })).toEqual({
+            ok: false,
+            error: 'pageUrl must use http:// or https:// (received file:)',
+        });
+    });
+    it('rejects invalid url strings for the url field', () => {
+        const result = normalizeConnectTarget({ url: ':::not-a-url' });
+        expect(result.ok).toBe(false);
+        if (!result.ok) {
+            expect(result.error).toContain('Invalid url:');
+            expect(result.error).toContain('ws://');
+        }
+    });
+    it('rejects unsupported protocols on the url field (neither http(s) nor ws(s))', () => {
+        expect(normalizeConnectTarget({ url: 'ftp://files.example.com/pub' })).toEqual({
+            ok: false,
+            error: 'Unsupported url protocol ftp:. Use ws://... for an already-running Geometra server, or http:// / https:// for webpages.',
+        });
+    });
+    it('trims whitespace-only inputs to empty (same as omitting url/pageUrl)', () => {
+        expect(normalizeConnectTarget({ url: '   ', pageUrl: undefined })).toEqual({
+            ok: false,
+            error: CONNECT_TARGET_EXACTLY_ONE_ERROR,
+        });
+    });
+    it('trims whitespace-only pageUrl to empty (symmetric with url-only whitespace)', () => {
+        expect(normalizeConnectTarget({ pageUrl: '   ' })).toEqual({
+            ok: false,
+            error: CONNECT_TARGET_EXACTLY_ONE_ERROR,
         });
     });
 });
+describe('isHttpUrl', () => {
+    it('accepts http and https URLs', () => {
+        expect(isHttpUrl('https://example.com/path')).toBe(true);
+        expect(isHttpUrl('http://localhost:8080/')).toBe(true);
+    });
+    it('accepts IPv6 literal hosts (URL parser canonical form)', () => {
+        expect(isHttpUrl('https://[::1]:8443/')).toBe(true);
+        expect(isHttpUrl('http://[2001:db8::1]/')).toBe(true);
+    });
+    it('rejects ws(s), file, and other schemes', () => {
+        expect(isHttpUrl('ws://127.0.0.1:3100')).toBe(false);
+        expect(isHttpUrl('wss://example.com')).toBe(false);
+        expect(isHttpUrl('file:///tmp/x')).toBe(false);
+    });
+    it('rejects malformed strings', () => {
+        expect(isHttpUrl('not a url')).toBe(false);
+        expect(isHttpUrl('')).toBe(false);
+    });
+});
 describe('formatConnectFailureMessage', () => {
     it('adds a targeted hint when ws connect fails for a normal webpage flow', () => {
         const message = formatConnectFailureMessage(new Error('WebSocket error connecting to ws://localhost:3100: connect ECONNREFUSED'), { kind: 'ws', wsUrl: 'ws://localhost:3100', autoCoercedFromUrl: false });
         expect(message).toContain('ECONNREFUSED');
         expect(message).toContain('pageUrl: "https://…"');
     });
+    it('adds the same hint when ws connect fails with DNS resolution errors (wrong host or offline resolver)', () => {
+        const message = formatConnectFailureMessage(new Error('getaddrinfo ENOTFOUND bad.example.com'), { kind: 'ws', wsUrl: 'ws://bad.example.com:3100', autoCoercedFromUrl: false });
+        expect(message).toContain('ENOTFOUND');
+        expect(message).toContain('pageUrl:');
+    });
+    it('adds an install hint when the proxy package cannot be resolved', () => {
+        const message = formatConnectFailureMessage(new Error('Could not resolve @geometra/proxy from mcp'), { kind: 'proxy', pageUrl: 'https://example.com', autoCoercedFromUrl: false });
+        expect(message).toContain('Could not resolve @geometra/proxy');
+        expect(message).toContain('@geometra/proxy');
+    });
 });
 describe('proxy ready helpers', () => {
     it('resolves the bundled proxy CLI entry in the source tree', () => {

package/dist/__tests__/proxy-session-actions.test.js

@@ -287,4 +287,70 @@ describe('proxy-backed MCP actions', () => {
             await new Promise((resolve, reject) => wss.close(err => (err ? reject(err) : resolve())));
         }
     });
+    it('reconnects once when an action is sent on a closed socket', async () => {
+        const wss = new WebSocketServer({ port: 0 });
+        let connectionCount = 0;
+        wss.on('connection', ws => {
+            connectionCount += 1;
+            ws.on('message', raw => {
+                const msg = JSON.parse(String(raw));
+                if (msg.type === 'resize') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: { x: 0, y: 0, width: 1024, height: 768, children: [] },
+                        tree: { kind: 'box', props: {}, semantic: { tag: 'body', role: 'group' }, children: [] },
+                    }));
+                    return;
+                }
+                if (msg.type === 'event') {
+                    ws.send(JSON.stringify({
+                        type: 'frame',
+                        layout: { x: 0, y: 0, width: 1024, height: 768, children: [] },
+                        tree: {
+                            kind: 'box',
+                            props: {},
+                            semantic: { tag: 'body', role: 'group', ariaLabel: 'Reconnected' },
+                            children: [],
+                        },
+                    }));
+                    ws.send(JSON.stringify({
+                        type: 'ack',
+                        requestId: msg.requestId,
+                        result: { ok: true },
+                    }));
+                }
+            });
+        });
+        const port = await new Promise((resolve, reject) => {
+            wss.once('listening', () => {
+                const address = wss.address();
+                if (typeof address === 'object' && address)
+                    resolve(address.port);
+                else
+                    reject(new Error('Failed to resolve ephemeral WebSocket port'));
+            });
+            wss.once('error', reject);
+        });
+        try {
+            const session = await connect(`ws://127.0.0.1:${port}`);
+            await new Promise(resolve => {
+                if (session.ws.readyState === session.ws.CLOSED) {
+                    resolve();
+                    return;
+                }
+                session.ws.once('close', () => resolve());
+                session.ws.close();
+            });
+            await expect(sendClick(session, 5, 5, 150)).resolves.toMatchObject({
+                status: 'updated',
+                timeoutMs: 150,
+                result: { ok: true },
+            });
+            expect(connectionCount).toBeGreaterThanOrEqual(2);
+        }
+        finally {
+            disconnect();
+            await new Promise((resolve, reject) => wss.close(err => (err ? reject(err) : resolve())));
+        }
+    });
 });

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

@@ -47,6 +47,7 @@ const mockState = vi.hoisted(() => ({
     sendSetChecked: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
     sendWheel: vi.fn(async () => ({ status: 'updated', timeoutMs: 2000 })),
     waitForUiCondition: vi.fn(async (_session, _check, _timeoutMs) => true),
+    expandPageSection: vi.fn((_root, _id, _opts) => null),
 }));
 function resetMockSessionCaches() {
     mockState.session.updateRevision = 1;
@@ -66,6 +67,7 @@ vi.mock('../session.js', () => ({
     connectThroughProxy: mockState.connectThroughProxy,
     prewarmProxy: mockState.prewarmProxy,
     disconnect: vi.fn(),
+    pruneDisconnectedSessions: vi.fn(() => []),
     getSession: vi.fn(() => mockState.session),
     resolveSession: vi.fn((id) => ({ kind: 'ok', session: mockState.session, ...(id ? { id } : {}) })),
     listSessions: vi.fn(() => [{ id: 's1', url: 'https://jobs.example.com/application' }]),
@@ -96,7 +98,7 @@ vi.mock('../session.js', () => ({
     })),
     buildFormSchemas: vi.fn(() => mockState.formSchemas),
     buildFormRequiredSnapshot: vi.fn(() => []),
-    expandPageSection: vi.fn(() => null),
+    expandPageSection: mockState.expandPageSection,
     buildUiDelta: vi.fn(() => ({})),
     hasUiDelta: vi.fn(() => false),
     nodeIdForPath: vi.fn((path) => `n:${path.length > 0 ? path.join('.') : 'root'}`),
@@ -365,6 +367,130 @@ describe('batch MCP result shaping', () => {
         expect(payload).not.toHaveProperty('steps');
         expect(payload).not.toHaveProperty('stepCount');
     });
+    it('attaches verifyFills readback results to run_actions fill_fields step', 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: 'Taylor Applicant', path: [0] }),
+                node('textbox', 'Phone', { value: '(929) 608-1737', path: [1] }),
+            ],
+        });
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            actions: [
+                {
+                    type: 'fill_fields',
+                    verifyFills: true,
+                    fields: [
+                        { kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' },
+                        { kind: 'text', fieldLabel: 'Phone', value: '+1-929-608-1737' },
+                    ],
+                },
+            ],
+            stopOnError: true,
+            includeSteps: true,
+            detail: 'terse',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        const steps = payload.steps;
+        expect(steps).toHaveLength(1);
+        expect(steps[0]).toMatchObject({
+            type: 'fill_fields',
+            ok: true,
+            fieldCount: 2,
+            verification: { verified: 2, mismatches: [] },
+        });
+    });
+    it('runs expand_section inside run_actions and returns the section detail inline', async () => {
+        const handler = getToolHandler('geometra_run_actions');
+        const fakeDetail = {
+            id: 'fm:1.0',
+            kind: 'form',
+            name: 'Application',
+            fieldCount: 3,
+            fields: [{ id: 'f1', label: 'Full name', required: true }],
+        };
+        mockState.expandPageSection.mockReturnValueOnce(fakeDetail);
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            actions: [
+                {
+                    type: 'expand_section',
+                    id: 'fm:1.0',
+                    maxFields: 10,
+                    onlyRequiredFields: true,
+                },
+            ],
+            includeSteps: true,
+            detail: 'terse',
+        });
+        expect(mockState.expandPageSection).toHaveBeenCalledWith(mockState.currentA11yRoot, 'fm:1.0', expect.objectContaining({ maxFields: 10, onlyRequiredFields: true }));
+        const payload = JSON.parse(result.content[0].text);
+        const steps = payload.steps;
+        expect(steps).toHaveLength(1);
+        expect(steps[0]).toMatchObject({
+            type: 'expand_section',
+            ok: true,
+            id: 'fm:1.0',
+            detail: fakeDetail,
+        });
+    });
+    it('surfaces an error when expand_section id does not match a section', async () => {
+        const handler = getToolHandler('geometra_run_actions');
+        mockState.expandPageSection.mockReturnValueOnce(null);
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            actions: [{ type: 'expand_section', id: 'fm:9.9' }],
+            includeSteps: true,
+            stopOnError: false,
+            detail: 'terse',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        const steps = payload.steps;
+        expect(steps[0]).toMatchObject({
+            type: 'expand_section',
+            ok: false,
+            error: expect.stringContaining('fm:9.9'),
+        });
+    });
+    it('flags mismatched fields in run_actions verifyFills output', 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: 'Unexpected Name', path: [0] }),
+            ],
+        });
+        const result = await handler({
+            pageUrl: 'https://jobs.example.com/application',
+            headless: true,
+            actions: [
+                {
+                    type: 'fill_fields',
+                    verifyFills: true,
+                    fields: [
+                        { kind: 'text', fieldLabel: 'Full name', value: 'Taylor Applicant' },
+                    ],
+                },
+            ],
+            includeSteps: true,
+            detail: 'terse',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        const steps = payload.steps;
+        const verification = steps[0].verification;
+        expect(verification.verified).toBe(0);
+        expect(verification.mismatches).toHaveLength(1);
+        expect(verification.mismatches[0]).toMatchObject({
+            fieldLabel: 'Full name',
+            expected: 'Taylor Applicant',
+            actual: 'Unexpected Name',
+        });
+    });
     it('finds repeated actions by itemText in terse mode', async () => {
         const handler = getToolHandler('geometra_find_action');
         mockState.currentA11yRoot = node('group', undefined, {

package/dist/__tests__/server-session-resolution.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/server-session-resolution.test.js

@@ -0,0 +1,88 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+const mockState = vi.hoisted(() => ({
+    pruneDisconnectedSessions: vi.fn(() => []),
+    resolveSession: vi.fn(() => ({ kind: 'none' })),
+}));
+vi.mock('../session.js', () => ({
+    connect: vi.fn(),
+    connectThroughProxy: vi.fn(),
+    disconnect: vi.fn(),
+    pruneDisconnectedSessions: mockState.pruneDisconnectedSessions,
+    resolveSession: mockState.resolveSession,
+    listSessions: vi.fn(() => []),
+    getDefaultSessionId: vi.fn(() => null),
+    prewarmProxy: vi.fn(),
+    sendClick: vi.fn(),
+    sendFillFields: vi.fn(),
+    sendFillOtp: vi.fn(),
+    sendType: vi.fn(),
+    sendKey: vi.fn(),
+    sendFileUpload: vi.fn(),
+    sendFieldText: vi.fn(),
+    sendFieldChoice: vi.fn(),
+    sendListboxPick: vi.fn(),
+    sendSelectOption: vi.fn(),
+    sendSetChecked: vi.fn(),
+    sendWheel: vi.fn(),
+    sendScreenshot: vi.fn(),
+    sendPdfGenerate: vi.fn(),
+    buildA11yTree: vi.fn(),
+    buildCompactUiIndex: vi.fn(() => ({ nodes: [], context: {} })),
+    buildFormRequiredSnapshot: vi.fn(() => []),
+    buildPageModel: vi.fn(),
+    buildFormSchemas: vi.fn(() => []),
+    expandPageSection: vi.fn(),
+    buildUiDelta: vi.fn(() => ({})),
+    hasUiDelta: vi.fn(() => false),
+    nodeIdForPath: vi.fn(),
+    nodeContextForNode: vi.fn(),
+    parseSectionId: vi.fn(),
+    findNodeByPath: vi.fn(),
+    summarizeCompactIndex: vi.fn(() => ''),
+    summarizePageModel: vi.fn(() => ''),
+    summarizeUiDelta: vi.fn(() => ''),
+    waitForUiCondition: vi.fn(),
+}));
+const { createServer } = await import('../server.js');
+function getToolHandler(name) {
+    const server = createServer();
+    return server._registeredTools[name].handler;
+}
+describe('server session resolution', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockState.pruneDisconnectedSessions.mockReturnValue([]);
+        mockState.resolveSession.mockReturnValue({ kind: 'none' });
+    });
+    it('prunes disconnected sessions before resolving explicit session ids', async () => {
+        const handler = getToolHandler('geometra_query');
+        mockState.pruneDisconnectedSessions.mockReturnValue(['s7']);
+        mockState.resolveSession.mockReturnValue({
+            kind: 'not_found',
+            id: 's7',
+            activeIds: [],
+        });
+        const result = await handler({ sessionId: 's7', role: 'button' });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('session_not_found: no active session with id "s7"');
+        expect(result.content[0].text).toContain('disconnected or expired');
+        expect(mockState.pruneDisconnectedSessions).toHaveBeenCalledTimes(1);
+        expect(mockState.resolveSession).toHaveBeenCalledWith('s7');
+    });
+    it('preserves ambiguous-session errors after pruning disconnected sessions', async () => {
+        const handler = getToolHandler('geometra_query');
+        mockState.pruneDisconnectedSessions.mockReturnValue(['s3']);
+        mockState.resolveSession.mockReturnValue({
+            kind: 'ambiguous',
+            activeIds: ['s1', 's2'],
+            isolatedIds: ['s2'],
+        });
+        const result = await handler({ role: 'button' });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain('multiple_active_sessions_provide_id');
+        expect(result.content[0].text).toContain('s1, s2');
+        expect(result.content[0].text).toContain('isolated: s2');
+        expect(mockState.pruneDisconnectedSessions).toHaveBeenCalledTimes(1);
+        expect(mockState.resolveSession).toHaveBeenCalledWith(undefined);
+    });
+});

package/dist/connect-utils.d.ts

@@ -4,6 +4,8 @@ export interface NormalizedConnectTarget {
     pageUrl?: string;
     wsUrl?: string;
 }
+/** Returned when `geometra_connect` omits both `url` and `pageUrl`, or supplies both at once. */
+export declare const CONNECT_TARGET_EXACTLY_ONE_ERROR = "Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://\u2026).";
 export declare function normalizeConnectTarget(input: {
     url?: string;
     pageUrl?: string;

package/dist/connect-utils.js

@@ -1,11 +1,13 @@
+/** Returned when `geometra_connect` omits both `url` and `pageUrl`, or supplies both at once. */
+export const CONNECT_TARGET_EXACTLY_ONE_ERROR = 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).';
 export function normalizeConnectTarget(input) {
     const rawUrl = normalizeOptional(input.url);
     const rawPageUrl = normalizeOptional(input.pageUrl);
     if (rawUrl && rawPageUrl) {
-        return { ok: false, error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).' };
+        return { ok: false, error: CONNECT_TARGET_EXACTLY_ONE_ERROR };
     }
     if (!rawUrl && !rawPageUrl) {
-        return { ok: false, error: 'Provide exactly one of: url (WebSocket or webpage URL) or pageUrl (https://…).' };
+        return { ok: false, error: CONNECT_TARGET_EXACTLY_ONE_ERROR };
     }
     if (rawPageUrl) {
         const parsed = parseUrl(rawPageUrl);
@@ -60,7 +62,7 @@ export function formatConnectFailureMessage(err, target) {
     const base = err instanceof Error ? err.message : String(err);
     const hints = [];
     if (target.kind === 'ws' &&
-        /ECONNREFUSED|timed out|closed before first frame|WebSocket error connecting/i.test(base)) {
+        /ECONNREFUSED|ENOTFOUND|getaddrinfo|timed out|closed before first frame|WebSocket error connecting/i.test(base)) {
         hints.push('If this is a normal website, call geometra_connect with pageUrl: "https://…" so MCP can start @geometra/proxy for you.');
     }
     if (/Could not resolve @geometra\/proxy/i.test(base)) {

package/dist/server.js

@@ -3,7 +3,7 @@ import { performance } from 'node:perf_hooks';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { formatConnectFailureMessage, isHttpUrl, normalizeConnectTarget } from './connect-utils.js';
-import { connect, connectThroughProxy, disconnect, resolveSession, listSessions, getDefaultSessionId, prewarmProxy, sendClick, sendFillFields, sendFillOtp, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, sendScreenshot, sendPdfGenerate, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, nodeContextForNode, parseSectionId, findNodeByPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
+import { connect, connectThroughProxy, disconnect, pruneDisconnectedSessions, resolveSession, listSessions, getDefaultSessionId, prewarmProxy, sendClick, sendFillFields, sendFillOtp, sendType, sendKey, sendFileUpload, sendFieldText, sendFieldChoice, sendListboxPick, sendSelectOption, sendSetChecked, sendWheel, sendScreenshot, sendPdfGenerate, buildA11yTree, buildCompactUiIndex, buildFormRequiredSnapshot, buildPageModel, buildFormSchemas, expandPageSection, buildUiDelta, hasUiDelta, nodeIdForPath, nodeContextForNode, parseSectionId, findNodeByPath, summarizeCompactIndex, summarizePageModel, summarizeUiDelta, waitForUiCondition, } from './session.js';
 function checkedStateInput() {
     return z
         .union([z.boolean(), z.literal('mixed')])
@@ -124,6 +124,17 @@ const fillFieldSchema = z.union([
         fieldLabel: z.string().describe('Visible field label / accessible name. Optional to duplicate when fieldId is present.'),
         value: z.string().describe('Text value to set'),
         exact: z.boolean().optional().describe('Exact label match'),
+        typingDelayMs: z
+            .number()
+            .int()
+            .min(0)
+            .max(500)
+            .optional()
+            .describe('Milliseconds between keystrokes when the proxy falls back to keyboard typing (masked inputs).'),
+        imeFriendly: z
+            .boolean()
+            .optional()
+            .describe('Use composition-friendly events for IME-heavy controlled fields.'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
     }),
     z.object({
@@ -132,6 +143,17 @@ const fillFieldSchema = z.union([
         fieldLabel: z.string().optional().describe('Optional when fieldId is present; MCP resolves the current label from geometra_form_schema'),
         value: z.string().describe('Text value to set'),
         exact: z.boolean().optional().describe('Exact label match'),
+        typingDelayMs: z
+            .number()
+            .int()
+            .min(0)
+            .max(500)
+            .optional()
+            .describe('Milliseconds between keystrokes when the proxy falls back to keyboard typing (masked inputs).'),
+        imeFriendly: z
+            .boolean()
+            .optional()
+            .describe('Use composition-friendly events for IME-heavy controlled fields.'),
         timeoutMs: timeoutMsInput.describe('Optional action wait timeout'),
     }),
     z.object({
@@ -284,6 +306,27 @@ const batchActionSchema = z.discriminatedUnion('type', [
     z.object({
         type: z.literal('fill_fields'),
         fields: z.array(fillFieldSchema).min(1).max(80),
+        verifyFills: z
+            .boolean()
+            .optional()
+            .describe('After filling, read each text/choice field back and flag mismatches (e.g. autocomplete rejected input, format transformed). Adds a `verification` entry to the step.'),
+    }),
+    z.object({
+        type: z.literal('expand_section'),
+        id: z.string().describe('Stable section id from geometra_page_model (e.g. fm:1.0, ls:2.1).'),
+        maxHeadings: z.number().int().min(1).max(20).optional(),
+        maxFields: z.number().int().min(1).max(40).optional(),
+        fieldOffset: z.number().int().min(0).optional(),
+        onlyRequiredFields: z.boolean().optional(),
+        onlyInvalidFields: z.boolean().optional(),
+        maxActions: z.number().int().min(1).max(30).optional(),
+        actionOffset: z.number().int().min(0).optional(),
+        maxLists: z.number().int().min(0).max(20).optional(),
+        listOffset: z.number().int().min(0).optional(),
+        maxItems: z.number().int().min(0).max(50).optional(),
+        itemOffset: z.number().int().min(0).optional(),
+        maxTextPreview: z.number().int().min(0).max(20).optional(),
+        includeBounds: z.boolean().optional(),
     }),
 ]);
 export function createServer() {
@@ -1115,7 +1158,7 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
     });
     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\`, and \`fill_fields\`. \`click\` steps can also carry a nested \`waitFor\` condition. Pass \`pageUrl\` / \`url\` to auto-connect so an entire flow can run in one MCP call.`, {
+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.`, {
         url: z.string().optional().describe('Optional target URL. Use a ws:// Geometra server URL or an http(s) page URL to auto-connect before running actions.'),
         pageUrl: z.string().optional().describe('Optional http(s) page URL to auto-connect before running actions. Prefer this over url for browser pages.'),
         port: z.number().int().min(0).max(65535).optional().describe('Preferred local port for an auto-spawned proxy (default: ephemeral OS-assigned port).'),
@@ -3225,6 +3268,7 @@ function batchFieldReadbackMatches(a11y, field) {
 function actionNeedsUiTree(action) {
     switch (action.type) {
         case 'wait_for':
+        case 'expand_section':
             return true;
         case 'click':
             return action.x === undefined || action.y === undefined || Boolean(action.waitFor);
@@ -3480,13 +3524,45 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                 compact: waitConditionCompact(waited.value),
             };
         }
+        case 'expand_section': {
+            const a11y = sessionA11y(session);
+            if (!a11y)
+                throw new Error('No UI tree available to expand section');
+            const sectionDetail = expandPageSection(a11y, action.id, {
+                maxHeadings: action.maxHeadings,
+                maxFields: action.maxFields,
+                fieldOffset: action.fieldOffset,
+                onlyRequiredFields: action.onlyRequiredFields,
+                onlyInvalidFields: action.onlyInvalidFields,
+                maxActions: action.maxActions,
+                actionOffset: action.actionOffset,
+                maxLists: action.maxLists,
+                listOffset: action.listOffset,
+                maxItems: action.maxItems,
+                itemOffset: action.itemOffset,
+                maxTextPreview: action.maxTextPreview,
+                includeBounds: action.includeBounds,
+            });
+            if (!sectionDetail)
+                throw new Error(`No expandable section found for id ${action.id}`);
+            return {
+                summary: detail === 'verbose'
+                    ? JSON.stringify(sectionDetail, null, 2)
+                    : `Expanded section "${action.id}".`,
+                compact: { id: action.id, detail: sectionDetail },
+            };
+        }
         case 'fill_fields': {
             const resolvedFields = resolveFillFieldInputs(session, action.fields);
             if (!resolvedFields.ok)
                 throw new Error(resolvedFields.error);
+            const verifyFillsFn = action.verifyFills
+                ? () => verifyFormFills(session, resolvedFields.fields.map(field => ({ field, confidence: 1.0, matchMethod: 'label-exact' })))
+                : undefined;
             if (!includeSteps) {
                 const batched = await tryBatchedResolvedFields(session, resolvedFields.fields, detail);
                 if (batched.ok) {
+                    const verification = verifyFillsFn?.();
                     return {
                         summary: `Filled ${resolvedFields.fields.length} field(s) in one proxy batch.`,
                         compact: {
@@ -3494,6 +3570,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                             execution: 'batched',
                             finalSource: batched.finalSource,
                             final: batched.final,
+                            ...(verification ? { verification } : {}),
                         },
                     };
                 }
@@ -3519,11 +3596,13 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                     ? { index, kind: field.kind, ok, summary: result.summary }
                     : { index, kind: field.kind, ok, ...result.compact });
             }
+            const verification = verifyFillsFn?.();
             return {
                 summary: steps.map(step => String(step.summary ?? '')).filter(Boolean).join('\n'),
                 compact: {
                     fieldCount: resolvedFields.fields.length,
                     ...(includeSteps ? { steps } : {}),
+                    ...(verification ? { verification } : {}),
                 },
             };
         }
@@ -3674,7 +3753,12 @@ async function executeFillField(session, field, detail) {
     switch (field.kind) {
         case 'text': {
             const before = sessionA11y(session);
-            const wait = await sendFieldText(session, field.fieldLabel, field.value, { exact: field.exact, fieldId: field.fieldId }, field.timeoutMs);
+            const wait = await sendFieldText(session, field.fieldLabel, field.value, {
+                exact: field.exact,
+                fieldId: field.fieldId,
+                typingDelayMs: field.typingDelayMs,
+                imeFriendly: field.imeFriendly,
+            }, field.timeoutMs);
             const fieldSummary = summarizeFieldLabelState(session, field.fieldLabel);
             return {
                 summary: [
@@ -3806,6 +3890,7 @@ function err(text) {
  *     const session = sessionResult.session
  */
 function resolveToolSession(sessionId) {
+    pruneDisconnectedSessions();
     const result = resolveSession(sessionId);
     switch (result.kind) {
         case 'ok':
@@ -3814,7 +3899,7 @@ function resolveToolSession(sessionId) {
             return { error: err('Not connected. Call geometra_connect first.') };
         case 'not_found':
             return {
-                error: err(`session_not_found: no active session with id "${result.id}". Active sessions: ${result.activeIds.length > 0 ? result.activeIds.join(', ') : '(none)'}. Call geometra_connect again to start a new session — the MCP server never silently routes an explicit sessionId onto a different session.`),
+                error: err(`session_not_found: no active session with id "${result.id}". Active sessions: ${result.activeIds.length > 0 ? result.activeIds.join(', ') : '(none)'}. The requested session may have disconnected or expired; call geometra_connect again to start a new session — the MCP server never silently routes an explicit sessionId onto a different session.`),
             };
         case 'ambiguous': {
             const isolatedSuffix = result.isolatedIds.length > 0

package/dist/session.d.ts

@@ -420,6 +420,7 @@ export interface Session {
         forms: FormSchemaModel[];
     }>;
     workflowState?: WorkflowState;
+    reconnectInFlight?: Promise<boolean>;
 }
 export interface SessionConnectTrace {
     mode: 'direct-ws' | 'fresh-proxy' | 'reused-proxy';
@@ -453,6 +454,8 @@ export type ProxyFillField = {
     fieldLabel: string;
     value: string;
     exact?: boolean;
+    typingDelayMs?: number;
+    imeFriendly?: boolean;
 } | {
     kind: 'choice';
     fieldId?: string;
@@ -526,6 +529,7 @@ export declare function connectThroughProxy(options: {
     isolated?: boolean;
 }): Promise<Session>;
 export declare function getSession(id?: string): Session | null;
+export declare function pruneDisconnectedSessions(): string[];
 /**
  * Tool-side session resolution with strict routing semantics.
  *
@@ -608,6 +612,8 @@ export declare function sendFileUpload(session: Session, paths: string[], opts?:
 export declare function sendFieldText(session: Session, fieldLabel: string, value: string, opts?: {
     exact?: boolean;
     fieldId?: string;
+    typingDelayMs?: number;
+    imeFriendly?: boolean;
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** Choose a value for a labeled choice field (select, custom combobox, or radio-style group). */
 export declare function sendFieldChoice(session: Session, fieldLabel: string, value: string, opts?: {

package/dist/session.js

@@ -22,6 +22,7 @@ const FILL_BATCH_CHOICE_FIELD_TIMEOUT_MS = 500;
 const FILL_BATCH_TOGGLE_FIELD_TIMEOUT_MS = 225;
 const FILL_BATCH_FILE_FIELD_TIMEOUT_MS = 5000;
 const FILL_BATCH_MAX_TIMEOUT_MS = 60_000;
+const SESSION_RECONNECT_TIMEOUT_MS = 5_000;
 let nextRequestSequence = 0;
 function invalidateSessionCaches(session) {
     session.cachedA11y = null;
@@ -682,6 +683,8 @@ export function connect(url, opts) {
             heartbeatInterval.unref();
         }
         ws.on('pong', () => {
+            if (session.ws !== ws)
+                return;
             lastMessageAt = Date.now();
             pendingPongBy = null;
         });
@@ -693,6 +696,8 @@ export function connect(url, opts) {
             }
         }, 10_000);
         ws.on('open', () => {
+            if (session.ws !== ws)
+                return;
             if (session.connectTrace) {
                 session.connectTrace.wsOpenMs = performance.now() - startedAt;
             }
@@ -715,6 +720,8 @@ export function connect(url, opts) {
             }
         });
         ws.on('message', (data) => {
+            if (session.ws !== ws)
+                return;
             lastMessageAt = Date.now();
             try {
                 const msg = JSON.parse(String(data));
@@ -755,6 +762,8 @@ export function connect(url, opts) {
             }
         });
         ws.on('close', () => {
+            if (session.ws !== ws)
+                return;
             if (heartbeatInterval) {
                 clearInterval(heartbeatInterval);
                 heartbeatInterval = null;
@@ -846,6 +855,19 @@ export function getSession(id) {
         return activeSessions.get(defaultSessionId) ?? null;
     return null;
 }
+export function pruneDisconnectedSessions() {
+    const removedIds = [];
+    for (const [id, session] of activeSessions.entries()) {
+        if (session.ws.readyState === WebSocket.OPEN)
+            continue;
+        removedIds.push(id);
+        activeSessions.delete(id);
+        if (defaultSessionId === id) {
+            promoteDefaultSession();
+        }
+    }
+    return removedIds;
+}
 export function resolveSession(id) {
     if (id) {
         const found = activeSessions.get(id);
@@ -903,6 +925,9 @@ function estimateFillBatchTimeout(fields) {
                 totalTextLength += field.value.length;
                 total += FILL_BATCH_TEXT_FIELD_TIMEOUT_MS;
                 total += Math.ceil(Math.max(1, field.value.length) / FILL_BATCH_TEXT_LENGTH_SLICE) * FILL_BATCH_TEXT_LENGTH_TIMEOUT_MS;
+                if (field.typingDelayMs !== undefined) {
+                    total += field.typingDelayMs * field.value.length;
+                }
                 break;
             case 'choice':
                 total += field.choiceType === 'group' ? FILL_BATCH_TOGGLE_FIELD_TIMEOUT_MS : FILL_BATCH_CHOICE_FIELD_TIMEOUT_MS;
@@ -956,16 +981,128 @@ export function waitForUiCondition(session, predicate, timeoutMs) {
         check();
     });
 }
-function sendResizeAndWaitForUpdate(session, width, height, timeoutMs = 5_000) {
-    return new Promise((resolve, reject) => {
-        if (session.ws.readyState !== WebSocket.OPEN) {
-            reject(new Error('Not connected'));
+function reconnectUrlForSession(session) {
+    if (session.proxyRuntime && typeof session.proxyRuntime.wsUrl === 'string') {
+        return session.proxyRuntime.wsUrl;
+    }
+    const pooled = reusableProxyEntryForSession(session);
+    if (pooled) {
+        return pooled.wsUrl;
+    }
+    if (typeof session.url === 'string' && /^wss?:\/\//i.test(session.url)) {
+        return session.url;
+    }
+    return null;
+}
+async function openWebSocket(url, timeoutMs = SESSION_RECONNECT_TIMEOUT_MS) {
+    return await new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        const timeout = setTimeout(() => {
+            cleanup();
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+            reject(new Error(`Reconnect to ${url} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        const onOpen = () => {
+            cleanup();
+            resolve(ws);
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(new Error(`WebSocket reconnect failed for ${url}: ${err.message}`));
+        };
+        function cleanup() {
+            clearTimeout(timeout);
+            ws.off('open', onOpen);
+            ws.off('error', onError);
+        }
+        ws.on('open', onOpen);
+        ws.on('error', onError);
+    });
+}
+function bindReconnectedSocket(session, ws) {
+    ws.on('message', data => {
+        if (session.ws !== ws)
             return;
+        try {
+            const msg = JSON.parse(String(data));
+            if (msg.type === 'frame') {
+                session.layout = msg.layout;
+                session.tree = msg.tree;
+                session.updateRevision++;
+                invalidateSessionCaches(session);
+            }
+            else if (msg.type === 'patch' && session.layout) {
+                applyPatches(session.layout, msg.patches);
+                session.updateRevision++;
+                invalidateSessionCaches(session);
+            }
+        }
+        catch {
+            /* ignore malformed messages */
         }
-        const startRevision = session.updateRevision;
-        session.ws.send(JSON.stringify({ type: 'resize', width, height }));
-        waitForNextUpdate(session, timeoutMs, undefined, startRevision).then(resolve).catch(reject);
     });
+    ws.on('close', () => {
+        if (session.ws !== ws)
+            return;
+        if (activeSessions.get(session.id) === session) {
+            activeSessions.delete(session.id);
+            if (defaultSessionId === session.id)
+                promoteDefaultSession();
+        }
+    });
+}
+async function ensureSessionConnected(session) {
+    if (session.ws.readyState === WebSocket.OPEN)
+        return;
+    if (session.reconnectInFlight) {
+        const recovered = await session.reconnectInFlight;
+        if (!recovered) {
+            throw new Error('Not connected');
+        }
+        return;
+    }
+    const targetUrl = reconnectUrlForSession(session);
+    if (!targetUrl) {
+        throw new Error('Not connected');
+    }
+    const reconnectPromise = (async () => {
+        const nextWs = await openWebSocket(targetUrl);
+        try {
+            session.ws.close();
+        }
+        catch {
+            /* ignore */
+        }
+        session.ws = nextWs;
+        bindReconnectedSocket(session, nextWs);
+        activeSessions.set(session.id, session);
+        if (!session.isolated) {
+            defaultSessionId = session.id;
+        }
+        return true;
+    })();
+    session.reconnectInFlight = reconnectPromise;
+    let recovered = false;
+    try {
+        recovered = await reconnectPromise;
+    }
+    finally {
+        session.reconnectInFlight = undefined;
+    }
+    if (!recovered) {
+        throw new Error('Not connected');
+    }
+}
+async function sendResizeAndWaitForUpdate(session, width, height, timeoutMs = 5_000) {
+    await ensureSessionConnected(session);
+    const startRevision = session.updateRevision;
+    session.ws.send(JSON.stringify({ type: 'resize', width, height }));
+    return await waitForNextUpdate(session, timeoutMs, undefined, startRevision);
 }
 /**
  * Send a click event at (x, y) and wait for the next frame/patch response.
@@ -982,11 +1119,8 @@ export function sendClick(session, x, y, timeoutMs) {
  * Send a sequence of key events to type text into the focused element.
  */
 export function sendType(session, text, timeoutMs) {
-    return new Promise((resolve, reject) => {
-        if (session.ws.readyState !== WebSocket.OPEN) {
-            reject(new Error('Not connected'));
-            return;
-        }
+    return (async () => {
+        await ensureSessionConnected(session);
         // Send each character as keydown + keyup
         for (const char of text) {
             const keyEvent = {
@@ -1003,8 +1137,8 @@ export function sendType(session, text, timeoutMs) {
             session.ws.send(JSON.stringify({ ...keyEvent, eventType: 'onKeyUp' }));
         }
         // Wait briefly for server to process and send update
-        waitForNextUpdate(session, timeoutMs).then(resolve).catch(reject);
-    });
+        return await waitForNextUpdate(session, timeoutMs);
+    })();
 }
 /**
  * Send a special key (Enter, Tab, Escape, etc.)
@@ -1054,6 +1188,10 @@ export function sendFieldText(session, fieldLabel, value, opts, timeoutMs) {
         payload.exact = opts.exact;
     if (opts?.fieldId)
         payload.fieldId = opts.fieldId;
+    if (opts?.typingDelayMs !== undefined)
+        payload.typingDelayMs = opts.typingDelayMs;
+    if (opts?.imeFriendly !== undefined)
+        payload.imeFriendly = opts.imeFriendly;
     return sendAndWaitForUpdate(session, payload, timeoutMs);
 }
 /** Choose a value for a labeled choice field (select, custom combobox, or radio-style group). */
@@ -2955,17 +3093,12 @@ function applyPatches(layout, patches) {
             node.height = patch.height;
     }
 }
-function sendAndWaitForUpdate(session, message, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, opts) {
-    return new Promise((resolve, reject) => {
-        if (session.ws.readyState !== WebSocket.OPEN) {
-            reject(new Error('Not connected'));
-            return;
-        }
-        const requestId = `req-${++nextRequestSequence}`;
-        const startRevision = session.updateRevision;
-        session.ws.send(JSON.stringify({ ...message, requestId }));
-        waitForNextUpdate(session, timeoutMs, requestId, startRevision, opts).then(resolve).catch(reject);
-    });
+async function sendAndWaitForUpdate(session, message, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, opts) {
+    await ensureSessionConnected(session);
+    const requestId = `req-${++nextRequestSequence}`;
+    const startRevision = session.updateRevision;
+    session.ws.send(JSON.stringify({ ...message, requestId }));
+    return await waitForNextUpdate(session, timeoutMs, requestId, startRevision, opts);
 }
 function waitForNextUpdate(session, timeoutMs = ACTION_UPDATE_TIMEOUT_MS, requestId, startRevision = session.updateRevision, opts) {
     return new Promise((resolve, reject) => {

package/package.json

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