@geometra/mcp 1.49.0 → 1.53.0

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,10 +306,31 @@ 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() {
-    const server = new McpServer({ name: 'geometra', version: '1.19.21' }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: 'geometra', version: '1.19.22' }, { capabilities: { tools: {} } });
     const sessionIdInput = z.string().optional().describe('Session identifier returned by geometra_connect. Omit to use the most recent session.');
     // ── connect ──────────────────────────────────────────────────
     server.tool('geometra_connect', `Connect to a Geometra WebSocket peer, or start \`geometra-proxy\` automatically for a normal web page.
@@ -1113,9 +1156,167 @@ Pass \`valuesById\` with field ids from \`geometra_form_schema\` for the most st
         }
         return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
     });
+    // ── fill + submit + wait ──────────────────────────────────────
+    server.tool('geometra_submit_form', `Fill a form, click its submit button, and optionally wait for the post-submit UI state — all in one MCP call. This is the preferred path for the canonical ATS / sign-in flow when the whole sequence should run server-side.
+
+Pass \`valuesById\` or \`valuesByLabel\` to populate fields, \`submit\` to target the submit button (default: semantic \`{ role: 'button', name: 'Submit' }\`), and \`waitFor\` to block on the post-submit state (success banner, navigation, submit button gone, etc.). Navigation is detected automatically and surfaced as \`navigated: true\` with \`afterUrl\`.
+
+Pass \`pageUrl\`/\`url\` to auto-connect in the same call — use \`isolated: true\` for safe parallel submissions.`, {
+        url: z.string().optional().describe('Optional target URL. Use a ws:// Geometra server URL or an http(s) page URL to auto-connect before submitting.'),
+        pageUrl: z.string().optional().describe('Optional http(s) page URL to auto-connect before submitting. Prefer this over url for browser pages.'),
+        port: z.number().int().min(0).max(65535).optional().describe('Preferred local port for an auto-spawned proxy (default: ephemeral OS-assigned port).'),
+        headless: z.boolean().optional().describe('Run Chromium headless when auto-spawning a proxy (default false = visible window).'),
+        width: z.number().int().positive().optional().describe('Viewport width for auto-connected sessions.'),
+        height: z.number().int().positive().optional().describe('Viewport height for auto-connected sessions.'),
+        slowMo: z.number().int().nonnegative().optional().describe('Playwright slowMo (ms) when auto-spawning a proxy.'),
+        isolated: z.boolean().optional().default(false).describe('When auto-connecting via pageUrl/url, request an isolated proxy. Required for safe parallel form submission.'),
+        formId: z.string().optional().describe('Optional form id from geometra_form_schema or geometra_page_model'),
+        valuesById: formValuesRecordSchema.optional().describe('Form values keyed by stable field id from geometra_form_schema'),
+        valuesByLabel: formValuesRecordSchema.optional().describe('Form values keyed by schema field label'),
+        submit: z.object(nodeFilterShape()).optional().describe('Semantic target for the submit button. Defaults to {role: "button", name: "Submit"}.'),
+        submitIndex: z.number().int().min(0).optional().default(0).describe('Which matching submit target to click after sorting top-to-bottom (default 0)'),
+        submitTimeoutMs: z.number().int().min(50).max(60_000).optional().default(15_000).describe('Action wait timeout for the submit click (default 15000ms). Increase for slow backends.'),
+        waitFor: z.object(waitConditionShape()).optional().describe('Optional semantic condition to wait for after the submit click (success banner, navigation, submit gone, etc.)'),
+        skipFill: z.boolean().optional().default(false).describe('Skip the fill phase and go straight to submit+wait. Use when values have already been filled by a previous call.'),
+        failOnInvalid: z.boolean().optional().default(false).describe('Return an error if invalid fields remain after the submit wait resolves.'),
+        detail: detailInput(),
+        sessionId: sessionIdInput,
+    }, async ({ url, pageUrl, port, headless, width, height, slowMo, isolated, formId, valuesById, valuesByLabel, submit, submitIndex, submitTimeoutMs, waitFor, skipFill, failOnInvalid, detail, sessionId }) => {
+        const resolved = await ensureToolSession({ sessionId, url, pageUrl, port, headless, width, height, slowMo, isolated }, 'Not connected. Call geometra_connect first, or pass pageUrl/url to geometra_submit_form.');
+        if (!resolved.ok)
+            return err(resolved.error);
+        const session = resolved.session;
+        const connection = autoConnectionPayload(resolved);
+        if (!session.tree || !session.layout) {
+            await waitForUiCondition(session, () => Boolean(session.tree && session.layout), 2_000);
+        }
+        const entryA11y = sessionA11y(session);
+        if (!entryA11y)
+            return err('No UI tree available for form submission');
+        const entryUrl = entryA11y.meta?.pageUrl;
+        let fillSummary;
+        if (!skipFill) {
+            const entryCount = Object.keys(valuesById ?? {}).length + Object.keys(valuesByLabel ?? {}).length;
+            if (entryCount === 0) {
+                return err('Provide at least one value in valuesById or valuesByLabel, or set skipFill: true to submit already-filled values.');
+            }
+            const schemas = getSessionFormSchemas(session, { includeOptions: true, includeContext: 'auto' });
+            if (schemas.length === 0)
+                return err('No forms found in the current UI');
+            const resolution = resolveTargetFormSchema(schemas, { formId, valuesById, valuesByLabel });
+            if (!resolution.ok)
+                return err(resolution.error);
+            const schema = resolution.schema;
+            const planned = planFormFill(schema, { valuesById, valuesByLabel });
+            if (!planned.ok)
+                return err(planned.error);
+            try {
+                const startRevision = session.updateRevision;
+                const wait = await sendFillFields(session, planned.fields);
+                const ack = parseProxyFillAckResult(wait.result);
+                await waitForDeferredBatchUpdate(session, startRevision, wait);
+                fillSummary = {
+                    formId: schema.formId,
+                    fieldCount: planned.fields.length,
+                    ...(ack ? { invalidCount: ack.invalidCount, alertCount: ack.alertCount } : {}),
+                    ...(entryCount !== planned.fields.length ? { requestedValueCount: entryCount } : {}),
+                };
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                return err(`Failed to fill form before submit: ${message}`);
+            }
+        }
+        const submitFilter = submit ?? { role: 'button', name: 'Submit' };
+        const resolvedClick = await resolveClickLocation(session, {
+            filter: submitFilter,
+            index: submitIndex,
+            fullyVisible: true,
+            revealTimeoutMs: 2_500,
+        });
+        if (!resolvedClick.ok)
+            return err(`Submit target not found: ${resolvedClick.error}`);
+        const beforeSubmit = sessionA11y(session);
+        const clickWait = await sendClick(session, resolvedClick.value.x, resolvedClick.value.y, submitTimeoutMs);
+        let waitResult;
+        if (waitFor) {
+            const postWait = await waitForSemanticCondition(session, {
+                filter: {
+                    id: waitFor.id,
+                    role: waitFor.role,
+                    name: waitFor.name,
+                    text: waitFor.text,
+                    contextText: waitFor.contextText,
+                    promptText: waitFor.promptText,
+                    sectionText: waitFor.sectionText,
+                    itemText: waitFor.itemText,
+                    value: waitFor.value,
+                    checked: waitFor.checked,
+                    disabled: waitFor.disabled,
+                    focused: waitFor.focused,
+                    selected: waitFor.selected,
+                    expanded: waitFor.expanded,
+                    invalid: waitFor.invalid,
+                    required: waitFor.required,
+                    busy: waitFor.busy,
+                },
+                present: waitFor.present ?? true,
+                timeoutMs: waitFor.timeoutMs ?? 15_000,
+            });
+            if (!postWait.ok) {
+                const payload = {
+                    ...connection,
+                    completed: false,
+                    ...(fillSummary ? { fill: fillSummary } : {}),
+                    submit: {
+                        at: { x: resolvedClick.value.x, y: resolvedClick.value.y },
+                        ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target) } : {}),
+                        ...waitStatusPayload(clickWait),
+                    },
+                    waitFor: { ok: false, error: postWait.error },
+                };
+                return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+            }
+            waitResult = postWait.value;
+        }
+        const after = sessionA11y(session);
+        const signals = after ? collectSessionSignals(after) : undefined;
+        const afterUrl = after?.meta?.pageUrl;
+        const navigated = Boolean(afterUrl && entryUrl && afterUrl !== entryUrl);
+        const payload = {
+            ...connection,
+            completed: true,
+            ...(fillSummary ? { fill: fillSummary } : {}),
+            submit: {
+                at: { x: resolvedClick.value.x, y: resolvedClick.value.y },
+                ...(resolvedClick.value.target ? { target: compactNodeReference(resolvedClick.value.target), revealSteps: resolvedClick.value.revealAttempts ?? 0 } : {}),
+                ...waitStatusPayload(clickWait),
+            },
+            ...(waitResult ? { waitFor: waitConditionCompact(waitResult) } : {}),
+            ...(navigated ? { navigated: true, afterUrl } : {}),
+            ...(signals ? { final: sessionSignalsPayload(signals, detail) } : {}),
+        };
+        // Pull in page model hints on navigation to mirror fill_form behavior.
+        if (navigated && after) {
+            const model = buildPageModel(after);
+            if (model.captcha)
+                payload.captcha = model.captcha;
+            if (model.verification)
+                payload.verification = model.verification;
+        }
+        if (failOnInvalid && signals && signals.invalidFields.length > 0) {
+            return err(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+        }
+        // Swallow the unused `beforeSubmit` binding; it anchors that the a11y tree was
+        // captured pre-click and keeps the pattern consistent with other tools that
+        // diff before/after for summaries (we rely on the waitFor / final signals
+        // for the actual comparison here).
+        void beforeSubmit;
+        return ok(JSON.stringify(payload, null, detail === 'verbose' ? 2 : undefined));
+    });
     server.tool('geometra_run_actions', `Execute several Geometra actions in one MCP round trip and return one consolidated result. This is the preferred path for long, multi-step form fills where one-tool-per-field would otherwise create too much chatter.
 
-Supported step types: \`click\`, \`type\`, \`key\`, \`upload_files\`, \`pick_listbox_option\`, \`select_option\`, \`set_checked\`, \`wheel\`, \`wait_for\`, 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).'),
@@ -1465,7 +1666,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             return sessionResult.error;
         const session = sessionResult.session;
         const before = sessionA11y(session);
-        const resolved = await resolveClickLocation(session, {
+        const resolved = await resolveClickLocationWithFallback(session, {
             x,
             y,
             filter: {
@@ -1531,6 +1732,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
                 at: { x: resolved.value.x, y: resolved.value.y },
                 ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
                 ...waitStatusPayload(wait),
+                ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
                 postWait: waitConditionCompact(postWait.value),
             };
             return ok(detailText(lines.filter(Boolean).join('\n'), compact, detail));
@@ -1539,6 +1741,7 @@ After clicking, returns a compact semantic delta when possible (dialogs/forms/li
             at: { x: resolved.value.x, y: resolved.value.y },
             ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
             ...waitStatusPayload(wait),
+            ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
         };
         return ok(detailText(lines.filter(Boolean).join('\n'), compact, detail));
     });
@@ -2774,6 +2977,48 @@ async function resolveClickLocation(session, options) {
         },
     };
 }
+async function resolveClickLocationWithFallback(session, options) {
+    const first = await resolveClickLocation(session, options);
+    if (first.ok)
+        return first;
+    // Fallback only applies to semantic resolves. Explicit coordinates never enter
+    // the reveal path, so there is nothing to retry.
+    const hasExplicitCoordinates = options.x !== undefined || options.y !== undefined;
+    if (hasExplicitCoordinates)
+        return first;
+    if (!hasNodeFilter(options.filter))
+        return first;
+    let attempts = 1;
+    const startRevision = session.updateRevision;
+    const revisionAdvanced = await waitForUiCondition(session, () => session.updateRevision > startRevision, 600);
+    if (revisionAdvanced) {
+        attempts += 1;
+        const retry = await resolveClickLocation(session, options);
+        if (retry.ok) {
+            return {
+                ok: true,
+                value: retry.value,
+                fallback: { used: true, reason: 'revision-retry', attempts },
+            };
+        }
+    }
+    if (options.fullyVisible !== false) {
+        attempts += 1;
+        const relaxed = await resolveClickLocation(session, {
+            ...options,
+            fullyVisible: false,
+            maxRevealSteps: Math.max(options.maxRevealSteps ?? 0, 24),
+        });
+        if (relaxed.ok) {
+            return {
+                ok: true,
+                value: relaxed.value,
+                fallback: { used: true, reason: 'relaxed-visibility', attempts },
+            };
+        }
+    }
+    return first;
+}
 function describeFormattedNode(node) {
     return `${node.role}${node.name ? ` ${JSON.stringify(node.name)}` : ''} (${node.id})`;
 }
@@ -3225,6 +3470,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);
@@ -3242,7 +3488,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
     switch (action.type) {
         case 'click': {
             const before = sessionA11y(session);
-            const resolved = await resolveClickLocation(session, {
+            const resolved = await resolveClickLocationWithFallback(session, {
                 x: action.x,
                 y: action.y,
                 filter: {
@@ -3313,6 +3559,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                     at: { x: resolved.value.x, y: resolved.value.y },
                     ...(resolved.value.target ? { target: compactNodeReference(resolved.value.target), revealSteps: resolved.value.revealAttempts ?? 0 } : {}),
                     ...waitStatusPayload(wait),
+                    ...(resolved.fallback ? { fallback: resolved.fallback } : {}),
                     ...(postWaitCompact ? { postWait: postWaitCompact } : {}),
                 },
             };
@@ -3480,13 +3727,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 +3773,7 @@ async function executeBatchAction(session, action, detail, includeSteps) {
                             execution: 'batched',
                             finalSource: batched.finalSource,
                             final: batched.final,
+                            ...(verification ? { verification } : {}),
                         },
                     };
                 }
@@ -3519,11 +3799,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 +3956,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 +4093,7 @@ function err(text) {
  *     const session = sessionResult.session
  */
 function resolveToolSession(sessionId) {
+    pruneDisconnectedSessions();
     const result = resolveSession(sessionId);
     switch (result.kind) {
         case 'ok':
@@ -3814,7 +4102,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?: {