@metamask/client-mcp-core 0.1.0

package/dist/mcp-server/tools/error-classification.mjs

@@ -0,0 +1,281 @@
+/**
+ * Error classification utilities for tool handlers.
+ *
+ * These utilities help classify errors into specific error codes
+ * based on error message patterns.
+ */
+import { ErrorCodes } from "../types/index.mjs";
+import { extractErrorMessage } from "../utils/index.mjs";
+const ERROR_PATTERNS = {
+    targetNotFound: [
+        'Unknown a11yRef',
+        'not found',
+        'No element found',
+        'Timeout waiting for selector',
+    ],
+    timeout: ['Timeout', 'exceeded', 'timed out'],
+    navigation: ['Navigation failed', 'net::ERR'],
+    pageClosed: [
+        'Target page, context or browser has been closed',
+        'page has been closed',
+        'context has been closed',
+        'browser has been closed',
+        'Target closed',
+        'Session closed',
+    ],
+};
+/**
+ * Check if an error indicates the page was closed.
+ *
+ * @param error - The error to check for page closure indicators
+ * @returns True if the error indicates the page was closed
+ */
+export function isPageClosedError(error) {
+    const message = extractErrorMessage(error);
+    return ERROR_PATTERNS.pageClosed.some((pattern) => message.includes(pattern));
+}
+/**
+ * Classify an interaction error into a specific error code.
+ *
+ * @param error - The error to classify
+ * @param fallbackCode - The fallback error code if no pattern matches
+ * @returns Object with error code and message
+ */
+export function classifyInteractionError(error, fallbackCode) {
+    const message = extractErrorMessage(error);
+    for (const pattern of ERROR_PATTERNS.targetNotFound) {
+        if (message.includes(pattern)) {
+            return { code: ErrorCodes.MM_TARGET_NOT_FOUND, message };
+        }
+    }
+    for (const pattern of ERROR_PATTERNS.timeout) {
+        if (message.includes(pattern)) {
+            return { code: ErrorCodes.MM_WAIT_TIMEOUT, message };
+        }
+    }
+    return { code: fallbackCode, message: `Operation failed: ${message}` };
+}
+/**
+ * Classify a click error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyClickError(error) {
+    return classifyInteractionError(error, ErrorCodes.MM_CLICK_FAILED);
+}
+/**
+ * Classify a type error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyTypeError(error) {
+    return classifyInteractionError(error, ErrorCodes.MM_TYPE_FAILED);
+}
+/**
+ * Classify a wait error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyWaitError(error) {
+    const message = extractErrorMessage(error);
+    return {
+        code: ErrorCodes.MM_WAIT_TIMEOUT,
+        message: `Wait timed out: ${message}`,
+    };
+}
+/**
+ * Classify a navigation error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyNavigationError(error) {
+    const message = extractErrorMessage(error);
+    for (const pattern of ERROR_PATTERNS.navigation) {
+        if (message.includes(pattern)) {
+            return { code: ErrorCodes.MM_NAVIGATION_FAILED, message };
+        }
+    }
+    for (const pattern of ERROR_PATTERNS.timeout) {
+        if (message.includes(pattern)) {
+            return { code: ErrorCodes.MM_WAIT_TIMEOUT, message };
+        }
+    }
+    for (const pattern of ERROR_PATTERNS.pageClosed) {
+        if (message.includes(pattern)) {
+            return {
+                code: ErrorCodes.MM_NAVIGATION_FAILED,
+                message: `Page closed during navigation: ${message}`,
+            };
+        }
+    }
+    return {
+        code: ErrorCodes.MM_NAVIGATION_FAILED,
+        message: `Navigation failed: ${message}`,
+    };
+}
+/**
+ * Classify a tab operation error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyTabError(error) {
+    const message = extractErrorMessage(error);
+    if (message.includes('not found') || message.includes('No tab found')) {
+        return { code: ErrorCodes.MM_TAB_NOT_FOUND, message };
+    }
+    for (const pattern of ERROR_PATTERNS.timeout) {
+        if (message.includes(pattern)) {
+            return { code: ErrorCodes.MM_WAIT_TIMEOUT, message };
+        }
+    }
+    for (const pattern of ERROR_PATTERNS.pageClosed) {
+        if (message.includes(pattern)) {
+            return {
+                code: ErrorCodes.MM_NAVIGATION_FAILED,
+                message: `Tab operation failed - page closed: ${message}`,
+            };
+        }
+    }
+    return {
+        code: ErrorCodes.MM_NAVIGATION_FAILED,
+        message: `Tab operation failed: ${message}`,
+    };
+}
+/**
+ * Classify a notification wait error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyNotificationError(error) {
+    const message = extractErrorMessage(error);
+    for (const pattern of ERROR_PATTERNS.timeout) {
+        if (message.includes(pattern)) {
+            return {
+                code: ErrorCodes.MM_NOTIFICATION_TIMEOUT,
+                message: `Notification popup did not appear: ${message}`,
+            };
+        }
+    }
+    for (const pattern of ERROR_PATTERNS.pageClosed) {
+        if (message.includes(pattern)) {
+            return {
+                code: ErrorCodes.MM_NOTIFICATION_TIMEOUT,
+                message: `Browser closed while waiting for notification: ${message}`,
+            };
+        }
+    }
+    return {
+        code: ErrorCodes.MM_NOTIFICATION_TIMEOUT,
+        message: `Notification popup did not appear: ${message}`,
+    };
+}
+/**
+ * Classify a discovery tool error (list_testids, accessibility_snapshot, describe_screen).
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyDiscoveryError(error) {
+    const message = extractErrorMessage(error);
+    for (const pattern of ERROR_PATTERNS.pageClosed) {
+        if (message.includes(pattern)) {
+            return {
+                code: ErrorCodes.MM_PAGE_CLOSED,
+                message: `Page closed during discovery: ${message}`,
+            };
+        }
+    }
+    for (const pattern of ERROR_PATTERNS.timeout) {
+        if (message.includes(pattern)) {
+            return {
+                code: ErrorCodes.MM_WAIT_TIMEOUT,
+                message: `Discovery timed out: ${message}`,
+            };
+        }
+    }
+    return {
+        code: ErrorCodes.MM_DISCOVERY_FAILED,
+        message: `Discovery failed: ${message}`,
+    };
+}
+/**
+ * Classify a screenshot error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyScreenshotError(error) {
+    const message = extractErrorMessage(error);
+    for (const pattern of ERROR_PATTERNS.pageClosed) {
+        if (message.includes(pattern)) {
+            return {
+                code: ErrorCodes.MM_PAGE_CLOSED,
+                message: `Page closed during screenshot: ${message}`,
+            };
+        }
+    }
+    return {
+        code: ErrorCodes.MM_SCREENSHOT_FAILED,
+        message: `Screenshot failed: ${message}`,
+    };
+}
+/**
+ * Classify a state tool error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyStateError(error) {
+    const message = extractErrorMessage(error);
+    for (const pattern of ERROR_PATTERNS.pageClosed) {
+        if (message.includes(pattern)) {
+            return {
+                code: ErrorCodes.MM_PAGE_CLOSED,
+                message: `Page closed during state retrieval: ${message}`,
+            };
+        }
+    }
+    return {
+        code: ErrorCodes.MM_STATE_FAILED,
+        message: `State retrieval failed: ${message}`,
+    };
+}
+/**
+ * Classify a seeding/contract deployment error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifySeedingError(error) {
+    const message = extractErrorMessage(error);
+    if (message.includes('not found') || message.includes('Unknown contract')) {
+        return { code: ErrorCodes.MM_CONTRACT_NOT_FOUND, message };
+    }
+    return {
+        code: ErrorCodes.MM_SEED_FAILED,
+        message: `Contract operation failed: ${message}`,
+    };
+}
+/**
+ * Classify a context switching error.
+ *
+ * @param error - The error to classify
+ * @returns Object with error code and message
+ */
+export function classifyContextError(error) {
+    const message = extractErrorMessage(error);
+    if (message.includes(ErrorCodes.MM_CONTEXT_SWITCH_BLOCKED)) {
+        return { code: ErrorCodes.MM_CONTEXT_SWITCH_BLOCKED, message };
+    }
+    return {
+        code: ErrorCodes.MM_SET_CONTEXT_FAILED,
+        message: `Context switch failed: ${message}`,
+    };
+}
+//# sourceMappingURL=error-classification.mjs.map

package/dist/mcp-server/tools/error-classification.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-classification.mjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/error-classification.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,2BAAiB;AACtC,OAAO,EAAE,mBAAmB,EAAE,2BAAiB;AAE/C,MAAM,cAAc,GAAG;IACrB,cAAc,EAAE;QACd,iBAAiB;QACjB,WAAW;QACX,kBAAkB;QAClB,8BAA8B;KAC/B;IACD,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC;IAC7C,UAAU,EAAE,CAAC,mBAAmB,EAAE,UAAU,CAAC;IAC7C,UAAU,EAAE;QACV,iDAAiD;QACjD,sBAAsB;QACtB,yBAAyB;QACzB,yBAAyB;QACzB,eAAe;QACf,gBAAgB;KACjB;CACO,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAc,EACd,YAAoB;IAKpB,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,cAAc,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,mBAAmB,EAAE,OAAO,EAAE,CAAC;QAC3D,CAAC;IACH,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,eAAe,EAAE,OAAO,EAAE,CAAC;QACvD,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,qBAAqB,OAAO,EAAE,EAAE,CAAC;AACzE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAI/C,OAAO,wBAAwB,CAAC,KAAK,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAI9C,OAAO,wBAAwB,CAAC,KAAK,EAAE,UAAU,CAAC,cAAc,CAAC,CAAC;AACpE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAI9C,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC3C,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,eAAe;QAChC,OAAO,EAAE,mBAAmB,OAAO,EAAE;KACtC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IAIpD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,oBAAoB,EAAE,OAAO,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,eAAe,EAAE,OAAO,EAAE,CAAC;QACvD,CAAC;IACH,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,oBAAoB;gBACrC,OAAO,EAAE,kCAAkC,OAAO,EAAE;aACrD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,oBAAoB;QACrC,OAAO,EAAE,sBAAsB,OAAO,EAAE;KACzC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAI7C,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACtE,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,gBAAgB,EAAE,OAAO,EAAE,CAAC;IACxD,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,eAAe,EAAE,OAAO,EAAE,CAAC;QACvD,CAAC;IACH,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,oBAAoB;gBACrC,OAAO,EAAE,uCAAuC,OAAO,EAAE;aAC1D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,oBAAoB;QACrC,OAAO,EAAE,yBAAyB,OAAO,EAAE;KAC5C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAc;IAItD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,uBAAuB;gBACxC,OAAO,EAAE,sCAAsC,OAAO,EAAE;aACzD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,uBAAuB;gBACxC,OAAO,EAAE,kDAAkD,OAAO,EAAE;aACrE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,uBAAuB;QACxC,OAAO,EAAE,sCAAsC,OAAO,EAAE;KACzD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IAInD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,cAAc;gBAC/B,OAAO,EAAE,iCAAiC,OAAO,EAAE;aACpD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,OAAO,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,eAAe;gBAChC,OAAO,EAAE,wBAAwB,OAAO,EAAE;aAC3C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,mBAAmB;QACpC,OAAO,EAAE,qBAAqB,OAAO,EAAE;KACxC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IAIpD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,cAAc;gBAC/B,OAAO,EAAE,kCAAkC,OAAO,EAAE;aACrD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,oBAAoB;QACrC,OAAO,EAAE,sBAAsB,OAAO,EAAE;KACzC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAI/C,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,UAAU,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,IAAI,EAAE,UAAU,CAAC,cAAc;gBAC/B,OAAO,EAAE,uCAAuC,OAAO,EAAE;aAC1D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,eAAe;QAChC,OAAO,EAAE,2BAA2B,OAAO,EAAE;KAC9C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAIjD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC1E,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,qBAAqB,EAAE,OAAO,EAAE,CAAC;IAC7D,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,cAAc;QAC/B,OAAO,EAAE,8BAA8B,OAAO,EAAE;KACjD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAc;IAIjD,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAE3C,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,yBAAyB,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,yBAAyB,EAAE,OAAO,EAAE,CAAC;IACjE,CAAC;IAED,OAAO;QACL,IAAI,EAAE,UAAU,CAAC,qBAAqB;QACtC,OAAO,EAAE,0BAA0B,OAAO,EAAE;KAC7C,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Error classification utilities for tool handlers.\n *\n * These utilities help classify errors into specific error codes\n * based on error message patterns.\n */\n\nimport { ErrorCodes } from '../types';\nimport { extractErrorMessage } from '../utils';\n\nconst ERROR_PATTERNS = {\n  targetNotFound: [\n    'Unknown a11yRef',\n    'not found',\n    'No element found',\n    'Timeout waiting for selector',\n  ],\n  timeout: ['Timeout', 'exceeded', 'timed out'],\n  navigation: ['Navigation failed', 'net::ERR'],\n  pageClosed: [\n    'Target page, context or browser has been closed',\n    'page has been closed',\n    'context has been closed',\n    'browser has been closed',\n    'Target closed',\n    'Session closed',\n  ],\n} as const;\n\n/**\n * Check if an error indicates the page was closed.\n *\n * @param error - The error to check for page closure indicators\n * @returns True if the error indicates the page was closed\n */\nexport function isPageClosedError(error: unknown): boolean {\n  const message = extractErrorMessage(error);\n  return ERROR_PATTERNS.pageClosed.some((pattern) => message.includes(pattern));\n}\n\n/**\n * Classify an interaction error into a specific error code.\n *\n * @param error - The error to classify\n * @param fallbackCode - The fallback error code if no pattern matches\n * @returns Object with error code and message\n */\nexport function classifyInteractionError(\n  error: unknown,\n  fallbackCode: string,\n): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  for (const pattern of ERROR_PATTERNS.targetNotFound) {\n    if (message.includes(pattern)) {\n      return { code: ErrorCodes.MM_TARGET_NOT_FOUND, message };\n    }\n  }\n\n  for (const pattern of ERROR_PATTERNS.timeout) {\n    if (message.includes(pattern)) {\n      return { code: ErrorCodes.MM_WAIT_TIMEOUT, message };\n    }\n  }\n\n  return { code: fallbackCode, message: `Operation failed: ${message}` };\n}\n\n/**\n * Classify a click error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyClickError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  return classifyInteractionError(error, ErrorCodes.MM_CLICK_FAILED);\n}\n\n/**\n * Classify a type error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyTypeError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  return classifyInteractionError(error, ErrorCodes.MM_TYPE_FAILED);\n}\n\n/**\n * Classify a wait error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyWaitError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n  return {\n    code: ErrorCodes.MM_WAIT_TIMEOUT,\n    message: `Wait timed out: ${message}`,\n  };\n}\n\n/**\n * Classify a navigation error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyNavigationError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  for (const pattern of ERROR_PATTERNS.navigation) {\n    if (message.includes(pattern)) {\n      return { code: ErrorCodes.MM_NAVIGATION_FAILED, message };\n    }\n  }\n\n  for (const pattern of ERROR_PATTERNS.timeout) {\n    if (message.includes(pattern)) {\n      return { code: ErrorCodes.MM_WAIT_TIMEOUT, message };\n    }\n  }\n\n  for (const pattern of ERROR_PATTERNS.pageClosed) {\n    if (message.includes(pattern)) {\n      return {\n        code: ErrorCodes.MM_NAVIGATION_FAILED,\n        message: `Page closed during navigation: ${message}`,\n      };\n    }\n  }\n\n  return {\n    code: ErrorCodes.MM_NAVIGATION_FAILED,\n    message: `Navigation failed: ${message}`,\n  };\n}\n\n/**\n * Classify a tab operation error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyTabError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  if (message.includes('not found') || message.includes('No tab found')) {\n    return { code: ErrorCodes.MM_TAB_NOT_FOUND, message };\n  }\n\n  for (const pattern of ERROR_PATTERNS.timeout) {\n    if (message.includes(pattern)) {\n      return { code: ErrorCodes.MM_WAIT_TIMEOUT, message };\n    }\n  }\n\n  for (const pattern of ERROR_PATTERNS.pageClosed) {\n    if (message.includes(pattern)) {\n      return {\n        code: ErrorCodes.MM_NAVIGATION_FAILED,\n        message: `Tab operation failed - page closed: ${message}`,\n      };\n    }\n  }\n\n  return {\n    code: ErrorCodes.MM_NAVIGATION_FAILED,\n    message: `Tab operation failed: ${message}`,\n  };\n}\n\n/**\n * Classify a notification wait error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyNotificationError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  for (const pattern of ERROR_PATTERNS.timeout) {\n    if (message.includes(pattern)) {\n      return {\n        code: ErrorCodes.MM_NOTIFICATION_TIMEOUT,\n        message: `Notification popup did not appear: ${message}`,\n      };\n    }\n  }\n\n  for (const pattern of ERROR_PATTERNS.pageClosed) {\n    if (message.includes(pattern)) {\n      return {\n        code: ErrorCodes.MM_NOTIFICATION_TIMEOUT,\n        message: `Browser closed while waiting for notification: ${message}`,\n      };\n    }\n  }\n\n  return {\n    code: ErrorCodes.MM_NOTIFICATION_TIMEOUT,\n    message: `Notification popup did not appear: ${message}`,\n  };\n}\n\n/**\n * Classify a discovery tool error (list_testids, accessibility_snapshot, describe_screen).\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyDiscoveryError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  for (const pattern of ERROR_PATTERNS.pageClosed) {\n    if (message.includes(pattern)) {\n      return {\n        code: ErrorCodes.MM_PAGE_CLOSED,\n        message: `Page closed during discovery: ${message}`,\n      };\n    }\n  }\n\n  for (const pattern of ERROR_PATTERNS.timeout) {\n    if (message.includes(pattern)) {\n      return {\n        code: ErrorCodes.MM_WAIT_TIMEOUT,\n        message: `Discovery timed out: ${message}`,\n      };\n    }\n  }\n\n  return {\n    code: ErrorCodes.MM_DISCOVERY_FAILED,\n    message: `Discovery failed: ${message}`,\n  };\n}\n\n/**\n * Classify a screenshot error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyScreenshotError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  for (const pattern of ERROR_PATTERNS.pageClosed) {\n    if (message.includes(pattern)) {\n      return {\n        code: ErrorCodes.MM_PAGE_CLOSED,\n        message: `Page closed during screenshot: ${message}`,\n      };\n    }\n  }\n\n  return {\n    code: ErrorCodes.MM_SCREENSHOT_FAILED,\n    message: `Screenshot failed: ${message}`,\n  };\n}\n\n/**\n * Classify a state tool error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyStateError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  for (const pattern of ERROR_PATTERNS.pageClosed) {\n    if (message.includes(pattern)) {\n      return {\n        code: ErrorCodes.MM_PAGE_CLOSED,\n        message: `Page closed during state retrieval: ${message}`,\n      };\n    }\n  }\n\n  return {\n    code: ErrorCodes.MM_STATE_FAILED,\n    message: `State retrieval failed: ${message}`,\n  };\n}\n\n/**\n * Classify a seeding/contract deployment error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifySeedingError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  if (message.includes('not found') || message.includes('Unknown contract')) {\n    return { code: ErrorCodes.MM_CONTRACT_NOT_FOUND, message };\n  }\n\n  return {\n    code: ErrorCodes.MM_SEED_FAILED,\n    message: `Contract operation failed: ${message}`,\n  };\n}\n\n/**\n * Classify a context switching error.\n *\n * @param error - The error to classify\n * @returns Object with error code and message\n */\nexport function classifyContextError(error: unknown): {\n  code: string;\n  message: string;\n} {\n  const message = extractErrorMessage(error);\n\n  if (message.includes(ErrorCodes.MM_CONTEXT_SWITCH_BLOCKED)) {\n    return { code: ErrorCodes.MM_CONTEXT_SWITCH_BLOCKED, message };\n  }\n\n  return {\n    code: ErrorCodes.MM_SET_CONTEXT_FAILED,\n    message: `Context switch failed: ${message}`,\n  };\n}\n"]}

package/dist/mcp-server/tools/helpers.cjs

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireActiveSession = requireActiveSession;
+exports.collectObservation = collectObservation;
+exports.withActiveSession = withActiveSession;
+exports.recordToolStep = recordToolStep;
+exports.collectObservationAndRecord = collectObservationAndRecord;
+exports.handleToolError = handleToolError;
+const constants_js_1 = require("../constants.cjs");
+const discovery_js_1 = require("../discovery.cjs");
+const knowledge_store_js_1 = require("../knowledge-store.cjs");
+const session_manager_js_1 = require("../session-manager.cjs");
+const types_1 = require("../types/index.cjs");
+const utils_1 = require("../utils/index.cjs");
+/**
+ * Check if an active session exists and return error if not.
+ *
+ * @param startTime - Timestamp when the operation started
+ * @returns Error response if no active session, undefined otherwise
+ */
+function requireActiveSession(startTime) {
+    const sessionManager = (0, session_manager_js_1.getSessionManager)();
+    if (!sessionManager.hasActiveSession()) {
+        return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_NO_ACTIVE_SESSION, 'No active session. Call launch first.', undefined, undefined, startTime);
+    }
+    return undefined;
+}
+/**
+ * Collect observation data from the current page state.
+ *
+ * @param page - The page to collect observation from
+ * @param level - Level of detail to collect (full, minimal, or none)
+ * @param presetState - Optional pre-fetched extension state to use instead of querying
+ * @returns Observation data with state, testIds, and accessibility tree
+ */
+async function collectObservation(page, level, presetState) {
+    const sessionManager = (0, session_manager_js_1.getSessionManager)();
+    if (level === 'none') {
+        return (0, knowledge_store_js_1.createDefaultObservation)({}, [], []);
+    }
+    const state = presetState ?? (await sessionManager.getExtensionState());
+    if (level === 'minimal') {
+        return (0, knowledge_store_js_1.createDefaultObservation)(state, [], []);
+    }
+    if (!page) {
+        (0, utils_1.debugWarn)('collectObservation', 'Page not provided for full observation');
+        return (0, knowledge_store_js_1.createDefaultObservation)(state, [], []);
+    }
+    try {
+        const testIds = await (0, discovery_js_1.collectTestIds)(page, constants_js_1.OBSERVATION_TESTID_LIMIT);
+        const { nodes, refMap } = await (0, discovery_js_1.collectTrimmedA11ySnapshot)(page);
+        sessionManager.setRefMap(refMap);
+        return (0, knowledge_store_js_1.createDefaultObservation)(state, testIds, nodes);
+    }
+    catch (error) {
+        (0, utils_1.debugWarn)('collectObservation', error);
+        return (0, knowledge_store_js_1.createDefaultObservation)(state, [], []);
+    }
+}
+/**
+ * Wrapper that ensures an active session exists before executing a handler.
+ *
+ * @param handler - Function to execute with active session context
+ * @returns Wrapped function that validates session before calling handler
+ */
+function withActiveSession(handler) {
+    return async (input) => {
+        const startTime = Date.now();
+        const sessionManager = (0, session_manager_js_1.getSessionManager)();
+        const sessionError = requireActiveSession(startTime);
+        if (sessionError) {
+            return sessionError;
+        }
+        const sessionId = sessionManager.getSessionId();
+        if (!sessionId) {
+            return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_NO_ACTIVE_SESSION, 'Session ID not found', undefined, undefined, startTime);
+        }
+        const page = sessionManager.getPage();
+        const refMap = sessionManager.getRefMap();
+        return handler(input, { sessionId, page, refMap }, startTime);
+    };
+}
+/**
+ * Record a tool execution step in the knowledge store.
+ *
+ * @param params - Parameters containing tool name, input, observation, and metadata
+ */
+async function recordToolStep(params) {
+    const sessionManager = (0, session_manager_js_1.getSessionManager)();
+    const sessionId = sessionManager.getSessionId() ?? '';
+    await knowledge_store_js_1.knowledgeStore.recordStep({
+        sessionId,
+        toolName: params.toolName,
+        input: params.input,
+        target: params.target,
+        outcome: { ok: true },
+        observation: params.observation,
+        durationMs: Date.now() - params.startTime,
+        screenshotPath: params.screenshotPath,
+        screenshotDimensions: params.screenshotDimensions,
+    });
+}
+/**
+ * Collect observation data and record the tool step in the knowledge store.
+ *
+ * @param page - The page to collect observation from
+ * @param toolName - Name of the tool that was executed
+ * @param input - Input parameters passed to the tool
+ * @param startTime - Timestamp when the tool execution started
+ * @param options - Optional metadata for the step record
+ * @param options.target - Target element information
+ * @param options.screenshotPath - Path to screenshot file if captured
+ * @param options.screenshotDimensions - Screenshot dimensions
+ * @param options.screenshotDimensions.width - Screenshot width in pixels
+ * @param options.screenshotDimensions.height - Screenshot height in pixels
+ * @returns Observation data collected after tool execution
+ */
+async function collectObservationAndRecord(page, toolName, input, startTime, options = {}) {
+    const observation = await collectObservation(page, 'full');
+    await recordToolStep({
+        toolName,
+        input,
+        startTime,
+        observation,
+        target: options.target,
+        screenshotPath: options.screenshotPath,
+        screenshotDimensions: options.screenshotDimensions,
+    });
+    return observation;
+}
+/**
+ * Handle tool execution errors and return appropriate error response.
+ *
+ * @param error - The error that occurred during tool execution
+ * @param defaultCode - Default error code to use if no specific match found
+ * @param defaultMessage - Default error message to use
+ * @param input - Input parameters that were passed to the tool
+ * @param sessionId - Current session ID for error context
+ * @param startTime - Timestamp when the tool execution started
+ * @returns Error response with appropriate code and message
+ */
+function handleToolError(error, defaultCode, defaultMessage, input, sessionId, startTime) {
+    const message = (0, utils_1.extractErrorMessage)(error);
+    if (message.includes('Unknown a11yRef') || message.includes('not found')) {
+        return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_TARGET_NOT_FOUND, message, { input }, sessionId, startTime);
+    }
+    return (0, utils_1.createErrorResponse)(defaultCode, `${defaultMessage}: ${message}`, { input }, sessionId, startTime);
+}
+//# sourceMappingURL=helpers.cjs.map

package/dist/mcp-server/tools/helpers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.cjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/helpers.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from '@playwright/test';\n\nimport type { ExtensionState } from '../../capabilities/types.js';\nimport { OBSERVATION_TESTID_LIMIT } from '../constants.js';\nimport { collectTestIds, collectTrimmedA11ySnapshot } from '../discovery.js';\nimport {\n  knowledgeStore,\n  createDefaultObservation,\n} from '../knowledge-store.js';\nimport { getSessionManager } from '../session-manager.js';\nimport type {\n  McpResponse,\n  ErrorCode,\n  TestIdItem,\n  StepRecordObservation,\n} from '../types';\nimport { ErrorCodes } from '../types';\nimport { createErrorResponse, extractErrorMessage, debugWarn } from '../utils';\n\n/**\n * Level of detail to collect for observation data.\n * - \"full\": Collect state, testIds, and a11y tree\n * - \"minimal\": Collect state only (no testIds or a11y)\n * - \"none\": Return empty observation\n */\nexport type ObservationLevel = 'full' | 'minimal' | 'none';\n\n/**\n * Parameters for recording a tool step in the knowledge store.\n */\nexport type RecordStepParams = {\n  /**\n   * Name of the tool that was executed\n   */\n  toolName: string;\n  /**\n   * Input parameters passed to the tool\n   */\n  input: Record<string, unknown>;\n  /**\n   * Timestamp when the tool execution started\n   */\n  startTime: number;\n  /**\n   * Observation data collected after tool execution\n   */\n  observation: StepRecordObservation;\n  /**\n   * Target element information (selector, testId, etc.)\n   */\n  target?: Record<string, string>;\n  /**\n   * Path to screenshot file if captured\n   */\n  screenshotPath?: string;\n  /**\n   * Screenshot dimensions if captured\n   */\n  screenshotDimensions?: {\n    /**\n     * Screenshot width in pixels\n     */\n    width: number;\n    /**\n     * Screenshot height in pixels\n     */\n    height: number;\n  };\n};\n\n/**\n * Context information for an active session.\n */\nexport type ActiveSessionContext = {\n  /**\n   * Unique session identifier\n   */\n  sessionId: string;\n  /**\n   * Current active page instance\n   */\n  page: Page;\n  /**\n   * Map of accessibility references to selectors\n   */\n  refMap: Map<string, string>;\n};\n\n/**\n * Check if an active session exists and return error if not.\n *\n * @param startTime - Timestamp when the operation started\n * @returns Error response if no active session, undefined otherwise\n */\nexport function requireActiveSession<Result>(\n  startTime: number,\n): McpResponse<Result> | undefined {\n  const sessionManager = getSessionManager();\n  if (!sessionManager.hasActiveSession()) {\n    return createErrorResponse(\n      ErrorCodes.MM_NO_ACTIVE_SESSION,\n      'No active session. Call launch first.',\n      undefined,\n      undefined,\n      startTime,\n    ) as McpResponse<Result>;\n  }\n  return undefined;\n}\n\n/**\n * Collect observation data from the current page state.\n *\n * @param page - The page to collect observation from\n * @param level - Level of detail to collect (full, minimal, or none)\n * @param presetState - Optional pre-fetched extension state to use instead of querying\n * @returns Observation data with state, testIds, and accessibility tree\n */\nexport async function collectObservation(\n  page: Page | undefined,\n  level: ObservationLevel,\n  presetState?: ExtensionState,\n): Promise<StepRecordObservation> {\n  const sessionManager = getSessionManager();\n\n  if (level === 'none') {\n    return createDefaultObservation({} as ExtensionState, [], []);\n  }\n\n  const state = presetState ?? (await sessionManager.getExtensionState());\n\n  if (level === 'minimal') {\n    return createDefaultObservation(state, [], []);\n  }\n\n  if (!page) {\n    debugWarn('collectObservation', 'Page not provided for full observation');\n    return createDefaultObservation(state, [], []);\n  }\n\n  try {\n    const testIds: TestIdItem[] = await collectTestIds(\n      page,\n      OBSERVATION_TESTID_LIMIT,\n    );\n    const { nodes, refMap } = await collectTrimmedA11ySnapshot(page);\n    sessionManager.setRefMap(refMap);\n    return createDefaultObservation(state, testIds, nodes);\n  } catch (error) {\n    debugWarn('collectObservation', error);\n    return createDefaultObservation(state, [], []);\n  }\n}\n\n/**\n * Wrapper that ensures an active session exists before executing a handler.\n *\n * @param handler - Function to execute with active session context\n * @returns Wrapped function that validates session before calling handler\n */\nexport function withActiveSession<TInput, TResult>(\n  handler: (\n    input: TInput,\n    ctx: ActiveSessionContext,\n    startTime: number,\n  ) => Promise<McpResponse<TResult>>,\n): (input: TInput) => Promise<McpResponse<TResult>> {\n  return async (input: TInput): Promise<McpResponse<TResult>> => {\n    const startTime = Date.now();\n    const sessionManager = getSessionManager();\n\n    const sessionError = requireActiveSession<TResult>(startTime);\n    if (sessionError) {\n      return sessionError;\n    }\n\n    const sessionId = sessionManager.getSessionId();\n    if (!sessionId) {\n      return createErrorResponse(\n        ErrorCodes.MM_NO_ACTIVE_SESSION,\n        'Session ID not found',\n        undefined,\n        undefined,\n        startTime,\n      ) as McpResponse<TResult>;\n    }\n    const page = sessionManager.getPage();\n    const refMap = sessionManager.getRefMap();\n\n    return handler(input, { sessionId, page, refMap }, startTime);\n  };\n}\n\n/**\n * Record a tool execution step in the knowledge store.\n *\n * @param params - Parameters containing tool name, input, observation, and metadata\n */\nexport async function recordToolStep(params: RecordStepParams): Promise<void> {\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId() ?? '';\n\n  await knowledgeStore.recordStep({\n    sessionId,\n    toolName: params.toolName,\n    input: params.input,\n    target: params.target,\n    outcome: { ok: true },\n    observation: params.observation,\n    durationMs: Date.now() - params.startTime,\n    screenshotPath: params.screenshotPath,\n    screenshotDimensions: params.screenshotDimensions,\n  });\n}\n\n/**\n * Collect observation data and record the tool step in the knowledge store.\n *\n * @param page - The page to collect observation from\n * @param toolName - Name of the tool that was executed\n * @param input - Input parameters passed to the tool\n * @param startTime - Timestamp when the tool execution started\n * @param options - Optional metadata for the step record\n * @param options.target - Target element information\n * @param options.screenshotPath - Path to screenshot file if captured\n * @param options.screenshotDimensions - Screenshot dimensions\n * @param options.screenshotDimensions.width - Screenshot width in pixels\n * @param options.screenshotDimensions.height - Screenshot height in pixels\n * @returns Observation data collected after tool execution\n */\nexport async function collectObservationAndRecord(\n  page: Page,\n  toolName: string,\n  input: Record<string, unknown>,\n  startTime: number,\n  options: {\n    /**\n     * Target element information (selector, testId, etc.)\n     */\n    target?: Record<string, string>;\n    /**\n     * Path to screenshot file if captured\n     */\n    screenshotPath?: string;\n    /**\n     * Screenshot dimensions if captured\n     */\n    screenshotDimensions?: {\n      /**\n       * Screenshot width in pixels\n       */\n      width: number;\n      /**\n       * Screenshot height in pixels\n       */\n      height: number;\n    };\n  } = {},\n): Promise<StepRecordObservation> {\n  const observation = await collectObservation(page, 'full');\n\n  await recordToolStep({\n    toolName,\n    input,\n    startTime,\n    observation,\n    target: options.target,\n    screenshotPath: options.screenshotPath,\n    screenshotDimensions: options.screenshotDimensions,\n  });\n\n  return observation;\n}\n\n/**\n * Handle tool execution errors and return appropriate error response.\n *\n * @param error - The error that occurred during tool execution\n * @param defaultCode - Default error code to use if no specific match found\n * @param defaultMessage - Default error message to use\n * @param input - Input parameters that were passed to the tool\n * @param sessionId - Current session ID for error context\n * @param startTime - Timestamp when the tool execution started\n * @returns Error response with appropriate code and message\n */\nexport function handleToolError<Result>(\n  error: unknown,\n  defaultCode: ErrorCode,\n  defaultMessage: string,\n  input: unknown,\n  sessionId: string | undefined,\n  startTime: number,\n): McpResponse<Result> {\n  const message = extractErrorMessage(error);\n\n  if (message.includes('Unknown a11yRef') || message.includes('not found')) {\n    return createErrorResponse(\n      ErrorCodes.MM_TARGET_NOT_FOUND,\n      message,\n      { input },\n      sessionId,\n      startTime,\n    ) as McpResponse<Result>;\n  }\n\n  return createErrorResponse(\n    defaultCode,\n    `${defaultMessage}: ${message}`,\n    { input },\n    sessionId,\n    startTime,\n  ) as McpResponse<Result>;\n}\n"]}

package/dist/mcp-server/tools/helpers.d.cts

@@ -0,0 +1,149 @@
+import type { Page } from "@playwright/test";
+import type { ExtensionState } from "../../capabilities/types.cjs";
+import type { McpResponse, ErrorCode, StepRecordObservation } from "../types/index.cjs";
+/**
+ * Level of detail to collect for observation data.
+ * - "full": Collect state, testIds, and a11y tree
+ * - "minimal": Collect state only (no testIds or a11y)
+ * - "none": Return empty observation
+ */
+export type ObservationLevel = 'full' | 'minimal' | 'none';
+/**
+ * Parameters for recording a tool step in the knowledge store.
+ */
+export type RecordStepParams = {
+    /**
+     * Name of the tool that was executed
+     */
+    toolName: string;
+    /**
+     * Input parameters passed to the tool
+     */
+    input: Record<string, unknown>;
+    /**
+     * Timestamp when the tool execution started
+     */
+    startTime: number;
+    /**
+     * Observation data collected after tool execution
+     */
+    observation: StepRecordObservation;
+    /**
+     * Target element information (selector, testId, etc.)
+     */
+    target?: Record<string, string>;
+    /**
+     * Path to screenshot file if captured
+     */
+    screenshotPath?: string;
+    /**
+     * Screenshot dimensions if captured
+     */
+    screenshotDimensions?: {
+        /**
+         * Screenshot width in pixels
+         */
+        width: number;
+        /**
+         * Screenshot height in pixels
+         */
+        height: number;
+    };
+};
+/**
+ * Context information for an active session.
+ */
+export type ActiveSessionContext = {
+    /**
+     * Unique session identifier
+     */
+    sessionId: string;
+    /**
+     * Current active page instance
+     */
+    page: Page;
+    /**
+     * Map of accessibility references to selectors
+     */
+    refMap: Map<string, string>;
+};
+/**
+ * Check if an active session exists and return error if not.
+ *
+ * @param startTime - Timestamp when the operation started
+ * @returns Error response if no active session, undefined otherwise
+ */
+export declare function requireActiveSession<Result>(startTime: number): McpResponse<Result> | undefined;
+/**
+ * Collect observation data from the current page state.
+ *
+ * @param page - The page to collect observation from
+ * @param level - Level of detail to collect (full, minimal, or none)
+ * @param presetState - Optional pre-fetched extension state to use instead of querying
+ * @returns Observation data with state, testIds, and accessibility tree
+ */
+export declare function collectObservation(page: Page | undefined, level: ObservationLevel, presetState?: ExtensionState): Promise<StepRecordObservation>;
+/**
+ * Wrapper that ensures an active session exists before executing a handler.
+ *
+ * @param handler - Function to execute with active session context
+ * @returns Wrapped function that validates session before calling handler
+ */
+export declare function withActiveSession<TInput, TResult>(handler: (input: TInput, ctx: ActiveSessionContext, startTime: number) => Promise<McpResponse<TResult>>): (input: TInput) => Promise<McpResponse<TResult>>;
+/**
+ * Record a tool execution step in the knowledge store.
+ *
+ * @param params - Parameters containing tool name, input, observation, and metadata
+ */
+export declare function recordToolStep(params: RecordStepParams): Promise<void>;
+/**
+ * Collect observation data and record the tool step in the knowledge store.
+ *
+ * @param page - The page to collect observation from
+ * @param toolName - Name of the tool that was executed
+ * @param input - Input parameters passed to the tool
+ * @param startTime - Timestamp when the tool execution started
+ * @param options - Optional metadata for the step record
+ * @param options.target - Target element information
+ * @param options.screenshotPath - Path to screenshot file if captured
+ * @param options.screenshotDimensions - Screenshot dimensions
+ * @param options.screenshotDimensions.width - Screenshot width in pixels
+ * @param options.screenshotDimensions.height - Screenshot height in pixels
+ * @returns Observation data collected after tool execution
+ */
+export declare function collectObservationAndRecord(page: Page, toolName: string, input: Record<string, unknown>, startTime: number, options?: {
+    /**
+     * Target element information (selector, testId, etc.)
+     */
+    target?: Record<string, string>;
+    /**
+     * Path to screenshot file if captured
+     */
+    screenshotPath?: string;
+    /**
+     * Screenshot dimensions if captured
+     */
+    screenshotDimensions?: {
+        /**
+         * Screenshot width in pixels
+         */
+        width: number;
+        /**
+         * Screenshot height in pixels
+         */
+        height: number;
+    };
+}): Promise<StepRecordObservation>;
+/**
+ * Handle tool execution errors and return appropriate error response.
+ *
+ * @param error - The error that occurred during tool execution
+ * @param defaultCode - Default error code to use if no specific match found
+ * @param defaultMessage - Default error message to use
+ * @param input - Input parameters that were passed to the tool
+ * @param sessionId - Current session ID for error context
+ * @param startTime - Timestamp when the tool execution started
+ * @returns Error response with appropriate code and message
+ */
+export declare function handleToolError<Result>(error: unknown, defaultCode: ErrorCode, defaultMessage: string, input: unknown, sessionId: string | undefined, startTime: number): McpResponse<Result>;
+//# sourceMappingURL=helpers.d.cts.map

package/dist/mcp-server/tools/helpers.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.cts","sourceRoot":"","sources":["../../../src/mcp-server/tools/helpers.ts"],"names":[],"mappings":"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"}