explorbot 0.1.26 → 0.1.28

package/dist/src/ai/captain.js

@@ -18,7 +18,6 @@ import { TaskAgent } from "./task-agent.js";
 const MAX_STEPS = 15;
 const CaptainBase = WithTestMode(WithWebMode(WithIdleMode(TaskAgent)));
 export class Captain extends CaptainBase {
-    ACTION_TOOLS = ['click', 'pressKey', 'form', 'navigate'];
     emoji = '🧑‍✈️';
     explorBot;
     conversation = null;
@@ -56,6 +55,12 @@ export class Captain extends CaptainBase {
     }
     trackToolExecutions(toolExecutions) {
         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)
@@ -64,15 +69,20 @@ export class Captain extends CaptainBase {
             tag('substep').log(`${icon} ${label}`);
         }
     }
-    detectMode() {
-        if (this.explorBot.getExplorer().activeTest)
+    getMode() {
+        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 (this.explorBot.getExplorer().getStateManager().getCurrentState())
+        if (explorer.getStateManager().getCurrentState())
             return 'web';
         return 'idle';
     }
     systemPrompt() {
-        const mode = this.detectMode();
+        const mode = this.getMode();
         const currentUrl = this.explorBot.getExplorer().getStateManager().getCurrentState()?.url;
         const customPrompt = this.explorBot.getProvider().getSystemPromptForAgent('captain', currentUrl);
         return dedent `
@@ -85,18 +95,21 @@ export class Captain extends CaptainBase {
     - 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 || ''}
@@ -228,9 +241,20 @@ export class Captain extends CaptainBase {
                 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 };
@@ -239,6 +263,9 @@ export class Captain extends CaptainBase {
             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})` : '';
@@ -253,6 +280,13 @@ export class Captain extends CaptainBase {
                     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);
@@ -265,10 +299,12 @@ export class Captain extends CaptainBase {
         };
     }
     async tools(task, onDone) {
-        const mode = this.detectMode();
+        const mode = this.getMode();
         const ctx = { 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')
@@ -333,17 +369,24 @@ export class Captain extends CaptainBase {
         }
         return result.object;
     }
+    async processExecutionError(error, activeTest) {
+        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,
+        };
+    }
+    canCompleteWithoutDetails() {
+        return (this.recentToolCalls || []).some(hasBrowserCompletionEvidence);
+    }
     async handle(input, options = {}) {
         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 = null;
-        const startUrl = initialState.url || '';
+        const startUrl = initialState?.url || '';
         const task = new Task(input, startUrl);
         const onDone = (summary) => {
             isDone = true;
@@ -376,11 +419,13 @@ export class Captain extends CaptainBase {
                 return;
             }
             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();
                 conversation.addUserText(dedent `
@@ -410,7 +455,7 @@ export class Captain extends CaptainBase {
             }
             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.');
                 }
             }
@@ -437,3 +482,26 @@ export class Captain extends CaptainBase {
     }
 }
 export default Captain;
+function isExplicitSlashRequest(input, command) {
+    const requested = slashCommandToken(input);
+    const actual = slashCommandToken(command);
+    if (!requested || !actual)
+        return false;
+    return requested === actual;
+}
+function slashCommandToken(value) {
+    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) {
+    if (!execution?.wasSuccessful)
+        return false;
+    const output = execution.output || {};
+    return Boolean(output.pageDiff || output.code || output.playwrightGroupId);
+}

package/dist/src/ai/historian/screencast.js

@@ -7,6 +7,7 @@ import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
 import { safeFilename } from "../../utils/strings.js";
 import { debugLog } from "./mixin.js";
+const FATAL_SCREENCAST_STOP_ERRORS = /Target page, context or browser has been closed|Target closed|Session closed|Protocol error/i;
 export function WithScreencast(Base) {
     return class extends Base {
         screencastPage = null;
@@ -100,18 +101,26 @@ export function WithScreencast(Base) {
                 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.message}`);
+                const message = err.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/dist/src/ai/navigator.js

@@ -121,6 +121,9 @@ class Navigator {
         return normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
     }
     async visit(url) {
+        return this.explorer.runWithBrowserRecovery('navigator.visit', () => this.visitOnce(url));
+    }
+    async visitOnce(url) {
         try {
             const action = this.explorer.createAction();
             await action.execute(`I.amOnPage('${url}')`);
@@ -150,7 +153,7 @@ class Navigator {
                     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) {
@@ -349,7 +352,7 @@ class Navigator {
                         // 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/dist/src/ai/pilot.js

@@ -50,7 +50,7 @@ export class Pilot {
         return this.reviewDecision('finish', task, currentState, testerConversation, navigator);
     }
     async reviewCompletion(task, currentState, testerConversation, navigator) {
-        const verdictType = task.hasAchievedAny() ? 'finish' : 'stop';
+        const verdictType = this.hasCompletionEvidence(task, currentState, testerConversation) ? 'finish' : 'stop';
         return this.reviewDecision(verdictType, task, currentState, testerConversation, navigator);
     }
     async finalReview(task, currentState, testerConversation, navigator) {
@@ -67,13 +67,13 @@ export class Pilot {
         tag('substep').log(`Pilot reviewing ${type} verdict...`);
         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 = 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}`)) || '';
                 }
@@ -102,6 +102,10 @@ export class Pilot {
 
       ${this.formatExpectations(task)}
 
+      <successful_assertions>
+      ${successfulAssertions || 'None'}
+      </successful_assertions>
+
       <notes>
       ${notes}
       </notes>
@@ -587,8 +591,7 @@ export class Pilot {
     async checkDataAvailability(task, requestedData, fishermanReason) {
         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 `
@@ -791,6 +794,31 @@ export class Pilot {
         }
         return parts.join('\n\n');
     }
+    hasCompletionEvidence(task, currentState, testerConversation) {
+        if (task.hasAchievedAny())
+            return true;
+        return this.hasSuccessfulCheckEvidence(currentState, testerConversation);
+    }
+    hasSuccessfulCheckEvidence(currentState, testerConversation) {
+        if (Object.values(currentState.verifications ?? {}).some(Boolean))
+            return true;
+        return testerConversation.getToolExecutions().some((t) => CHECK_TOOLS.includes(t.toolName) && t.wasSuccessful);
+    }
+    formatSuccessfulAssertions(currentState, testerConversation) {
+        const lines = [];
+        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');
+    }
     formatActions(toolCalls) {
         return toolCalls
             .map((t) => {

package/dist/src/ai/researcher/cache.js

@@ -46,6 +46,14 @@ export function getCachedResearch(hash) {
     memoryCacheTimestamps[hash] = now;
     return cached;
 }
+export function getPreviousResearch(hash) {
+    if (!hash)
+        return '';
+    const researchFile = outputPath('research', `${hash}.md`);
+    if (!existsSync(researchFile))
+        return '';
+    return readFileSync(researchFile, 'utf8');
+}
 export function saveResearch(hash, text, combinedHtml) {
     const researchDir = outputPath('research');
     const researchFile = join(researchDir, `${hash}.md`);

package/dist/src/ai/researcher/coordinates.js

@@ -67,7 +67,7 @@ export function WithCoordinates(Base) {
             return this._analyzeScreenshotForVisualProps();
         }
         async visuallyAnnotateElements(opts) {
-            return visuallyAnnotateContainers(this.explorer.playwrightHelper.page, opts?.containers || []);
+            return this.explorer.visuallyAnnotateElements(opts);
         }
         async _analyzeScreenshotForVisualProps() {
             const elements = new Map();
@@ -177,7 +177,6 @@ export function WithCoordinates(Base) {
             debugLog(`Merged visual props for ${merged} elements`);
         }
         async backfillCoordinates(result) {
-            const page = this.explorer.playwrightHelper.page;
             const sections = parseResearchSections(result.text);
             const eidxWithoutCoords = [];
             for (const section of sections) {
@@ -188,7 +187,7 @@ export function WithCoordinates(Base) {
             }
             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]));