agent-web-interface 4.3.0 → 4.5.0

package/dist/src/form/purpose-inference.js

@@ -0,0 +1,313 @@
+/**
+ * Purpose Inference
+ *
+ * Infers the semantic purpose of form fields based on input type,
+ * autocomplete attributes, label text, and naming patterns.
+ *
+ * Priority order:
+ * 1. input type attribute
+ * 2. autocomplete attribute
+ * 3. aria-label / label text
+ * 4. placeholder
+ * 5. name attribute patterns
+ *
+ * @module form/purpose-inference
+ */
+/**
+ * Mapping from input type to semantic type
+ */
+export const INPUT_TYPE_TO_SEMANTIC = {
+    email: 'email',
+    tel: 'phone',
+    password: 'password',
+    url: 'url',
+    search: 'search',
+    date: 'date',
+    'datetime-local': 'date',
+    time: 'date',
+    month: 'date',
+    week: 'date',
+    number: 'quantity',
+    file: 'file',
+    color: 'color',
+};
+/**
+ * Mapping from autocomplete attribute to semantic type
+ */
+export const AUTOCOMPLETE_TO_SEMANTIC = {
+    email: 'email',
+    tel: 'phone',
+    'tel-national': 'phone',
+    'tel-local': 'phone',
+    password: 'password',
+    'new-password': 'password',
+    'current-password': 'password',
+    username: 'username',
+    name: 'full_name',
+    'given-name': 'first_name',
+    'family-name': 'last_name',
+    'additional-name': 'name',
+    nickname: 'username',
+    'street-address': 'street',
+    'address-line1': 'street',
+    'address-line2': 'address',
+    'address-level1': 'state',
+    'address-level2': 'city',
+    'postal-code': 'zip',
+    country: 'country',
+    'country-name': 'country',
+    'cc-number': 'card_number',
+    'cc-exp': 'card_expiry',
+    'cc-exp-month': 'card_expiry',
+    'cc-exp-year': 'card_expiry',
+    'cc-csc': 'card_cvv',
+    bday: 'date_of_birth',
+    'bday-day': 'date_of_birth',
+    'bday-month': 'date_of_birth',
+    'bday-year': 'date_of_birth',
+    url: 'url',
+    photo: 'file',
+};
+/**
+ * Keywords for semantic type inference from labels
+ */
+export const LABEL_KEYWORDS = {
+    email: ['email', 'e-mail', 'mail address'],
+    phone: ['phone', 'telephone', 'mobile', 'cell', 'contact number'],
+    password: ['password', 'passcode', 'pin'],
+    password_confirm: ['confirm password', 'repeat password', 'retype password', 're-enter password'],
+    name: ['name', 'full name'],
+    first_name: ['first name', 'given name', 'forename'],
+    last_name: ['last name', 'surname', 'family name'],
+    full_name: ['full name', 'your name', 'customer name'],
+    username: ['username', 'user name', 'user id', 'login', 'account name'],
+    address: ['address', 'location'],
+    street: ['street', 'address line', 'street address'],
+    city: ['city', 'town', 'locality'],
+    state: ['state', 'province', 'region'],
+    zip: ['zip', 'postal code', 'postcode', 'zip code'],
+    country: ['country', 'nation'],
+    card_number: ['card number', 'credit card', 'debit card', 'card #'],
+    card_expiry: ['expiry', 'expiration', 'exp date', 'valid thru'],
+    card_cvv: ['cvv', 'cvc', 'security code', 'card verification'],
+    date: ['date', 'when'],
+    date_of_birth: ['birth', 'dob', 'birthday', 'date of birth'],
+    quantity: ['quantity', 'qty', 'amount', 'count', 'number of'],
+    price: ['price', 'cost', 'amount', 'total'],
+    search: ['search', 'find', 'lookup', 'query'],
+    comment: ['comment', 'note', 'remarks', 'feedback'],
+    message: ['message', 'text', 'content', 'body'],
+    url: ['url', 'website', 'link', 'web address'],
+    file: ['file', 'upload', 'attachment', 'document'],
+    color: ['color', 'colour'],
+    selection: ['select', 'choose', 'option'],
+    toggle: ['enable', 'disable', 'turn on', 'turn off'],
+    consent: ['agree', 'consent', 'accept', 'terms', 'privacy', 'subscribe'],
+    unknown: [],
+};
+/**
+ * Name patterns for semantic type inference.
+ * Maps common naming patterns (camelCase, snake_case, kebab-case) to semantic types.
+ */
+export const NAME_PATTERNS = {
+    // Email patterns
+    email: 'email',
+    emailaddress: 'email',
+    email_address: 'email',
+    'email-address': 'email',
+    useremail: 'email',
+    user_email: 'email',
+    // Phone patterns
+    phone: 'phone',
+    phonenumber: 'phone',
+    phone_number: 'phone',
+    'phone-number': 'phone',
+    tel: 'phone',
+    telephone: 'phone',
+    mobile: 'phone',
+    // Password patterns
+    password: 'password',
+    passwd: 'password',
+    pass: 'password',
+    confirmpassword: 'password_confirm',
+    confirm_password: 'password_confirm',
+    passwordconfirm: 'password_confirm',
+    // Name patterns
+    firstname: 'first_name',
+    first_name: 'first_name',
+    'first-name': 'first_name',
+    givenname: 'first_name',
+    lastname: 'last_name',
+    last_name: 'last_name',
+    'last-name': 'last_name',
+    familyname: 'last_name',
+    fullname: 'full_name',
+    full_name: 'full_name',
+    // Username
+    username: 'username',
+    user_name: 'username',
+    userid: 'username',
+    user_id: 'username',
+    // Address
+    streetaddress: 'street',
+    street_address: 'street',
+    addressline: 'street',
+    address_line: 'street',
+    city: 'city',
+    state: 'state',
+    province: 'state',
+    zip: 'zip',
+    zipcode: 'zip',
+    zip_code: 'zip',
+    postalcode: 'zip',
+    postal_code: 'zip',
+    country: 'country',
+    // Payment
+    cardnumber: 'card_number',
+    card_number: 'card_number',
+    ccnumber: 'card_number',
+    cc_number: 'card_number',
+    cvv: 'card_cvv',
+    cvc: 'card_cvv',
+    expiry: 'card_expiry',
+    expiration: 'card_expiry',
+    // Dates
+    dateofbirth: 'date_of_birth',
+    date_of_birth: 'date_of_birth',
+    dob: 'date_of_birth',
+    birthday: 'date_of_birth',
+    birthdate: 'date_of_birth',
+};
+/**
+ * Extract semantic type from naming patterns.
+ *
+ * @param label - The accessible label
+ * @param testId - Optional test ID attribute
+ * @returns Object with inferred type and signal description
+ */
+export function extractNamePatterns(label, testId) {
+    // Normalize label to check against patterns
+    const normalizedLabel = label.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+    // Check label against patterns
+    for (const [pattern, type] of Object.entries(NAME_PATTERNS)) {
+        if (normalizedLabel.includes(pattern)) {
+            return { type, signal: `label matches pattern "${pattern}"` };
+        }
+    }
+    // Check test_id against patterns
+    if (testId) {
+        const normalizedTestId = testId.toLowerCase().replace(/[^a-z0-9_-]/g, '');
+        for (const [pattern, type] of Object.entries(NAME_PATTERNS)) {
+            if (normalizedTestId.includes(pattern)) {
+                return { type, signal: `test_id matches pattern "${pattern}"` };
+            }
+        }
+    }
+    return { type: 'unknown', signal: '' };
+}
+/**
+ * Infer the semantic purpose of a field.
+ */
+export function inferPurpose(node) {
+    const inferredFrom = [];
+    let semanticType = 'unknown';
+    let confidence = 0;
+    // Priority 1: Input type attribute (high confidence)
+    const inputType = node.attributes?.input_type;
+    if (inputType && INPUT_TYPE_TO_SEMANTIC[inputType]) {
+        semanticType = INPUT_TYPE_TO_SEMANTIC[inputType];
+        confidence = 0.95;
+        inferredFrom.push(`input_type="${inputType}"`);
+    }
+    // Priority 2: Autocomplete attribute (high confidence)
+    const autocomplete = node.attributes?.autocomplete;
+    if (autocomplete && AUTOCOMPLETE_TO_SEMANTIC[autocomplete]) {
+        const autoType = AUTOCOMPLETE_TO_SEMANTIC[autocomplete];
+        if (semanticType === 'unknown' || confidence < 0.9) {
+            semanticType = autoType;
+            confidence = Math.max(confidence, 0.9);
+            inferredFrom.push(`autocomplete="${autocomplete}"`);
+        }
+    }
+    // Priority 3-5: Label, placeholder, aria-label (medium confidence)
+    // Note: node.label is the computed accessible name which includes aria-label,
+    // aria-labelledby, and other ARIA labeling mechanisms
+    if (semanticType === 'unknown' || confidence < 0.8) {
+        const textSources = [
+            { text: node.label, source: 'label', confidence: 0.7 },
+            { text: node.attributes?.placeholder, source: 'placeholder', confidence: 0.65 },
+        ];
+        for (const { text, source, confidence: sourceConfidence } of textSources) {
+            if (!text)
+                continue;
+            const lowerText = text.toLowerCase();
+            for (const [type, keywords] of Object.entries(LABEL_KEYWORDS)) {
+                if (type === 'unknown')
+                    continue;
+                for (const keyword of keywords) {
+                    if (lowerText.includes(keyword)) {
+                        if (semanticType === 'unknown' || confidence < sourceConfidence) {
+                            semanticType = type;
+                            confidence = Math.max(confidence, sourceConfidence);
+                            inferredFrom.push(`${source} contains "${keyword}"`);
+                        }
+                        break;
+                    }
+                }
+                if (semanticType !== 'unknown' && confidence >= 0.7)
+                    break;
+            }
+            if (semanticType !== 'unknown' && confidence >= 0.7)
+                break;
+        }
+    }
+    // Priority 6: Name attribute patterns (low confidence: 0.5)
+    // Detect naming conventions like camelCase (firstName), snake_case (first_name),
+    // or kebab-case (first-name) that may indicate field purpose
+    if (semanticType === 'unknown' || confidence < 0.5) {
+        const testId = node.attributes?.test_id ?? '';
+        const namePatterns = extractNamePatterns(node.label, testId);
+        if (namePatterns.type !== 'unknown') {
+            semanticType = namePatterns.type;
+            confidence = Math.max(confidence, 0.5);
+            inferredFrom.push(namePatterns.signal);
+        }
+    }
+    // Fallback based on node kind
+    if (semanticType === 'unknown') {
+        switch (node.kind) {
+            case 'checkbox':
+                semanticType = 'toggle';
+                confidence = 0.5;
+                inferredFrom.push('node kind is checkbox');
+                break;
+            case 'radio':
+                semanticType = 'selection';
+                confidence = 0.5;
+                inferredFrom.push('node kind is radio');
+                break;
+            case 'select':
+            case 'combobox':
+                semanticType = 'selection';
+                confidence = 0.5;
+                inferredFrom.push(`node kind is ${node.kind}`);
+                break;
+            case 'textarea':
+                semanticType = 'message';
+                confidence = 0.4;
+                inferredFrom.push('node kind is textarea');
+                break;
+            case 'slider':
+                semanticType = 'quantity';
+                confidence = 0.4;
+                inferredFrom.push('node kind is slider');
+                break;
+        }
+    }
+    return {
+        semantic_type: semanticType,
+        confidence,
+        inferred_from: inferredFrom.length > 0 ? inferredFrom : ['no signals found'],
+    };
+}
+//# sourceMappingURL=purpose-inference.js.map

package/dist/src/form/purpose-inference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"purpose-inference.js","sourceRoot":"","sources":["../../../src/form/purpose-inference.ts"],"names":[],"mappings":"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"}

package/dist/src/form/submit-detection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Submit Button Detection
+ *
+ * Detects submit buttons associated with forms or input clusters
+ * using keyword matching and spatial proximity.
+ *
+ * @module form/submit-detection
+ */
+import type { BaseSnapshot, ReadableNode } from '../snapshot/snapshot.types.js';
+/**
+ * Submit button keywords
+ */
+export declare const SUBMIT_KEYWORDS: string[];
+/**
+ * Find a submit button associated with a form.
+ */
+export declare function findSubmitButton(snapshot: BaseSnapshot, formNode: ReadableNode, fieldEids: string[], isNodeWithinForm: (node: ReadableNode, formNode: ReadableNode, snapshot: BaseSnapshot) => boolean, computeClusterBbox: (nodes: ReadableNode[]) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | undefined): ReadableNode | undefined;
+/**
+ * Find a submit button near a cluster of inputs.
+ */
+export declare function findSubmitButtonNearCluster(snapshot: BaseSnapshot, cluster: ReadableNode[], computeClusterBbox: (nodes: ReadableNode[]) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+} | undefined): ReadableNode | undefined;
+/**
+ * Check if a button looks like a submit button.
+ */
+export declare function isSubmitButton(button: ReadableNode): boolean;
+//# sourceMappingURL=submit-detection.d.ts.map

package/dist/src/form/submit-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit-detection.d.ts","sourceRoot":"","sources":["../../../src/form/submit-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAGhF;;GAEG;AACH,eAAO,MAAM,eAAe,UAkB3B,CAAC;AAEF;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,QAAQ,EAAE,YAAY,EACtB,SAAS,EAAE,MAAM,EAAE,EACnB,gBAAgB,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,KAAK,OAAO,EACjG,kBAAkB,EAAE,CAClB,KAAK,EAAE,YAAY,EAAE,KAClB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GACvE,YAAY,GAAG,SAAS,CAyB1B;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,YAAY,EAAE,EACvB,kBAAkB,EAAE,CAClB,KAAK,EAAE,YAAY,EAAE,KAClB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,GACvE,YAAY,GAAG,SAAS,CA8B1B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAgB5D"}

package/dist/src/form/submit-detection.js

@@ -0,0 +1,101 @@
+/**
+ * Submit Button Detection
+ *
+ * Detects submit buttons associated with forms or input clusters
+ * using keyword matching and spatial proximity.
+ *
+ * @module form/submit-detection
+ */
+import { BUTTON_KINDS } from './form-actions.js';
+/**
+ * Submit button keywords
+ */
+export const SUBMIT_KEYWORDS = [
+    'submit',
+    'send',
+    'continue',
+    'next',
+    'save',
+    'apply',
+    'confirm',
+    'add to',
+    'sign in',
+    'log in',
+    'sign up',
+    'register',
+    'search',
+    'buy',
+    'checkout',
+    'purchase',
+    'subscribe',
+];
+/**
+ * Find a submit button associated with a form.
+ */
+export function findSubmitButton(snapshot, formNode, fieldEids, isNodeWithinForm, computeClusterBbox) {
+    const buttons = snapshot.nodes.filter((n) => BUTTON_KINDS.has(n.kind));
+    for (const button of buttons) {
+        // Check if button is within form's scope
+        if (!isNodeWithinForm(button, formNode, snapshot)) {
+            continue;
+        }
+        // Check if button label suggests submission
+        if (isSubmitButton(button)) {
+            return button;
+        }
+    }
+    // Also check buttons near the fields
+    if (fieldEids.length > 0) {
+        const fieldNodes = fieldEids
+            .map((eid) => snapshot.nodes.find((n) => n.node_id === eid))
+            .filter((n) => n !== undefined);
+        return findSubmitButtonNearCluster(snapshot, fieldNodes, computeClusterBbox);
+    }
+    return undefined;
+}
+/**
+ * Find a submit button near a cluster of inputs.
+ */
+export function findSubmitButtonNearCluster(snapshot, cluster, computeClusterBbox) {
+    if (cluster.length === 0)
+        return undefined;
+    const buttons = snapshot.nodes.filter((n) => BUTTON_KINDS.has(n.kind));
+    const clusterBbox = computeClusterBbox(cluster);
+    if (!clusterBbox)
+        return undefined;
+    // Find buttons near the cluster
+    const nearbyButtons = buttons.filter((button) => {
+        if (!button.layout?.bbox)
+            return false;
+        const btnBbox = button.layout.bbox;
+        // Check if button is below or to the right of the cluster
+        const isNearX = btnBbox.x >= clusterBbox.x - 100 && btnBbox.x <= clusterBbox.x + clusterBbox.width + 100;
+        const isNearY = btnBbox.y >= clusterBbox.y - 50 && btnBbox.y <= clusterBbox.y + clusterBbox.height + 150;
+        return isNearX && isNearY;
+    });
+    // Find the best submit button candidate
+    for (const button of nearbyButtons) {
+        if (isSubmitButton(button)) {
+            return button;
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if a button looks like a submit button.
+ */
+export function isSubmitButton(button) {
+    const label = button.label.toLowerCase();
+    // Check for submit keywords
+    for (const keyword of SUBMIT_KEYWORDS) {
+        if (label.includes(keyword)) {
+            return true;
+        }
+    }
+    // Check for type="submit" attribute
+    if (button.attributes?.input_type === 'submit') {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=submit-detection.js.map

package/dist/src/form/submit-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"submit-detection.js","sourceRoot":"","sources":["../../../src/form/submit-detection.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,QAAQ;IACR,MAAM;IACN,UAAU;IACV,MAAM;IACN,MAAM;IACN,OAAO;IACP,SAAS;IACT,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,SAAS;IACT,UAAU;IACV,QAAQ;IACR,KAAK;IACL,UAAU;IACV,UAAU;IACV,WAAW;CACZ,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,QAAsB,EACtB,QAAsB,EACtB,SAAmB,EACnB,gBAAiG,EACjG,kBAEwE;IAExE,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEvE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,yCAAyC;QACzC,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;YAClD,SAAS;QACX,CAAC;QAED,4CAA4C;QAC5C,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,qCAAqC;IACrC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,SAAS;aACzB,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,GAAG,CAAC,CAAC;aAC3D,MAAM,CAAC,CAAC,CAAC,EAAqB,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;QAErD,OAAO,2BAA2B,CAAC,QAAQ,EAAE,UAAU,EAAE,kBAAkB,CAAC,CAAC;IAC/E,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAAsB,EACtB,OAAuB,EACvB,kBAEwE;IAExE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAE3C,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACvE,MAAM,WAAW,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAEhD,IAAI,CAAC,WAAW;QAAE,OAAO,SAAS,CAAC;IAEnC,gCAAgC;IAChC,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;QAC9C,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI;YAAE,OAAO,KAAK,CAAC;QACvC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;QAEnC,0DAA0D;QAC1D,MAAM,OAAO,GACX,OAAO,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,GAAG,GAAG,IAAI,OAAO,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,GAAG,GAAG,CAAC;QAC3F,MAAM,OAAO,GACX,OAAO,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,GAAG,WAAW,CAAC,MAAM,GAAG,GAAG,CAAC;QAE3F,OAAO,OAAO,IAAI,OAAO,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,wCAAwC;IACxC,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,IAAI,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;IAEzC,4BAA4B;IAC5B,KAAK,MAAM,OAAO,IAAI,eAAe,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,oCAAoC;IACpC,IAAI,MAAM,CAAC,UAAU,EAAE,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/src/form/types.d.ts

@@ -276,7 +276,7 @@ export interface ObservedEffect {
     confidence: number;
 }
 /**
- * Response from get_form_understanding tool.
+ * Response from get_form tool.
  */
 export interface FormUnderstandingResponse {
     /** Page ID */
@@ -289,7 +289,7 @@ export interface FormUnderstandingResponse {
     form_count: number;
 }
 /**
- * Response from get_field_context tool.
+ * Response from get_field tool.
  */
 export interface FieldContextResponse {
     /** The requested field */

package/dist/src/gateway/http-gateway.d.ts

@@ -0,0 +1,56 @@
+/**
+ * HTTP Gateway
+ *
+ * Supports multiple concurrent AI agents via Streamable HTTP transport.
+ * Each client connection gets its own McpServer instance with tools
+ * closing over a dedicated SessionController.
+ *
+ * Architecture: per-session McpServer - each HTTP client connection gets
+ * its own McpServer + transport pair. This avoids the problem that the
+ * MCP SDK does not expose which transport triggered a tool call.
+ *
+ * @module gateway/http-gateway
+ */
+import type { Request, Response } from 'express';
+import { SessionRouter } from './session-router.js';
+export interface HttpGatewayOptions {
+    router: SessionRouter;
+    version?: string;
+}
+export declare class HttpGateway {
+    private readonly sessions;
+    private readonly router;
+    private readonly version;
+    constructor(options: HttpGatewayOptions);
+    /**
+     * Handle POST requests to the /mcp endpoint.
+     *
+     * Routing logic follows the MCP Streamable HTTP specification:
+     * - Requests with a valid mcp-session-id are routed to the existing transport
+     * - POST without a session ID that contains an initialize request creates a new session
+     * - All other requests are rejected with 400
+     */
+    handlePost(req: Request, res: Response): Promise<void>;
+    /**
+     * Handle GET requests to the /mcp endpoint (SSE streams).
+     */
+    handleGet(req: Request, res: Response): Promise<void>;
+    /**
+     * Handle DELETE requests to the /mcp endpoint (session termination).
+     */
+    handleDelete(req: Request, res: Response): Promise<void>;
+    private createNewSession;
+    private closeSession;
+    /**
+     * Clean up gateway-owned resources (McpServer + transport) for a session
+     * that was already destroyed by the router (e.g., idle eviction).
+     * Unlike closeSession(), this does NOT call router.destroySession().
+     */
+    private cleanupGatewaySession;
+    private teardownOrphanedSession;
+    /** Get count of active HTTP sessions */
+    get sessionCount(): number;
+    /** Shutdown all HTTP sessions */
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=http-gateway.d.ts.map

package/dist/src/gateway/http-gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-gateway.d.ts","sourceRoot":"","sources":["../../../src/gateway/http-gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAKjD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAkBpD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkCD,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,kBAAkB;IAWvC;;;;;;;OAOG;IACG,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IA6B5D;;OAEG;IACG,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAY3D;;OAEG;IACG,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;YAYhD,gBAAgB;YAgEhB,YAAY;IAkB1B;;;;OAIG;YACW,qBAAqB;YAwBrB,uBAAuB;IAYrC,wCAAwC;IACxC,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,iCAAiC;IAC3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAIhC"}