@geometra/mcp 1.63.0 → 1.64.0

package/dist/session-state.js

@@ -18,16 +18,59 @@ function resolveSessionStateFile() {
     mkdirSync(dir, { recursive: true });
     return path.join(dir, `parallel-mcp-${process.pid}-${threadId}.sqlite`);
 }
-const orchestrator = new ParallelMcpOrchestrator(new SqliteParallelMcpStore({ filename: resolveSessionStateFile() }), { defaultLeaseMs: SESSION_LEASE_MS });
-const leaseSweep = setInterval(() => {
+function isSessionLifecycleDisabled() {
+    const raw = process.env.GEOMETRA_MCP_DISABLE_SESSION_LIFECYCLE?.trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes' || raw === 'on';
+}
+function formatSessionLifecycleInitError(error) {
+    if (error instanceof Error) {
+        if (error.code === 'ERR_DLOPEN_FAILED' &&
+            error.message.includes('better_sqlite3.node')) {
+            return `${error.message}. Rebuild the native module with \`npm rebuild better-sqlite3\` in the MCP package directory, or reinstall dependencies for the current Node.js version.`;
+        }
+        return error.message;
+    }
+    return String(error);
+}
+function createSessionLifecycleRegistry() {
+    if (isSessionLifecycleDisabled()) {
+        process.stderr.write('[geometra-mcp] durable session lifecycle disabled via GEOMETRA_MCP_DISABLE_SESSION_LIFECYCLE\n');
+        return {
+            available: false,
+            orchestrator: null,
+            close: () => { },
+        };
+    }
     try {
-        orchestrator.expireLeases();
+        const orchestrator = new ParallelMcpOrchestrator(new SqliteParallelMcpStore({ filename: resolveSessionStateFile() }), { defaultLeaseMs: SESSION_LEASE_MS });
+        const leaseSweep = setInterval(() => {
+            try {
+                orchestrator.expireLeases();
+            }
+            catch {
+                /* ignore background lease sweep failures */
+            }
+        }, SESSION_SWEEP_MS);
+        leaseSweep.unref();
+        return {
+            available: true,
+            orchestrator,
+            close: () => {
+                clearInterval(leaseSweep);
+                orchestrator.close();
+            },
+        };
     }
-    catch {
-        /* ignore background lease sweep failures */
+    catch (error) {
+        process.stderr.write(`[geometra-mcp] durable session lifecycle disabled: ${formatSessionLifecycleInitError(error)}\n`);
+        return {
+            available: false,
+            orchestrator: null,
+            close: () => { },
+        };
     }
-}, SESSION_SWEEP_MS);
-leaseSweep.unref();
+}
+const lifecycleRegistry = createSessionLifecycleRegistry();
 function extractPageUrl(target) {
     const cached = target.cachedA11y?.meta?.pageUrl;
     if (typeof cached === 'string' && cached.length > 0)
@@ -86,6 +129,15 @@ function workerIdFor(sessionId) {
     return `${SESSION_WORKER_PREFIX}:${sessionId}`;
 }
 export function initializeSessionLifecycle(target, options) {
+    if (!lifecycleRegistry.available || !lifecycleRegistry.orchestrator) {
+        target.lifecycleFinalized = true;
+        target.lifecycleTaskId = undefined;
+        target.lifecycleTaskKind = undefined;
+        target.lifecycleLeaseId = undefined;
+        target.lifecycleWorkerId = undefined;
+        return;
+    }
+    const orchestrator = lifecycleRegistry.orchestrator;
     const sessionId = target.id;
     const taskId = liveTaskIdFor(sessionId);
     const taskKind = liveTaskKindFor(sessionId);
@@ -131,6 +183,9 @@ export function initializeSessionLifecycle(target, options) {
     target.lifecycleFinalized = false;
 }
 export function heartbeatSessionLifecycle(target) {
+    if (!lifecycleRegistry.orchestrator)
+        return;
+    const orchestrator = lifecycleRegistry.orchestrator;
     if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
         return;
     orchestrator.heartbeatLease({
@@ -141,6 +196,9 @@ export function heartbeatSessionLifecycle(target) {
     });
 }
 export function recordSessionSnapshot(target, label, extra) {
+    if (!lifecycleRegistry.orchestrator)
+        return;
+    const orchestrator = lifecycleRegistry.orchestrator;
     if (!target.lifecycleTaskId)
         return;
     orchestrator.appendContextSnapshot({
@@ -152,6 +210,9 @@ export function recordSessionSnapshot(target, label, extra) {
     });
 }
 export function completeSessionLifecycle(target, reason, extra) {
+    if (!lifecycleRegistry.orchestrator)
+        return;
+    const orchestrator = lifecycleRegistry.orchestrator;
     if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
         return;
     orchestrator.completeTask({
@@ -171,6 +232,9 @@ export function completeSessionLifecycle(target, reason, extra) {
     target.lifecycleFinalized = true;
 }
 export function failSessionLifecycle(target, error, extra) {
+    if (!lifecycleRegistry.orchestrator)
+        return;
+    const orchestrator = lifecycleRegistry.orchestrator;
     if (target.lifecycleFinalized || !target.lifecycleTaskId || !target.lifecycleLeaseId || !target.lifecycleWorkerId)
         return;
     recordSessionSnapshot(target, 'session.failed', {
@@ -187,6 +251,5 @@ export function failSessionLifecycle(target, error, extra) {
     target.lifecycleFinalized = true;
 }
 export function shutdownSessionLifecycleRegistry() {
-    clearInterval(leaseSweep);
-    orchestrator.close();
+    lifecycleRegistry.close();
 }

package/dist/session.d.ts

@@ -29,6 +29,17 @@ export interface A11yNode {
         scrollX?: number;
         scrollY?: number;
         controlTag?: string;
+        /** Stable authored DOM identity emitted by the proxy extractor (`id:` or `name:`). */
+        controlKey?: string;
+        controlId?: string;
+        controlName?: string;
+        options?: Array<{
+            value: string;
+            label: string;
+            disabled: boolean;
+            selected: boolean;
+            index: number;
+        }>;
         placeholder?: string;
         inputPattern?: string;
         inputType?: string;
@@ -284,8 +295,19 @@ export interface PageSectionDetail {
 export type FormSchemaFieldKind = 'text' | 'choice' | 'toggle' | 'multi_choice';
 export type FormSchemaChoiceType = 'select' | 'group' | 'listbox';
 export type FormSchemaContextMode = 'auto' | 'always' | 'none';
+export interface FormSchemaOption {
+    /** Stable within the authored control identity; index disambiguates duplicate values/labels. */
+    id: string;
+    value: string;
+    label: string;
+    index: number;
+    disabled?: boolean;
+    selected?: boolean;
+}
 export interface FormSchemaField {
     id: string;
+    /** Authored DOM identity used for exact proxy-side resolution before accessible-label fallback. */
+    fieldKey?: string;
     kind: FormSchemaFieldKind;
     label: string;
     required?: boolean;
@@ -299,6 +321,7 @@ export interface FormSchemaField {
     values?: string[];
     optionCount?: number;
     options?: string[];
+    optionDetails?: FormSchemaOption[];
     aliases?: Record<string, string[]>;
     format?: {
         placeholder?: string;
@@ -346,6 +369,60 @@ export interface FormSchemaBuildOptions {
     includeOptions?: boolean;
     includeContext?: FormSchemaContextMode;
 }
+export interface FormGraphSource {
+    id: string;
+    kind: 'html';
+    title?: string;
+    url?: string;
+}
+export interface FormGraphSourceAnchor {
+    sourceId: string;
+    kind: 'html';
+    fieldName?: string;
+    pointer?: string;
+}
+export interface FormGraphField {
+    id: string;
+    path: string;
+    label: string;
+    kind: 'boolean' | 'enum' | 'text' | 'textarea' | 'email' | 'phone' | 'date' | 'number';
+    required?: boolean;
+    reviewRequired?: boolean;
+    aliases?: string[];
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    constraints?: {
+        pattern?: string;
+    };
+    sourceAnchors?: FormGraphSourceAnchor[];
+    metadata?: Record<string, unknown>;
+}
+export interface FormGraphModel {
+    formgraph: '0.1';
+    id: string;
+    title: string;
+    description?: string;
+    sources: FormGraphSource[];
+    fields: FormGraphField[];
+    evidence: [];
+    dependencies: [];
+    review: {
+        autoSubmitAllowed: false;
+        requiredBeforeSubmit: true;
+    };
+    metadata: {
+        producer: 'geometra';
+        geometra: {
+            formId: string;
+            fieldCount: number;
+            requiredCount: number;
+            invalidCount: number;
+            sections?: FormSchemaSection[];
+        };
+    };
+}
 export interface UiNodeUpdate {
     before: CompactUiNode;
     after: CompactUiNode;
@@ -460,12 +537,14 @@ export interface UpdateWaitResult {
 export type ProxyFillField = {
     kind: 'auto';
     fieldId?: string;
+    fieldKey?: string;
     fieldLabel: string;
     value: string | boolean;
     exact?: boolean;
 } | {
     kind: 'text';
     fieldId?: string;
+    fieldKey?: string;
     fieldLabel: string;
     value: string;
     exact?: boolean;
@@ -474,13 +553,17 @@ export type ProxyFillField = {
 } | {
     kind: 'choice';
     fieldId?: string;
+    fieldKey?: string;
     fieldLabel: string;
     value: string;
+    optionIndex?: number;
     query?: string;
     exact?: boolean;
     choiceType?: FormSchemaChoiceType;
 } | {
     kind: 'toggle';
+    fieldId?: string;
+    fieldKey?: string;
     label: string;
     checked?: boolean;
     exact?: boolean;
@@ -488,6 +571,7 @@ export type ProxyFillField = {
 } | {
     kind: 'file';
     fieldId?: string;
+    fieldKey?: string;
     fieldLabel: string;
     paths: string[];
     exact?: boolean;
@@ -625,6 +709,8 @@ export declare function sendFileUpload(session: Session, paths: string[], opts?:
         x: number;
         y: number;
     };
+    fieldId?: string;
+    fieldKey?: string;
     fieldLabel?: string;
     exact?: boolean;
     strategy?: 'auto' | 'chooser' | 'hidden' | 'drop';
@@ -637,6 +723,7 @@ export declare function sendFileUpload(session: Session, paths: string[], opts?:
 export declare function sendFieldText(session: Session, fieldLabel: string, value: string, opts?: {
     exact?: boolean;
     fieldId?: string;
+    fieldKey?: string;
     typingDelayMs?: number;
     imeFriendly?: boolean;
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
@@ -646,6 +733,8 @@ export declare function sendFieldChoice(session: Session, fieldLabel: string, va
     query?: string;
     choiceType?: FormSchemaChoiceType;
     fieldId?: string;
+    fieldKey?: string;
+    optionIndex?: number;
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** Fill several semantic form fields in one proxy-side batch. */
 export declare function sendFillFields(session: Session, fields: ProxyFillField[], timeoutMs?: number): Promise<UpdateWaitResult>;
@@ -668,6 +757,8 @@ export declare function sendListboxPick(session: Session, label: string, opts?:
     };
     fieldLabel?: string;
     query?: string;
+    fieldId?: string;
+    fieldKey?: string;
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** Native `<select>` only: click the control center, then pick by value, label text, or zero-based index. */
 export declare function sendSelectOption(session: Session, x: number, y: number, option: {
@@ -680,6 +771,9 @@ export declare function sendSetChecked(session: Session, label: string, opts?: {
     checked?: boolean;
     exact?: boolean;
     controlType?: 'checkbox' | 'radio';
+    fieldKey?: string;
+    contextText?: string;
+    sectionText?: string;
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** Mouse wheel / scroll. Optional `x`,`y` move pointer before scrolling. */
 export declare function sendWheel(session: Session, deltaY: number, opts?: {
@@ -732,6 +826,8 @@ export declare function buildPageModel(root: A11yNode, options?: {
     blockDetection?: boolean;
 }): PageModel;
 export declare function buildFormSchemas(root: A11yNode, options?: FormSchemaBuildOptions): FormSchemaModel[];
+export declare function buildFormGraphs(root: A11yNode, options?: FormSchemaBuildOptions): FormGraphModel[];
+export declare function formSchemaToFormGraph(schema: FormSchemaModel, pageUrl?: string): FormGraphModel;
 /**
  * Required-field snapshot for automation: every required field in a form, including
  * offscreen entries, annotated with visibility and scroll hints so agents do not