explorbot 0.1.27 → 0.1.29

package/src/ai/tester.ts

@@ -4,7 +4,7 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.ts';
-import { setActivity } from '../activity.ts';
+import { clearActivity, setActivity } from '../activity.ts';
 import { ConfigParser } from '../config.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
@@ -13,7 +13,7 @@ import type { StateTransition, WebPageState } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Note, type Test, TestResult, type TestResultType } from '../test-plan.ts';
 import { detectFocusArea, extractFocusedElement } from '../utils/aria.ts';
-import { ErrorPageError } from '../utils/error-page.ts';
+import { ErrorPageError, isErrorPage } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { codeToMarkdown } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -25,7 +25,7 @@ import { Navigator } from './navigator.ts';
 import type { Pilot } from './pilot.ts';
 import { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
-import { actionRule, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, protectionRule, sectionContextRule } from './rules.ts';
+import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from './rules.ts';
 import { TaskAgent } from './task-agent.ts';
 import { createCodeceptJSTools, createSpecialContextTools } from './tools.ts';
 
@@ -43,7 +43,7 @@ const SAMPLE_FILES: Record<string, string> = {
 };
 
 export class Tester extends TaskAgent implements Agent {
-  protected readonly ACTION_TOOLS = ['click', 'pressKey', 'form'];
+  protected readonly ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
   protected readonly SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
   emoji = '🧪';
   private explorer: Explorer;
@@ -66,6 +66,8 @@ export class Tester extends TaskAgent implements Agent {
   private hooksRunner: HooksRunner;
   private seenUiMapUrls = new Set<string>();
   private lastAnalyzedStateHash: string | null = null;
+  private stalledIterations = 0;
+  private readonly MAX_STALLED_ITERATIONS = 3;
 
   constructor(explorer: Explorer, provider: Provider, researcher: Researcher, navigator: Navigator, agentTools?: any) {
     super();
@@ -126,6 +128,7 @@ export class Tester extends TaskAgent implements Agent {
     this.pageActionResult = null;
     this.seenUiMapUrls.clear();
     this.lastAnalyzedStateHash = null;
+    this.stalledIterations = 0;
     this.explorer.getStateManager().clearHistory();
     this.resetFailureCount();
     this.pilot?.reset();
@@ -136,18 +139,13 @@ export class Tester extends TaskAgent implements Agent {
       task.addNote(`Network error: ${r.method} ${r.path} → ${r.status}`, TestResult.FAILED);
     });
 
-    const page = this.explorer.playwrightHelper?.page;
-    const onPageError = (err: Error) => {
-      task.addNote(`Console error: ${err.message}`, TestResult.FAILED);
-    };
-    const onConsoleMessage = (msg: any) => {
-      if (msg.type() !== 'error') return;
-      task.addNote(`Console error: ${msg.text()}`, TestResult.FAILED);
-    };
-    page?.on('pageerror', onPageError);
-    page?.on('console', onConsoleMessage);
-
     const initialState = ActionResult.fromState(state);
+    if (isErrorPage(initialState)) {
+      task.start();
+      await this.explorer.startTest(task);
+      offFailedRequest?.();
+      return await this.abortStartedTestOnErrorPage(task, initialState);
+    }
 
     const conversation = this.provider.startConversation(this.getSystemMessage(), 'tester');
     conversation.markLastMessageCacheable();
@@ -176,20 +174,18 @@ export class Tester extends TaskAgent implements Agent {
           expected: task.expected,
         },
       },
-      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest, page, onPageError, onConsoleMessage })
+      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest })
     );
   }
 
-  private async runTestSession(task: Test, initialState: ActionResult, conversation: Conversation, handlers: { offFailedRequest?: () => void; page: any; onPageError: (err: Error) => void; onConsoleMessage: (msg: any) => void }): Promise<{ success: boolean }> {
-    const { offFailedRequest, page, onPageError, onConsoleMessage } = handlers;
+  private async runTestSession(task: Test, initialState: ActionResult, conversation: Conversation, handlers: TestSessionHandlers): Promise<{ success: boolean }> {
+    const { offFailedRequest } = handlers;
 
     if (this.pilot) {
       try {
         const plan = await this.pilot.planTest(task, initialState);
         if (task.hasFinished) {
           offFailedRequest?.();
-          page?.off('pageerror', onPageError);
-          page?.off('console', onConsoleMessage);
           return { success: task.isSuccessful };
         }
         if (plan) {
@@ -201,22 +197,39 @@ export class Tester extends TaskAgent implements Agent {
         task.addNote(`Planning failed: ${message}`, TestResult.FAILED);
         task.finish(TestResult.FAILED);
         offFailedRequest?.();
-        page?.off('pageerror', onPageError);
-        page?.off('console', onConsoleMessage);
         return { success: false };
       }
     }
 
     debugLog('Starting test execution with tools');
 
-    task.start();
-    await this.explorer.startTest(task);
+    if (!(await this.explorer.startTest(task))) {
+      offFailedRequest?.();
+      await this.cleanupStartedTest(task);
+      return { success: task.isSuccessful };
+    }
 
     debugLog(`Navigating to ${task.startUrl}`);
-    await this.explorer.visit(task.startUrl!);
+    try {
+      await this.explorer.visit(task.startUrl!);
+    } catch (error) {
+      const result = await this.handleLoopError(task, error);
+      if (result === 'stop') {
+        offFailedRequest?.();
+        await this.cleanupStartedTest(task);
+        return { success: task.isSuccessful };
+      }
+    }
 
     const startState = this.explorer.getStateManager().getCurrentState();
-    if (startState) task.addUrlNote(startState);
+    if (startState) {
+      task.addUrlNote(startState);
+      const startActionResult = ActionResult.fromState(startState);
+      if (isErrorPage(startActionResult)) {
+        offFailedRequest?.();
+        return await this.abortStartedTestOnErrorPage(task, startActionResult);
+      }
+    }
     const currentUrl = startState?.url || task.startUrl || '';
     await this.hooksRunner.runBeforeHook('tester', currentUrl);
 
@@ -238,6 +251,12 @@ export class Tester extends TaskAgent implements Agent {
       await loop(
         async ({ stop, pause, iteration, userInput }) => {
           debugLog('iteration', iteration);
+          if (!(await this.explorer.ensurePageAvailable())) {
+            task.addNote('Browser page is unavailable');
+            task.finish(TestResult.FAILED);
+            stop();
+            return;
+          }
           const currentState = this.getCurrentState();
 
           const tools = {
@@ -332,6 +351,11 @@ export class Tester extends TaskAgent implements Agent {
               });
           }
 
+          if (this.shouldStopForStalledExecution(task, currentState, result?.toolExecutions || [])) {
+            stop();
+            return;
+          }
+
           if (assertionPerformed) {
             const message = result?.toolExecutions?.find((execution: any) => execution.toolName === 'verify')?.output?.message || '';
             task.addNote(message, wasSuccessful ? TestResult.PASSED : TestResult.FAILED);
@@ -385,22 +409,16 @@ export class Tester extends TaskAgent implements Agent {
               }
             : undefined,
           catch: async ({ error, stop }) => {
-            tag('error').log(`Test execution error: ${error}`);
-            const message = error instanceof Error ? error.message : String(error);
-            if (!task.hasFinished) {
-              task.addNote(`Execution error: ${message}`);
-            }
-            if (error instanceof Error && error.name === 'AbortError') {
-              stop();
-              return;
-            }
-            conversation.addUserText(`Previous AI call failed: ${message}. Take a different approach on the next step.`);
+            const result = await this.handleLoopError(task, error);
+            if (result === 'stop') stop();
           },
         }
       );
 
       if (task.hasFinished) break;
 
+      if (!(await this.explorer.ensurePageAvailable())) break;
+
       const finalState = this.getCurrentState();
       const wantsContinue = await this.pilot!.finalReview(task, finalState, conversation, this.navigator);
 
@@ -429,14 +447,8 @@ export class Tester extends TaskAgent implements Agent {
 
     offStateChange();
     offFailedRequest?.();
-    page?.off('pageerror', onPageError);
-    page?.off('console', onConsoleMessage);
     await this.finishTest(task);
-    await this.explorer.stopTest(task, {
-      startUrl: task.startUrl,
-      style: task.style,
-      sessionName: task.sessionName,
-    });
+    await this.explorer.stopTest(task, this.buildStopTestMeta(task));
 
     return {
       success: task.isSuccessful,
@@ -452,6 +464,31 @@ export class Tester extends TaskAgent implements Agent {
     return true;
   }
 
+  private shouldStopForStalledExecution(task: Test, previousState: ActionResult, toolExecutions: any[]): boolean {
+    if (task.hasFinished) return false;
+
+    const currentState = this.getCurrentState();
+    const stateChanged = previousState.url !== currentState.url || previousState.hash !== currentState.hash;
+    const actionTools = [...this.ACTION_TOOLS, ...this.SPECIAL_CONTEXT_ACTION_TOOLS];
+    const hasSuccessfulAction = toolExecutions.some((execution) => execution.wasSuccessful && actionTools.includes(execution.toolName));
+    const hasSuccessfulAssertion = toolExecutions.some((execution) => execution.wasSuccessful && this.ASSERTION_TOOLS.includes(execution.toolName));
+
+    if (stateChanged || hasSuccessfulAction || hasSuccessfulAssertion) {
+      this.stalledIterations = 0;
+      return false;
+    }
+
+    const hasNoBrowserProgress = toolExecutions.length === 0 || toolExecutions.every((execution) => !actionTools.includes(execution.toolName) || !execution.wasSuccessful);
+    if (!hasNoBrowserProgress) return false;
+
+    this.stalledIterations++;
+    if (this.stalledIterations < this.MAX_STALLED_ITERATIONS) return false;
+
+    task.addNote('No browser progress after repeated attempts on unchanged page', TestResult.FAILED);
+    task.finish(TestResult.FAILED);
+    return true;
+  }
+
   private async prepareInstructionsForNextStep(task: Test): Promise<string> {
     let outcomeStatus = dedent`
       <task>
@@ -460,6 +497,8 @@ export class Tester extends TaskAgent implements Agent {
   
       <rules>
       Use tools ${this.ACTION_TOOLS.join(', ')} to interact with the page.
+      Use tool names exactly as listed in this prompt. Do not invent combined tool names, aliases, or names with channel markers such as "commentary".
+      Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
       Do not do unsuccesful clicks again.
       Do not run same tool calls with same parameters again.
       </rules>
@@ -689,6 +728,26 @@ export class Tester extends TaskAgent implements Agent {
     }
   }
 
+  private async abortStartedTestOnErrorPage(task: Test, actionResult: ActionResult): Promise<{ success: boolean }> {
+    const error = new ErrorPageError(actionResult.url || task.startUrl || '', actionResult.title, actionResult.httpStatus);
+    tag('warning').log(error.message);
+    task.addNote(error.message, TestResult.FAILED, actionResult.screenshotFile, actionResult.fullUrl || actionResult.url);
+    task.finish(TestResult.FAILED);
+    this.finishTest(task);
+    await this.explorer.stopTest(task, this.buildStopTestMeta(task));
+    clearActivity(true);
+    return { success: false };
+  }
+
+  private buildStopTestMeta(task: Test): Record<string, string> {
+    const meta: Record<string, string> = {
+      startUrl: task.startUrl,
+    };
+    if (task.style) meta.style = task.style;
+    if (task.sessionName) meta.sessionName = task.sessionName;
+    return meta;
+  }
+
   getSystemMessage(): string {
     return dedent`
     <role>
@@ -722,6 +781,7 @@ export class Tester extends TaskAgent implements Agent {
     <rules>
     - Refer to UI Map from <page_ui_map> to understand the page structure and its main elements
     - Use only elements that exist in the provided ARIA tree or HTML, <page_aria> and <page_html>
+    - Use tool input schemas exactly as documented. Do not invent parameter names or add fields not listed by the tool schema.
     - Use click() for buttons, links, and clickable elements ONLY - do NOT include I.fillField() or I.type() commands in click() tool
     - click() commands array is for FALLBACK LOCATORS of the SAME element, NOT for clicking different elements in sequence. If you need to click two different elements, make two separate click() calls.
     - Use form() for text input (I.fillField, I.type), dropdown selection (I.selectOption), file uploads (I.attachFile), and multi-step form interactions
@@ -734,6 +794,7 @@ export class Tester extends TaskAgent implements Agent {
     - NEVER call record(status: "success") if your last verify() or see() call FAILED. A failed check means the outcome is NOT confirmed — use record(status: "fail") instead, or retry with a different approach.
     - Use finish() to complete the test, not record(). record() is for intermediate notes.
     - Call finish(verify) when all goals are achieved — provide an assertion to verify
+    - NEVER call finish() with a negative assertion that says the goal did NOT happen. If the goal cannot be achieved after real attempts, record the blocker and call stop().
     - ONLY call stop() if the scenario itself is completely irrelevant to this page and no expectations can be achieved
     - Use reset() ONLY as a last resort when the current page cannot host the scenario. Never reset after a successful flow just because an assertion or milestone did not match — verify differently or record() the finding instead. Reset is destructive and does not undo server-side side effects.
     - Be precise with locators (CSS or XPath)
@@ -747,6 +808,13 @@ export class Tester extends TaskAgent implements Agent {
     - When you interact with form with inputs, ensure that you click corresponding button to save its data
     - Follow <locator_priority> rules when selecting locators for all tools
     - Before retrying your actions check maybe they already achived expected results. Use see() tool for that
+    - If the current URL is already a create/edit/new form and the scenario is about creating/editing that entity, fill and submit that form. Do not click the list-page "New" button again from inside the form.
+    - If the scenario is about search/filter/sort/tabs/list inspection and the current URL is a create/edit/new form, go back or reset to the stable list page before interacting with list controls.
+    - When selecting related entities from a list, do not choose rows/options/cards marked as "0 items", "0 tests", or otherwise empty if the scenario requires selecting real content.
+    - In selection pickers, counters such as "Selected 0", "Matched tests 0", or disabled Save/Apply mean the selection did not register. Choose a non-empty item or change filters before submitting.
+    - A passed form/click command only means the command executed. If a required field remains empty, submit stays disabled, or the expected text is not visible, treat the action as not completed and correct the missing field/state.
+    - For filter/tab scenarios, success requires BOTH: the requested filter/tab is visibly active/selected AND the list content matches that filter. Do not finish from only one of these signals.
+    - Empty-state text such as "No matched items" only proves a filter when the requested filter/tab is active and the empty state belongs to the filtered list.
     - When filling complex form with lot of actions performed, use see() to look which fields were filled and which are not
     - When verify() fails, use see() to visually confirm the result — visual confirmation is equally valid evidence
     - For visual state verification (active tabs, selected items, counts, colors), prefer see() over DOM-based verify()
@@ -775,6 +843,10 @@ export class Tester extends TaskAgent implements Agent {
 
     ${formRequirementsRule}
 
+    ${capabilityGroundingRule}
+
+    ${dataProtectionRules}
+
     ${this.provider.getSystemPromptForAgent('tester', this.explorer.getStateManager().getCurrentState()?.url) || ''}
     `;
   }
@@ -798,10 +870,13 @@ export class Tester extends TaskAgent implements Agent {
       Try to achieve as many goals as possible.
       If goal is not achievable, log that and skip to next one.
       Do not hallucinate that goal was achieved when it was not.
+      If the scenario action could not be completed, do not finish with a verification of the failure state.
       When creating or editing items via form() or type() you should include ${task.sessionName} in the value (if it is not restricted by the application logic)
       Initial page URL: ${actionResult.url}
 
-      ${protectionRule}
+      ${capabilityGroundingRule}
+
+      ${dataProtectionRules}
 
       ${this.buildDeletionScope(task)}
 
@@ -939,12 +1014,13 @@ export class Tester extends TaskAgent implements Agent {
       }),
       stop: tool({
         description: dedent`
-          Stop the current test because the scenario is fundamentally incompatible with the page.
-          Use this ONLY when the scenario cannot be executed on the current page or application.
-          Do NOT use this for failures — use reset() and retry instead.
+          Stop the current test because it cannot be completed in the current session.
+          Use this when the scenario is incompatible, required UI/data is absent, or repeated varied attempts
+          show that automation cannot complete the workflow.
+          Do NOT use this immediately after the first failed action — retry with a materially different approach first.
         `,
         inputSchema: z.object({
-          reason: z.string().describe('Explanation why the scenario is incompatible'),
+          reason: z.string().describe('Explanation why the scenario cannot be completed'),
         }),
         execute: async ({ reason }) => {
           task.addNote(`Stop requested: ${reason}`);
@@ -979,6 +1055,7 @@ export class Tester extends TaskAgent implements Agent {
           Provide a specific assertion to verify the final state.
           The assertion MUST prove that YOUR ACTIONS changed the page state.
           Do NOT verify something that was already true before you started testing.
+          Do NOT provide an assertion that verifies absence, failure, an empty state, or that the goal did not happen.
 
           Examples of good assertions:
           - "New user 'john@example.com' is visible in the users list"
@@ -1093,4 +1170,54 @@ export class Tester extends TaskAgent implements Agent {
       }),
     };
   }
+
+  private async handleLoopError(task: Test, error: unknown): Promise<'continue' | 'stop'> {
+    const message = error instanceof Error ? error.message : String(error);
+    if (!task.hasFinished) task.addNote(`Execution error: ${message}`);
+
+    const result = await this.explorer.handleExecutionError(error);
+    tag('info').log(`Browser supervisor: ${result.action} - ${result.message}`);
+    task.addNote(result.message);
+
+    if (result.action === 'stop') {
+      task.finish(TestResult.FAILED);
+      return 'stop';
+    }
+
+    if (result.recovered) {
+      this.resetFailureCount();
+      this.previousUrl = null;
+      this.previousStateHash = null;
+      this.stalledIterations = 0;
+    } else if (this.shouldStopAfterStalledLoopError(task)) {
+      return 'stop';
+    }
+
+    this.currentConversation?.addUserText(result.message);
+    return 'continue';
+  }
+
+  private shouldStopAfterStalledLoopError(task: Test): boolean {
+    if (task.hasFinished) return false;
+
+    this.stalledIterations++;
+    if (this.stalledIterations < this.MAX_STALLED_ITERATIONS) return false;
+
+    task.addNote('No browser progress after repeated execution errors', TestResult.FAILED);
+    task.finish(TestResult.FAILED);
+    return true;
+  }
+
+  private async cleanupStartedTest(task: Test): Promise<void> {
+    await this.finishTest(task);
+    await this.explorer.stopTest(task, {
+      startUrl: task.startUrl,
+      style: task.style,
+      sessionName: task.sessionName,
+    });
+  }
+}
+
+interface TestSessionHandlers {
+  offFailedRequest?: () => void;
 }

package/src/ai/tools.ts

@@ -6,6 +6,7 @@ import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
 import { type Task, TestResult } from '../test-plan.js';
 import { extractFocusedElement } from '../utils/aria.ts';
+import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
@@ -17,7 +18,7 @@ import { isInteractive } from './task-agent.ts';
 
 const debugLog = createDebug('explorbot:tools');
 
-export const CODECEPT_TOOLS = ['click', 'pressKey', 'form'] as const;
+export const CODECEPT_TOOLS = ['click', 'hover', 'pressKey', 'form'] as const;
 export const ASSERTION_TOOLS = ['verify'] as const;
 
 export function createCodeceptJSTools(explorer: Explorer, task: Task) {
@@ -159,6 +160,84 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
       },
     }),
 
+    hover: tool({
+      description: dedent`
+        Move the mouse cursor to an element to reveal hover-only controls.
+
+        Use this before clicking row actions, icon buttons, menus, or toolbars that appear only
+        when the user hovers a list item, table row, card, or tree node.
+
+        This tool ONLY accepts I.moveCursorTo(locator) commands. It does not click.
+        After hovering, use context(), see(), or click() the revealed control.
+      `,
+      inputSchema: z.object({
+        commands: z.array(z.string()).describe(dedent`
+          FALLBACK LOCATORS for ONE element to hover.
+          Order by reliability:
+          1. I.moveCursorTo(text, container)
+          2. I.moveCursorTo(ARIA, container)
+          3. I.moveCursorTo(CSS, container)
+          4. I.moveCursorTo(CSS) or I.moveCursorTo(XPath)
+        `),
+        explanation: z.string().describe('Why you are hovering this element'),
+      }),
+      execute: async ({ commands: rawCommands, explanation }) => {
+        const activeNote = task.startNote(explanation);
+
+        if (rawCommands.length === 0) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('hover', 'No commands provided');
+        }
+
+        const invalidCommands = rawCommands.map((cmd) => cmd.trim()).filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.moveCursorTo'));
+
+        if (invalidCommands.length > 0) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('hover', `Invalid commands: ${invalidCommands.join(', ')}. Hover tool only accepts I.moveCursorTo() commands.`, {
+            suggestion: 'Use click() to click elements, or form() for typing/selecting.',
+          });
+        }
+
+        const commands = rawCommands.map((cmd) => {
+          const trimmed = cmd.trim();
+          if (trimmed.startsWith('I.moveCursorTo')) return trimmed;
+          return `I.moveCursorTo(${JSON.stringify(trimmed)})`;
+        });
+
+        const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
+        const action = explorer.createAction();
+        const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
+
+        for (const command of commands) {
+          const success = await action.attempt(command, explanation, true);
+          attempts.push({
+            command,
+            success,
+            ...(action.lastError && { error: action.lastError.toString() }),
+          });
+
+          if (!success) continue;
+
+          const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
+          activeNote.commit(TestResult.PASSED);
+          return successToolResult('hover', { ...toolResult, attempts, code: command }, action);
+        }
+
+        const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, commands[0]);
+        activeNote.commit(TestResult.FAILED);
+        return failedToolResult(
+          'hover',
+          'All hover commands failed',
+          {
+            ...toolResult,
+            attempts,
+            suggestion: 'Use xpathCheck() to locate the row/card/tree node, or visualClick() if the hover target is only visually identifiable.',
+          },
+          action.lastError
+        );
+      },
+    }),
+
     pressKey: tool({
       description: dedent`
         Press a keyboard key or key combination. Use this for special keys like Enter, Escape, Tab, Arrow keys, or key combinations with modifiers.
@@ -287,6 +366,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
             suggestion: 'Verify the key name is correct. For typing text, use form() tool instead.',
           });
         } catch (error) {
+          throwIfFatalBrowserError(error);
           activeNote.commit(TestResult.FAILED);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
           return failedToolResult('pressKey', `PressKey tool failed: ${errorMessage}`);
@@ -405,6 +485,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
             action
           );
         } catch (error) {
+          throwIfFatalBrowserError(error);
           activeNote.commit(TestResult.FAILED);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
           return failedToolResult('form', `Form tool failed: ${errorMessage}`);
@@ -444,8 +525,7 @@ export function createSpecialContextTools(explorer: Explorer, context: 'iframe')
 
           await explorer.switchToMainFrame();
 
-          const action = explorer.createAction();
-          const nextState = await action.capturePageState();
+          const nextState = await explorer.capturePageState();
           const toolResult = await nextState.toToolResult(previousState, 'I.switchTo()');
 
           return successToolResult('exitIframe', {
@@ -454,6 +534,7 @@ export function createSpecialContextTools(explorer: Explorer, context: 'iframe')
             code: 'I.switchTo()',
           });
         } catch (error) {
+          throwIfFatalBrowserError(error);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
           return failedToolResult('exitIframe', `Failed to exit iframe: ${errorMessage}`);
         }
@@ -485,6 +566,7 @@ export function createAgentTools({
         Check the page contents based on current page state and screenshot.
         This tool will trigger visual research to check the page contents on request.
         Use it to verify the actions were performed correctly and the page is in the expected state.
+        Input schema has exactly one field: request. Do not pass text, reason, assertion, or other fields.
 
         <example>
         request: "Check current state of the Login form"
@@ -500,8 +582,7 @@ export function createAgentTools({
         }
 
         try {
-          const action = explorer.createAction();
-          const actionResult = await action.caputrePageWithScreenshot();
+          const actionResult = await explorer.capturePageWithScreenshot();
 
           if (!actionResult.screenshot) {
             return failedToolResult('see', 'Failed to capture screenshot for analysis');
@@ -519,6 +600,7 @@ export function createAgentTools({
             suggestion: 'Visual confirmation is valid evidence for test results. Use record() to note the visual findings.',
           });
         } catch (error) {
+          throwIfFatalBrowserError(error);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
           visionDisabled = true;
           tag('warning').log('⚠️ Vision model is not available. Visual checks are disabled for this session.');
@@ -600,8 +682,7 @@ export function createAgentTools({
             });
           }
 
-          const action = explorer.createAction();
-          const actionResult = await action.capturePageState();
+          const actionResult = await explorer.capturePageState();
           const result = await navigator.verifyState(assertion, actionResult);
 
           if (result.verified) {
@@ -619,6 +700,7 @@ export function createAgentTools({
             suggestion: 'The assertion could not be verified. Check if the condition is actually present on the page or try a different assertion.',
           });
         } catch (error) {
+          throwIfFatalBrowserError(error);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
           return failedToolResult('verify', `Verify tool failed: ${errorMessage}`, {
             error: errorMessage,
@@ -674,6 +756,7 @@ export function createAgentTools({
             `,
           });
         } catch (error) {
+          throwIfFatalBrowserError(error);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
           return failedToolResult('research', `Research tool failed: ${errorMessage}`, {
             error: errorMessage,
@@ -718,6 +801,7 @@ export function createAgentTools({
             suggestion: 'The action could not be completed. Try a different instruction or use more specific element descriptions.',
           });
         } catch (error) {
+          throwIfFatalBrowserError(error);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
           return failedToolResult('interact', `Interact tool failed: ${errorMessage}`, {
             error: errorMessage,
@@ -756,7 +840,7 @@ export function createAgentTools({
 
           const previousState = ActionResult.fromState(currentState);
           const action = explorer.createAction();
-          const actionResult = await action.caputrePageWithScreenshot();
+          const actionResult = await explorer.capturePageWithScreenshot();
 
           if (!actionResult.screenshot) {
             return failedToolResult('visualClick', 'Failed to capture screenshot for visual analysis');
@@ -797,6 +881,7 @@ export function createAgentTools({
             analysis: locationResult,
           });
         } catch (error) {
+          throwIfFatalBrowserError(error);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
           visionDisabled = true;
           tag('warning').log('⚠️ Vision model is not available. Visual clicks are disabled for this session.');
@@ -1018,6 +1103,10 @@ function cap(text: string | undefined | null, max: number): string {
   return `${text.slice(0, max)}\n[...truncated; ${text.length - max} chars omitted...]`;
 }
 
+function throwIfFatalBrowserError(error: unknown): void {
+  if (isFatalBrowserError(error)) throw error;
+}
+
 function transformContainsCommand(command: string): string {
   if (!command.includes(':contains(')) return command;
 

package/src/commands/explore-command.ts

@@ -5,7 +5,7 @@ import { normalizeUrl } from '../state-manager.js';
 import { Stats } from '../stats.js';
 import { type Plan, type Test, TestResult } from '../test-plan.js';
 import { getCliName } from '../utils/cli-name.ts';
-import { ErrorPageError } from '../utils/error-page.ts';
+import { ErrorPageError, getStateErrorPageError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
 import { safeFilename } from '../utils/strings.ts';
@@ -56,6 +56,11 @@ export class ExploreCommand extends BaseCommand {
     Stats.mode ??= 'explore';
     Stats.focus ??= feature;
     const mainUrl = this.getCurrentPageUrl();
+    const error = getStateErrorPageError(this.explorBot.getExplorer().getStateManager().getCurrentState());
+    if (error) {
+      tag('warning').log(error.message);
+      return;
+    }
 
     if (cfg.enabled) {
       await this.runReuseMode(mainUrl, feature, cfg);