@geometra/mcp 1.49.0 → 1.53.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, {
@@ -856,6 +982,152 @@ describe('batch MCP result shaping', () => {
         });
     });
 });
+describe('submit_form tool', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        resetMockSessionCaches();
+        mockState.formSchemas = [];
+    });
+    it('combines fill + submit-click + post-submit wait in one call', async () => {
+        const handler = getToolHandler('geometra_submit_form');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('textbox', 'Full name', { value: '', path: [0] }),
+                node('textbox', 'Email', { value: '', path: [1] }),
+                node('button', 'Submit application', {
+                    bounds: { x: 60, y: 480, width: 180, height: 40 },
+                    path: [2],
+                }),
+            ],
+        });
+        mockState.formSchemas = [{
+                formId: 'fm:0',
+                name: 'Application',
+                fieldCount: 2,
+                requiredCount: 2,
+                invalidCount: 2,
+                fields: [
+                    { id: 'ff:0.0', kind: 'text', label: 'Full name' },
+                    { id: 'ff:0.1', kind: 'text', label: 'Email' },
+                ],
+            }];
+        mockState.sendFillFields.mockImplementationOnce(async () => ({
+            status: 'acknowledged',
+            timeoutMs: 6000,
+            result: { invalidCount: 0, alertCount: 0, dialogCount: 0, busyCount: 0, pageUrl: 'https://jobs.example.com/application' },
+        }));
+        mockState.sendClick.mockImplementationOnce(async () => {
+            mockState.currentA11yRoot = node('group', undefined, {
+                bounds: { x: 0, y: 0, width: 1280, height: 800 },
+                meta: { pageUrl: 'https://jobs.example.com/confirm', scrollX: 0, scrollY: 0 },
+                children: [
+                    node('dialog', 'Application submitted', {
+                        bounds: { x: 240, y: 140, width: 420, height: 260 },
+                        path: [0],
+                    }),
+                ],
+            });
+            bumpMockUiRevision();
+            return { status: 'updated', timeoutMs: 2000 };
+        });
+        const result = await handler({
+            valuesByLabel: { 'Full name': 'Taylor Applicant', Email: 'taylor@example.com' },
+            submit: { role: 'button', name: 'Submit application' },
+            waitFor: { role: 'dialog', name: 'Application submitted', timeoutMs: 5000 },
+            detail: 'minimal',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            completed: true,
+            fill: { fieldCount: 2, formId: 'fm:0' },
+            submit: { target: { role: 'button', name: 'Submit application' } },
+            waitFor: { present: true, matchCount: 1 },
+            navigated: true,
+            afterUrl: 'https://jobs.example.com/confirm',
+        });
+        expect(mockState.sendFillFields).toHaveBeenCalledTimes(1);
+        expect(mockState.sendClick).toHaveBeenCalledTimes(1);
+    });
+    it('rejects missing values when skipFill is false', async () => {
+        const handler = getToolHandler('geometra_submit_form');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('button', 'Submit', { bounds: { x: 60, y: 480, width: 100, height: 40 }, path: [0] }),
+            ],
+        });
+        const result = await handler({ detail: 'minimal' });
+        expect(result.content[0].text).toContain('Provide at least one value');
+    });
+    it('skipFill: true goes straight to submit + wait', async () => {
+        const handler = getToolHandler('geometra_submit_form');
+        mockState.currentA11yRoot = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('button', 'Submit', { bounds: { x: 60, y: 480, width: 100, height: 40 }, path: [0] }),
+            ],
+        });
+        mockState.sendClick.mockImplementationOnce(async () => {
+            bumpMockUiRevision();
+            return { status: 'updated', timeoutMs: 2000 };
+        });
+        const result = await handler({
+            skipFill: true,
+            submit: { role: 'button', name: 'Submit' },
+            detail: 'minimal',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({ completed: true });
+        expect(payload).not.toHaveProperty('fill');
+        expect(mockState.sendFillFields).not.toHaveBeenCalled();
+        expect(mockState.sendClick).toHaveBeenCalledTimes(1);
+    });
+});
+describe('click transparent fallback', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        resetMockSessionCaches();
+    });
+    it('surfaces fallback.used when relaxed-visibility lets an offscreen submit resolve', async () => {
+        const handler = getToolHandler('geometra_click');
+        // First tree: target exists but is offscreen below the viewport, so a
+        // fullyVisible requirement cannot be satisfied before the reveal budget runs out.
+        // The relaxed-visibility fallback drops the fullyVisible requirement and tries
+        // once more with a larger reveal budget.
+        const offscreenTree = node('group', undefined, {
+            bounds: { x: 0, y: 0, width: 1280, height: 800 },
+            meta: { pageUrl: 'https://jobs.example.com/application', scrollX: 0, scrollY: 0 },
+            children: [
+                node('button', 'Submit', {
+                    // Starts fully offscreen-below and wheel stubs don't move it in tests,
+                    // so the fullyVisible attempt will fail. Relaxed-visibility sees it
+                    // intersect enough to count as revealed.
+                    bounds: { x: 60, y: 780, width: 180, height: 60 },
+                    path: [0],
+                }),
+            ],
+        });
+        mockState.currentA11yRoot = offscreenTree;
+        mockState.sendClick.mockResolvedValueOnce({ status: 'updated', timeoutMs: 2000 });
+        const result = await handler({
+            role: 'button',
+            name: 'Submit',
+            fullyVisible: true,
+            maxRevealSteps: 1,
+            revealTimeoutMs: 100,
+            detail: 'terse',
+        });
+        const payload = JSON.parse(result.content[0].text);
+        expect(payload).toMatchObject({
+            target: { role: 'button', name: 'Submit' },
+            fallback: { used: true, reason: 'relaxed-visibility' },
+        });
+    });
+});
 describe('query and reveal tools', () => {
     beforeEach(() => {
         vi.clearAllMocks();

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)) {