explorbot 0.1.26 → 0.1.28

package/src/ai/captain.ts

@@ -26,7 +26,6 @@ const MAX_STEPS = 15;
 const CaptainBase = WithTestMode(WithWebMode(WithIdleMode(TaskAgent as unknown as new (...args: any[]) => TaskAgent)));
 
 export class Captain extends CaptainBase implements Agent {
-  protected readonly ACTION_TOOLS = ['click', 'pressKey', 'form', 'navigate'];
   emoji = '🧑‍✈️';
   private explorBot: ExplorBot;
   private conversation: Conversation | null = null;
@@ -72,6 +71,12 @@ export class Captain extends CaptainBase implements Agent {
 
   protected trackToolExecutions(toolExecutions: any[]): void {
     super.trackToolExecutions(toolExecutions);
+    if (toolExecutions.length > 0) {
+      this.recentToolCalls.push(...toolExecutions);
+      if (this.recentToolCalls.length > 20) {
+        this.recentToolCalls = this.recentToolCalls.slice(-20);
+      }
+    }
     for (const exec of toolExecutions) {
       const label = toolExecutionLabel(exec.input);
       if (!label) continue;
@@ -80,14 +85,19 @@ export class Captain extends CaptainBase implements Agent {
     }
   }
 
-  private detectMode(): CaptainMode {
-    if (this.explorBot.getExplorer().activeTest) return 'test';
-    if (this.explorBot.getExplorer().getStateManager().getCurrentState()) return 'web';
+  getMode(): CaptainMode {
+    const explorer = this.explorBot.getExplorer();
+    const activeTest = explorer.activeTest;
+    const page = explorer.playwrightHelper?.page;
+
+    if (activeTest && (!page || page.isClosed?.())) return 'heal';
+    if (activeTest) return 'test';
+    if (explorer.getStateManager().getCurrentState()) return 'web';
     return 'idle';
   }
 
   private systemPrompt(): string {
-    const mode = this.detectMode();
+    const mode = this.getMode();
     const currentUrl = this.explorBot.getExplorer().getStateManager().getCurrentState()?.url;
     const customPrompt = this.explorBot.getProvider().getSystemPromptForAgent('captain', currentUrl);
 
@@ -101,18 +111,21 @@ export class Captain extends CaptainBase implements Agent {
     - idle: plan management, file operations, knowledge. Always available.
     - web: page interaction, navigation, browser diagnostics. When working with a web page.
     - test: test analysis, state inspection. When a test is running or analyzing results.
+    - heal: browser/test recovery. When a test is running and browser state is broken or unavailable.
     </modes>
 
     ${this.idleModePrompt()}
-    ${mode === 'web' ? this.webModePrompt() : ''}
-    ${mode === 'test' ? this.testModePrompt() : ''}
+    ${mode === 'web' || mode === 'heal' ? this.webModePrompt() : ''}
+    ${mode === 'test' || mode === 'heal' ? this.testModePrompt() : ''}
 
     <rules>
     - After a successful action, if the pageDiff confirms the goal, call done() immediately — do not verify with see() or context() unless the user explicitly asked for verification
     - Prefer completing in fewer tool calls over thoroughness
     - NEVER run tests unless the user explicitly asks
-    ${mode === 'web' ? this.webModeRules() : ''}
-    ${mode === 'test' ? this.testModeRules() : ''}
+    - If you are answering with information rather than completing a browser action, include the actual user-facing answer in done({ details }). Do not only say that it was shown or explained.
+    ${mode === 'web' || mode === 'heal' ? this.webModeRules() : ''}
+    ${mode === 'test' || mode === 'heal' ? this.testModeRules() : ''}
+    ${mode === 'heal' ? '- First diagnose browser availability, then recover the browser/page before continuing test analysis.' : ''}
     </rules>
 
     ${customPrompt || ''}
@@ -250,9 +263,20 @@ export class Captain extends CaptainBase implements Agent {
         description: 'Call when the user request is fulfilled.',
         inputSchema: z.object({
           summary: z.string().describe('What was done'),
+          details: z.string().optional().describe('Actual user-facing content. Required when the user asked to show, display, explain, summarize, compare, or diagnose information.'),
         }),
-        execute: async ({ summary }) => {
+        execute: async ({ summary, details }) => {
           debugLog('done', summary);
+          if (!details?.trim() && !this.canCompleteWithoutDetails()) {
+            return {
+              success: false,
+              message: 'No user-facing result was provided. Call done() again with the actual answer in details, or complete a browser action first.',
+            };
+          }
+          if (details?.trim()) {
+            tag('details').log(details);
+            task.addNote(details);
+          }
           task.addNote(summary);
           onDone(summary);
           return { success: true, summary };
@@ -261,6 +285,9 @@ export class Captain extends CaptainBase implements Agent {
       runCommand: tool({
         description: dedent`
           Execute a TUI command. Returns log output from command execution.
+          Use only when the user explicitly asks to run a slash command.
+          Never use this to analyze files, reports, logs, plans, generated tests, knowledge, or experience.
+          Never run a slash command unless the user request itself starts with that slash command.
           ${this.commandDescriptions
             .map((c) => {
               const opts = c.options ? ` (${c.options})` : '';
@@ -274,6 +301,13 @@ export class Captain extends CaptainBase implements Agent {
         execute: async ({ command }) => {
           if (!this.commandExecutor) return { success: false, message: 'Command executor not available' };
           const cmd = command.startsWith('/') ? command : `/${command}`;
+          if (!isExplicitSlashRequest(task.description, cmd)) {
+            return {
+              success: false,
+              command: cmd,
+              message: 'Command blocked: slash commands require an explicit matching slash-command request from the user.',
+            };
+          }
           startLogCapture();
           try {
             await this.commandExecutor(cmd);
@@ -286,11 +320,12 @@ export class Captain extends CaptainBase implements Agent {
   }
 
   private async tools(task: Task, onDone: (summary: string) => void) {
-    const mode = this.detectMode();
+    const mode = this.getMode();
     const ctx: ModeContext = { explorBot: this.explorBot, task };
     const core = this.coreTools(task, onDone);
     const idle = await this.idleModeTools(ctx);
 
+    if (mode === 'heal') return { ...core, ...idle, ...this.testModeTools(ctx), ...this.webModeTools(ctx) };
     if (mode === 'test') return { ...core, ...idle, ...this.testModeTools(ctx) };
     if (mode === 'web') return { ...core, ...idle, ...this.webModeTools(ctx) };
     return { ...core, ...idle };
@@ -365,20 +400,28 @@ export class Captain extends CaptainBase implements Agent {
     return result.object;
   }
 
+  async processExecutionError(error: Error, activeTest: Test): Promise<ExecutionRecoveryAction> {
+    const explorer = this.explorBot.getExplorer();
+    const result = await explorer.handleExecutionError(error);
+    return {
+      ...result,
+      message: result.recovered ? `${result.message}\nContinue the test "${activeTest.scenario}" from the restored page.` : result.message,
+    };
+  }
+
+  private canCompleteWithoutDetails(): boolean {
+    return (this.recentToolCalls || []).some(hasBrowserCompletionEvidence);
+  }
+
   async handle(input: string, options: { reset?: boolean } = {}): Promise<string | null> {
     const stateManager = this.explorBot.getExplorer().getStateManager();
     const initialState = stateManager.getCurrentState();
 
-    if (!initialState) {
-      tag('warning').log('No page loaded. Use /navigate or I.amOnPage() first.');
-      return null;
-    }
-
     const conversation = options.reset ? this.resetConversation() : this.ensureConversation();
     let isDone = false;
     let finalSummary: string | null = null;
 
-    const startUrl = initialState.url || '';
+    const startUrl = initialState?.url || '';
     const task = new Task(input, startUrl);
     const onDone = (summary: string) => {
       isDone = true;
@@ -421,12 +464,14 @@ export class Captain extends CaptainBase implements Agent {
         }
 
         const currentState = stateManager.getCurrentState();
-        if (!currentState) {
+        if (!currentState && this.getMode() !== 'idle') {
           stop();
           return;
         }
 
-        await this.reinjectContextIfNeeded(conversation, currentState);
+        if (currentState) {
+          await this.reinjectContextIfNeeded(conversation, currentState);
+        }
 
         if (userInput) {
           const newContext = await this.getPageContext();
@@ -463,7 +508,7 @@ export class Captain extends CaptainBase implements Agent {
 
         if (result?.toolExecutions?.length) {
           const lastExec = result.toolExecutions[result.toolExecutions.length - 1];
-          if (lastExec.wasSuccessful && this.ACTION_TOOLS.includes(lastExec.toolName)) {
+          if (hasBrowserCompletionEvidence(lastExec)) {
             conversation.addUserText('Action succeeded. If the goal is achieved, call done() now with a brief summary.');
           }
         }
@@ -500,3 +545,32 @@ interface SupervisorAction {
   action: 'inject' | 'stop' | 'pass' | 'skip';
   message: string;
 }
+
+interface ExecutionRecoveryAction {
+  action: 'continue' | 'stop';
+  message: string;
+  recovered?: boolean;
+}
+
+function isExplicitSlashRequest(input: string, command: string): boolean {
+  const requested = slashCommandToken(input);
+  const actual = slashCommandToken(command);
+  if (!requested || !actual) return false;
+  return requested === actual;
+}
+
+function slashCommandToken(value: string): string | null {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('/')) return null;
+
+  for (let i = 1; i < trimmed.length; i++) {
+    if (trimmed[i] <= ' ') return trimmed.slice(0, i);
+  }
+  return trimmed;
+}
+
+function hasBrowserCompletionEvidence(execution: any): boolean {
+  if (!execution?.wasSuccessful) return false;
+  const output = execution.output || {};
+  return Boolean(output.pageDiff || output.code || output.playwrightGroupId);
+}

package/src/ai/historian/screencast.ts

@@ -10,6 +10,8 @@ import { relativeToCwd } from '../../utils/next-steps.ts';
 import { safeFilename } from '../../utils/strings.ts';
 import { type Constructor, debugLog } from './mixin.ts';
 
+const FATAL_SCREENCAST_STOP_ERRORS = /Target page, context or browser has been closed|Target closed|Session closed|Protocol error/i;
+
 export interface ScreencastMethods {
   attachScreencast(): void;
   isScreencastActive(): boolean;
@@ -113,17 +115,24 @@ export function WithScreencast<T extends Constructor>(Base: T) {
       if (!this.screencastActive) return;
       const path = this.screencastPath;
       const task = this.screencastTask;
+      let stopped = false;
       try {
         await this.screencastPage.screencast.stop();
+        stopped = true;
       } catch (err) {
-        tag('operation').log(`Screencast stop failed: ${(err as Error).message}`);
+        const message = (err as Error).message;
+        if (FATAL_SCREENCAST_STOP_ERRORS.test(message)) {
+          tag('operation').log('Screencast skipped: browser was closed before recording could be finalized');
+        } else {
+          tag('operation').log(`Screencast stop failed: ${message}`);
+        }
       }
       this.screencastActive = false;
       this.screencastPage = null;
       this.screencastPath = null;
       this.screencastTask = null;
       this.screencastLastChapter = null;
-      if (path) {
+      if (path && stopped) {
         this.savedFiles.add(path);
         task?.addArtifact?.(path);
         tag('operation').log(`Saved screencast: ${relativeToCwd(path)}`);

package/src/ai/navigator.ts

@@ -136,6 +136,10 @@ class Navigator implements Agent {
   }
 
   async visit(url: string): Promise<void> {
+    return this.explorer.runWithBrowserRecovery('navigator.visit', () => this.visitOnce(url));
+  }
+
+  private async visitOnce(url: string): Promise<void> {
     try {
       const action = this.explorer.createAction();
 
@@ -170,7 +174,7 @@ class Navigator implements Agent {
           throw new Error(`Navigation to ${url} failed: ${action.lastError?.message}`);
         }
       }
-      await action.caputrePageWithScreenshot();
+      await this.explorer.capturePageWithScreenshot();
       await this.hooksRunner.runAfterHook('navigator', url);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -382,7 +386,7 @@ class Navigator implements Agent {
               // URL did not transition to expectedUrl within timeout
             }
           }
-          const freshState = await action.capturePageState();
+          const freshState = await this.explorer.capturePageState();
           const currentUrl = /^https?:\/\//i.test(expectedUrl) ? freshState.fullUrl || freshState.url || '' : freshState.url || '';
           const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
           const stateChanged = freshState.getStateHash() !== actionResult.getStateHash();

package/src/ai/pilot.ts

@@ -67,7 +67,7 @@ export class Pilot implements Agent {
   }
 
   async reviewCompletion(task: Test, currentState: ActionResult, testerConversation: Conversation, navigator?: Navigator): Promise<boolean> {
-    const verdictType = task.hasAchievedAny() ? 'finish' : 'stop';
+    const verdictType = this.hasCompletionEvidence(task, currentState, testerConversation) ? 'finish' : 'stop';
     return this.reviewDecision(verdictType, task, currentState, testerConversation, navigator);
   }
 
@@ -86,14 +86,14 @@ export class Pilot implements Agent {
 
     const sessionLog = this.formatSessionLog(testerConversation);
     const stateContext = this.buildStateContext(currentState);
+    const successfulAssertions = this.formatSuccessfulAssertions(currentState, testerConversation);
     const notes = task.notesToString() || 'No notes recorded.';
 
     let visualAnalysis = '';
     let screenshotState: ActionResult | null = null;
     if (this.provider.hasVision()) {
       try {
-        const action = this.explorer.createAction();
-        screenshotState = await action.caputrePageWithScreenshot();
+        screenshotState = await this.explorer.capturePageWithScreenshot();
         if (screenshotState.screenshot) {
           visualAnalysis = (await this.researcher.answerQuestionAboutScreenshot(screenshotState, `Describe current page state relevant to: ${task.scenario}`)) || '';
         }
@@ -125,6 +125,10 @@ export class Pilot implements Agent {
 
       ${this.formatExpectations(task)}
 
+      <successful_assertions>
+      ${successfulAssertions || 'None'}
+      </successful_assertions>
+
       <notes>
       ${notes}
       </notes>
@@ -658,8 +662,7 @@ export class Pilot implements Agent {
   private async checkDataAvailability(task: Test, requestedData: string, fishermanReason: string | undefined): Promise<string | null> {
     if (!this.provider.hasVision()) return null;
 
-    const action = this.explorer.createAction();
-    const screenshotState = await action.caputrePageWithScreenshot().catch(() => null);
+    const screenshotState = await this.explorer.capturePageWithScreenshot().catch(() => null);
     if (!screenshotState?.screenshot) return null;
 
     const question = dedent`
@@ -882,6 +885,32 @@ export class Pilot implements Agent {
     return parts.join('\n\n');
   }
 
+  private hasCompletionEvidence(task: Test, currentState: ActionResult, testerConversation: Conversation): boolean {
+    if (task.hasAchievedAny()) return true;
+    return this.hasSuccessfulCheckEvidence(currentState, testerConversation);
+  }
+
+  private hasSuccessfulCheckEvidence(currentState: ActionResult, testerConversation: Conversation): boolean {
+    if (Object.values(currentState.verifications ?? {}).some(Boolean)) return true;
+    return testerConversation.getToolExecutions().some((t) => CHECK_TOOLS.includes(t.toolName) && t.wasSuccessful);
+  }
+
+  private formatSuccessfulAssertions(currentState: ActionResult, testerConversation: Conversation): string {
+    const lines: string[] = [];
+    for (const [assertion, passed] of Object.entries(currentState.verifications ?? {})) {
+      if (passed) lines.push(`PASS state verification: ${assertion}`);
+    }
+
+    for (const exec of testerConversation.getToolExecutions()) {
+      if (!CHECK_TOOLS.includes(exec.toolName) || !exec.wasSuccessful) continue;
+      const description = exec.input?.assertion || exec.input?.request || truncateJson(exec.input);
+      const result = exec.output?.message || exec.output?.analysis || exec.output?.result;
+      lines.push(`PASS ${exec.toolName}: ${description}${result ? ` -> ${result}` : ''}`);
+    }
+
+    return [...new Set(lines)].join('\n');
+  }
+
   private formatActions(toolCalls: any[]): string {
     return toolCalls
       .map((t) => {

package/src/ai/researcher/cache.ts

@@ -49,6 +49,13 @@ export function getCachedResearch(hash: string): string {
   return cached;
 }
 
+export function getPreviousResearch(hash: string): string {
+  if (!hash) return '';
+  const researchFile = outputPath('research', `${hash}.md`);
+  if (!existsSync(researchFile)) return '';
+  return readFileSync(researchFile, 'utf8');
+}
+
 export function saveResearch(hash: string, text: string, combinedHtml?: string): string {
   const researchDir = outputPath('research');
   const researchFile = join(researchDir, `${hash}.md`);

package/src/ai/researcher/coordinates.ts

@@ -81,7 +81,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
     }
 
     async visuallyAnnotateElements(opts?: { containers?: Array<{ css: string; label: string }> }): Promise<number> {
-      return visuallyAnnotateContainers(this.explorer.playwrightHelper.page, opts?.containers || []);
+      return this.explorer.visuallyAnnotateElements(opts);
     }
 
     private async _analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult> {
@@ -193,7 +193,6 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
     }
 
     async backfillCoordinates(result: ResearchResult): Promise<void> {
-      const page = this.explorer.playwrightHelper.page;
       const sections = parseResearchSections(result.text);
       const eidxWithoutCoords: string[] = [];
       for (const section of sections) {
@@ -203,7 +202,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
       }
       if (eidxWithoutCoords.length === 0) return;
 
-      const webElements = await WebElement.fromEidxList(page, eidxWithoutCoords);
+      const webElements = await this.explorer.runWithBrowserRecovery('backfillCoordinates', () => WebElement.fromEidxList(this.explorer.playwrightHelper.page, eidxWithoutCoords));
       if (webElements.length === 0) return;
 
       const rectMap = new Map(webElements.map((w) => [w.eidx!, w]));