@diegosouzacdv/jev-browser-mcp 0.7.0 → 0.7.1

package/mcp_servers/jev-browser-npm/src/server.mjs

@@ -8,59 +8,13 @@ import { chromium } from "playwright";
 import * as z from "zod/v4";
 import packageManifest from "../../../package.json" with { type: "json" };
 import { loadSettings, JevBrowserError } from "./config.mjs";
-import { chooseNextAction, createMutationAuthorizationStore, describeBrowserActions, executeBrowserFlow } from "./flow.mjs";
+import { chooseNextAction, collectFlowContractIssues, createMutationAuthorizationStore, describeBrowserActions, executeBrowserFlow } from "./flow.mjs";
 
 const browserContract = describeBrowserActions();
-const actionNames = Object.keys(browserContract.actions);
 const jsonObject = z.record(z.string(), z.unknown());
-function browserStepFieldSchema(field) {
-  if (["mutating", "screenshot", "expect_download", "expect_popup", "blur", "sensitive", "full_page"].includes(field)) return z.boolean();
-  if (["timeout_ms", "timeout_seconds"].includes(field)) return z.number().positive();
-  if (["index", "context_index", "ms", "duration_ms", "status", "close_code"].includes(field)) return z.number().int();
-  if (field === "file_paths") return z.union([z.string(), z.array(z.string())]);
-  if (["near", "within", "if_visible", "json"].includes(field)) return jsonObject;
-  if (field === "name_match") return z.enum(["exact", "contains", "regex"]);
-  if (field === "condition") return z.enum(["network_idle", "angular_idle", "url", "hidden"]);
-  if (field === "standard") return z.enum(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa", "section508"]);
-  return z.string();
-}
-function browserStepVariant(action, contract, aliases = []) {
-  const required = new Set(contract.required);
-  const optional = new Set([...contract.optional, "timeout_ms", "mutating", "screenshot", ...aliases]);
-  if (action === "wait") { required.delete("ms"); optional.add("ms"); }
-  if (action === "wait_for_text") { required.delete("text"); optional.add("text"); }
-  if (action === "assert_text" || action === "assert_value") { required.delete("expected"); optional.add("expected"); }
-  if (action === "upload_file") { required.delete("file_paths"); optional.add("file_paths"); }
-  if (action === "wait") optional.add("duration_ms");
-  if (action === "wait_for_text" || action === "assert_text" || action === "assert_value") optional.add("value");
-  if (action === "upload_file") optional.add("file_path");
-  if (action === "confirm_modal") {
-    required.delete("button");
-    optional.add("button");
-    optional.add("trigger");
-    optional.add("confirm");
-  }
-  const shape = { action: z.literal(action) };
-  for (const key of new Set([...required, ...optional])) {
-    const field = browserStepFieldSchema(key);
-    shape[key] = required.has(key) ? field : field.optional();
-  }
-  return z.object(shape).strict();
-}
-const browserStepVariants = Object.entries(browserContract.actions).map(([action, contract]) => browserStepVariant(action, contract));
-browserStepVariants.push(
-  browserStepVariant("fill", browserContract.actions.type, ["value"]),
-  browserStepVariant("press_key", browserContract.actions.press),
-);
-const browserStepSchema = z.discriminatedUnion("action", browserStepVariants);
-const candidatePlanSchema = z.object({
-  description: z.string(),
-  steps: z.array(browserStepSchema).min(1),
-  comment: z.string().optional(),
-  when: z.object({ visible: z.string() }).strict().optional(),
-}).strict();
 const browserOptionsShape = Object.fromEntries(browserContract.options.map((key) => {
   const value = key === "return_snapshot" ? z.enum(["diff", "full", "none"])
+    : key === "capture_network" ? z.enum(["none", "errors", "all"])
     : key === "reuse_page_match" ? z.enum(["url", "path"])
       : key === "color_scheme" ? z.enum(["light", "dark", "no-preference"])
         : key === "permissions" ? z.array(z.enum(["microphone", "geolocation"]))
@@ -74,6 +28,12 @@ const browserOptionsShape = Object.fromEntries(browserContract.options.map((key)
   return [key, value.optional()];
 }));
 const browserOptionsSchema = z.object(browserOptionsShape).passthrough();
+const candidatePlanSchema = z.object({
+  description: z.string().optional(),
+  steps: z.array(z.record(z.string(), z.unknown())).optional(),
+  comment: z.string().optional(),
+  when: z.unknown().optional(),
+}).strict();
 const expectedOutcomeSchema = z.union([
   z.string(),
   z.object({
@@ -97,8 +57,9 @@ class BrowserPool {
   #contextBrowsers = new Map();
   #page;
   #startedAt;
-  #everStarted = false;
-  #navigationError;
+  #everStarted = false;
+  #navigationError;
+  #unrestoredPage = false;
   #flowQueue = Promise.resolve();
   #configurationKey;
   #lastConfiguration = {};
@@ -107,12 +68,13 @@ class BrowserPool {
     this.#settings = settings;
   }
 
-  getNavigationError() {
-    return this.#navigationError;
-  }
-
-  setNavigationError(error) {
-    this.#navigationError = error || undefined;
+  getNavigationError() {
+    return this.#unrestoredPage ? "BROWSER_PAGE_NOT_RESTORED" : this.#navigationError;
+  }
+
+  setNavigationError(error) {
+    this.#navigationError = error || undefined;
+    this.#unrestoredPage = error === "BROWSER_PAGE_NOT_RESTORED";
   }
 
   async runFlow(work) {
@@ -125,9 +87,10 @@ class BrowserPool {
     } finally {
       release();
     }
-  }
-
+  }
+
   async getPage(configuration) {
+    const hadStartedBeforeRequest = this.#everStarted;
     if (configuration === undefined) configuration = this.#lastConfiguration;
     else this.#lastConfiguration = configuration;
     const configurationKey = JSON.stringify(configuration);
@@ -156,7 +119,12 @@ class BrowserPool {
         throw error;
       }
     }
-    return { page: this.#page, context: this.#context, sessionMs: isOpening ? performance.now() - this.#startedAt : 0 };
+    return {
+      page: this.#page,
+      context: this.#context,
+      sessionMs: isOpening ? performance.now() - this.#startedAt : 0,
+      recovered: isOpening && hadStartedBeforeRequest,
+    };
   }
 
   #invalidate(reason) {
@@ -290,17 +258,47 @@ class BrowserPool {
     this.#contextPromise = undefined;
     this.#navigationError = undefined;
     this.#configurationKey = undefined;
+    this.#unrestoredPage = false;
   }
 }
 
-function toolError(error, settings) {
-  let message = error instanceof JevBrowserError ? error.message : error?.message || `Jev browser flow failed (${error?.name || "Error"})`;
-  const credential = settings.env?.[settings.jev.credentialEnv];
-  if (credential) message = message.split(credential).join("[redacted]");
-  message = message.replace(/\bBearer\s+\S+/gi, "Bearer [redacted]")
-    .replace(/([?&](?:token|api[_-]?key|password|secret)=)[^&\s]+/gi, "$1[redacted]");
-  return { isError: true, content: [{ type: "text", text: `[jev-browser ${packageManifest.version}] ${message}` }] };
-}
+function safeErrorMessage(error, settings) {
+  let message = error instanceof JevBrowserError ? error.message : error?.message || `Jev browser flow failed (${error?.name || "Error"})`;
+  const credential = settings.env?.[settings.jev.credentialEnv];
+  if (credential) message = message.split(credential).join("[redacted]");
+  message = message.replace(/\bBearer\s+\S+/gi, "Bearer [redacted]")
+    .replace(/([?&](?:token|api[_-]?key|password|secret)=)[^&\s]+/gi, "$1[redacted]");
+  return message;
+}
+
+function toolError(error, settings) {
+  const message = safeErrorMessage(error, settings);
+  return { isError: true, content: [{ type: "text", text: `[jev-browser ${packageManifest.version}] ${message}` }] };
+}
+
+function isBrowserDisconnectError(error) {
+  return /(?:target page, context or browser has been closed|browser has been closed|browser disconnected|context has been closed|connection closed|connection is closed)/i
+    .test(String(error?.message || error?.name || error || ""));
+}
+
+function isBrowserStartupError(error) {
+  return /(?:could not start the configured .* browser|browser profile is in use by PID \d+)/i
+    .test(String(error?.message || error?.name || error || ""));
+}
+
+function browserEnvironmentError(reason, navigationError, extra = {}) {
+  return {
+    server_version: packageManifest.version,
+    status: "environment_error",
+    navigation_error: navigationError,
+    reason,
+    acceptance_criteria_met: false,
+    expected_outcome_visible: false,
+    steps_executed: 0,
+    steps: [],
+    ...extra,
+  };
+}
 
 export function fitToolResponse(value, maxBytes) {
   const clone = structuredClone(value && typeof value === "object" ? value : { result: value });
@@ -472,37 +470,93 @@ export function createJevBrowserServer({ env = process.env, configPath, fetchImp
     {
       description: "Run a bounded screen flow in an isolated per-server browser profile. Continues the current SPA page by default. Supports media fakes, tabs and contexts, read-only page inspection, conditional plans, HTTP/network/WebSocket assertions, named storage state, guarded mutation confirmation, per-step timeouts and evidence. expected_outcome accepts descriptive text or structured text/request assertions. Use describe_actions for required and optional fields and the exact options contract. Jev chooses among eligible supplied plans; a single plan skips the decision call when fast_path is enabled.",
       inputSchema: {
-        flow: z.string(),
+        flow: z.string().optional(),
         initial_url: z.string().optional(),
         expected_outcome: expectedOutcomeSchema.optional(),
-        candidate_plans: z.record(z.string(), candidatePlanSchema),
+        candidate_plans: z.record(z.string(), candidatePlanSchema).optional(),
         params: z.record(z.string(), z.unknown()).optional(),
         options: browserOptionsSchema.optional(),
       },
-    },
-    async ({ flow, initial_url: initialUrl, expected_outcome: expectedOutcome, candidate_plans: candidatePlans, params, options }) => {
-      try {
+    },
+    async ({ flow, initial_url: initialUrl, expected_outcome: expectedOutcome, candidate_plans: candidatePlans, params, options }) => {
+      try {
+        const contractIssues = collectFlowContractIssues({ flow, candidatePlans });
+        if (contractIssues.length) throw new JevBrowserError(`flow contract validation failed:\n- ${contractIssues.join("\n- ")}`);
         return toolText(await browserPool.runFlow(async () => {
-          const args = {
-          flow,
-          initialUrl,
-          expectedOutcome,
-          candidatePlans,
-          params,
-          options,
-          settings,
-          browserPool,
-          fetchImpl,
-          serverVersion: packageManifest.version,
-          mutationAuthorizationStore,
-          };
-          const first = await executeBrowserFlow(args);
-          if (first.status !== "environment_error" || first.navigation_error !== "BROWSER_DISCONNECTED"
-            || first.mutating_steps?.length || options?.confirmation_token) return first;
-          const recovery = await browserPool.restart();
-          if (!recovery.connected) return { ...first, browser_restart: recovery, retry_count: 0 };
-          const retry = await executeBrowserFlow({ ...args, options: { ...options, reuse_page: false } });
-          return { ...retry, browser_restart: recovery, retry_count: 1 };
+          const args = {
+            flow,
+            initialUrl,
+            expectedOutcome,
+            candidatePlans,
+            params,
+            options,
+            settings,
+            browserPool,
+            fetchImpl,
+            serverVersion: packageManifest.version,
+            mutationAuthorizationStore,
+          };
+          const retryAfterRestart = async (first) => {
+            const recovery = await browserPool.restart();
+            if (recovery.reason) recovery.reason = safeErrorMessage(new Error(recovery.reason), settings);
+            if (!recovery.connected) {
+              if (!initialUrl) browserPool.setNavigationError("BROWSER_PAGE_NOT_RESTORED");
+              return {
+                ...first,
+                ...(initialUrl ? {} : { navigation_error: "BROWSER_PAGE_NOT_RESTORED" }),
+                browser_restart: recovery,
+                retry_count: 0,
+              };
+            }
+            if (!initialUrl) {
+              browserPool.setNavigationError("BROWSER_PAGE_NOT_RESTORED");
+              return {
+                ...first,
+                navigation_error: "BROWSER_PAGE_NOT_RESTORED",
+                reason: "The browser reconnected, but the previous page was not restored. Provide initial_url to start a new navigation.",
+                browser_restart: recovery,
+                retry_count: 0,
+              };
+            }
+            try {
+              const retry = await executeBrowserFlow({ ...args, options: { ...options, reuse_page: false } });
+              return { ...retry, browser_restart: recovery, retry_count: 1 };
+            } catch (error) {
+              if (!isBrowserDisconnectError(error) && !isBrowserStartupError(error)) throw error;
+              return {
+                ...browserEnvironmentError(
+                  `The browser reconnected, but the flow could not restart: ${safeErrorMessage(error, settings)}`,
+                  "BROWSER_RESTART_FAILED",
+                ),
+                browser_restart: recovery,
+                retry_count: 1,
+              };
+            }
+          };
+
+          let first;
+          try {
+            first = await executeBrowserFlow(args);
+          } catch (error) {
+            if (isBrowserStartupError(error)) {
+              const profileInUse = /browser profile is in use by PID \d+/i.test(String(error.message || ""));
+              return browserEnvironmentError(
+                safeErrorMessage(error, settings),
+                profileInUse ? "BROWSER_PROFILE_IN_USE" : "BROWSER_START_FAILED",
+                { retry_count: 0 },
+              );
+            }
+            if (!isBrowserDisconnectError(error)) throw error;
+            const failedBeforeSteps = browserEnvironmentError(
+              "The browser disconnected before the flow could obtain its page.",
+              "BROWSER_DISCONNECTED",
+            );
+            return retryAfterRestart(failedBeforeSteps);
+          }
+          const disconnected = /^(?:BROWSER_DISCONNECTED|CONNECTION_CLOSED)$/.test(String(first.navigation_error || ""));
+          if (first.status !== "environment_error" || !disconnected
+            || first.steps_executed > 0 || first.mutating_steps?.length || options?.confirmation_token) return first;
+          return retryAfterRestart(first);
         }), settings.browser.maxToolResponseBytes);
       } catch (error) {
         return toolError(error, settings);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diegosouzacdv/jev-browser-mcp",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Portable MCP server for bounded Playwright screen flows selected by Jev",
   "license": "MIT",
   "repository": {