@geometra/mcp 1.63.2 → 1.65.0

package/dist/session.d.ts

@@ -29,10 +29,29 @@ 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;
         autocomplete?: string;
+        /** True when this semantic node represents an `<input type="file">`. */
+        fileInput?: boolean;
+        /** Authored file-type filter from the input's `accept` attribute. */
+        accept?: string;
+        /** True when the file input accepts more than one file. */
+        multiple?: boolean;
+        /** Geometry-only fallback that cannot be resolved by semantic proxy actions. */
+        coordinateOnly?: boolean;
         /**
          * True when the extractor detected that this `<input>` (or role=textbox)
          * lives inside an autocomplete / searchable combobox wrapper — React
@@ -281,11 +300,22 @@ export interface PageSectionDetail {
     items: PageListItemModel[];
     textPreview: string[];
 }
-export type FormSchemaFieldKind = 'text' | 'choice' | 'toggle' | 'multi_choice';
+export type FormSchemaFieldKind = 'text' | 'choice' | 'toggle' | 'multi_choice' | 'file';
 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,12 +329,15 @@ export interface FormSchemaField {
     values?: string[];
     optionCount?: number;
     options?: string[];
+    optionDetails?: FormSchemaOption[];
     aliases?: Record<string, string[]>;
     format?: {
         placeholder?: string;
         pattern?: string;
         inputType?: string;
         autocomplete?: string;
+        accept?: string;
+        multiple?: boolean;
     };
     context?: NodeContextModel;
 }
@@ -346,6 +379,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;
@@ -389,7 +476,11 @@ export interface WorkflowPageEntry {
     pageUrl: string;
     formId?: string;
     formName?: string;
-    filledValues: Record<string, string | boolean>;
+    /** Backward-compatible value map whose contents are always redaction markers. */
+    filledValues: Record<string, '[REDACTED]'>;
+    /** Stable field identities retained without submitted values. */
+    filledFields: string[];
+    valuesRedacted: true;
     filledAt: number;
     fieldCount: number;
     invalidCount: number;
@@ -405,7 +496,28 @@ export interface Session {
     layout: Record<string, unknown> | null;
     tree: Record<string, unknown> | null;
     url: string;
+    /** Private bearer capability for an authenticated proxy transport. */
+    transportAuthToken?: string;
     updateRevision: number;
+    /** Negotiated owner of the WebSocket endpoint. */
+    peerTransport?: 'native' | 'proxy';
+    /** Negotiated shared geometry protocol version. */
+    peerGeometryProtocolVersion?: number;
+    /** Negotiated browser-only action protocol version. */
+    peerProxyActionProtocolVersion?: number;
+    /** True when the peer advertised the split protocol contract explicitly. */
+    peerAdvertisedSplitProtocol?: boolean;
+    peerProtocolCapabilities?: {
+        authenticatedController?: boolean;
+        requestScopedAcks?: boolean;
+        actionDeadlines?: boolean;
+        idempotentRequestIds?: boolean;
+        atomicTypeText?: boolean;
+        proxyActions?: boolean;
+        exactFieldIdentity?: boolean;
+        verifiedFileUploads?: boolean;
+        binaryFraming?: boolean;
+    };
     /** Present when this session owns a child geometra-proxy process (pageUrl connect). */
     proxyChild?: ChildProcess;
     proxyRuntime?: EmbeddedProxyRuntime;
@@ -426,6 +538,10 @@ export interface Session {
         revision: number;
         forms: FormSchemaModel[];
     }>;
+    /** True only after the current WebSocket transport has supplied a full frame. */
+    hasFreshFrame?: boolean;
+    /** Permanently set when this session has been disconnected or otherwise retired. */
+    disposed?: boolean;
     workflowState?: WorkflowState;
     reconnectInFlight?: Promise<boolean>;
     lifecycleTaskId?: string;
@@ -436,6 +552,10 @@ export interface Session {
     heartbeatInterval?: ReturnType<typeof setInterval> | null;
     heartbeatLastMessageAt?: number;
     heartbeatPendingPongBy?: number | null;
+    /** Mutating operations whose caller timed out before a terminal response. */
+    ambiguousOperations?: Map<string, AmbiguousOperation>;
+    /** Mutating operations currently awaiting a terminal response. */
+    inFlightMutations?: Map<string, AmbiguousOperation>;
 }
 export interface SessionConnectTrace {
     mode: 'direct-ws' | 'fresh-proxy' | 'reused-proxy';
@@ -455,17 +575,53 @@ export interface SessionConnectTrace {
 export interface UpdateWaitResult {
     status: 'updated' | 'acknowledged' | 'timed_out';
     timeoutMs: number;
+    /** Wire identity used to correlate the terminal proxy response. */
+    requestId: string;
+    /** Stable logical identity shared by every wire phase of one action. */
+    actionId: string;
     result?: unknown;
 }
+interface AmbiguousOperation {
+    fingerprint: string;
+    actionId: string;
+    requestId: string;
+    requestIds: string[];
+    wireMessages: string[];
+    actionTimeoutMs?: number;
+    timeoutMs: number;
+    idempotent: boolean;
+    mutating: boolean;
+    /** A correlated ACK alone is insufficient for actions such as navigation. */
+    requireUpdateOnAck?: boolean;
+    /** Protocol floor that the terminal ACK must explicitly satisfy. */
+    requiredProtocolVersion?: number;
+    /** Any non-deduplication phase error permanently blocks later ACK promotion. */
+    stickyError?: Error;
+    /**
+     * Once any caller observes a timeout, identical intent is permanently
+     * pinned to this identity for the rest of the session. A future caller
+     * cannot prove it is (or is not) the timed-out caller.
+     */
+    permanentTombstone?: boolean;
+    completion?: {
+        kind: 'result';
+        value: UpdateWaitResult;
+    } | {
+        kind: 'error';
+        error: Error;
+    };
+}
 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 +630,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 +648,7 @@ export type ProxyFillField = {
 } | {
     kind: 'file';
     fieldId?: string;
+    fieldKey?: string;
     fieldLabel: string;
     paths: string[];
     exact?: boolean;
@@ -522,6 +683,8 @@ export declare function connect(url: string, opts?: {
     skipInitialResize?: boolean;
     closePreviousProxy?: boolean;
     awaitInitialFrame?: boolean;
+    authToken?: string;
+    isolated?: boolean;
 }): Promise<Session>;
 /**
  * Start geometra-proxy for `pageUrl`, connect to its WebSocket, and attach the child
@@ -538,12 +701,10 @@ export declare function connectThroughProxy(options: {
     awaitInitialFrame?: boolean;
     eagerInitialExtract?: boolean;
     /**
-     * When true, bypass the reusable proxy pool entirely and always spawn a
-     * fresh Chromium for this session. The session is tagged isolated, never
-     * entered into the pool on disconnect, and its underlying browser is
-     * destroyed when the session disconnects. Use for parallel form
-     * submission so localStorage / cookies / page state from one job cannot
-     * leak into another. Default false preserves the existing pool behavior.
+     * Browser sessions are isolated by default. Pass `false` explicitly to
+     * opt into sequential warm-browser reuse, including shared cookies and
+     * localStorage. Isolated sessions never enter the reusable pool and their
+     * browser is destroyed on disconnect.
      */
     isolated?: boolean;
     /**
@@ -598,7 +759,10 @@ export declare function disconnect(opts?: {
     closeProxy?: boolean;
     sessionId?: string;
 }): void;
+/** Process/test teardown only. User-facing disconnects are always owner-scoped. */
+export declare function shutdownAllSessionsAndProxies(): void;
 export declare function waitForUiCondition(session: Session, predicate: () => boolean, timeoutMs: number): Promise<boolean>;
+export declare function ensureSessionConnected(session: Session): Promise<void>;
 /**
  * Send a click event at (x, y) and wait for the next frame/patch response.
  */
@@ -618,13 +782,17 @@ export declare function sendKey(session: Session, key: string, modifiers?: {
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
 /**
  * Attach local file(s). Paths must exist on the machine running `@geometra/proxy` (not the MCP host).
- * Optional `x`,`y` click opens a file chooser; omit to use the first `input[type=file]` in any frame.
+ * Optional `x`,`y` click opens a file chooser. Callers must provide an explicit
+ * coordinate or semantic target; MCP never intentionally requests a global
+ * first-file-input fallback.
  */
 export declare function sendFileUpload(session: Session, paths: string[], opts?: {
     click?: {
         x: number;
         y: number;
     };
+    fieldId?: string;
+    fieldKey?: string;
     fieldLabel?: string;
     exact?: boolean;
     strategy?: 'auto' | 'chooser' | 'hidden' | 'drop';
@@ -632,11 +800,14 @@ export declare function sendFileUpload(session: Session, paths: string[], opts?:
         x: number;
         y: number;
     };
+    contextText?: string;
+    sectionText?: string;
 }, timeoutMs?: number): Promise<UpdateWaitResult>;
 /** Set a labeled text-like field (`input`, `textarea`, contenteditable, ARIA textbox) semantically. */
 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 +817,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>;
@@ -662,12 +835,10 @@ export declare function sendFillOtp(session: Session, value: string, opts?: {
 /** ARIA `role=option` listbox (e.g. React Select). Optional click opens the list. */
 export declare function sendListboxPick(session: Session, label: string, opts?: {
     exact?: boolean;
-    open?: {
-        x: number;
-        y: number;
-    };
     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 +851,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 +906,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