explorbot 0.1.27 → 0.1.28

package/dist/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/dist/src/action-result.js

@@ -10,6 +10,7 @@ const debugLog = createDebug('explorbot:state');
 export class ActionResult {
     id;
     title = '';
+    httpStatus = undefined;
     error = null;
     timestamp = new Date();
     h1 = undefined;
@@ -39,6 +40,7 @@ export class ActionResult {
         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 ?? [];

package/dist/src/action.js

@@ -13,8 +13,8 @@ import { Observability } from "./observability.js";
 import { htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
 import { safeFilename } from "./utils/strings.js";
+import { isFatalBrowserError } from "./utils/browser-errors.js";
 const debugLog = createDebug('explorbot:action');
-const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
 class Action {
     actor;
     stateManager;
@@ -28,6 +28,7 @@ class Action {
     playwrightGroupId = null;
     assertionSteps = [];
     recorder;
+    mainDocumentStatus = undefined;
     constructor(actor, stateManager, recorder) {
         this.actor = actor;
         this.stateManager = stateManager;
@@ -63,20 +64,25 @@ class Action {
             const page = this.playwrightHelper.page;
             const frame = this.playwrightHelper.frame;
             await page?.waitForLoadState('domcontentloaded', { timeout: 10000 })?.catch(() => { });
-            const grabAll = () => Promise.all([this.actor.grabSource(), this.actor.grabTitle(), this.captureBrowserLogs()]);
+            await waitForUsablePageDom(page);
+            const grabAll = () => Promise.all([captureHtml(page, frame, this.actor), captureTitle(page, this.actor), this.captureBrowserLogs()]);
             const [html, title, browserLogs] = await grabAll().catch(async (err) => {
                 const msg = err instanceof Error ? err.message : String(err);
                 if (!/navigating and changing the content/i.test(msg))
                     throw err;
                 await page?.waitForLoadState('domcontentloaded', { timeout: 10000 })?.catch(() => { });
+                await waitForUsablePageDom(page);
                 return grabAll();
             });
             const url = page?.url() || (await this.actor.grabCurrentUrl?.());
             let screenshotFile = undefined;
+            const statesDir = outputPath('states');
+            fs.mkdirSync(statesDir, { recursive: true });
             if (includeScreenshot) {
                 const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
-                screenshotFile = await this.actor
-                    .saveScreenshot(filename)
+                const screenshotPath = join(statesDir, filename);
+                screenshotFile = await page
+                    ?.screenshot({ path: screenshotPath, fullPage: true })
                     .then(() => filename)
                     .catch((err) => {
                     debugLog('Screenshot failed, continuing without it:', err);
@@ -84,8 +90,6 @@ class Action {
                 });
             }
             // Save HTML to file
-            const statesDir = outputPath('states');
-            fs.mkdirSync(statesDir, { recursive: true });
             const htmlFile = safeFilename(`${stateHash}_${timestamp}`, '.html');
             const htmlPath = join(statesDir, htmlFile);
             fs.writeFileSync(htmlPath, html, 'utf8');
@@ -121,6 +125,7 @@ class Action {
             const result = new ActionResult({
                 html,
                 title,
+                httpStatus: await this.captureMainDocumentStatus(),
                 url,
                 browserLogs,
                 htmlFile,
@@ -136,13 +141,57 @@ class Action {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            if (FATAL_BROWSER_ERRORS.test(msg))
+            if (isFatalBrowserError(err))
                 throw err;
             debugLog('capturePageState failed with non-fatal error:', msg);
             const url = this.playwrightHelper.page?.url?.() || '';
             return new ActionResult({ url, error: msg });
         }
     }
+    async captureMainDocumentStatus() {
+        if (this.mainDocumentStatus)
+            return this.mainDocumentStatus;
+        try {
+            const page = this.playwrightHelper.page;
+            const status = await page.evaluate(() => {
+                const navigation = performance.getEntriesByType('navigation').at(-1);
+                if (!navigation)
+                    return undefined;
+                if (new URL(navigation.name).href !== window.location.href)
+                    return undefined;
+                return navigation.responseStatus;
+            });
+            if (typeof status !== 'number')
+                return undefined;
+            if (status <= 0)
+                return undefined;
+            return status;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    captureMainDocumentResponse() {
+        const page = this.playwrightHelper.page;
+        if (!page?.on || !page?.off)
+            return () => { };
+        this.mainDocumentStatus = undefined;
+        const handler = (response) => {
+            const request = response.request();
+            if (request.resourceType() !== 'document')
+                return;
+            if (response.frame() !== page.mainFrame())
+                return;
+            const status = response.status();
+            if (typeof status !== 'number')
+                return;
+            if (status <= 0)
+                return;
+            this.mainDocumentStatus = status;
+        };
+        page.on('response', handler);
+        return () => page.off('response', handler);
+    }
     /**
      * Capture HTML snapshots of all iframes on the page
      */
@@ -200,6 +249,7 @@ class Action {
         const stepListener = attachStepLogger(executedSteps, assertionSteps);
         const groupId = this.recorder ? await this.recorder.beginAction(codeString) : null;
         this.playwrightGroupId = groupId;
+        const detachMainDocumentResponse = this.captureMainDocumentResponse();
         const activeSpan = Observability.getSpan();
         const tracer = trace.getTracer('ai');
         const stepSpan = activeSpan ? tracer.startSpan('codeceptjs.step', undefined, trace.setSpan(context.active(), activeSpan)) : null;
@@ -242,6 +292,7 @@ class Action {
             throw err;
         }
         finally {
+            detachMainDocumentResponse();
             if (groupId)
                 await this.recorder.endAction();
             detachStepLogger(stepListener);
@@ -330,6 +381,8 @@ class Action {
         }
         catch (error) {
             this.lastError = error;
+            if (isFatalBrowserError(error))
+                throw error;
             debugLog(`Attempt failed: ${codeBlock}: ${errorToString(error) || this.lastError?.toString()}`);
             return false;
         }
@@ -354,6 +407,34 @@ function errorToString(error) {
     }
     return error.message || error.toString();
 }
+async function waitForUsablePageDom(page) {
+    if (!page?.waitForFunction)
+        return;
+    await page
+        .waitForFunction(() => {
+        const body = document.body;
+        if (!body)
+            return false;
+        return body.children.length > 0 || body.textContent?.trim().length > 0;
+    }, undefined, { timeout: 5000 })
+        .catch(() => { });
+}
+async function captureHtml(page, frame, actor) {
+    if (frame?.content)
+        return frame.content();
+    if (page?.content)
+        return page.content();
+    if (actor?.grabSource)
+        return actor.grabSource();
+    throw new Error('Playwright page is unavailable for HTML capture');
+}
+async function captureTitle(page, actor) {
+    if (page?.title)
+        return page.title();
+    if (actor?.grabTitle)
+        return actor.grabTitle();
+    return '';
+}
 function sanitizeCodeBlock(code) {
     return code
         .split('\n')

package/dist/src/ai/captain/file-tools.js

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+export const CAPTAIN_ARTIFACT_DIRS = ['reports', 'plans', 'tests', 'states'];
+export const CAPTAIN_ALLOWED_READ_DIRS = ['output', 'knowledge', 'experience'];
+export const CAPTAIN_ARTIFACT_SCAN_LIMIT = 200;
+export const CAPTAIN_ARTIFACT_LIST_LIMIT = 20;
+export const CAPTAIN_READ_FILE_DEFAULT_LIMIT = 12000;
+export const CAPTAIN_READ_FILE_MAX_LIMIT = 50000;
+export const CAPTAIN_READ_FILE_MIN_LIMIT = 1000;
+export function listRecentArtifacts(outputDir) {
+    const artifacts = [];
+    for (const dir of CAPTAIN_ARTIFACT_DIRS) {
+        if (artifacts.length >= CAPTAIN_ARTIFACT_SCAN_LIMIT)
+            break;
+        const targetDir = join(outputDir, dir);
+        if (!existsSync(targetDir))
+            continue;
+        collectArtifacts(outputDir, targetDir, artifacts);
+    }
+    return artifacts
+        .sort((a, b) => b.timestamp - a.timestamp)
+        .slice(0, CAPTAIN_ARTIFACT_LIST_LIMIT)
+        .map(({ timestamp, ...artifact }) => artifact);
+}
+export function readCaptainFile(projectRoot, input, allowedDirs = CAPTAIN_ALLOWED_READ_DIRS) {
+    const resolved = resolveReadableFile(projectRoot, input.path, allowedDirs);
+    if (!resolved) {
+        return { success: false, message: 'File is outside allowed directories' };
+    }
+    if (!existsSync(resolved)) {
+        return { success: false, message: `File not found: ${input.path}` };
+    }
+    if (!statSync(resolved).isFile()) {
+        return { success: false, message: `Not a file: ${input.path}` };
+    }
+    const maxChars = normalizeMaxChars(input.maxChars);
+    const fullContent = readFileSync(resolved, 'utf8');
+    const content = selectContent(fullContent, input);
+    return {
+        success: true,
+        path: relative(projectRoot || process.cwd(), resolved),
+        truncated: content.length > maxChars,
+        content: content.slice(0, maxChars),
+    };
+}
+function collectArtifacts(outputDir, targetDir, artifacts) {
+    for (const entry of readdirSync(targetDir, { withFileTypes: true })) {
+        if (artifacts.length >= CAPTAIN_ARTIFACT_SCAN_LIMIT)
+            return;
+        const entryPath = join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            collectArtifacts(outputDir, entryPath, artifacts);
+            continue;
+        }
+        const stats = statSync(entryPath);
+        artifacts.push({
+            path: relative(outputDir, entryPath),
+            size: stats.size,
+            modifiedAt: stats.mtime.toISOString(),
+            timestamp: stats.mtimeMs,
+        });
+    }
+}
+function resolveReadableFile(projectRoot, requestedPath, allowedDirs) {
+    if (!projectRoot)
+        return null;
+    let cleanPath = requestedPath.trim();
+    const projectName = basename(projectRoot);
+    if (cleanPath.startsWith(`${projectName}/`) || cleanPath.startsWith(`${projectName}\\`)) {
+        cleanPath = cleanPath.slice(projectName.length + 1);
+    }
+    const resolved = isAbsolute(cleanPath) ? resolve(cleanPath) : resolve(projectRoot, cleanPath);
+    const allowedRoots = allowedDirs.map((dir) => resolve(projectRoot, dir));
+    for (const root of allowedRoots) {
+        const rel = relative(root, resolved);
+        if (!rel || (!rel.startsWith('..') && !isAbsolute(rel)))
+            return resolved;
+    }
+    return null;
+}
+function selectContent(content, input) {
+    if (!input.startLine && !input.endLine)
+        return content;
+    const lines = content.split(/\r?\n/);
+    const startIndex = resolveLineIndex(input.startLine, lines.length, 1);
+    const endIndex = resolveLineIndex(input.endLine, lines.length, lines.length);
+    if (endIndex < startIndex)
+        return '';
+    return lines.slice(startIndex - 1, endIndex).join('\n');
+}
+function resolveLineIndex(line, totalLines, fallback) {
+    if (!line)
+        return fallback;
+    if (line < 0)
+        return Math.max(1, totalLines + line + 1);
+    return Math.min(Math.max(1, line), totalLines);
+}
+function normalizeMaxChars(maxChars) {
+    return Math.max(CAPTAIN_READ_FILE_MIN_LIMIT, Math.min(maxChars || CAPTAIN_READ_FILE_DEFAULT_LIMIT, CAPTAIN_READ_FILE_MAX_LIMIT));
+}

package/dist/src/ai/captain/idle-mode.js

@@ -4,6 +4,7 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ConfigParser } from "../../config.js";
 import { Test } from "../../test-plan.js";
+import { listRecentArtifacts, readCaptainFile } from "./file-tools.js";
 import { resolveProjectRoot } from "./mixin.js";
 let cachedBashTool = null;
 export function WithIdleMode(Base) {
@@ -13,6 +14,8 @@ export function WithIdleMode(Base) {
             const config = ConfigParser.getInstance().getConfig();
             const knowledgeDir = config.dirs?.knowledge || 'knowledge';
             const experienceDir = config.dirs?.experience || 'experience';
+            const outputDir = config.dirs?.output || 'output';
+            const readableDirs = [outputDir, knowledgeDir, experienceDir];
             if (!cachedBashTool && projectRoot) {
                 cachedBashTool = await createBashTool({
                     destination: projectRoot,
@@ -69,6 +72,53 @@ export function WithIdleMode(Base) {
                         return { success: true, tests: plan.tests.length };
                     },
                 }),
+                project: tool({
+                    description: dedent `
+            Inspect Explorbot project configuration and recent generated artifacts.
+            Use this before answering questions about setup, previous sessions, reports, saved plans, or output files.
+          `,
+                    inputSchema: z.object({
+                        view: z.enum(['config', 'artifacts']).optional().describe('config shows setup summary; artifacts lists recent generated files'),
+                    }),
+                    execute: async ({ view }) => {
+                        const parser = ConfigParser.getInstance();
+                        const config = parser.getConfig();
+                        const outputDir = parser.getOutputDir();
+                        if (view === 'artifacts') {
+                            return {
+                                success: true,
+                                outputDir,
+                                artifacts: listRecentArtifacts(outputDir),
+                                suggestion: 'Use readFile to inspect specific reports, plans, logs, generated tests, knowledge, or experience files.',
+                            };
+                        }
+                        return {
+                            success: true,
+                            configPath: parser.getConfigPath(),
+                            baseUrl: config.playwright?.url,
+                            browser: config.playwright?.browser,
+                            headed: config.playwright?.show === true,
+                            dirs: config.dirs,
+                            agents: Object.fromEntries(Object.entries(config.ai?.agents || {}).map(([name, agentConfig]) => [name, { enabled: agentConfig?.enabled !== false, hasModelOverride: !!agentConfig?.model }])),
+                            reporterEnabled: config.reporter?.enabled === true,
+                            apiEnabled: !!config.api,
+                        };
+                    },
+                }),
+                readFile: tool({
+                    description: dedent `
+            Read a specific Explorbot project file for analysis.
+            Use this for explicit user questions about reports, plans, logs, generated tests, knowledge, or experience files.
+            Prefer this over bash() for reading file contents after bash has found the file.
+          `,
+                    inputSchema: z.object({
+                        path: z.string().describe('Path inside output, knowledge, or experience directories'),
+                        startLine: z.number().optional().describe('First line to read, 1-based. Negative values count from the end of the file'),
+                        endLine: z.number().optional().describe('Last line to read, 1-based and inclusive. Negative values count from the end of the file'),
+                        maxChars: z.number().optional().describe('Maximum characters to return, default 12000'),
+                    }),
+                    execute: async (input) => readCaptainFile(projectRoot, input, readableDirs),
+                }),
             };
             if (cachedBashTool) {
                 tools.bash = cachedBashTool.bash;
@@ -79,17 +129,31 @@ export function WithIdleMode(Base) {
             const config = ConfigParser.getInstance().getConfig();
             const knowledgeDir = config.dirs?.knowledge || 'knowledge';
             const experienceDir = config.dirs?.experience || 'experience';
+            const outputDir = config.dirs?.output || 'output';
             return dedent `
         <idle_capabilities>
         - Plan management: updatePlan() — replace or append tests in the current plan
-        - bash() — run shell commands for file operations
-          - READ from: ${knowledgeDir}/, ${experienceDir}/, output/
-          - WRITE to: ${knowledgeDir}/, ${experienceDir}/ only (NOT output/)
-          - Use ls to list files, cat to read small files
-          - Use head/tail for large files to avoid excessive output
-          - Use grep to search file contents
+        - readFile() — read specific report, plan, log, generated test, knowledge, or experience file content
+        - bash() — discover files and inspect file metadata
+          - READ from: ${knowledgeDir}/, ${experienceDir}/, ${outputDir}/
+          - WRITE to: ${knowledgeDir}/, ${experienceDir}/ only (NOT ${outputDir}/)
+          - Use wc -l -c file.txt to inspect size
+          - Use file file.txt to inspect type
+          - Use find . -name "*.md" to discover files
+          - Use grep -n "keyword" file.txt to find matching lines
+          - Use ls -lh to list files
         </idle_capabilities>
 
+        <file_reading>
+        Use bash() for file discovery and search. Once the needed file and line range are known,
+        use readFile() to read its contents. Do not use bash() to print file contents.
+        </file_reading>
+
+        <project_inspection>
+        Use project({ view: "config" }) before explaining Explorbot setup or suggesting config improvements.
+        Use project({ view: "artifacts" }) before answering questions about previous sessions, reports, plans, generated tests, or logs.
+        </project_inspection>
+
         <knowledge_saving>
         When user shares credentials, selectors, or important domain info during conversation,
         suggest saving it to a knowledge file using bash tool.

package/dist/src/ai/captain/web-mode.js

@@ -45,19 +45,49 @@ export function WithWebMode(Base) {
                     description: dedent `
             Direct browser access via Playwright. Use for diagnostics and browser management.
             Actions:
+            - status: Inspect browser/page availability, URL, title, tab count
             - evaluate: Run JavaScript in browser context (localStorage, cookies, DOM, console)
             - closeTabs: Close all browser tabs except the current one
-            - screenshot: Take a screenshot of current page
             - reload: Reload the current page
+            - screenshot: Take a screenshot of current page
+            - recover: Recover from a closed/crashed page using Explorer recovery
+            - restart: Restart the browser when page/context recovery is not enough
+            - openFreshTab: Open a fresh tab in the current browser context
           `,
                     inputSchema: z.object({
-                        action: z.enum(['evaluate', 'closeTabs', 'screenshot', 'reload']).describe('Browser action to perform'),
+                        action: z.enum(['status', 'evaluate', 'closeTabs', 'reload', 'screenshot', 'recover', 'restart', 'openFreshTab']).describe('Browser action to perform'),
                         code: z.string().optional().describe('JavaScript code for evaluate action'),
                     }),
                     execute: async ({ action, code }) => {
-                        const page = ctx.explorBot.getExplorer().playwrightHelper?.page;
-                        if (!page)
-                            return { success: false, message: 'No browser page available' };
+                        const explorer = ctx.explorBot.getExplorer();
+                        if (action === 'status') {
+                            const page = explorer.playwrightHelper?.page;
+                            const pages = page?.context?.().pages?.() || [];
+                            return {
+                                success: true,
+                                hasPage: !!page,
+                                isClosed: page?.isClosed?.() || false,
+                                url: page && !page.isClosed?.() ? await page.url() : null,
+                                title: page && !page.isClosed?.() ? await page.title().catch(() => null) : null,
+                                tabs: pages.length,
+                            };
+                        }
+                        if (action === 'recover') {
+                            const recovered = await explorer.recoverFromBrowserError();
+                            return { success: recovered, message: recovered ? 'Browser page recovered' : 'Browser recovery failed' };
+                        }
+                        if (action === 'restart') {
+                            const restarted = await explorer.restartBrowser();
+                            return { success: restarted, message: restarted ? 'Browser restarted' : 'Browser restart failed' };
+                        }
+                        if (action === 'openFreshTab') {
+                            await ctx.explorBot.openFreshTab();
+                            const state = explorer.getStateManager().getCurrentState();
+                            return { success: true, url: state?.url, title: state?.title };
+                        }
+                        const page = explorer.playwrightHelper?.page;
+                        if (!page || page.isClosed?.())
+                            return { success: false, message: 'No browser page available. Try browser({ action: "recover" }) first.' };
                         if (action === 'evaluate') {
                             if (!code)
                                 return { success: false, message: 'Code required for evaluate action' };
@@ -106,7 +136,7 @@ export function WithWebMode(Base) {
         <web_capabilities>
         - Page actions: click, pressKey, form (CodeceptJS tools)
         - Navigation: navigate() — AI-powered navigation to URLs or page descriptions
-        - Browser diagnostics: browser() — evaluate JS, close tabs, screenshot, reload
+        - Browser diagnostics: browser() — inspect status, evaluate JS, close tabs, screenshot, reload, recover closed/crashed pages, restart browser, open a fresh tab
         - Visual analysis: see() — screenshot-based page verification
         - Context refresh: context() — get fresh HTML/ARIA snapshot
         - Visual fallback: visualClick() — coordinate-based click when locators fail