explorbot 0.2.0 → 0.2.1

package/dist/src/state-manager.d.ts

@@ -1,6 +1,6 @@
 import { ActionResult } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
-import type { KnowledgeTracker, Knowledge } from './knowledge-tracker.js';
+import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
 export interface Link {
     title: string;
     url: string;
@@ -55,8 +55,13 @@ export interface StateTransition {
     trigger: 'manual' | 'navigation' | 'automatic';
 }
 export type StateChangeListener = (event: StateTransition) => void;
+export interface TabInfo {
+    url: string;
+    title: string;
+}
 export type { Knowledge };
 export declare class StateManager {
+    otherTabs: TabInfo[];
     currentState: WebPageState | null;
     stateHistory: StateTransition[];
     allVisitedUrls: Set<string>;

package/dist/src/state-manager.js

@@ -5,6 +5,7 @@ import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 const debugLog = createDebug('explorbot:state');
 export class StateManager {
+    otherTabs = [];
     currentState = null;
     stateHistory = [];
     allVisitedUrls = new Set();

package/dist/src/utils/hooks-runner.js

@@ -49,12 +49,10 @@ export class HooksRunner {
     async executeHook(hook, url) {
         try {
             if (hook.type === 'playwright') {
-                const page = this.explorer.playwrightHelper.page;
-                await hook.hook({ page, url });
+                await this.explorer.withPage(async (page) => hook.hook({ page, url }));
             }
             else {
-                const I = this.explorer.actor;
-                await hook.hook({ I, url });
+                await hook.hook({ I: this.explorer.actor, url });
             }
         }
         catch (error) {

package/dist/src/utils/test-files.js

@@ -64,7 +64,7 @@ export async function dryRunTestFile(filePath) {
             Playwright: { browser: config.playwright.browser, url: config.playwright.url },
         },
     };
-    global.output_dir = path.join(projectRoot, 'output', 'states');
+    global.output_dir = ConfigParser.getInstance().getStatesDir();
     global.codecept_dir = projectRoot;
     codeceptjs.container.create(codeceptConfig, {});
     await codeceptjs.recorder.start();

package/dist/src/utils/web-annotate.d.ts

@@ -0,0 +1,5 @@
+import { WebElement } from './web-element.js';
+export declare function annotatePageElements(page: any): Promise<{
+    ariaSnapshot: string;
+    elements: WebElement[];
+}>;

package/dist/src/utils/web-annotate.js

@@ -0,0 +1,58 @@
+import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from "./html.js";
+import { createDebug } from './logger.js';
+import { WebElement } from "./web-element.js";
+const debugLog = createDebug('explorbot:web-annotate');
+const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
+const ANNOTATABLE_ROLES = new Set(['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'switch', 'combobox', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'treeitem']);
+function parseAriaRefs(ariaSnapshot) {
+    const entries = [];
+    for (const line of ariaSnapshot.split('\n')) {
+        const match = line.match(REF_LINE_PATTERN);
+        if (!match)
+            continue;
+        if (!ANNOTATABLE_ROLES.has(match[2]))
+            continue;
+        entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
+    }
+    return entries;
+}
+export async function annotatePageElements(page) {
+    const ariaSnapshot = await page.locator('body').ariaSnapshot({ mode: 'ai' });
+    const refEntries = parseAriaRefs(ariaSnapshot);
+    const byRole = new Map();
+    for (const { role, name, ref } of refEntries) {
+        let list = byRole.get(role);
+        if (!list) {
+            list = [];
+            byRole.set(role, list);
+        }
+        list.push({ name, ref });
+    }
+    const elements = [];
+    for (const [role, entries] of byRole) {
+        try {
+            const rawList = await page.getByRole(role).evaluateAll((domElements, [data, extractFnStr, config]) => {
+                const extract = new Function(`return ${extractFnStr}`)();
+                const results = [];
+                let ariaIdx = 0;
+                for (const el of domElements) {
+                    if (ariaIdx >= data.length)
+                        break;
+                    el.setAttribute(config.attrs.eidx, data[ariaIdx].ref);
+                    const elData = extract(el, config);
+                    if (elData)
+                        results.push(elData);
+                    ariaIdx++;
+                }
+                return results;
+            }, [entries, getElementDataExtractorSource(), ELEMENT_EXTRACTION_CONFIG]);
+            for (const raw of rawList) {
+                elements.push(WebElement.fromRawData(raw, role));
+            }
+        }
+        catch {
+            debugLog(`Failed to annotate role=${role}`);
+        }
+    }
+    return { ariaSnapshot, elements };
+}

package/dist/src/utils/web-eidx.d.ts

@@ -0,0 +1,2 @@
+export declare function eidxInContainer(page: any, containerCss: string | null): Promise<string[]>;
+export declare function eidxByLocator(page: any, locator: string, container?: string | null): Promise<string | null>;

package/dist/src/utils/web-eidx.js

@@ -0,0 +1,20 @@
+import { ELEMENT_EXTRACTION_CONFIG } from "./html.js";
+export async function eidxInContainer(page, containerCss) {
+    const selector = containerCss ? `${containerCss} [${ELEMENT_EXTRACTION_CONFIG.attrs.eidx}]` : `[${ELEMENT_EXTRACTION_CONFIG.attrs.eidx}]`;
+    const elements = await page.locator(selector).all();
+    const result = [];
+    for (const el of elements) {
+        const attr = await el.getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx).catch(() => null);
+        if (attr)
+            result.push(attr);
+    }
+    return result;
+}
+export async function eidxByLocator(page, locator, container) {
+    const base = container ? page.locator(container) : page;
+    const el = locator.startsWith('//') ? base.locator(`xpath=${locator}`) : base.locator(locator);
+    return el
+        .first()
+        .getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx)
+        .catch(() => null);
+}

package/dist/src/utils/web-element.d.ts

@@ -37,6 +37,7 @@ export declare class WebElement {
     static fromPlaywrightLocator(locator: any): Promise<WebElement | null>;
     static fromEidx(page: any, eidx: string): Promise<WebElement | null>;
     static fromEidxList(page: any, eidxList: string[]): Promise<WebElement[]>;
+    static commonAncestor(page: any, eidxList: string[]): Promise<WebElement | null>;
     static findByXPath(html: string, xpath: string): Promise<{
         totalFound: number;
         elements: WebElement[];

package/dist/src/utils/web-element.js

@@ -130,6 +130,35 @@ export class WebElement {
         }, [validEidxList, getElementDataExtractorSource(), ELEMENT_EXTRACTION_CONFIG]);
         return rawList.map((d) => WebElement.fromRawData(d));
     }
+    static async commonAncestor(page, eidxList) {
+        const validEidxList = eidxList.filter((eidx) => /^e\d+$/i.test(eidx));
+        if (validEidxList.length < 2)
+            return null;
+        const raw = await page.evaluate(([list, extractFnStr, config]) => {
+            const extract = new Function(`return ${extractFnStr}`)();
+            const els = [];
+            for (const eidx of list) {
+                const el = document.querySelector(`[${config.attrs.eidx}="${eidx}"]`);
+                if (el && !els.includes(el))
+                    els.push(el);
+            }
+            if (els.length < 2)
+                return null;
+            const containsAll = (node) => els.every((el) => node.contains(el));
+            let ancestor = els[0].parentElement;
+            while (ancestor && !containsAll(ancestor))
+                ancestor = ancestor.parentElement;
+            if (!ancestor)
+                return null;
+            const tag = ancestor.tagName.toLowerCase();
+            if (tag === 'body' || tag === 'html')
+                return null;
+            return extract(ancestor, config);
+        }, [validEidxList, getElementDataExtractorSource(), ELEMENT_EXTRACTION_CONFIG]);
+        if (!raw)
+            return null;
+        return WebElement.fromRawData(raw);
+    }
     static async findByXPath(html, xpath) {
         const result = await evaluateXPath(html, xpath);
         if (result.error)

package/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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",

package/src/action.ts

@@ -14,8 +14,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.ts';
-import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from './utils/web-sandbox.ts';
 import { safeFilename } from './utils/strings.ts';
+import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from './utils/web-sandbox.ts';
 
 const debugLog = createDebug('explorbot:action');
 const CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS = 3;
@@ -33,14 +33,16 @@ class Action {
   public playwrightGroupId: string | null = null;
   public assertionSteps: Array<{ name: string; args: any[] }> = [];
   private recorder?: PlaywrightRecorder;
+  private recovery: RecoveryRunner;
   private mainDocumentStatus: number | undefined = undefined;
 
-  constructor(actor: CodeceptJS.I, stateManager: StateManager, recorder?: PlaywrightRecorder) {
+  constructor(actor: CodeceptJS.I, stateManager: StateManager, recorder?: PlaywrightRecorder, recovery?: RecoveryRunner) {
     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(): Promise<string | undefined> {
@@ -59,7 +61,15 @@ class Action {
     }
   }
 
-  async capturePageState({ includeScreenshot = false, codeBlock }: { includeScreenshot?: boolean; codeBlock?: string } = {}): Promise<ActionResult> {
+  async capturePageState(opts: { includeScreenshot?: boolean; codeBlock?: string } = {}): Promise<ActionResult> {
+    return this.recovery(() => this.captureOnce(opts));
+  }
+
+  async execute(code: string): Promise<Action> {
+    return this.recovery(() => this.executeOnce(code));
+  }
+
+  private async captureOnce({ includeScreenshot = false, codeBlock }: { includeScreenshot?: boolean; codeBlock?: string } = {}): Promise<ActionResult> {
     try {
       const currentState = this.stateManager.getCurrentState();
       const stateHash = currentState?.hash || 'screenshot';
@@ -260,7 +270,7 @@ class Action {
     }
   }
 
-  async execute(code: string): Promise<Action> {
+  private async executeOnce(code: string): Promise<Action> {
     let error: Error | null = null;
 
     setActivity('🔎 Browsing...', 'action');
@@ -301,7 +311,7 @@ class Action {
         codeString = executedSteps.join('\n');
       }
 
-      const pageState = await this.capturePageState({ codeBlock: codeString });
+      const pageState = await this.captureOnce({ codeBlock: codeString });
 
       this.actionResult = pageState;
       this.assertionSteps = assertionSteps;
@@ -329,6 +339,7 @@ class Action {
   }
 
   public async attempt(codeBlock: string, originalMessage?: string): Promise<boolean> {
+    const wasInFrame = !!this.playwrightHelper.frame;
     try {
       debugLog('Resolution attempt...');
       setActivity('🦾 Acting in browser...', 'action');
@@ -343,11 +354,18 @@ class Action {
     } catch (error) {
       this.lastError = error as 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(): Promise<void> {
+    if (!this.playwrightHelper.frame) return;
+    debugLog('Switching to main frame');
+    await this.playwrightHelper.switchTo();
+  }
+
   getActor(): CodeceptJS.I {
     return this.actor;
   }
@@ -366,6 +384,8 @@ class Action {
 
 export default Action;
 
+export type RecoveryRunner = <T>(fn: () => Promise<T>) => Promise<T>;
+
 function errorToString(error: any): string {
   if (error.cliMessage) {
     return error.cliMessage();

package/src/ai/agent.ts

@@ -1,3 +1,23 @@
+import type { RequestStore } from '../api/request-store.ts';
+import type { ExplorbotConfig } from '../config.ts';
+import type Explorer from '../explorer.ts';
+import type { KnowledgeTracker } from '../knowledge-tracker.ts';
+import type { PlaywrightRecorder } from '../playwright-recorder.ts';
+import type { StateManager } from '../state-manager.ts';
+import type { AIProvider } from './provider.ts';
+
 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/src/ai/captain/idle-mode.ts

@@ -66,7 +66,7 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
               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/src/ai/captain/test-mode.ts

@@ -146,7 +146,7 @@ export function WithTestMode<T extends Constructor>(Base: T) {
               if (!t) return { success: false, message: `Test "${session}" not found` };
               states = t.states;
             } else {
-              const stateManager = ctx.explorBot.getExplorer().getStateManager();
+              const stateManager = ctx.explorBot.stateManager();
               const history = stateManager.getStateHistory();
               const seen = new Set<string>();
               states = history

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

@@ -9,9 +9,10 @@ export function WithWebMode<T extends Constructor>(Base: T) {
   return class extends Base {
     webModeTools(ctx: ModeContext): Record<string, any> {
       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(),
       });
@@ -27,7 +28,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
             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 };
             } catch (error: any) {
@@ -45,48 +46,42 @@ export function WithWebMode<T extends Constructor>(Base: T) {
             - 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?.()) return { success: false, message: 'No browser page available. Try browser({ action: "recover" }) first.' };
+            const page = explorer.page;
+            if (!page) 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' };

package/src/ai/captain.ts

@@ -49,7 +49,7 @@ export class Captain extends CaptainBase implements Agent {
   private getHooksRunner(): HooksRunner {
     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;
   }
@@ -89,17 +89,16 @@ export class Captain extends CaptainBase implements Agent {
   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 && !explorer.page) return 'heal';
     if (activeTest) return 'test';
-    if (explorer.getStateManager().getCurrentState()) return 'web';
+    if (this.explorBot.stateManager().getCurrentState()) return 'web';
     return 'idle';
   }
 
   private systemPrompt(): string {
     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`
@@ -147,7 +146,7 @@ export class Captain extends CaptainBase implements Agent {
   }
 
   private async getPageContext(): Promise<string> {
-    const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+    const state = this.explorBot.stateManager().getCurrentState();
     if (!state) {
       return 'No page loaded';
     }
@@ -221,10 +220,9 @@ export class Captain extends CaptainBase implements Agent {
   }
 
   private async reinjectContextIfNeeded(conversation: Conversation, currentState: WebPageState): Promise<void> {
-    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:
 
@@ -236,13 +234,8 @@ export class Captain extends CaptainBase implements Agent {
         <page_aria>
         ${actionResult.getInteractiveARIA()}
         </page_aria>
-
-        <page_html>
-        ${html}
-        </page_html>
       `;
     conversation.addUserText(context);
-    return Promise.resolve();
   }
 
   private coreTools(task: Task, onDone: (summary: string) => void) {
@@ -273,15 +266,8 @@ 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})` : '';
-              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"'),
@@ -339,7 +325,7 @@ export class Captain extends CaptainBase implements Agent {
     }
 
     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']),
@@ -390,7 +376,7 @@ export class Captain extends CaptainBase implements Agent {
 
   async processExecutionError(error: Error, activeTest: Test): Promise<ExecutionRecoveryAction> {
     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,
@@ -402,7 +388,7 @@ export class Captain extends CaptainBase implements Agent {
   }
 
   async handle(input: string, options: { reset?: boolean } = {}): Promise<string | null> {
-    const stateManager = this.explorBot.getExplorer().getStateManager();
+    const stateManager = this.explorBot.stateManager();
     const initialState = stateManager.getCurrentState();
 
     const conversation = options.reset ? this.resetConversation() : this.ensureConversation();
@@ -477,6 +463,7 @@ export class Captain extends CaptainBase implements Agent {
         const result = await this.explorBot.getProvider().invokeConversation(conversation, tools, {
           maxToolRoundtrips: 5,
           toolChoice: 'auto',
+          stopWhen: () => isDone,
         });
 
         if (!result) {