explorbot 0.1.27 → 0.1.28

package/dist/src/explorer.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 // @ts-ignore
 import * as codeceptjs from 'codeceptjs';
+import dedent from 'dedent';
 import stepsListener from 'codeceptjs/lib/listener/steps';
 import storeListener from 'codeceptjs/lib/listener/store';
 import { createTest } from 'codeceptjs/lib/mocha/test';
@@ -15,11 +16,12 @@ import { KnowledgeTracker } from './knowledge-tracker.js';
 import { PlaywrightRecorder } from "./playwright-recorder.js";
 import { Reporter } from "./reporter.js";
 import { StateManager } from './state-manager.js';
+import { TestResult } from "./test-plan.js";
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from "./utils/html.js";
 import { createDebug, log, tag } from './utils/logger.js';
 import { WebElement } from "./utils/web-element.js";
+import { BrowserRecoveryError, isFatalBrowserError } from "./utils/browser-errors.js";
 const debugLog = createDebug('explorbot:explorer');
-const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
 const RECOVERABLE_NAVIGATION_ERRORS = /net::ERR_ABORTED|page\.screenshot.*Timeout|waiting for fonts to load/i;
 class Explorer {
     aiProvider;
@@ -38,6 +40,10 @@ class Explorer {
     xhrCapture = null;
     requestStore = null;
     playwrightRecorder = new PlaywrightRecorder();
+    observedTestPages = new Set();
+    testPageErrorHandler = null;
+    testConsoleHandler = null;
+    testDialogHandler = null;
     constructor(config, aiProvider, options) {
         this.config = config;
         this.aiProvider = aiProvider;
@@ -154,10 +160,12 @@ class Explorer {
             return {};
         }
     }
-    setupXhrCapture() {
+    setupXhrCapture(reuseRequestStore = false) {
         const configParser = ConfigParser.getInstance();
         const outputDir = configParser.getOutputDir();
-        this.requestStore = new RequestStore(outputDir);
+        if (!reuseRequestStore || !this.requestStore) {
+            this.requestStore = new RequestStore(outputDir);
+        }
         const baseUrl = this.config.playwright.url;
         this.xhrCapture = new XhrCapture(this.requestStore, baseUrl);
         this.xhrCapture.attach(this.playwrightHelper.page);
@@ -189,21 +197,7 @@ class Explorer {
         }
         await this.connectOrLaunchBrowser();
         const hasSession = this.options?.session && existsSync(this.options.session);
-        const helperOptions = this.playwrightHelper.options || {};
-        // CodeceptJS skips _createContextPage when sessions/storageState are involved, so we
-        // build contextOptions ourselves. Most keys share a name with Playwright's
-        // BrowserContextOptions and are copied as-is; `emulate` must be flattened, `basicAuth`
-        // renamed to `httpCredentials`, and `storageState` comes from the --session flag.
-        const contextOptions = {
-            ...helperOptions,
-        };
-        if (helperOptions.emulate)
-            Object.assign(contextOptions, helperOptions.emulate);
-        if (helperOptions.basicAuth)
-            contextOptions.httpCredentials = helperOptions.basicAuth;
-        if (hasSession)
-            contextOptions.storageState = this.options.session;
-        await this.playwrightHelper._createContextPage(contextOptions);
+        await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
         await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
         this.setupXhrCapture();
         if (hasSession) {
@@ -232,13 +226,70 @@ class Explorer {
         }
         await this.playwrightHelper._startBrowser();
     }
+    createBrowserContextOptions() {
+        const helperOptions = this.playwrightHelper.options || {};
+        const contextOptions = {
+            ...helperOptions,
+        };
+        if (helperOptions.emulate)
+            Object.assign(contextOptions, helperOptions.emulate);
+        if (helperOptions.basicAuth)
+            contextOptions.httpCredentials = helperOptions.basicAuth;
+        if (this.options?.session && existsSync(this.options.session))
+            contextOptions.storageState = this.options.session;
+        return contextOptions;
+    }
     createAction() {
         return new Action(this.actor, this.stateManager, this.playwrightRecorder);
     }
+    async runWithBrowserRecovery(label, operation) {
+        if (!(await this.ensurePageAvailable())) {
+            throw new Error(`Browser page is unavailable before ${label}`);
+        }
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (!this.isFatalBrowserError(error))
+                throw error;
+            tag('warning').log(`${label}: browser page is unavailable, recovering...`);
+            let recovered = await this.recoverFromBrowserError();
+            if (!recovered)
+                recovered = await this.restartBrowser();
+            if (!recovered)
+                throw new BrowserRecoveryError(label, error, false);
+            if (!(await this.waitForUsablePageDom()))
+                throw new BrowserRecoveryError(label, error, true);
+            try {
+                return await operation();
+            }
+            catch (retryError) {
+                if (this.isFatalBrowserError(retryError)) {
+                    throw new BrowserRecoveryError(label, retryError, true);
+                }
+                throw retryError;
+            }
+        }
+    }
+    async capturePageState(opts = {}) {
+        return this.runWithBrowserRecovery('capturePageState', () => this.createAction().capturePageState(opts));
+    }
+    async capturePageWithScreenshot() {
+        return this.capturePageState({ includeScreenshot: true });
+    }
+    async executeAction(code) {
+        return this.runWithBrowserRecovery('executeAction', () => this.createAction().execute(code));
+    }
+    async attemptAction(code, originalMessage, experience = true) {
+        return this.runWithBrowserRecovery('attemptAction', () => this.createAction().attempt(code, originalMessage, experience));
+    }
     getPlaywrightRecorder() {
         return this.playwrightRecorder;
     }
     async visit(url) {
+        return this.runWithBrowserRecovery('visit', () => this.visitOnce(url));
+    }
+    async visitOnce(url) {
         await this.closeOtherTabs();
         const serializedUrl = JSON.stringify(url);
         const currentState = this.stateManager.getCurrentState();
@@ -275,11 +326,13 @@ class Explorer {
         return action;
     }
     async annotateElements() {
-        const { elements } = await annotatePageElements(this.playwrightHelper.page);
-        return elements;
+        return this.runWithBrowserRecovery('annotateElements', async () => {
+            const { elements } = await annotatePageElements(this.playwrightHelper.page);
+            return elements;
+        });
     }
     async visuallyAnnotateElements(opts) {
-        return visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []);
+        return this.runWithBrowserRecovery('visuallyAnnotateElements', () => visuallyAnnotateContainers(this.playwrightHelper.page, opts?.containers || []));
     }
     async getEidxInContainer(containerCss) {
         const page = this.playwrightHelper.page;
@@ -321,33 +374,120 @@ class Explorer {
         await this.closeOtherTabs();
         await this.playwrightHelper.page.reload();
     }
+    resolveBrowserUrl(url) {
+        if (!url)
+            return null;
+        try {
+            return new URL(url).toString();
+        }
+        catch { }
+        const baseUrl = this.config.playwright?.url || this.config.web?.url;
+        if (!baseUrl)
+            return null;
+        try {
+            return new URL(url, baseUrl).toString();
+        }
+        catch {
+            return null;
+        }
+    }
     isFatalBrowserError(error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return FATAL_BROWSER_ERRORS.test(msg);
+        return isFatalBrowserError(error);
     }
     async recoverFromBrowserError() {
         try {
-            const url = this.stateManager.getCurrentState()?.url;
+            if (!this.playwrightHelper?.page || this.playwrightHelper.page.isClosed?.()) {
+                const context = this.playwrightHelper?.browserContext;
+                if (!context)
+                    return await this.restartBrowser();
+                const page = await context.newPage();
+                await page.bringToFront();
+                await this.playwrightHelper._setPage(page);
+                this.bindFrameNavigated(page);
+                if (this.xhrCapture) {
+                    this.xhrCapture.attach(this.playwrightHelper.page);
+                }
+            }
+            const url = this.resolveBrowserUrl(this.stateManager.getCurrentState()?.url);
             if (url) {
                 tag('warning').log(`Browser error detected, recovering by navigating to ${url}`);
                 await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
-                return true;
+                return this.waitForUsablePageDom();
             }
             tag('warning').log('Browser error detected, reloading page');
             await this.playwrightHelper.page.reload({ waitUntil: 'domcontentloaded', timeout: 10000 });
-            return true;
+            return this.waitForUsablePageDom();
         }
         catch (err) {
             tag('error').log(`Browser recovery failed: ${err instanceof Error ? err.message : err}`);
             return false;
         }
     }
+    async restartBrowser() {
+        if (!this.playwrightHelper)
+            return false;
+        const url = this.resolveBrowserUrl(this.stateManager.getCurrentState()?.url);
+        try {
+            if (this.xhrCapture && this.playwrightHelper.page) {
+                this.xhrCapture.detach(this.playwrightHelper.page);
+            }
+            await this.playwrightRecorder.stop();
+            if (this.playwrightHelper.browserContext) {
+                await this.playwrightHelper.browserContext.close().catch((err) => {
+                    debugLog('Failed to close browser context before restart:', err);
+                });
+                this.playwrightHelper.browserContext = null;
+            }
+            if (!this.isSharedBrowser) {
+                await this.playwrightHelper._stopBrowser().catch((err) => {
+                    debugLog('Failed to stop browser before restart:', err);
+                });
+            }
+            await this.connectOrLaunchBrowser();
+            await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+            await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
+            this.setupXhrCapture(true);
+            this.listenToStateChanged();
+            if (url) {
+                await this.playwrightHelper.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 10000 });
+                if (!(await this.waitForUsablePageDom()))
+                    return false;
+            }
+            tag('success').log('Browser restarted');
+            return true;
+        }
+        catch (err) {
+            tag('error').log(`Browser restart failed: ${err instanceof Error ? err.message : err}`);
+            return false;
+        }
+    }
     async switchToMainFrame() {
         if (this.playwrightHelper.frame) {
             debugLog('Switching to main frame');
             await this.playwrightHelper.switchTo();
         }
     }
+    async waitForUsablePageDom() {
+        const page = this.playwrightHelper?.page;
+        if (!page)
+            return false;
+        await page.waitForLoadState?.('domcontentloaded', { timeout: 5000 }).catch(() => { });
+        if (page.waitForFunction) {
+            const hasUsableDom = await page
+                .waitForFunction(() => {
+                const body = document.body;
+                if (!body)
+                    return false;
+                return body.children.length > 0 || body.textContent?.trim().length > 0;
+            }, undefined, { timeout: 5000 })
+                .then(() => true)
+                .catch(() => false);
+            if (!hasUsableDom)
+                return false;
+        }
+        await page.waitForLoadState?.('networkidle', { timeout: 3000 }).catch(() => { });
+        return true;
+    }
     async isInsideIframe() {
         if (this.playwrightHelper.frame)
             return true;
@@ -465,9 +605,12 @@ class Explorer {
     }
     async startTest(test) {
         this._activeTest = test;
+        test.start();
         await this.reporter.reportTestStart(test);
         await this.closeOtherTabs();
         this.otherTabs = [];
+        if (!(await this.ensurePageAvailable()))
+            return false;
         const codeceptjsTest = toCodeceptjsTest(test);
         const stepHandler = (step, status, error, log) => {
             if (!step.toCode)
@@ -482,12 +625,7 @@ class Explorer {
             const lastScreenshot = ActionResult.fromState(this.stateManager.getCurrentState()).screenshotFile;
             test.setActiveNoteScreenshot(lastScreenshot);
         };
-        const dialogHandler = (dialog) => {
-            const dialogType = dialog.type();
-            const dialogMessage = dialog.message();
-            test.addNote(`Native dialog ${dialogType} appeared: ${dialogMessage}. Accepted automatically`);
-        };
-        this.playwrightHelper?.page?.on('dialog', dialogHandler);
+        this.watchActiveTestPage();
         codeceptjs.event.dispatcher.emit('test.before', codeceptjsTest);
         codeceptjs.event.dispatcher.emit('test.start', codeceptjsTest);
         codeceptjs.event.dispatcher.on('step.passed', (step) => stepHandler(step, 'passed'));
@@ -497,10 +635,96 @@ class Explorer {
         codeceptjs.event.dispatcher.on('test.after', () => {
             codeceptjs.event.dispatcher.off('step.passed', stepHandler);
             codeceptjs.event.dispatcher.off('step.failed', stepHandler);
-            this.playwrightHelper?.page?.off('dialog', dialogHandler);
+            this.unwatchActiveTestPages();
         });
+        return true;
+    }
+    async ensurePageAvailable() {
+        const page = this.playwrightHelper?.page;
+        if (page && !page.isClosed?.()) {
+            this.watchActiveTestPage(page);
+            return true;
+        }
+        const recovered = await this.recoverFromBrowserError();
+        if (!recovered)
+            return false;
+        this.watchActiveTestPage();
+        return true;
+    }
+    async ensureActiveTestPageAvailable() {
+        return this.ensurePageAvailable();
+    }
+    async handleExecutionError(error) {
+        const message = error instanceof Error ? error.message : String(error);
+        tag('error').log(`Browser execution error: ${message}`);
+        if (error instanceof Error && error.name === 'AbortError') {
+            return {
+                action: 'stop',
+                message,
+            };
+        }
+        if (error instanceof BrowserRecoveryError) {
+            return {
+                action: 'stop',
+                recovered: error.recovered,
+                message: error.message,
+            };
+        }
+        if (!this.isFatalBrowserError(error)) {
+            return {
+                action: 'continue',
+                message: `Previous execution error: ${message}. Investigate the current state and choose a different approach.`,
+            };
+        }
+        let recovered = await this.recoverFromBrowserError();
+        if (!recovered)
+            recovered = await this.restartBrowser();
+        if (!recovered) {
+            return {
+                action: 'stop',
+                recovered: false,
+                message: `Browser could not be recovered after fatal error: ${message}`,
+            };
+        }
+        this.watchActiveTestPage();
+        return {
+            action: 'continue',
+            recovered: true,
+            message: dedent `
+        Browser was recovered after a fatal page error.
+        Continue from the restored page.
+        The interrupted browser action is not product evidence.
+        Inspect the restored page and retry the current step when it is still required.
+      `,
+        };
+    }
+    watchActiveTestPage(page = this.playwrightHelper?.page) {
+        if (!this._activeTest)
+            return;
+        if (!page)
+            return;
+        if (this.observedTestPages.has(page))
+            return;
+        this.testPageErrorHandler ||= (err) => {
+            this._activeTest?.addNote(`Console error: ${err.message}`, TestResult.FAILED);
+        };
+        this.testConsoleHandler ||= (msg) => {
+            if (msg.type() !== 'error')
+                return;
+            this._activeTest?.addNote(`Console error: ${msg.text()}`, TestResult.FAILED);
+        };
+        this.testDialogHandler ||= (dialog) => {
+            const dialogType = dialog.type();
+            const dialogMessage = dialog.message();
+            this._activeTest?.addNote(`Native dialog ${dialogType} appeared: ${dialogMessage}. Accepted automatically`);
+        };
+        page.on('pageerror', this.testPageErrorHandler);
+        page.on('console', this.testConsoleHandler);
+        page.on('dialog', this.testDialogHandler);
+        this.observedTestPages.add(page);
     }
     async stopTest(test, meta) {
+        this.unwatchActiveTestPages();
         this._activeTest = null;
         const lastScreenshot = this.stateManager.getCurrentState()?.screenshotFile;
         if (lastScreenshot) {
@@ -524,6 +748,17 @@ class Explorer {
         codeceptjs.event.dispatcher.emit('test.finish', codeceptjsTest);
         codeceptjs.event.dispatcher.emit('test.after', codeceptjsTest);
     }
+    unwatchActiveTestPages() {
+        for (const page of this.observedTestPages) {
+            if (this.testPageErrorHandler)
+                page.off('pageerror', this.testPageErrorHandler);
+            if (this.testConsoleHandler)
+                page.off('console', this.testConsoleHandler);
+            if (this.testDialogHandler)
+                page.off('dialog', this.testDialogHandler);
+        }
+        this.observedTestPages.clear();
+    }
     async hasPlaywrightLocator(locatorFn, opts = {}) {
         try {
             const pwLocator = locatorFn(this.playwrightHelper.page);
@@ -584,7 +819,7 @@ class Explorer {
         const newPage = await context.newPage();
         await oldPage.close();
         await newPage.bringToFront();
-        this.playwrightHelper.page = newPage;
+        await this.playwrightHelper._setPage(newPage);
         this.otherTabs = [];
         this.bindFrameNavigated(newPage);
         if (this.xhrCapture) {
@@ -609,7 +844,7 @@ class Explorer {
             debugLog(`Closed extra tab: ${await page.url()}`);
         }
         await firstPage.bringToFront();
-        this.playwrightHelper.page = firstPage;
+        await this.playwrightHelper._setPage(firstPage);
         debugLog(`Cleaned up tabs, now focused on: ${await firstPage.url()}`);
     }
 }

package/dist/src/utils/browser-errors.js

@@ -0,0 +1,23 @@
+// Playwright and CodeceptJS surface browser/page disposal as plain Error objects,
+// not typed exceptions. Keep those external message markers in one adapter so
+// recovery decisions are not duplicated across agents/actions.
+const FATAL_BROWSER_ERROR_MARKERS = ['Frame was detached', 'Target closed', 'Target page, context or browser has been closed', 'Execution context was destroyed', 'Protocol error', 'Session closed'];
+export class BrowserRecoveryError extends Error {
+    originalError;
+    recovered;
+    constructor(label, originalError, recovered) {
+        super(`${label} failed ${recovered ? 'after browser recovery' : 'because browser could not be recovered'}: ${browserErrorMessage(originalError)}`);
+        this.originalError = originalError;
+        this.recovered = recovered;
+        this.name = 'BrowserRecoveryError';
+    }
+}
+export function isFatalBrowserError(error) {
+    if (error instanceof BrowserRecoveryError)
+        return true;
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return FATAL_BROWSER_ERROR_MARKERS.some((marker) => message.includes(marker.toLowerCase()));
+}
+export function browserErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/utils/error-page.js

@@ -1,8 +1,11 @@
+import { ActionResult } from '../action-result.js';
 import { isBodyEmpty } from './html.js';
 const HTTP_ERRORS = ['400 Bad Request', '401 Unauthorized', '403 Forbidden', '404 Not Found', '405 Method Not Allowed', '408 Request Timeout', '500 Internal Server Error', '502 Bad Gateway', '503 Service Unavailable', '504 Gateway Timeout'];
 const SMALL_PAGE_THRESHOLD = 500;
 const LOADING_WORD = /\bloading\b/i;
 export function detectPageCondition(actionResult) {
+    if (actionResult.httpStatus && actionResult.httpStatus >= 400)
+        return 'error';
     const headingFields = [actionResult.title, actionResult.h1, actionResult.h2].filter(Boolean);
     for (const field of headingFields) {
         for (const error of HTTP_ERRORS) {
@@ -29,13 +32,25 @@ export function detectPageCondition(actionResult) {
 export function isErrorPage(actionResult) {
     return detectPageCondition(actionResult) === 'error';
 }
+export function getStateErrorPageError(state) {
+    if (!state)
+        return null;
+    const actionResult = ActionResult.fromState(state);
+    if (!isErrorPage(actionResult))
+        return null;
+    return new ErrorPageError(actionResult.url, actionResult.title, actionResult.httpStatus);
+}
 export class ErrorPageError extends Error {
     url;
     title;
-    constructor(url, title) {
-        super(`Error page detected at ${url}${title ? ` (${title})` : ''}`);
+    httpStatus;
+    constructor(url, title, httpStatus) {
+        const status = httpStatus ? `HTTP ${httpStatus}` : '';
+        const details = [status, title].filter(Boolean).join(', ');
+        super(`Error page detected at ${url}${details ? ` (${details})` : ''}`);
         this.url = url;
         this.title = title;
+        this.httpStatus = httpStatus;
         this.name = 'ErrorPageError';
     }
 }

package/dist/src/utils/logger.js

@@ -72,7 +72,7 @@ class ConsoleDestination {
         if (entry.type === 'step' && !this.verboseMode && this.recentSteps.shouldSuppress(entry.content))
             return;
         let content = entry.content;
-        if (entry.type === 'multiline') {
+        if (entry.type === 'multiline' || entry.type === 'details') {
             const cleaned = stripAnsi(dedent(entry.content));
             const parsed = parseMarkdownToTerminal(cleaned);
             content = parsed;
@@ -280,7 +280,7 @@ class CaptainDestination {
     }
     stopCapture() {
         this.capturing = false;
-        const logs = this.entries.filter((e) => e.type !== 'debug' && e.type !== 'html' && e.type !== 'multiline' && e.type !== 'operation').map((e) => `[${e.type}] ${e.content}`);
+        const logs = this.entries.filter((e) => e.type !== 'debug' && e.type !== 'html' && e.type !== 'multiline' && e.type !== 'details' && e.type !== 'operation').map((e) => `[${e.type}] ${e.content}`);
         this.entries = [];
         return logs;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/src/action-result.ts

@@ -52,6 +52,7 @@ export interface ToolResultMetadata {
 export class ActionResult implements ActionResultData {
   public id?: number;
   public title = '';
+  public httpStatus: number | undefined = undefined;
   public error: string | null = null;
   public timestamp: Date = new Date();
   public h1: string | undefined = undefined;
@@ -82,6 +83,7 @@ export class ActionResult implements ActionResultData {
     this.url = data.url ?? '';
     this.fullUrl = data.fullUrl;
     this.title = data.title ?? '';
+    this.httpStatus = data.httpStatus;
     this.error = data.error ?? null;
     this.browserLogs = data.browserLogs ?? [];
     this.iframeSnapshots = data.iframeSnapshots ?? [];