explorbot 0.2.0 → 0.2.2

package/dist/boat/doc-collector/src/interaction-screenshots.js

@@ -0,0 +1,156 @@
+import { writeFileSync } from 'node:fs';
+import pixelmatch from 'pixelmatch';
+import { PNG } from 'pngjs';
+const REGION_PADDING = 30;
+const SCREENSHOT_OPTIONS = { animations: 'disabled', caret: 'hide' };
+export async function captureInteractionBefore(page) {
+    await removeVisualAnnotations(page);
+    try {
+        return await page.screenshot(SCREENSHOT_OPTIONS);
+    }
+    catch {
+        return null;
+    }
+}
+export async function captureInteractionAfter(page, beforeScreenshot, filePath, detectUnmarkedOverlay = false) {
+    if (!beforeScreenshot)
+        return 'failed';
+    await removeVisualAnnotations(page);
+    try {
+        const afterScreenshot = await page.screenshot(SCREENSHOT_OPTIONS);
+        const before = PNG.sync.read(beforeScreenshot);
+        const after = PNG.sync.read(afterScreenshot);
+        if (before.width !== after.width || before.height !== after.height)
+            return 'failed';
+        const changedPixels = findChangedPixelBounds(before, after);
+        if (!changedPixels)
+            return 'unchanged';
+        const fullViewportChanged = changedPixels.x === 0 && changedPixels.y === 0 && changedPixels.width === after.width && changedPixels.height === after.height;
+        const changedRegion = addPadding(changedPixels, after.width, after.height);
+        const overlayRegion = fullViewportChanged ? await findOverlayRegion(page, after, detectUnmarkedOverlay) : null;
+        saveRegion(after, overlayRegion || changedRegion, filePath);
+        return 'captured';
+    }
+    catch {
+        return 'failed';
+    }
+}
+export function findChangedRegion(beforeScreenshot, afterScreenshot, padding = REGION_PADDING) {
+    const before = PNG.sync.read(beforeScreenshot);
+    const after = PNG.sync.read(afterScreenshot);
+    if (before.width !== after.width || before.height !== after.height)
+        return null;
+    const changedPixels = findChangedPixelBounds(before, after);
+    return changedPixels ? addPadding(changedPixels, before.width, before.height, padding) : null;
+}
+function saveRegion(after, region, filePath) {
+    const cropped = new PNG({ width: region.width, height: region.height });
+    PNG.bitblt(after, cropped, region.x, region.y, region.width, region.height, 0, 0);
+    writeFileSync(filePath, PNG.sync.write(cropped));
+}
+function findChangedPixelBounds(before, after) {
+    const diff = Buffer.alloc(before.width * before.height * 4);
+    const changedPixels = pixelmatch(before.data, after.data, diff, before.width, before.height, { diffMask: true });
+    if (changedPixels === 0)
+        return null;
+    let left = before.width;
+    let top = before.height;
+    let right = 0;
+    let bottom = 0;
+    for (let y = 0; y < before.height; y++) {
+        for (let x = 0; x < before.width; x++) {
+            if (diff[(y * before.width + x) * 4 + 3] === 0)
+                continue;
+            left = Math.min(left, x);
+            top = Math.min(top, y);
+            right = Math.max(right, x);
+            bottom = Math.max(bottom, y);
+        }
+    }
+    return { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+}
+function addPadding(region, imageWidth, imageHeight, padding = REGION_PADDING) {
+    const x = Math.max(0, region.x - padding);
+    const y = Math.max(0, region.y - padding);
+    const maxX = Math.min(imageWidth, region.x + region.width + padding);
+    const maxY = Math.min(imageHeight, region.y + region.height + padding);
+    return { x, y, width: maxX - x, height: maxY - y };
+}
+async function removeVisualAnnotations(page) {
+    try {
+        await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+            for (const element of elements)
+                element.remove();
+        });
+    }
+    catch { }
+}
+async function findOverlayRegion(page, image, detectUnmarkedOverlay) {
+    let box = null;
+    try {
+        const dialogs = page.locator('[role="dialog"]:visible, [role="alertdialog"]:visible, [aria-modal="true"]:visible');
+        if ((await dialogs.count()) > 0)
+            box = await dialogs.last().boundingBox();
+    }
+    catch { }
+    if (!box && detectUnmarkedOverlay) {
+        try {
+            box = await findUnmarkedOverlay(page);
+        }
+        catch { }
+    }
+    try {
+        const viewport = page.viewportSize();
+        if (!box || !viewport)
+            return null;
+        const scaleX = image.width / viewport.width;
+        const scaleY = image.height / viewport.height;
+        const x = Math.max(0, Math.floor(box.x * scaleX) - REGION_PADDING);
+        const y = Math.max(0, Math.floor(box.y * scaleY) - REGION_PADDING);
+        const maxX = Math.min(image.width, Math.ceil((box.x + box.width) * scaleX) + REGION_PADDING);
+        const maxY = Math.min(image.height, Math.ceil((box.y + box.height) * scaleY) + REGION_PADDING);
+        if (maxX <= x || maxY <= y)
+            return null;
+        return { x, y, width: maxX - x, height: maxY - y };
+    }
+    catch {
+        return null;
+    }
+}
+async function findUnmarkedOverlay(page) {
+    return page.evaluate(() => {
+        const elements = [...document.body.querySelectorAll('*')].map((element) => {
+            const style = getComputedStyle(element);
+            const box = element.getBoundingClientRect();
+            const zIndex = Number.parseInt(style.zIndex, 10);
+            return { element, style, box, zIndex, area: box.width * box.height };
+        });
+        const isVisibleLayer = ({ style, box, zIndex }) => {
+            if (style.visibility === 'hidden' || style.display === 'none' || Number(style.opacity) === 0)
+                return false;
+            if (box.width <= 0 || box.height <= 0)
+                return false;
+            if (style.position !== 'fixed' && style.position !== 'absolute')
+                return false;
+            return Number.isFinite(zIndex);
+        };
+        const backdropZIndex = elements.filter((item) => isVisibleLayer(item) && item.box.width >= window.innerWidth && item.box.height >= window.innerHeight).reduce((highest, item) => Math.max(highest, item.zIndex), Number.NEGATIVE_INFINITY);
+        if (!Number.isFinite(backdropZIndex))
+            return null;
+        const candidates = elements
+            .filter((item) => {
+            if (!isVisibleLayer(item))
+                return false;
+            if (item.box.width >= window.innerWidth && item.box.height >= window.innerHeight)
+                return false;
+            if (item.zIndex < backdropZIndex)
+                return false;
+            return item.element.matches('button, input, select, textarea, a[href]') || !!item.element.querySelector('button, input, select, textarea, a[href]');
+        })
+            .sort((left, right) => right.zIndex - left.zIndex || left.area - right.area);
+        const box = candidates[0]?.box;
+        if (!box)
+            return null;
+        return { x: box.x, y: box.y, width: box.width, height: box.height };
+    });
+}

package/dist/boat/doc-collector/src/screenshots.js

@@ -1,11 +1,11 @@
 import { mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { parseResearchSections } from "../../../src/ai/researcher/parser.js";
-import { detectFocusArea } from "../../../src/utils/aria.js";
 import { safeFilename, sanitizeFilename } from "../../../src/utils/strings.js";
+import { captureInteractionAfter, captureInteractionBefore } from "./interaction-screenshots.js";
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
 export async function captureDocumentationScreenshots(explorer, state, research, options) {
-    const page = explorer.playwrightHelper?.page;
+    const page = explorer.page;
     if (!page) {
         return [];
     }
@@ -47,27 +47,21 @@ export function getScreenshotSections(research) {
     }
     return sections;
 }
-export async function captureInteractionScreenshot(explorer, state, transition, options) {
-    const page = explorer.playwrightHelper?.page;
+export async function captureInteractionScreenshot(explorer, beforeScreenshot, state, transition, options) {
+    const page = explorer.page;
     if (!page) {
         return null;
     }
     mkdirSync(options.screenshotsDir, { recursive: true });
     const pageName = sanitizeFilename(state.url || 'page') || 'page';
     const stateName = sanitizeFilename(transition.targetState?.label || transition.action) || 'state';
-    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}`, '.png'));
-    const focus = detectFocusArea(state.ariaSnapshot || null);
-    try {
-        if (focus.detected) {
-            await page.locator('[role="dialog"], [role="alertdialog"], [aria-modal="true"]').last().screenshot({ path: filePath });
-        }
-        else {
-            await page.screenshot({ path: filePath });
-        }
-    }
-    catch {
+    const stateId = state.id ? `_${state.id}` : '';
+    const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_${stateName}${stateId}`, '.png'));
+    const result = await captureInteractionAfter(page, beforeScreenshot, filePath, transition.changes?.urlChanged !== true);
+    if (result === 'unchanged')
+        return null;
+    if (result === 'failed' && !(await captureViewport(page, filePath)))
         return null;
-    }
     return {
         title: transition.targetState?.label || transition.action,
         path: filePath,
@@ -75,6 +69,21 @@ export async function captureInteractionScreenshot(explorer, state, transition,
         kind: 'state',
     };
 }
+export async function captureBeforeInteraction(explorer) {
+    const page = explorer.page;
+    if (!page)
+        return null;
+    return captureInteractionBefore(page);
+}
+async function captureViewport(page, filePath) {
+    try {
+        await page.screenshot({ path: filePath });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function captureFullPageScreenshot(page, pageName, options) {
     const filePath = path.join(options.screenshotsDir, safeFilename(`${pageName}_page`, '.png'));
     try {

package/dist/models.json

@@ -0,0 +1,30 @@
+{
+  "openrouter": {
+    "model": "openai/gpt-oss-20b:nitro",
+    "visionModel": "google/gemma-4-31b-it:nitro",
+    "agenticModel": "google/gemma-4-31b-it:nitro"
+  },
+  "groq": {
+    "model": "openai/gpt-oss-20b",
+    "visionModel": "qwen/qwen3.6-27b",
+    "agenticModel": "qwen/qwen3.6-27b"
+  },
+  "openai": {
+    "model": "gpt-5.4-nano",
+    "visionModel": "gpt-5.4-nano",
+    "agenticModel": "gpt-5.6-luna"
+  },
+  "anthropic": {
+    "agenticModel": "claude-haiku-4-5-20251001"
+  },
+  "mistral": {
+    "model": "mistral-small-latest",
+    "visionModel": "mistral-small-latest",
+    "agenticModel": "mistral-large-latest"
+  },
+  "google": {
+    "model": "gemini-3.1-flash-lite",
+    "visionModel": "gemini-3.1-flash-lite",
+    "agenticModel": "gemini-3.5-flash"
+  }
+}

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -26,7 +26,8 @@
     "boat/doc-collector/bin/**/*.ts",
     "boat/doc-collector/package.json",
     "rules/",
-    "assets/sample-files/"
+    "assets/sample-files/",
+    "models.json"
   ],
   "scripts": {
     "build": "bun run build:bin",
@@ -68,7 +69,9 @@
   "author": "",
   "dependencies": {
     "@ai-sdk/anthropic": "^4.0",
+    "@ai-sdk/google": "^4.0.18",
     "@ai-sdk/groq": "^4.0",
+    "@ai-sdk/mistral": "^4.0.13",
     "@ai-sdk/openai": "^4.0",
     "@ai-sdk/otel": "^1.0.2",
     "@axe-core/playwright": "^4.11.0",
@@ -111,7 +114,9 @@
     "micromatch": "^4.0.8",
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
+    "pixelmatch": "^7.2.0",
     "playwright": "^1.60",
+    "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",
     "strip-ansi": "^7.1.2",
@@ -128,6 +133,7 @@
     "@types/debug": "^4.1.12",
     "@types/jsdom": "^27.0.0",
     "@types/micromatch": "^4.0.9",
+    "@types/pngjs": "^6.0.5",
     "@types/react": "^18.2.0",
     "@types/yargs": "^17.0.24",
     "bunosh": "^0.4.0",

package/dist/src/action.d.ts

@@ -16,10 +16,16 @@ declare class Action {
         args: any[];
     }>;
     recorder?: PlaywrightRecorder;
+    recovery: RecoveryRunner;
     mainDocumentStatus: number | undefined;
-    constructor(actor: CodeceptJS.I, stateManager: StateManager, recorder?: PlaywrightRecorder);
+    constructor(actor: CodeceptJS.I, stateManager: StateManager, recorder?: PlaywrightRecorder, recovery?: RecoveryRunner);
     saveScreenshot(): Promise<string | undefined>;
-    capturePageState({ includeScreenshot, codeBlock }?: {
+    capturePageState(opts?: {
+        includeScreenshot?: boolean;
+        codeBlock?: string;
+    }): Promise<ActionResult>;
+    execute(code: string): Promise<Action>;
+    captureOnce({ includeScreenshot, codeBlock }?: {
         includeScreenshot?: boolean;
         codeBlock?: string;
     }): Promise<ActionResult>;
@@ -34,10 +40,12 @@ declare class Action {
         id?: string;
     }>>;
     captureBrowserLogs(): Promise<any[]>;
-    execute(code: string): Promise<Action>;
+    executeOnce(code: string): Promise<Action>;
     attempt(codeBlock: string, originalMessage?: string): Promise<boolean>;
+    exitIframe(): Promise<void>;
     getActor(): CodeceptJS.I;
     getActionResult(): ActionResult | null;
     waitForPageReadiness(page: any): Promise<void>;
 }
 export default Action;
+export type RecoveryRunner = <T>(fn: () => Promise<T>) => Promise<T>;

package/dist/src/action.js

@@ -11,8 +11,8 @@ import { browserErrorMessage, isFatalBrowserError, isNavigationTransitionError }
 import { captureHtmlForSnapshot, htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
 import { sleep, waitForPageReadiness } from "./utils/page-readiness.js";
-import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from "./utils/web-sandbox.js";
 import { safeFilename } from "./utils/strings.js";
+import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from "./utils/web-sandbox.js";
 const debugLog = createDebug('explorbot:action');
 const CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS = 3;
 class Action {
@@ -27,13 +27,15 @@ class Action {
     playwrightGroupId = null;
     assertionSteps = [];
     recorder;
+    recovery;
     mainDocumentStatus = undefined;
-    constructor(actor, stateManager, recorder) {
+    constructor(actor, stateManager, recorder, recovery) {
         this.actor = actor;
         this.stateManager = stateManager;
         this.config = ConfigParser.getInstance().getConfig();
         this.playwrightHelper = container.helpers('Playwright');
         this.recorder = recorder;
+        this.recovery = recovery || ((fn) => fn());
     }
     async saveScreenshot() {
         const currentState = this.stateManager.getCurrentState();
@@ -52,7 +54,13 @@ class Action {
             return undefined;
         }
     }
-    async capturePageState({ includeScreenshot = false, codeBlock } = {}) {
+    async capturePageState(opts = {}) {
+        return this.recovery(() => this.captureOnce(opts));
+    }
+    async execute(code) {
+        return this.recovery(() => this.executeOnce(code));
+    }
+    async captureOnce({ includeScreenshot = false, codeBlock } = {}) {
         try {
             const currentState = this.stateManager.getCurrentState();
             const stateHash = currentState?.hash || 'screenshot';
@@ -243,7 +251,7 @@ class Action {
             return [];
         }
     }
-    async execute(code) {
+    async executeOnce(code) {
         let error = null;
         setActivity('🔎 Browsing...', 'action');
         let codeString = code.replace(/^\(I\) => /, '').trim();
@@ -277,7 +285,7 @@ class Action {
             if (executedSteps.length > 0) {
                 codeString = executedSteps.join('\n');
             }
-            const pageState = await this.capturePageState({ codeBlock: codeString });
+            const pageState = await this.captureOnce({ codeBlock: codeString });
             this.actionResult = pageState;
             this.assertionSteps = assertionSteps;
         }
@@ -305,6 +313,7 @@ class Action {
         return this;
     }
     async attempt(codeBlock, originalMessage) {
+        const wasInFrame = !!this.playwrightHelper.frame;
         try {
             debugLog('Resolution attempt...');
             setActivity('🦾 Acting in browser...', 'action');
@@ -319,10 +328,18 @@ class Action {
             this.lastError = error;
             if (isFatalBrowserError(error))
                 throw error;
+            if (!wasInFrame)
+                await this.exitIframe().catch(() => { });
             debugLog(`Attempt failed: ${codeBlock}: ${errorToString(error) || this.lastError?.toString()}`);
             return false;
         }
     }
+    async exitIframe() {
+        if (!this.playwrightHelper.frame)
+            return;
+        debugLog('Switching to main frame');
+        await this.playwrightHelper.switchTo();
+    }
     getActor() {
         return this.actor;
     }

package/dist/src/ai/agent.d.ts

@@ -1,3 +1,20 @@
+import type { RequestStore } from '../api/request-store.js';
+import type { ExplorbotConfig } from '../config.js';
+import type Explorer from '../explorer.js';
+import type { KnowledgeTracker } from '../knowledge-tracker.js';
+import type { PlaywrightRecorder } from '../playwright-recorder.js';
+import type { StateManager } from '../state-manager.js';
+import type { AIProvider } from './provider.js';
 export interface Agent {
     emoji?: string;
 }
+export interface AgentDeps {
+    explorer: Explorer;
+    ai: AIProvider;
+    config: ExplorbotConfig;
+    stateManager: StateManager;
+    knowledgeTracker: KnowledgeTracker;
+    requestStore: RequestStore;
+    playwrightRecorder: PlaywrightRecorder;
+}
+export type ToolDeps = Pick<AgentDeps, 'explorer' | 'stateManager' | 'ai'>;

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

@@ -60,7 +60,7 @@ export function WithIdleMode(Base) {
                             if (!action || action === 'replace') {
                                 plan.tests.length = 0;
                             }
-                            const currentUrl = ctx.explorBot.getExplorer().getStateManager().getCurrentState()?.url || '';
+                            const currentUrl = ctx.explorBot.stateManager().getCurrentState()?.url || '';
                             for (const testInput of tests) {
                                 const priority = testInput.priority || 'normal';
                                 const expected = testInput.expected?.length ? testInput.expected : [];

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

@@ -144,7 +144,7 @@ export function WithTestMode(Base) {
                             states = t.states;
                         }
                         else {
-                            const stateManager = ctx.explorBot.getExplorer().getStateManager();
+                            const stateManager = ctx.explorBot.stateManager();
                             const history = stateManager.getStateHistory();
                             const seen = new Set();
                             states = history

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

@@ -8,9 +8,10 @@ export function WithWebMode(Base) {
     return class extends Base {
         webModeTools(ctx) {
             const explorer = ctx.explorBot.getExplorer();
-            const codeceptTools = createCodeceptJSTools(explorer, ctx.task);
+            const toolDeps = { explorer, stateManager: ctx.explorBot.stateManager(), ai: ctx.explorBot.getProvider() };
+            const codeceptTools = createCodeceptJSTools(toolDeps, ctx.task);
             const agentTools = createAgentTools({
-                explorer,
+                ...toolDeps,
                 researcher: ctx.explorBot.agentResearcher(),
                 navigator: ctx.explorBot.agentNavigator(),
             });
@@ -25,7 +26,7 @@ export function WithWebMode(Base) {
                         try {
                             debugLog('navigate', destination);
                             await ctx.explorBot.agentNavigator().visit(destination);
-                            const stateManager = ctx.explorBot.getExplorer().getStateManager();
+                            const stateManager = ctx.explorBot.stateManager();
                             const state = stateManager.getCurrentState();
                             return { success: true, url: state?.url, title: state?.title };
                         }
@@ -43,43 +44,38 @@ export function WithWebMode(Base) {
             - closeTabs: Close all browser tabs except the current one
             - 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
+            - recover: Recover from a closed/crashed page, escalating to a full browser restart when needed
+            - openTab: Open a fresh tab in the current browser context
           `,
                     inputSchema: z.object({
-                        action: z.enum(['status', 'evaluate', 'closeTabs', 'reload', 'screenshot', 'recover', 'restart', 'openFreshTab']).describe('Browser action to perform'),
+                        action: z.enum(['status', 'evaluate', 'closeTabs', 'reload', 'screenshot', 'recover', 'openTab']).describe('Browser action to perform'),
                         code: z.string().optional().describe('JavaScript code for evaluate action'),
                     }),
                     execute: async ({ action, code }) => {
                         const explorer = ctx.explorBot.getExplorer();
                         if (action === 'status') {
-                            const page = explorer.playwrightHelper?.page;
+                            const page = explorer.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,
+                                isClosed: !page,
+                                url: page ? await page.url() : null,
+                                title: page ? 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' };
+                            const { ok } = await explorer.recover();
+                            return { success: ok, message: ok ? '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();
+                        if (action === 'openTab') {
+                            await ctx.explorBot.openTab();
+                            const state = ctx.explorBot.stateManager().getCurrentState();
                             return { success: true, url: state?.url, title: state?.title };
                         }
-                        const page = explorer.playwrightHelper?.page;
-                        if (!page || page.isClosed?.())
+                        const page = explorer.page;
+                        if (!page)
                             return { success: false, message: 'No browser page available. Try browser({ action: "recover" }) first.' };
                         if (action === 'evaluate') {
                             if (!code)

package/dist/src/ai/captain.js

@@ -37,7 +37,7 @@ export class Captain extends CaptainBase {
     getHooksRunner() {
         if (!this.hooksRunner) {
             const explorer = this.explorBot.getExplorer();
-            this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
+            this.hooksRunner = new HooksRunner(explorer, this.explorBot.getConfig());
         }
         return this.hooksRunner;
     }
@@ -72,18 +72,17 @@ export class Captain extends CaptainBase {
     getMode() {
         const explorer = this.explorBot.getExplorer();
         const activeTest = explorer.activeTest;
-        const page = explorer.playwrightHelper?.page;
-        if (activeTest && (!page || page.isClosed?.()))
+        if (activeTest && !explorer.page)
             return 'heal';
         if (activeTest)
             return 'test';
-        if (explorer.getStateManager().getCurrentState())
+        if (this.explorBot.stateManager().getCurrentState())
             return 'web';
         return 'idle';
     }
     systemPrompt() {
         const mode = this.getMode();
-        const currentUrl = this.explorBot.getExplorer().getStateManager().getCurrentState()?.url;
+        const currentUrl = this.explorBot.stateManager().getCurrentState()?.url;
         const customPrompt = this.explorBot.getProvider().getSystemPromptForAgent('captain', currentUrl);
         return dedent `
     <role>
@@ -127,7 +126,7 @@ export class Captain extends CaptainBase {
         return this.conversation;
     }
     async getPageContext() {
-        const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             return 'No page loaded';
         }
@@ -197,10 +196,9 @@ export class Captain extends CaptainBase {
     `;
     }
     async reinjectContextIfNeeded(conversation, currentState) {
-        if (conversation.hasTag('page_html', 5))
-            return Promise.resolve();
+        if (conversation.hasTag('page_aria', 5))
+            return;
         const actionResult = ActionResult.fromState(currentState);
-        const html = await actionResult.combinedHtml();
         const context = dedent `
         Context:
 
@@ -212,13 +210,8 @@ export class Captain extends CaptainBase {
         <page_aria>
         ${actionResult.getInteractiveARIA()}
         </page_aria>
-
-        <page_html>
-        ${html}
-        </page_html>
       `;
         conversation.addUserText(context);
-        return Promise.resolve();
     }
     coreTools(task, onDone) {
         return {
@@ -248,15 +241,8 @@ 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})` : '';
-                    return `${c.name} — ${c.description}${opts}`;
-                })
-                    .join('\n')}
+          Use only when the user request itself starts with a slash command; pass it through verbatim.
+          Available commands: ${this.commandDescriptions.map((c) => c.name).join(', ')}
         `,
                 inputSchema: z.object({
                     command: z.string().describe('Slash command to execute, e.g. "/research", "/plan authentication", "/test brave-fox123"'),
@@ -314,7 +300,7 @@ export class Captain extends CaptainBase {
             recentToolSummary = execs.map((e) => `${e.toolName}: ${e.wasSuccessful ? 'ok' : 'fail'} ${truncateJson(e.input)}`).join('\n');
         }
         const pilotAnalysis = this.explorBot.agentPilot().getLastAnalysis() || '';
-        const currentUrl = this.explorBot.getExplorer().getStateManager().getCurrentState()?.url || '';
+        const currentUrl = this.explorBot.stateManager().getCurrentState()?.url || '';
         const schema = z.object({
             action: z.enum(['inject', 'stop', 'pass', 'skip']),
             message: z.string().describe('Message to pass to the tester or display to user'),
@@ -356,7 +342,7 @@ export class Captain extends CaptainBase {
     }
     async processExecutionError(error, activeTest) {
         const explorer = this.explorBot.getExplorer();
-        const result = await explorer.handleExecutionError(error);
+        const result = await explorer.recover(error);
         return {
             ...result,
             message: result.recovered ? `${result.message}\nContinue the test "${activeTest.scenario}" from the restored page.` : result.message,
@@ -366,7 +352,7 @@ export class Captain extends CaptainBase {
         return (this.recentToolCalls || []).some(hasBrowserCompletionEvidence);
     }
     async handle(input, options = {}) {
-        const stateManager = this.explorBot.getExplorer().getStateManager();
+        const stateManager = this.explorBot.stateManager();
         const initialState = stateManager.getCurrentState();
         const conversation = options.reset ? this.resetConversation() : this.ensureConversation();
         let isDone = false;
@@ -426,6 +412,7 @@ export class Captain extends CaptainBase {
             const result = await this.explorBot.getProvider().invokeConversation(conversation, tools, {
                 maxToolRoundtrips: 5,
                 toolChoice: 'auto',
+                stopWhen: () => isDone,
             });
             if (!result) {
                 stop();