@metamask/client-mcp-core 0.1.0

package/dist/mcp-server/tools/navigation.mjs

@@ -0,0 +1,236 @@
+import { DEFAULT_INTERACTION_TIMEOUT_MS } from "../constants.mjs";
+import { getSessionManager } from "../session-manager.mjs";
+import { classifyNavigationError, classifyTabError, classifyNotificationError } from "./error-classification.mjs";
+import { runTool } from "./run-tool.mjs";
+import { ErrorCodes } from "../types/index.mjs";
+import { createErrorResponse } from "../utils/index.mjs";
+/**
+ * Handles navigation to a specific screen or URL.
+ *
+ * @param input The navigate input containing target screen and optional URL
+ * @param options Optional handler configuration
+ * @returns Promise resolving to navigate result with current URL information
+ */
+export async function handleNavigate(input, options) {
+    const startTime = Date.now();
+    const sessionManager = getSessionManager();
+    const sessionId = sessionManager.getSessionId();
+    if (input.screen === 'url' && !input.url) {
+        return createErrorResponse(ErrorCodes.MM_INVALID_INPUT, 'url is required when screen is "url"', { input }, sessionId, startTime);
+    }
+    const validScreens = ['home', 'settings', 'url', 'notification'];
+    if (!validScreens.includes(input.screen)) {
+        return createErrorResponse(ErrorCodes.MM_INVALID_INPUT, `Unknown screen: ${String(input.screen)}`, { input }, sessionId, startTime);
+    }
+    return runTool({
+        toolName: 'mm_navigate',
+        input,
+        options,
+        /**
+         * Executes the navigation action to the target screen.
+         *
+         * @param context The tool execution context containing page and reference map
+         * @returns Promise resolving to navigate result with success status and URL
+         */
+        execute: async (context) => {
+            switch (input.screen) {
+                case 'home':
+                    await sessionManager.navigateToHome();
+                    break;
+                case 'settings':
+                    await sessionManager.navigateToSettings();
+                    break;
+                case 'url':
+                    await sessionManager.navigateToUrl(input.url);
+                    break;
+                case 'notification':
+                    await sessionManager.navigateToNotification();
+                    break;
+                default:
+                    throw new Error(`Unsupported screen: ${String(input.screen)}`);
+            }
+            return {
+                navigated: true,
+                currentUrl: context.page.url(),
+            };
+        },
+        classifyError: classifyNavigationError,
+        /**
+         * Sanitizes input for knowledge store recording.
+         *
+         * @returns Sanitized input object with screen and URL information
+         */
+        sanitizeInputForRecording: () => ({
+            screen: input.screen,
+            url: input.url,
+        }),
+    });
+}
+/**
+ * Handles waiting for a notification popup to appear.
+ *
+ * @param input The wait input containing timeout options
+ * @param options Optional handler configuration
+ * @returns Promise resolving to wait result with notification page URL
+ */
+export async function handleWaitForNotification(input, options) {
+    const sessionManager = getSessionManager();
+    const timeoutMs = input.timeoutMs ?? DEFAULT_INTERACTION_TIMEOUT_MS;
+    return runTool({
+        toolName: 'mm_wait_for_notification',
+        input,
+        options,
+        /**
+         * Executes the wait action for notification popup.
+         *
+         * @returns Promise resolving to wait result with notification page URL
+         */
+        execute: async () => {
+            const notificationPage = await sessionManager.waitForNotificationPage(timeoutMs);
+            const pageUrl = notificationPage.url();
+            return {
+                found: true,
+                pageUrl,
+            };
+        },
+        classifyError: classifyNotificationError,
+        /**
+         * Sanitizes input for knowledge store recording.
+         *
+         * @returns Sanitized input object with timeout information
+         */
+        sanitizeInputForRecording: () => ({ timeoutMs }),
+    });
+}
+/**
+ * Handles switching to a different tab by role or URL.
+ *
+ * @param input The switch input containing tab role or URL to match
+ * @param options Optional handler configuration
+ * @returns Promise resolving to switch result with active tab information
+ */
+export async function handleSwitchToTab(input, options) {
+    const startTime = Date.now();
+    const sessionManager = getSessionManager();
+    const sessionId = sessionManager.getSessionId();
+    if (!input.role && !input.url) {
+        return createErrorResponse(ErrorCodes.MM_INVALID_INPUT, 'Either role or url must be provided', { input }, sessionId, startTime);
+    }
+    return runTool({
+        toolName: 'mm_switch_to_tab',
+        input,
+        options,
+        /**
+         * Executes the tab switch action.
+         *
+         * @param _context The tool execution context containing page and reference map
+         * @returns Promise resolving to switch result with active tab information
+         */
+        execute: async (_context) => {
+            const trackedPages = sessionManager.getTrackedPages();
+            const targetPage = trackedPages.find((trackedPage) => {
+                if (input.role) {
+                    return trackedPage.role === input.role;
+                }
+                if (input.url) {
+                    return trackedPage.url.startsWith(input.url);
+                }
+                return false;
+            });
+            if (!targetPage) {
+                const availableTabs = trackedPages.map((trackedPage) => ({
+                    role: trackedPage.role,
+                    url: trackedPage.url,
+                }));
+                throw new Error(`No tab found matching: ${input.role ?? input.url}. Available tabs: ${JSON.stringify(availableTabs)}`);
+            }
+            await targetPage.page.bringToFront();
+            sessionManager.setActivePage(targetPage.page);
+            const updatedTrackedPages = sessionManager.getTrackedPages();
+            const activeTabInfo = updatedTrackedPages.find((trackedPage) => trackedPage.page === targetPage.page);
+            return {
+                switched: true,
+                activeTab: {
+                    role: activeTabInfo?.role ?? 'other',
+                    url: targetPage.page.url(),
+                },
+            };
+        },
+        classifyError: classifyTabError,
+        /**
+         * Sanitizes input for knowledge store recording.
+         *
+         * @returns Sanitized input object with role and URL information
+         */
+        sanitizeInputForRecording: () => ({
+            role: input.role,
+            url: input.url,
+        }),
+    });
+}
+/**
+ * Handles closing a tab by role or URL.
+ *
+ * @param input The close input containing tab role or URL to match
+ * @param options Optional handler configuration
+ * @returns Promise resolving to close result with closed tab URL
+ */
+export async function handleCloseTab(input, options) {
+    const startTime = Date.now();
+    const sessionManager = getSessionManager();
+    const sessionId = sessionManager.getSessionId();
+    if (!input.role && !input.url) {
+        return createErrorResponse(ErrorCodes.MM_INVALID_INPUT, 'Either role or url must be provided', { input }, sessionId, startTime);
+    }
+    return runTool({
+        toolName: 'mm_close_tab',
+        input,
+        options,
+        /**
+         * Executes the tab close action.
+         *
+         * @param context The tool execution context containing page and reference map
+         * @returns Promise resolving to close result with closed tab URL
+         */
+        execute: async (context) => {
+            const trackedPages = sessionManager.getTrackedPages();
+            const targetPage = trackedPages.find((trackedPage) => {
+                if (input.role) {
+                    return trackedPage.role === input.role;
+                }
+                if (input.url) {
+                    return trackedPage.url.startsWith(input.url);
+                }
+                return false;
+            });
+            if (!targetPage) {
+                throw new Error(`No tab found matching: ${input.role ?? input.url}`);
+            }
+            const closedUrl = targetPage.url;
+            const currentActivePage = context.page;
+            if (targetPage.page === currentActivePage) {
+                const extensionPage = trackedPages.find((trackedPage) => trackedPage.role === 'extension');
+                if (extensionPage) {
+                    await extensionPage.page.bringToFront();
+                    sessionManager.setActivePage(extensionPage.page);
+                }
+            }
+            await targetPage.page.close();
+            return {
+                closed: true,
+                closedUrl,
+            };
+        },
+        classifyError: classifyTabError,
+        /**
+         * Sanitizes input for knowledge store recording.
+         *
+         * @returns Sanitized input object with role and URL information
+         */
+        sanitizeInputForRecording: () => ({
+            role: input.role,
+            url: input.url,
+        }),
+    });
+}
+//# sourceMappingURL=navigation.mjs.map

package/dist/mcp-server/tools/navigation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.mjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/navigation.ts"],"names":[],"mappings":"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","sourcesContent":["import { DEFAULT_INTERACTION_TIMEOUT_MS } from '../constants.js';\nimport { getSessionManager } from '../session-manager.js';\nimport {\n  classifyNavigationError,\n  classifyTabError,\n  classifyNotificationError,\n} from './error-classification.js';\nimport { runTool } from './run-tool.js';\nimport type {\n  NavigateInput,\n  NavigateResult,\n  WaitForNotificationInput,\n  WaitForNotificationResult,\n  SwitchToTabInput,\n  SwitchToTabResult,\n  CloseTabInput,\n  CloseTabResult,\n  McpResponse,\n  HandlerOptions,\n} from '../types';\nimport { ErrorCodes } from '../types';\nimport { createErrorResponse } from '../utils';\n\n/**\n * Handles navigation to a specific screen or URL.\n *\n * @param input The navigate input containing target screen and optional URL\n * @param options Optional handler configuration\n * @returns Promise resolving to navigate result with current URL information\n */\nexport async function handleNavigate(\n  input: NavigateInput,\n  options?: HandlerOptions,\n): Promise<McpResponse<NavigateResult>> {\n  const startTime = Date.now();\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId();\n\n  if (input.screen === 'url' && !input.url) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      'url is required when screen is \"url\"',\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  const validScreens = ['home', 'settings', 'url', 'notification'];\n  if (!validScreens.includes(input.screen)) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      `Unknown screen: ${String(input.screen)}`,\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  return runTool<NavigateInput, NavigateResult>({\n    toolName: 'mm_navigate',\n    input,\n    options,\n\n    /**\n     * Executes the navigation action to the target screen.\n     *\n     * @param context The tool execution context containing page and reference map\n     * @returns Promise resolving to navigate result with success status and URL\n     */\n    execute: async (context) => {\n      switch (input.screen) {\n        case 'home':\n          await sessionManager.navigateToHome();\n          break;\n        case 'settings':\n          await sessionManager.navigateToSettings();\n          break;\n        case 'url':\n          await sessionManager.navigateToUrl(input.url as string);\n          break;\n        case 'notification':\n          await sessionManager.navigateToNotification();\n          break;\n        default:\n          throw new Error(`Unsupported screen: ${String(input.screen)}`);\n      }\n\n      return {\n        navigated: true,\n        currentUrl: context.page.url(),\n      };\n    },\n\n    classifyError: classifyNavigationError,\n\n    /**\n     * Sanitizes input for knowledge store recording.\n     *\n     * @returns Sanitized input object with screen and URL information\n     */\n    sanitizeInputForRecording: () => ({\n      screen: input.screen,\n      url: input.url,\n    }),\n  });\n}\n\n/**\n * Handles waiting for a notification popup to appear.\n *\n * @param input The wait input containing timeout options\n * @param options Optional handler configuration\n * @returns Promise resolving to wait result with notification page URL\n */\nexport async function handleWaitForNotification(\n  input: WaitForNotificationInput,\n  options?: HandlerOptions,\n): Promise<McpResponse<WaitForNotificationResult>> {\n  const sessionManager = getSessionManager();\n  const timeoutMs = input.timeoutMs ?? DEFAULT_INTERACTION_TIMEOUT_MS;\n\n  return runTool<WaitForNotificationInput, WaitForNotificationResult>({\n    toolName: 'mm_wait_for_notification',\n    input,\n    options,\n\n    /**\n     * Executes the wait action for notification popup.\n     *\n     * @returns Promise resolving to wait result with notification page URL\n     */\n    execute: async () => {\n      const notificationPage =\n        await sessionManager.waitForNotificationPage(timeoutMs);\n      const pageUrl = notificationPage.url();\n\n      return {\n        found: true,\n        pageUrl,\n      };\n    },\n\n    classifyError: classifyNotificationError,\n\n    /**\n     * Sanitizes input for knowledge store recording.\n     *\n     * @returns Sanitized input object with timeout information\n     */\n    sanitizeInputForRecording: () => ({ timeoutMs }),\n  });\n}\n\n/**\n * Handles switching to a different tab by role or URL.\n *\n * @param input The switch input containing tab role or URL to match\n * @param options Optional handler configuration\n * @returns Promise resolving to switch result with active tab information\n */\nexport async function handleSwitchToTab(\n  input: SwitchToTabInput,\n  options?: HandlerOptions,\n): Promise<McpResponse<SwitchToTabResult>> {\n  const startTime = Date.now();\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId();\n\n  if (!input.role && !input.url) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      'Either role or url must be provided',\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  return runTool<SwitchToTabInput, SwitchToTabResult>({\n    toolName: 'mm_switch_to_tab',\n    input,\n    options,\n\n    /**\n     * Executes the tab switch action.\n     *\n     * @param _context The tool execution context containing page and reference map\n     * @returns Promise resolving to switch result with active tab information\n     */\n    execute: async (_context) => {\n      const trackedPages = sessionManager.getTrackedPages();\n      const targetPage = trackedPages.find((trackedPage) => {\n        if (input.role) {\n          return trackedPage.role === input.role;\n        }\n        if (input.url) {\n          return trackedPage.url.startsWith(input.url);\n        }\n        return false;\n      });\n\n      if (!targetPage) {\n        const availableTabs = trackedPages.map((trackedPage) => ({\n          role: trackedPage.role,\n          url: trackedPage.url,\n        }));\n        throw new Error(\n          `No tab found matching: ${input.role ?? input.url}. Available tabs: ${JSON.stringify(availableTabs)}`,\n        );\n      }\n\n      await targetPage.page.bringToFront();\n      sessionManager.setActivePage(targetPage.page);\n\n      const updatedTrackedPages = sessionManager.getTrackedPages();\n      const activeTabInfo = updatedTrackedPages.find(\n        (trackedPage) => trackedPage.page === targetPage.page,\n      );\n\n      return {\n        switched: true,\n        activeTab: {\n          role: activeTabInfo?.role ?? 'other',\n          url: targetPage.page.url(),\n        },\n      };\n    },\n\n    classifyError: classifyTabError,\n\n    /**\n     * Sanitizes input for knowledge store recording.\n     *\n     * @returns Sanitized input object with role and URL information\n     */\n    sanitizeInputForRecording: () => ({\n      role: input.role,\n      url: input.url,\n    }),\n  });\n}\n\n/**\n * Handles closing a tab by role or URL.\n *\n * @param input The close input containing tab role or URL to match\n * @param options Optional handler configuration\n * @returns Promise resolving to close result with closed tab URL\n */\nexport async function handleCloseTab(\n  input: CloseTabInput,\n  options?: HandlerOptions,\n): Promise<McpResponse<CloseTabResult>> {\n  const startTime = Date.now();\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId();\n\n  if (!input.role && !input.url) {\n    return createErrorResponse(\n      ErrorCodes.MM_INVALID_INPUT,\n      'Either role or url must be provided',\n      { input },\n      sessionId,\n      startTime,\n    );\n  }\n\n  return runTool<CloseTabInput, CloseTabResult>({\n    toolName: 'mm_close_tab',\n    input,\n    options,\n\n    /**\n     * Executes the tab close action.\n     *\n     * @param context The tool execution context containing page and reference map\n     * @returns Promise resolving to close result with closed tab URL\n     */\n    execute: async (context) => {\n      const trackedPages = sessionManager.getTrackedPages();\n      const targetPage = trackedPages.find((trackedPage) => {\n        if (input.role) {\n          return trackedPage.role === input.role;\n        }\n        if (input.url) {\n          return trackedPage.url.startsWith(input.url);\n        }\n        return false;\n      });\n\n      if (!targetPage) {\n        throw new Error(`No tab found matching: ${input.role ?? input.url}`);\n      }\n\n      const closedUrl = targetPage.url;\n\n      const currentActivePage = context.page;\n      if (targetPage.page === currentActivePage) {\n        const extensionPage = trackedPages.find(\n          (trackedPage) => trackedPage.role === 'extension',\n        );\n        if (extensionPage) {\n          await extensionPage.page.bringToFront();\n          sessionManager.setActivePage(extensionPage.page);\n        }\n      }\n\n      await targetPage.page.close();\n\n      return {\n        closed: true,\n        closedUrl,\n      };\n    },\n\n    classifyError: classifyTabError,\n\n    /**\n     * Sanitizes input for knowledge store recording.\n     *\n     * @returns Sanitized input object with role and URL information\n     */\n    sanitizeInputForRecording: () => ({\n      role: input.role,\n      url: input.url,\n    }),\n  });\n}\n"]}

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

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolHandlers = exports.buildToolHandlersRecord = exports.hasToolHandler = exports.getToolHandler = void 0;
+const definitions_js_1 = require("./definitions.cjs");
+var definitions_js_2 = require("./definitions.cjs");
+Object.defineProperty(exports, "getToolHandler", { enumerable: true, get: function () { return definitions_js_2.getToolHandler; } });
+Object.defineProperty(exports, "hasToolHandler", { enumerable: true, get: function () { return definitions_js_2.hasToolHandler; } });
+Object.defineProperty(exports, "buildToolHandlersRecord", { enumerable: true, get: function () { return definitions_js_2.buildToolHandlersRecord; } });
+exports.toolHandlers = (0, definitions_js_1.buildToolHandlersRecord)();
+//# sourceMappingURL=registry.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.cjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/registry.ts"],"names":[],"mappings":";;;AAAA,sDAA2D;AAE3D,oDAI0B;AAHxB,gHAAA,cAAc,OAAA;AACd,gHAAA,cAAc,OAAA;AACd,yHAAA,uBAAuB,OAAA;AAIZ,QAAA,YAAY,GAAG,IAAA,wCAAuB,GAAE,CAAC","sourcesContent":["import { buildToolHandlersRecord } from './definitions.js';\n\nexport {\n  getToolHandler,\n  hasToolHandler,\n  buildToolHandlersRecord,\n} from './definitions.js';\nexport type { ToolHandler } from './batch.js';\n\nexport const toolHandlers = buildToolHandlersRecord();\n"]}

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

@@ -0,0 +1,4 @@
+export { getToolHandler, hasToolHandler, buildToolHandlersRecord, } from "./definitions.cjs";
+export type { ToolHandler } from "./batch.cjs";
+export declare const toolHandlers: Record<string, import("./batch.cjs").ToolHandler>;
+//# sourceMappingURL=registry.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.cts","sourceRoot":"","sources":["../../../src/mcp-server/tools/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,cAAc,EACd,uBAAuB,GACxB,0BAAyB;AAC1B,YAAY,EAAE,WAAW,EAAE,oBAAmB;AAE9C,eAAO,MAAM,YAAY,kDAA4B,CAAC"}

package/dist/mcp-server/tools/registry.d.mts

@@ -0,0 +1,4 @@
+export { getToolHandler, hasToolHandler, buildToolHandlersRecord, } from "./definitions.mjs";
+export type { ToolHandler } from "./batch.mjs";
+export declare const toolHandlers: Record<string, import("./batch.mjs").ToolHandler>;
+//# sourceMappingURL=registry.d.mts.map

package/dist/mcp-server/tools/registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.mts","sourceRoot":"","sources":["../../../src/mcp-server/tools/registry.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,cAAc,EACd,uBAAuB,GACxB,0BAAyB;AAC1B,YAAY,EAAE,WAAW,EAAE,oBAAmB;AAE9C,eAAO,MAAM,YAAY,kDAA4B,CAAC"}

package/dist/mcp-server/tools/registry.mjs

@@ -0,0 +1,4 @@
+import { buildToolHandlersRecord } from "./definitions.mjs";
+export { getToolHandler, hasToolHandler, buildToolHandlersRecord } from "./definitions.mjs";
+export const toolHandlers = buildToolHandlersRecord();
+//# sourceMappingURL=registry.mjs.map

package/dist/mcp-server/tools/registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.mjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,0BAAyB;AAE3D,OAAO,EACL,cAAc,EACd,cAAc,EACd,uBAAuB,EACxB,0BAAyB;AAG1B,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,EAAE,CAAC","sourcesContent":["import { buildToolHandlersRecord } from './definitions.js';\n\nexport {\n  getToolHandler,\n  hasToolHandler,\n  buildToolHandlersRecord,\n} from './definitions.js';\nexport type { ToolHandler } from './batch.js';\n\nexport const toolHandlers = buildToolHandlersRecord();\n"]}

package/dist/mcp-server/tools/run-tool.cjs

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runTool = runTool;
+const knowledge_store_js_1 = require("../knowledge-store.cjs");
+const session_manager_js_1 = require("../session-manager.cjs");
+const helpers_js_1 = require("./helpers.cjs");
+const types_1 = require("../types/index.cjs");
+const utils_1 = require("../utils/index.cjs");
+/**
+ * Creates an empty observation object for step recording.
+ *
+ * @returns Empty observation with default state, testIds, and a11y nodes
+ */
+function createEmptyObservation() {
+    return {
+        state: {},
+        testIds: [],
+        a11y: { nodes: [] },
+    };
+}
+/**
+ * Type guard to check if result is a ToolExecuteResult with observation.
+ *
+ * @param result The result to check
+ * @returns True if result is a ToolExecuteResult with observation property
+ */
+function isToolExecuteResult(result) {
+    return (typeof result === 'object' &&
+        result !== null &&
+        'result' in result &&
+        Object.prototype.hasOwnProperty.call(result, 'result'));
+}
+/**
+ * Executes a tool with error handling, observation collection, and knowledge store recording.
+ *
+ * @param config The tool execution configuration with input, execute function, and error handling
+ * @returns Promise resolving to MCP response with tool result or error information
+ */
+async function runTool(config) {
+    const startTime = Date.now();
+    const sessionManager = (0, session_manager_js_1.getSessionManager)();
+    const sessionId = sessionManager.getSessionId();
+    const requiresSession = config.requiresSession ?? true;
+    const effectivePolicy = config.options?.observationPolicy ?? config.observationPolicy ?? 'default';
+    try {
+        if (requiresSession && !sessionManager.hasActiveSession()) {
+            return (0, utils_1.createErrorResponse)(types_1.ErrorCodes.MM_NO_ACTIVE_SESSION, 'No active session. Call launch first.', { input: config.input }, undefined, startTime);
+        }
+        const context = {
+            sessionId,
+            page: requiresSession ? sessionManager.getPage() : undefined,
+            refMap: requiresSession ? sessionManager.getRefMap() : new Map(),
+            startTime,
+        };
+        const executeResult = await config.execute(context);
+        let result;
+        let customObservation;
+        if (isToolExecuteResult(executeResult)) {
+            result = executeResult.result;
+            customObservation = executeResult.observation;
+        }
+        else {
+            result = executeResult;
+        }
+        let observation;
+        if (effectivePolicy === 'custom' && customObservation) {
+            observation = customObservation;
+        }
+        else if (effectivePolicy === 'default' && requiresSession) {
+            observation = await (0, helpers_js_1.collectObservation)(context.page, 'full');
+        }
+        else if ((effectivePolicy === 'none' || effectivePolicy === 'failures') &&
+            requiresSession) {
+            observation = await (0, helpers_js_1.collectObservation)(context.page, 'minimal');
+        }
+        if (sessionId) {
+            const recordInput = config.sanitizeInputForRecording
+                ? config.sanitizeInputForRecording(config.input)
+                : config.input;
+            await knowledge_store_js_1.knowledgeStore.recordStep({
+                sessionId,
+                toolName: config.toolName,
+                input: recordInput,
+                target: config.getTarget?.(config.input),
+                outcome: { ok: true },
+                observation: observation ?? createEmptyObservation(),
+                durationMs: Date.now() - startTime,
+                context: sessionManager.getEnvironmentMode(),
+            });
+        }
+        return (0, utils_1.createSuccessResponse)(result, sessionId, startTime);
+    }
+    catch (error) {
+        const errorInfo = config.classifyError?.(error) ?? {
+            code: `MM_${config.toolName.toUpperCase().replace(/^MM_/u, '')}_FAILED`,
+            message: (0, utils_1.extractErrorMessage)(error),
+        };
+        let failureObservation = createEmptyObservation();
+        if (requiresSession && sessionManager.hasActiveSession()) {
+            if (effectivePolicy === 'failures' || effectivePolicy === 'default') {
+                try {
+                    const page = sessionManager.getPage();
+                    failureObservation = await (0, helpers_js_1.collectObservation)(page, 'full');
+                }
+                catch (collectError) {
+                    (0, utils_1.debugWarn)('run-tool.collectObservation', collectError);
+                    failureObservation = await (0, helpers_js_1.collectObservation)(undefined, 'minimal');
+                }
+            }
+            else if (effectivePolicy === 'none') {
+                try {
+                    failureObservation = await (0, helpers_js_1.collectObservation)(undefined, 'minimal');
+                }
+                catch (collectError) {
+                    (0, utils_1.debugWarn)('run-tool.collectObservation', collectError);
+                }
+            }
+        }
+        if (sessionId) {
+            const recordInput = config.sanitizeInputForRecording
+                ? config.sanitizeInputForRecording(config.input)
+                : config.input;
+            await knowledge_store_js_1.knowledgeStore.recordStep({
+                sessionId,
+                toolName: config.toolName,
+                input: recordInput,
+                target: config.getTarget?.(config.input),
+                outcome: {
+                    ok: false,
+                    error: { code: errorInfo.code, message: errorInfo.message },
+                },
+                observation: failureObservation,
+                durationMs: Date.now() - startTime,
+                context: sessionManager.getEnvironmentMode(),
+            });
+        }
+        return (0, utils_1.createErrorResponse)(errorInfo.code, errorInfo.message, { input: config.input }, sessionId, startTime);
+    }
+}
+//# sourceMappingURL=run-tool.cjs.map

package/dist/mcp-server/tools/run-tool.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-tool.cjs","sourceRoot":"","sources":["../../../src/mcp-server/tools/run-tool.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page } from '@playwright/test';\n\nimport type { ExtensionState } from '../../capabilities/types.js';\nimport { knowledgeStore } from '../knowledge-store.js';\nimport { getSessionManager } from '../session-manager.js';\nimport { collectObservation } from './helpers.js';\nimport type {\n  McpResponse,\n  HandlerOptions,\n  StepRecordObservation,\n  ErrorCode,\n} from '../types';\nimport { ErrorCodes } from '../types';\nimport {\n  createSuccessResponse,\n  createErrorResponse,\n  extractErrorMessage,\n  debugWarn,\n} from '../utils';\n\n/**\n * Creates an empty observation object for step recording.\n *\n * @returns Empty observation with default state, testIds, and a11y nodes\n */\nfunction createEmptyObservation(): StepRecordObservation {\n  return {\n    state: {} as ExtensionState,\n    testIds: [],\n    a11y: { nodes: [] },\n  };\n}\n\nexport type ObservationPolicy = 'none' | 'default' | 'custom' | 'failures';\n\nexport type ToolExecutionContext = {\n  sessionId: string | undefined;\n  page: Page;\n  refMap: Map<string, string>;\n  startTime: number;\n};\n\nexport type ToolExecuteResult<TResult> = {\n  result: TResult;\n  observation?: StepRecordObservation;\n};\n\nexport type ToolExecutionConfig<TInput, TResult> = {\n  toolName: string;\n  input: TInput;\n  options?: HandlerOptions;\n  requiresSession?: boolean;\n  observationPolicy?: ObservationPolicy;\n  execute: (\n    context: ToolExecutionContext,\n  ) => Promise<TResult | ToolExecuteResult<TResult>>;\n  classifyError?: (error: unknown) => {\n    code: string;\n    message: string;\n  };\n  getTarget?: (input: TInput) =>\n    | {\n        testId?: string;\n        selector?: string;\n        a11yRef?: string;\n      }\n    | undefined;\n  sanitizeInputForRecording?: (input: TInput) => Record<string, unknown>;\n};\n\n/**\n * Type guard to check if result is a ToolExecuteResult with observation.\n *\n * @param result The result to check\n * @returns True if result is a ToolExecuteResult with observation property\n */\nfunction isToolExecuteResult<TResult>(\n  result: TResult | ToolExecuteResult<TResult>,\n): result is ToolExecuteResult<TResult> {\n  return (\n    typeof result === 'object' &&\n    result !== null &&\n    'result' in result &&\n    Object.prototype.hasOwnProperty.call(result, 'result')\n  );\n}\n\n/**\n * Executes a tool with error handling, observation collection, and knowledge store recording.\n *\n * @param config The tool execution configuration with input, execute function, and error handling\n * @returns Promise resolving to MCP response with tool result or error information\n */\nexport async function runTool<TInput, TResult>(\n  config: ToolExecutionConfig<TInput, TResult>,\n): Promise<McpResponse<TResult>> {\n  const startTime = Date.now();\n  const sessionManager = getSessionManager();\n  const sessionId = sessionManager.getSessionId();\n  const requiresSession = config.requiresSession ?? true;\n\n  const effectivePolicy =\n    config.options?.observationPolicy ?? config.observationPolicy ?? 'default';\n\n  try {\n    if (requiresSession && !sessionManager.hasActiveSession()) {\n      return createErrorResponse(\n        ErrorCodes.MM_NO_ACTIVE_SESSION,\n        'No active session. Call launch first.',\n        { input: config.input },\n        undefined,\n        startTime,\n      );\n    }\n\n    const context: ToolExecutionContext = {\n      sessionId,\n      page: requiresSession ? sessionManager.getPage() : (undefined as never),\n      refMap: requiresSession ? sessionManager.getRefMap() : new Map(),\n      startTime,\n    };\n\n    const executeResult = await config.execute(context);\n\n    let result: TResult;\n    let customObservation: StepRecordObservation | undefined;\n\n    if (isToolExecuteResult<TResult>(executeResult)) {\n      result = executeResult.result;\n      customObservation = executeResult.observation;\n    } else {\n      result = executeResult;\n    }\n\n    let observation: StepRecordObservation | undefined;\n\n    if (effectivePolicy === 'custom' && customObservation) {\n      observation = customObservation;\n    } else if (effectivePolicy === 'default' && requiresSession) {\n      observation = await collectObservation(context.page, 'full');\n    } else if (\n      (effectivePolicy === 'none' || effectivePolicy === 'failures') &&\n      requiresSession\n    ) {\n      observation = await collectObservation(context.page, 'minimal');\n    }\n\n    if (sessionId) {\n      const recordInput = config.sanitizeInputForRecording\n        ? config.sanitizeInputForRecording(config.input)\n        : (config.input as Record<string, unknown>);\n\n      await knowledgeStore.recordStep({\n        sessionId,\n        toolName: config.toolName,\n        input: recordInput,\n        target: config.getTarget?.(config.input),\n        outcome: { ok: true },\n        observation: observation ?? createEmptyObservation(),\n        durationMs: Date.now() - startTime,\n        context: sessionManager.getEnvironmentMode(),\n      });\n    }\n\n    return createSuccessResponse<TResult>(result, sessionId, startTime);\n  } catch (error) {\n    const errorInfo = config.classifyError?.(error) ?? {\n      code: `MM_${config.toolName.toUpperCase().replace(/^MM_/u, '')}_FAILED`,\n      message: extractErrorMessage(error),\n    };\n\n    let failureObservation: StepRecordObservation = createEmptyObservation();\n\n    if (requiresSession && sessionManager.hasActiveSession()) {\n      if (effectivePolicy === 'failures' || effectivePolicy === 'default') {\n        try {\n          const page = sessionManager.getPage();\n          failureObservation = await collectObservation(page, 'full');\n        } catch (collectError) {\n          debugWarn('run-tool.collectObservation', collectError);\n          failureObservation = await collectObservation(undefined, 'minimal');\n        }\n      } else if (effectivePolicy === 'none') {\n        try {\n          failureObservation = await collectObservation(undefined, 'minimal');\n        } catch (collectError) {\n          debugWarn('run-tool.collectObservation', collectError);\n        }\n      }\n    }\n\n    if (sessionId) {\n      const recordInput = config.sanitizeInputForRecording\n        ? config.sanitizeInputForRecording(config.input)\n        : (config.input as Record<string, unknown>);\n\n      await knowledgeStore.recordStep({\n        sessionId,\n        toolName: config.toolName,\n        input: recordInput,\n        target: config.getTarget?.(config.input),\n        outcome: {\n          ok: false,\n          error: { code: errorInfo.code, message: errorInfo.message },\n        },\n        observation: failureObservation,\n        durationMs: Date.now() - startTime,\n        context: sessionManager.getEnvironmentMode(),\n      });\n    }\n\n    return createErrorResponse(\n      errorInfo.code as ErrorCode,\n      errorInfo.message,\n      { input: config.input },\n      sessionId,\n      startTime,\n    );\n  }\n}\n"]}

package/dist/mcp-server/tools/run-tool.d.cts

@@ -0,0 +1,39 @@
+import type { Page } from "@playwright/test";
+import type { McpResponse, HandlerOptions, StepRecordObservation } from "../types/index.cjs";
+export type ObservationPolicy = 'none' | 'default' | 'custom' | 'failures';
+export type ToolExecutionContext = {
+    sessionId: string | undefined;
+    page: Page;
+    refMap: Map<string, string>;
+    startTime: number;
+};
+export type ToolExecuteResult<TResult> = {
+    result: TResult;
+    observation?: StepRecordObservation;
+};
+export type ToolExecutionConfig<TInput, TResult> = {
+    toolName: string;
+    input: TInput;
+    options?: HandlerOptions;
+    requiresSession?: boolean;
+    observationPolicy?: ObservationPolicy;
+    execute: (context: ToolExecutionContext) => Promise<TResult | ToolExecuteResult<TResult>>;
+    classifyError?: (error: unknown) => {
+        code: string;
+        message: string;
+    };
+    getTarget?: (input: TInput) => {
+        testId?: string;
+        selector?: string;
+        a11yRef?: string;
+    } | undefined;
+    sanitizeInputForRecording?: (input: TInput) => Record<string, unknown>;
+};
+/**
+ * Executes a tool with error handling, observation collection, and knowledge store recording.
+ *
+ * @param config The tool execution configuration with input, execute function, and error handling
+ * @returns Promise resolving to MCP response with tool result or error information
+ */
+export declare function runTool<TInput, TResult>(config: ToolExecutionConfig<TInput, TResult>): Promise<McpResponse<TResult>>;
+//# sourceMappingURL=run-tool.d.cts.map

package/dist/mcp-server/tools/run-tool.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-tool.d.cts","sourceRoot":"","sources":["../../../src/mcp-server/tools/run-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,yBAAyB;AAM7C,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,qBAAqB,EAEtB,2BAAiB;AAsBlB,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3E,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,MAAM,EAAE,OAAO,IAAI;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,OAAO,EAAE,CACP,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;IACnD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK;QAClC,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KACtB;QACE,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACD,SAAS,CAAC;IACd,yBAAyB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxE,CAAC;AAmBF;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,OAAO,EAC3C,MAAM,EAAE,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CA4H/B"}

package/dist/mcp-server/tools/run-tool.d.mts

@@ -0,0 +1,39 @@
+import type { Page } from "@playwright/test";
+import type { McpResponse, HandlerOptions, StepRecordObservation } from "../types/index.mjs";
+export type ObservationPolicy = 'none' | 'default' | 'custom' | 'failures';
+export type ToolExecutionContext = {
+    sessionId: string | undefined;
+    page: Page;
+    refMap: Map<string, string>;
+    startTime: number;
+};
+export type ToolExecuteResult<TResult> = {
+    result: TResult;
+    observation?: StepRecordObservation;
+};
+export type ToolExecutionConfig<TInput, TResult> = {
+    toolName: string;
+    input: TInput;
+    options?: HandlerOptions;
+    requiresSession?: boolean;
+    observationPolicy?: ObservationPolicy;
+    execute: (context: ToolExecutionContext) => Promise<TResult | ToolExecuteResult<TResult>>;
+    classifyError?: (error: unknown) => {
+        code: string;
+        message: string;
+    };
+    getTarget?: (input: TInput) => {
+        testId?: string;
+        selector?: string;
+        a11yRef?: string;
+    } | undefined;
+    sanitizeInputForRecording?: (input: TInput) => Record<string, unknown>;
+};
+/**
+ * Executes a tool with error handling, observation collection, and knowledge store recording.
+ *
+ * @param config The tool execution configuration with input, execute function, and error handling
+ * @returns Promise resolving to MCP response with tool result or error information
+ */
+export declare function runTool<TInput, TResult>(config: ToolExecutionConfig<TInput, TResult>): Promise<McpResponse<TResult>>;
+//# sourceMappingURL=run-tool.d.mts.map

package/dist/mcp-server/tools/run-tool.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-tool.d.mts","sourceRoot":"","sources":["../../../src/mcp-server/tools/run-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,yBAAyB;AAM7C,OAAO,KAAK,EACV,WAAW,EACX,cAAc,EACd,qBAAqB,EAEtB,2BAAiB;AAsBlB,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3E,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,OAAO,IAAI;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,MAAM,EAAE,OAAO,IAAI;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IACtC,OAAO,EAAE,CACP,OAAO,EAAE,oBAAoB,KAC1B,OAAO,CAAC,OAAO,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;IACnD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK;QAClC,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KACtB;QACE,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACD,SAAS,CAAC;IACd,yBAAyB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxE,CAAC;AAmBF;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,OAAO,EAC3C,MAAM,EAAE,mBAAmB,CAAC,MAAM,EAAE,OAAO,CAAC,GAC3C,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CA4H/B"}