explorbot 0.2.0 → 0.2.1

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

@@ -4,10 +4,6 @@ import { Command } from 'commander';
 import { setPreserveConsoleLogs } from "../../../src/utils/logger.js";
 import { DocBot } from "./docbot.js";
 function buildOptions(options) {
-    let session = options.session;
-    if (options.session === true) {
-        session = 'output/session.json';
-    }
     return {
         verbose: options.verbose || options.debug,
         config: options.config,
@@ -15,7 +11,7 @@ function buildOptions(options) {
         show: options.show,
         headless: options.headless,
         incognito: options.incognito,
-        session,
+        session: options.session,
         docsConfig: options.docsConfig,
     };
 }

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

@@ -7,10 +7,10 @@ import { sanitizeFilename } from "../../../src/utils/strings.js";
 import { Documentarian } from "./ai/documentarian.js";
 import { DocbotConfigParser } from "./config.js";
 import { renderPageDocumentation, renderSpecIndex } from "./docs-renderer.js";
-import { renderMermaidBody } from "./state-diagram.js";
 import { getDocPageKey, shouldCrawlDocPath } from "./path-filter.js";
 import { extractResearchNavigationTargets } from "./research-navigation.js";
 import { captureDocumentationScreenshots, captureInteractionScreenshot } from "./screenshots.js";
+import { renderMermaidBody } from "./state-diagram.js";
 class DocBot {
     explorBot;
     configParser;
@@ -39,7 +39,7 @@ class DocBot {
             config: this.options.docsConfig,
             path: this.options.path,
         });
-        this.documentarian = new Documentarian(this.explorBot.getProvider(), this.config, this.explorBot.getExplorer());
+        this.documentarian = new Documentarian(this.explorBot.getProvider(), this.config, this.explorBot.getExplorer(), this.explorBot.stateManager());
         this.ensureDirectory(this.configParser.getOutputDir());
         this.ensureDirectory(this.getPagesDir());
     }
@@ -66,7 +66,7 @@ class DocBot {
             if (documented.has(targetKey)) {
                 continue;
             }
-            const stateManager = this.explorBot.getExplorer().getStateManager();
+            const stateManager = this.explorBot.stateManager();
             if (stateManager.hasVisitedState(target)) {
                 continue;
             }

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

@@ -5,7 +5,7 @@ import { detectFocusArea } from "../../../src/utils/aria.js";
 import { safeFilename, sanitizeFilename } from "../../../src/utils/strings.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 [];
     }
@@ -48,7 +48,7 @@ export function getScreenshotSections(research) {
     return sections;
 }
 export async function captureInteractionScreenshot(explorer, state, transition, options) {
-    const page = explorer.playwrightHelper?.page;
+    const page = explorer.page;
     if (!page) {
         return null;
     }

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.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/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();

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

@@ -1,13 +1,8 @@
 import { ActionResult } from '../action-result.js';
-import type { ExperienceTracker } from '../experience-tracker.js';
-import type Explorer from '../explorer.js';
-import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import { Plan, Test } from '../test-plan.js';
-import { HooksRunner } from '../utils/hooks-runner.js';
 import { WebElement } from '../utils/web-element.js';
-import type { Agent } from './agent.js';
+import type { Agent, AgentDeps } from './agent.js';
 import type { Navigator } from './navigator.js';
-import type { Provider } from './provider.js';
 import { TaskAgent } from './task-agent.js';
 interface ComponentInfo {
     id: string;
@@ -48,10 +43,7 @@ interface DrillOptions {
 export declare class Driller extends TaskAgent implements Agent {
     readonly ACTION_TOOLS: string[];
     emoji: string;
-    explorer: Explorer;
-    provider: Provider;
     navigator: Navigator;
-    hooksRunner: HooksRunner;
     currentPlan?: Plan;
     allResults: InteractionResult[];
     verifiedAction: {
@@ -62,11 +54,8 @@ export declare class Driller extends TaskAgent implements Agent {
     } | null;
     pendingNestedContext: string | null;
     MAX_COMPONENT_ITERATIONS: number;
-    constructor(explorer: Explorer, provider: Provider, navigator: Navigator);
+    constructor(deps: AgentDeps, navigator: Navigator);
     getNavigator(): Navigator;
-    getExperienceTracker(): ExperienceTracker;
-    getKnowledgeTracker(): KnowledgeTracker;
-    getProvider(): Provider;
     getSystemMessage(component?: ComponentInfo): string;
     drill(opts?: DrillOptions): Promise<Plan>;
     captureAnnotatedState(): Promise<ActionResult>;