explorbot 0.1.27 → 0.1.28

package/src/action.ts

@@ -23,9 +23,9 @@ import { htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
 import { safeFilename } from './utils/strings.ts';
 import { throttle } from './utils/throttle.ts';
+import { isFatalBrowserError } from './utils/browser-errors.ts';
 
 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 {
   private actor: CodeceptJS.I;
@@ -41,6 +41,7 @@ class Action {
   public playwrightGroupId: string | null = null;
   public assertionSteps: Array<{ name: string; args: any[] }> = [];
   private recorder?: PlaywrightRecorder;
+  private mainDocumentStatus: number | undefined = undefined;
 
   constructor(actor: CodeceptJS.I, stateManager: StateManager, recorder?: PlaywrightRecorder) {
     this.actor = actor;
@@ -78,21 +79,26 @@ 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 as any).grabSource(), (this.actor as any).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: Error) => {
         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 as any).grabCurrentUrl?.());
 
       let screenshotFile: string | undefined = undefined;
+      const statesDir = outputPath('states');
+      fs.mkdirSync(statesDir, { recursive: true });
 
       if (includeScreenshot) {
         const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
-        screenshotFile = await (this.actor as any)
-          .saveScreenshot(filename)
+        const screenshotPath = join(statesDir, filename);
+        screenshotFile = await page
+          ?.screenshot({ path: screenshotPath, fullPage: true })
           .then(() => filename)
           .catch((err: Error) => {
             debugLog('Screenshot failed, continuing without it:', err);
@@ -101,8 +107,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');
@@ -144,6 +148,7 @@ class Action {
       const result = new ActionResult({
         html,
         title,
+        httpStatus: await this.captureMainDocumentStatus(),
         url,
         browserLogs,
         htmlFile,
@@ -158,13 +163,52 @@ class Action {
       return result;
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      if (FATAL_BROWSER_ERRORS.test(msg)) throw err;
+      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 });
     }
   }
 
+  private async captureMainDocumentStatus(): Promise<number | undefined> {
+    if (this.mainDocumentStatus) return this.mainDocumentStatus;
+
+    try {
+      const page = this.playwrightHelper.page;
+      const status = await page.evaluate(() => {
+        const navigation = performance.getEntriesByType('navigation').at(-1) as PerformanceNavigationTiming & { responseStatus?: number };
+        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;
+    }
+  }
+
+  private captureMainDocumentResponse(): () => void {
+    const page = this.playwrightHelper.page;
+    if (!page?.on || !page?.off) return () => {};
+
+    this.mainDocumentStatus = undefined;
+
+    const handler = (response: any) => {
+      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
    */
@@ -235,6 +279,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;
@@ -280,6 +325,7 @@ class Action {
       this.assertionSteps = [];
       throw err;
     } finally {
+      detachMainDocumentResponse();
       if (groupId) await this.recorder!.endAction();
       detachStepLogger(stepListener);
       if (stepSpan) {
@@ -375,6 +421,7 @@ class Action {
       return true;
     } catch (error) {
       this.lastError = error as Error;
+      if (isFatalBrowserError(error)) throw error;
       debugLog(`Attempt failed: ${codeBlock}: ${errorToString(error) || this.lastError?.toString()}`);
       return false;
     }
@@ -406,6 +453,35 @@ function errorToString(error: any): string {
   return error.message || error.toString();
 }
 
+async function waitForUsablePageDom(page: any): Promise<void> {
+  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: any, frame: any, actor: any): Promise<string> {
+  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: any, actor: any): Promise<string> {
+  if (page?.title) return page.title();
+  if (actor?.grabTitle) return actor.grabTitle();
+  return '';
+}
+
 function sanitizeCodeBlock(code: string): string {
   return code
     .split('\n')

package/src/ai/captain/file-tools.ts

@@ -0,0 +1,126 @@
+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'] as const;
+export const CAPTAIN_ALLOWED_READ_DIRS = ['output', 'knowledge', 'experience'] as const;
+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: string): Array<{ path: string; size: number; modifiedAt: string }> {
+  const artifacts: Array<{ path: string; size: number; modifiedAt: string; timestamp: number }> = [];
+
+  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: string | null, input: ReadCaptainFileInput, allowedDirs: readonly string[] = CAPTAIN_ALLOWED_READ_DIRS): ReadCaptainFileResult {
+  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: string, targetDir: string, artifacts: Array<{ path: string; size: number; modifiedAt: string; timestamp: number }>): void {
+  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: string | null, requestedPath: string, allowedDirs: readonly string[]): string | null {
+  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: string, input: ReadCaptainFileInput): string {
+  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: number | undefined, totalLines: number, fallback: number): number {
+  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?: number): number {
+  return Math.max(CAPTAIN_READ_FILE_MIN_LIMIT, Math.min(maxChars || CAPTAIN_READ_FILE_DEFAULT_LIMIT, CAPTAIN_READ_FILE_MAX_LIMIT));
+}
+
+export interface ReadCaptainFileInput {
+  path: string;
+  startLine?: number;
+  endLine?: number;
+  maxChars?: number;
+}
+
+export type ReadCaptainFileResult =
+  | {
+      success: true;
+      path: string;
+      truncated: boolean;
+      content: string;
+    }
+  | {
+      success: false;
+      message: string;
+    };

package/src/ai/captain/idle-mode.ts

@@ -4,6 +4,7 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ConfigParser } from '../../config.ts';
 import { Test } from '../../test-plan.ts';
+import { listRecentArtifacts, readCaptainFile } from './file-tools.ts';
 import { type Constructor, type ModeContext, resolveProjectRoot } from './mixin.ts';
 
 let cachedBashTool: Awaited<ReturnType<typeof createBashTool>> | null = null;
@@ -15,6 +16,8 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
       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({
@@ -75,6 +78,55 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
             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]: [string, any]) => [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) {
@@ -88,18 +140,32 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
       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/src/ai/captain/mixin.ts

@@ -8,7 +8,7 @@ export type Constructor<T = object> = new (...args: any[]) => T;
 
 export const debugLog = createDebug('explorbot:captain');
 
-export type CaptainMode = 'idle' | 'web' | 'test';
+export type CaptainMode = 'idle' | 'web' | 'test' | 'heal';
 
 export interface ModeContext {
   explorBot: ExplorBot;

package/src/ai/captain/web-mode.ts

@@ -47,18 +47,53 @@ export function WithWebMode<T extends Constructor>(Base: T) {
           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' };
@@ -112,7 +147,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
         <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