explorbot 0.2.0 → 0.2.2

package/dist/src/ai/tester.js

@@ -10,7 +10,6 @@ import { Stats } from "../stats.js";
 import { TestResult } from "../test-plan.js";
 import { detectFocusArea, extractFocusedElement } from "../utils/aria.js";
 import { ErrorPageError, isErrorPage } from "../utils/error-page.js";
-import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
 import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from "./rules.js";
@@ -31,8 +30,8 @@ export class Tester extends TaskAgent {
     ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
     SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
     emoji = '🧪';
-    explorer;
-    provider;
+    requestStore;
+    testRun = null;
     currentConversation = null;
     pilot = null;
     captain = null;
@@ -46,32 +45,20 @@ export class Tester extends TaskAgent {
     previousStateHash = null;
     pageStateHash = null;
     pageActionResult = null;
-    hooksRunner;
     seenUiMapUrls = new Set();
     lastAnalyzedStateHash = null;
     stalledIterations = 0;
     MAX_STALLED_ITERATIONS = 3;
-    constructor(explorer, provider, researcher, navigator, agentTools) {
-        super();
-        this.explorer = explorer;
-        this.provider = provider;
+    constructor(deps, researcher, navigator, agentTools) {
+        super(deps);
+        this.requestStore = deps.requestStore;
         this.researcher = researcher;
         this.navigator = navigator;
         this.agentTools = agentTools;
-        this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
     }
     getNavigator() {
         return this.navigator;
     }
-    getExperienceTracker() {
-        return this.explorer.getStateManager().getExperienceTracker();
-    }
-    getKnowledgeTracker() {
-        return this.explorer.getKnowledgeTracker();
-    }
-    getProvider() {
-        return this.provider;
-    }
     setPilot(pilot) {
         this.pilot = pilot;
     }
@@ -79,17 +66,17 @@ export class Tester extends TaskAgent {
         this.captain = captain;
     }
     getCurrentState() {
-        return ActionResult.fromState(this.explorer.getStateManager().getCurrentState());
+        return ActionResult.fromState(this.stateManager.getCurrentState());
     }
     get progressCheckInterval() {
-        return this.explorer.getConfig().ai?.agents?.tester?.progressCheckInterval ?? 3;
+        return this.config.ai?.agents?.tester?.progressCheckInterval ?? 3;
     }
     getConversation() {
         return this.currentConversation;
     }
     async test(task) {
         Stats.tests++;
-        const state = this.explorer.getStateManager().getCurrentState();
+        const state = this.stateManager.getCurrentState();
         if (!state)
             throw new Error('No state found');
         setActivity(`🧪 Testing: ${task.scenario}`, 'action');
@@ -100,18 +87,18 @@ export class Tester extends TaskAgent {
         this.seenUiMapUrls.clear();
         this.lastAnalyzedStateHash = null;
         this.stalledIterations = 0;
-        this.explorer.getStateManager().clearHistory();
+        this.stateManager.clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
-        const requestStore = this.explorer.getRequestStore();
-        requestStore?.clear();
-        const offFailedRequest = requestStore?.onFailedRequest((r) => {
+        const requestStore = this.requestStore;
+        requestStore.clear();
+        const offFailedRequest = requestStore.onFailedRequest((r) => {
             task.addNote(`Network error: ${r.method} ${r.path} → ${r.status}`, TestResult.FAILED);
         });
         const initialState = ActionResult.fromState(state);
         if (isErrorPage(initialState)) {
             task.start();
-            await this.explorer.startTest(task);
+            this.testRun = await this.explorer.beginTest(task);
             offFailedRequest?.();
             return await this.abortStartedTestOnErrorPage(task, initialState);
         }
@@ -158,7 +145,8 @@ export class Tester extends TaskAgent {
             }
         }
         debugLog('Starting test execution with tools');
-        if (!(await this.explorer.startTest(task))) {
+        this.testRun = await this.explorer.beginTest(task);
+        if (!this.testRun.started) {
             offFailedRequest?.();
             await this.cleanupStartedTest(task);
             return { success: task.isSuccessful };
@@ -175,7 +163,7 @@ export class Tester extends TaskAgent {
                 return { success: task.isSuccessful };
             }
         }
-        const startState = this.explorer.getStateManager().getCurrentState();
+        const startState = this.stateManager.getCurrentState();
         if (startState) {
             task.addUrlNote(startState);
             const startActionResult = ActionResult.fromState(startState);
@@ -186,7 +174,7 @@ export class Tester extends TaskAgent {
         }
         const currentUrl = startState?.url || task.startUrl || '';
         await this.hooksRunner.runBeforeHook('tester', currentUrl);
-        const offStateChange = this.explorer.getStateManager().onStateChange((event) => {
+        const offStateChange = this.stateManager.onStateChange((event) => {
             if (task.hasFinished)
                 return;
             if (event.toState?.url === event.fromState?.url)
@@ -195,7 +183,7 @@ export class Tester extends TaskAgent {
                 task.addUrlNote(event.toState, event.fromState || undefined);
             task.states.push(event.toState);
         });
-        const codeceptjsTools = createCodeceptJSTools(this.explorer, task);
+        const codeceptjsTools = createCodeceptJSTools(this.toolDeps, task);
         let assertionPerformed = false;
         let extensions = 0;
         let shouldContinue = true;
@@ -203,7 +191,7 @@ export class Tester extends TaskAgent {
             shouldContinue = false;
             await loop(async ({ stop, pause, iteration, userInput }) => {
                 debugLog('iteration', iteration);
-                if (!(await this.explorer.ensurePageAvailable())) {
+                if (!(await this.explorer.recover()).ok) {
                     task.addNote('Browser page is unavailable');
                     task.finish(TestResult.FAILED);
                     stop();
@@ -216,10 +204,10 @@ export class Tester extends TaskAgent {
                     ...this.agentTools,
                 };
                 if (currentState.isInsideIframe) {
-                    Object.assign(tools, createIframeTools(this.explorer));
+                    Object.assign(tools, createIframeTools(this.toolDeps));
                 }
                 debugLog(`Test ${task.scenario} iteration ${iteration}`);
-                if (this.explorer.getStateManager().isInDeadLoop()) {
+                if (this.stateManager.isInDeadLoop()) {
                     task.addNote('Dead loop detected. Stopped');
                     stop();
                     return;
@@ -354,7 +342,7 @@ export class Tester extends TaskAgent {
             });
             if (task.hasFinished)
                 break;
-            if (!(await this.explorer.ensurePageAvailable()))
+            if (!(await this.explorer.recover()).ok)
                 break;
             const finalState = this.getCurrentState();
             const wantsContinue = await this.pilot.finalReview(task, finalState, conversation, this.navigator);
@@ -372,7 +360,7 @@ export class Tester extends TaskAgent {
             conversation.compactToolResults(1);
             shouldContinue = true;
         }
-        const finalUrl = this.explorer.getStateManager().getCurrentState()?.url || currentUrl;
+        const finalUrl = this.stateManager.getCurrentState()?.url || currentUrl;
         await this.hooksRunner.runAfterHook('tester', finalUrl);
         await this.getHistorian().saveSession(task, initialState, conversation);
         if (task.plan) {
@@ -382,7 +370,7 @@ export class Tester extends TaskAgent {
         offStateChange();
         offFailedRequest?.();
         await this.finishTest(task);
-        await this.explorer.stopTest(task, this.buildStopTestMeta(task));
+        await this.testRun?.stop(this.buildStopTestMeta(task));
         return {
             success: task.isSuccessful,
             ...task,
@@ -486,7 +474,7 @@ export class Tester extends TaskAgent {
       `;
         }
         if (currentState.isInsideIframe) {
-            const iframeInfo = currentState.iframeURL || this.explorer.getCurrentIframeInfo() || 'iframe context active';
+            const iframeInfo = currentState.iframeURL || 'iframe context active';
             context += dedent `
         <iframe_context>
         INSIDE IFRAME: ${iframeInfo}
@@ -494,10 +482,10 @@ export class Tester extends TaskAgent {
         </iframe_context>
       `;
         }
-        if (this.explorer.hasOtherTabs()) {
-            const otherTabs = this.explorer.getOtherTabsInfo();
+        const otherTabs = this.stateManager.otherTabs;
+        if (otherTabs.length > 0) {
             context += multipleTabsRule(otherTabs);
-            this.explorer.clearOtherTabsInfo();
+            this.stateManager.otherTabs = [];
         }
         if (isNewUrl) {
             const alreadySeenUiMap = this.seenUiMapUrls.has(currentUrl);
@@ -600,7 +588,7 @@ export class Tester extends TaskAgent {
         task.addNote(error.message, TestResult.FAILED, actionResult.screenshotFile, actionResult.fullUrl || actionResult.url);
         task.finish(TestResult.FAILED);
         this.finishTest(task);
-        await this.explorer.stopTest(task, this.buildStopTestMeta(task));
+        await this.testRun?.stop(this.buildStopTestMeta(task));
         clearActivity(true);
         return { success: false };
     }
@@ -715,7 +703,7 @@ export class Tester extends TaskAgent {
 
     ${dataProtectionRules}
 
-    ${this.provider.getSystemPromptForAgent('tester', this.explorer.getStateManager().getCurrentState()?.url) || ''}
+    ${this.provider.getSystemPromptForAgent('tester', this.stateManager.getCurrentState()?.url) || ''}
     `;
     }
     buildScenarioBlock(task, actionResult) {
@@ -759,7 +747,7 @@ export class Tester extends TaskAgent {
             .map((t) => t.sessionName);
     }
     buildAvailableFiles() {
-        const userFiles = this.explorer.getConfig().files || {};
+        const userFiles = this.config.files || {};
         const codeceptDir = global.codecept_dir || process.cwd();
         const lines = [];
         for (const [description, filename] of Object.entries(SAMPLE_FILES)) {
@@ -813,10 +801,8 @@ export class Tester extends TaskAgent {
                     reason: z.string().optional().describe('Explanation why reset is the only option'),
                 }),
                 execute: async ({ reason }) => {
-                    if (this.getCurrentState().isInsideIframe) {
-                        await this.explorer.switchToMainFrame();
-                    }
-                    const currentState = this.explorer.getStateManager().getCurrentState();
+                    await this.explorer.action().exitIframe();
+                    const currentState = this.stateManager.getCurrentState();
                     const currentUrl = currentState?.fullUrl || currentState?.url;
                     if (currentUrl === resetUrl) {
                         return {
@@ -841,7 +827,7 @@ export class Tester extends TaskAgent {
                     const explanation = reason ? `${reason} (RESET)` : 'Resetting to initial page';
                     const targetUrl = resetUrl;
                     task.addNote(explanation);
-                    const resetAction = this.explorer.createAction();
+                    const resetAction = this.explorer.action();
                     const success = await resetAction.attempt(`I.amOnPage(${JSON.stringify(targetUrl)})`, explanation);
                     if (success) {
                         return {
@@ -984,7 +970,7 @@ export class Tester extends TaskAgent {
                     else if (input.status === 'fail') {
                         mappedStatus = TestResult.FAILED;
                     }
-                    const screenshotFile = this.explorer.getStateManager().getCurrentState()?.screenshotFile;
+                    const screenshotFile = this.stateManager.getCurrentState()?.screenshotFile;
                     for (const noteText of input.notes) {
                         task.addNote(noteText, mappedStatus, screenshotFile);
                         if (input.status === 'success') {
@@ -1021,7 +1007,7 @@ export class Tester extends TaskAgent {
         const message = error instanceof Error ? error.message : String(error);
         if (!task.hasFinished)
             task.addNote(`Execution error: ${message}`);
-        const result = await this.explorer.handleExecutionError(error);
+        const result = await this.explorer.recover(error);
         tag('info').log(`Browser supervisor: ${result.action} - ${result.message}`);
         task.addNote(result.message);
         if (result.action === 'stop') {
@@ -1052,7 +1038,7 @@ export class Tester extends TaskAgent {
     }
     async cleanupStartedTest(task) {
         await this.finishTest(task);
-        await this.explorer.stopTest(task, {
+        await this.testRun?.stop({
             startUrl: task.startUrl,
             style: task.style,
             sessionName: task.sessionName,

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

@@ -1,11 +1,17 @@
 import { ActionResult, type PageDiff } from '../action-result.js';
 import type { ExperienceTracker } from '../experience-tracker.js';
-import type Explorer from '../explorer.js';
 import { type Task } from '../test-plan.js';
+import type { ToolDeps } from './agent.js';
 import { Navigator } from './navigator.js';
 import { Researcher } from './researcher.js';
+interface AgentToolDeps extends ToolDeps {
+    researcher: Researcher;
+    navigator: Navigator;
+    supervisor?: boolean;
+    withExperience?: boolean;
+}
 export declare const ASSERTION_TOOLS: readonly ["verify"];
-export declare function createCodeceptJSTools(explorer: Explorer, task: Task): {
+export declare function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps, task: Task): {
     click: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
         commands: any;
         explanation: any;
@@ -24,7 +30,7 @@ export declare function createCodeceptJSTools(explorer: Explorer, task: Task): {
         explanation: any;
     }, Record<string, any>, import("@ai-sdk/provider-utils").Context>>;
 };
-export declare function createIframeTools(explorer: Explorer): {
+export declare function createIframeTools({ explorer, stateManager }: ToolDeps): {
     exitIframe: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
         reason?: string;
     }, Record<string, any>, import("@ai-sdk/provider-utils").Context>>;
@@ -42,11 +48,6 @@ export declare function createLearnExperienceTool({ getExperienceTracker, getSta
 } | {
     error: string;
 }, import("@ai-sdk/provider-utils").Context>>;
-export declare function createAgentTools({ explorer, researcher, navigator, supervisor, withExperience, }: {
-    explorer: Explorer;
-    researcher: Researcher;
-    navigator: Navigator;
-    supervisor?: boolean;
-    withExperience?: boolean;
-}): any;
+export declare function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }: AgentToolDeps): any;
 export declare function isMajorPageChange(pageDiff: PageDiff): boolean;
+export {};

package/dist/src/ai/tools.js

@@ -12,8 +12,7 @@ import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 const debugLog = createDebug('explorbot:tools');
 export const ASSERTION_TOOLS = ['verify'];
-export function createCodeceptJSTools(explorer, task) {
-    const stateManager = explorer.getStateManager();
+export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
     return {
         click: tool({
             description: dedent `
@@ -68,7 +67,7 @@ export function createCodeceptJSTools(explorer, task) {
                     return `I.click(${JSON.stringify(trimmed)})`;
                 });
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                const action = explorer.createAction();
+                const action = explorer.action();
                 const attempts = [];
                 for (let i = 0; i < commands.length; i++) {
                     const command = transformContainsCommand(commands[i]);
@@ -85,7 +84,7 @@ export function createCodeceptJSTools(explorer, task) {
                 }
                 let disambiguated = null;
                 if (attempts.some((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
-                    disambiguated = await disambiguateElements(action.lastError, explanation, explorer.getAIProvider());
+                    disambiguated = await disambiguateElements(action.lastError, explanation, ai);
                 }
                 if (disambiguated) {
                     debugLog('Disambiguation picked element %d', disambiguated.position);
@@ -163,7 +162,7 @@ export function createCodeceptJSTools(explorer, task) {
                     return `I.moveCursorTo(${JSON.stringify(trimmed)})`;
                 });
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                const action = explorer.createAction();
+                const action = explorer.action();
                 const attempts = [];
                 for (const command of commands) {
                     const success = await action.attempt(command, explanation);
@@ -223,7 +222,7 @@ export function createCodeceptJSTools(explorer, task) {
                     const keyToUse = matchingStandardKey || key;
                     if (!isSingleChar && !isStandardKey) {
                         const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                        const action = explorer.createAction();
+                        const action = explorer.action();
                         const typeCommand = `I.type(${JSON.stringify(key)})`;
                         await action.attempt(typeCommand, explanation);
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, key);
@@ -257,7 +256,7 @@ export function createCodeceptJSTools(explorer, task) {
                         }
                     }
                     const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                    const action = explorer.createAction();
+                    const action = explorer.action();
                     let pressKeyCommand;
                     if (modifier) {
                         const modifiers = Array.isArray(modifier) ? modifier : [modifier];
@@ -347,19 +346,15 @@ export function createCodeceptJSTools(explorer, task) {
                     }
                     const previousState = ActionResult.fromState(stateManager.getCurrentState());
                     const formLocator = codeLines[0] || 'form';
-                    const action = explorer.createAction();
-                    const wasInIframe = await explorer.isInsideIframe();
+                    const action = explorer.action();
                     await action.attempt(codeBlock, explanation);
-                    if (action.lastError && !wasInIframe && (await explorer.isInsideIframe())) {
-                        await explorer.switchToMainFrame();
-                    }
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, formLocator);
                     if (action.lastError) {
                         const message = action.lastError ? String(action.lastError) : 'Unknown error';
                         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                         let formSuggestion = 'Look into error message and identify which commands passed and which failed. Continue execution using step-by-step approach using click() and form() tools.';
                         if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
-                            const disambiguated = await disambiguateElements(action.lastError, explanation, explorer.getAIProvider());
+                            const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
                             if (disambiguated) {
                                 formSuggestion = `Multiple elements matched. Add step.opts({ elementIndex: ${disambiguated.position} }) to the failing command. Fallback locator: ${disambiguated.xpath}`;
                             }
@@ -397,8 +392,7 @@ export function createCodeceptJSTools(explorer, task) {
         }),
     };
 }
-export function createIframeTools(explorer) {
-    const stateManager = explorer.getStateManager();
+export function createIframeTools({ explorer, stateManager }) {
     return {
         exitIframe: tool({
             description: dedent `
@@ -418,8 +412,9 @@ export function createIframeTools(explorer) {
                             suggestion: 'Continue interacting with the current page context.',
                         });
                     }
-                    await explorer.switchToMainFrame();
-                    const nextState = await explorer.capturePageState();
+                    const action = explorer.action();
+                    await action.execute('I.switchTo()');
+                    const nextState = action.getActionResult();
                     const toolResult = await nextState.toToolResult(previousState, 'I.switchTo()');
                     return successToolResult('exitIframe', {
                         ...toolResult,
@@ -460,7 +455,7 @@ export function createLearnExperienceTool({ getExperienceTracker, getState }) {
         },
     });
 }
-export function createAgentTools({ explorer, researcher, navigator, supervisor, withExperience, }) {
+export function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }) {
     let visionDisabled = false;
     const tools = {
         see: tool({
@@ -483,7 +478,7 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
                     return failedToolResult('see', 'Vision tools are disabled for this session. Use context() to get fresh ARIA snapshot and analyze page state from ARIA data.');
                 }
                 try {
-                    const actionResult = await explorer.capturePageWithScreenshot();
+                    const actionResult = await explorer.capture({ screenshot: true });
                     if (!actionResult.screenshot) {
                         return failedToolResult('see', 'Failed to capture screenshot for analysis');
                     }
@@ -527,7 +522,6 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
             }),
             execute: async ({ reason }) => {
                 try {
-                    const stateManager = explorer.getStateManager();
                     const currentState = stateManager.getCurrentState();
                     if (!currentState) {
                         return failedToolResult('context', 'No current page state available.');
@@ -565,7 +559,7 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
             }),
             execute: async ({ assertion }) => {
                 try {
-                    const currentState = explorer.getStateManager().getCurrentState();
+                    const currentState = stateManager.getCurrentState();
                     const verifications = currentState?.verifications;
                     if (verifications?.[assertion] !== undefined) {
                         return failedToolResult('verify', `Already verified: "${assertion}" → ${verifications[assertion] ? 'PASS' : 'FAIL'}`, {
@@ -574,7 +568,7 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
                             suggestion: verifications[assertion] ? 'This verification already passed. Call finish() to complete the test.' : 'This verification already failed. Perform actions to change the page state, then try again.',
                         });
                     }
-                    const actionResult = await explorer.capturePageState();
+                    const actionResult = await explorer.capture();
                     const result = await navigator.verifyState(assertion, actionResult);
                     if (result.verified) {
                         return successToolResult('verify', {
@@ -618,7 +612,6 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
             }),
             execute: async ({ reason }) => {
                 try {
-                    const stateManager = explorer.getStateManager();
                     const currentState = stateManager.getCurrentState();
                     if (!currentState) {
                         return failedToolResult('research', 'No current page state available. Navigate to a page first.');
@@ -659,7 +652,6 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
             }),
             execute: async ({ instruction }) => {
                 try {
-                    const stateManager = explorer.getStateManager();
                     const currentState = stateManager.getCurrentState();
                     if (!currentState) {
                         return failedToolResult('interact', 'No current page state available. Navigate to a page first.');
@@ -708,14 +700,13 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
                     return failedToolResult('visualClick', 'Vision tools are disabled for this session. Use xpathCheck() to find the element, then click() with the discovered locator.');
                 }
                 try {
-                    const stateManager = explorer.getStateManager();
                     const currentState = stateManager.getCurrentState();
                     if (!currentState) {
                         return failedToolResult('visualClick', 'No current page state available.');
                     }
                     const previousState = ActionResult.fromState(currentState);
-                    const action = explorer.createAction();
-                    const actionResult = await explorer.capturePageWithScreenshot();
+                    const action = explorer.action();
+                    const actionResult = await explorer.capture({ screenshot: true });
                     if (!actionResult.screenshot) {
                         return failedToolResult('visualClick', 'Failed to capture screenshot for visual analysis');
                     }
@@ -768,7 +759,6 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
                 reason: z.string().describe('Why you need to go back'),
             }),
             execute: async ({ reason }) => {
-                const stateManager = explorer.getStateManager();
                 const currentState = stateManager.getCurrentState();
                 const currentUrl = currentState?.fullUrl || currentState?.url;
                 const history = stateManager.getStateHistory();
@@ -788,7 +778,7 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
                 let previousState = null;
                 if (currentState)
                     previousState = ActionResult.fromState(currentState);
-                const action = explorer.createAction();
+                const action = explorer.action();
                 const success = await action.attempt(`I.amOnPage(${JSON.stringify(targetUrl)})`, `${reason} (BACK to ${targetUrl})`);
                 if (success) {
                     const newState = ActionResult.fromState(stateManager.getCurrentState());
@@ -808,7 +798,7 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
             description: 'List all previously visited page states (deduped by URL). Use to find pages to navigate back to.',
             inputSchema: z.object({}),
             execute: async () => {
-                const history = explorer.getStateManager().getStateHistory();
+                const history = stateManager.getStateHistory();
                 const seen = new Set();
                 const states = history
                     .map((t) => t.toState)
@@ -841,7 +831,6 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
                 reason: z.string().describe('What element you are looking for and why'),
             }),
             execute: async ({ xpath, reason }) => {
-                const stateManager = explorer.getStateManager();
                 const currentState = stateManager.getCurrentState();
                 if (!currentState) {
                     return failedToolResult('xpathCheck', 'No current page state available.');
@@ -861,9 +850,9 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
                         suggestion: 'Try a broader expression. Examples: //*[contains(@class, "btn")], //button, //*[contains(text(), "keyword")]',
                     });
                 }
-                const action = explorer.createAction();
+                const action = explorer.action();
                 const visible = await action.attempt(`I.seeElement(${JSON.stringify(xpath)})`, 'xpathCheck visibility');
-                const liveElement = await WebElement.fromPlaywrightLocator(explorer.playwrightHelper.page.locator(`xpath=${xpath}`));
+                const liveElement = await explorer.withPage((page) => WebElement.fromPlaywrightLocator(page.locator(`xpath=${xpath}`)));
                 const matchesSummary = result.elements.map((el, i) => `${i + 1}. <${el.tag} ${el.keyAttrs}> text="${el.text}" html: ${el.outerHTML}`).join('\n');
                 const visibilityNote = visible ? 'Element IS visible in browser — Tester can use this XPath as locator.' : 'Element exists in DOM but is NOT visible. May need scrolling, a click to reveal, or is hidden.';
                 const hit = liveElement?.ourAttr('hit') || null;
@@ -888,9 +877,8 @@ export function createAgentTools({ explorer, researcher, navigator, supervisor,
     };
     if (withExperience !== false) {
         tools.learnExperience = createLearnExperienceTool({
-            getExperienceTracker: () => explorer.getStateManager().getExperienceTracker(),
+            getExperienceTracker: () => stateManager.getExperienceTracker(),
             getState: () => {
-                const stateManager = explorer.getStateManager();
                 const currentState = stateManager.getCurrentState();
                 return currentState ? ActionResult.fromState(currentState) : null;
             },
@@ -1103,7 +1091,7 @@ async function disambiguateElements(error, explanation, provider) {
             Return the position number, or null if none of them match.
           `,
             },
-        ], schema, provider.getAgenticModel(), { agentName: 'disambiguator', timeout: 15000 });
+        ], schema, provider.getModelForAgent(), { agentName: 'disambiguator', timeout: 15000 });
         const position = result?.object?.position;
         if (position && position >= 1 && position <= elementDetails.length) {
             return { position, xpath: elementDetails[position - 1].xpath };

package/dist/src/command-handler.js

@@ -131,7 +131,7 @@ export class CommandHandler {
         }
     }
     async executeBrowserCommand(input) {
-        const action = this.explorBot.getExplorer().createAction();
+        const action = this.explorBot.getExplorer().action();
         await action.execute(input);
     }
     isCommand(input) {

package/dist/src/commands/context-aria-command.js

@@ -4,7 +4,7 @@ export class ContextAriaCommand extends BaseCommand {
     name = 'context:aria';
     description = 'Print full ARIA snapshot for current page';
     async execute(_args) {
-        const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to snapshot');
         }

package/dist/src/commands/context-command.js

@@ -1,8 +1,10 @@
 import { Researcher } from '../ai/researcher.js';
+import { visuallyAnnotateContainers } from '../ai/researcher/coordinates.js';
 import { outputPath } from '../config.js';
 import { formatContextSummary } from '../utils/context-formatter.js';
 import { tag } from '../utils/logger.js';
 import { extractValidContainers } from '../utils/research-parser.js';
+import { annotatePageElements } from '../utils/web-annotate.js';
 import { BaseCommand } from './base-command.js';
 export class ContextCommand extends BaseCommand {
     name = 'context';
@@ -22,20 +24,20 @@ export class ContextCommand extends BaseCommand {
     ];
     async execute(args) {
         const explorer = this.explorBot.getExplorer();
-        const state = explorer.getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to show context for');
         }
         const { opts } = this.parseArgs(args);
         const isVisual = !!(opts.visual || opts.screenshot);
-        await explorer.annotateElements();
+        await explorer.withPage(annotatePageElements);
         if (isVisual) {
             const cachedResearch = Researcher.getCachedResearch(state);
             const containers = cachedResearch ? extractValidContainers(cachedResearch) : [];
-            await explorer.visuallyAnnotateElements({ containers });
+            await explorer.withPage((page) => visuallyAnnotateContainers(page, containers));
         }
-        const actionResult = await explorer.createAction().capturePageState({ includeScreenshot: isVisual });
-        const experienceTracker = explorer.getStateManager().getExperienceTracker();
+        const actionResult = await explorer.capture({ screenshot: isVisual });
+        const experienceTracker = this.explorBot.experienceTracker();
         const knowledgeTracker = this.explorBot.knowledgeTracker();
         let mode = 'compact';
         if (opts.full) {

package/dist/src/commands/context-data-command.js

@@ -6,14 +6,14 @@ export class ContextDataCommand extends BaseCommand {
     description = 'Extract structured data from current page';
     async execute(_args) {
         const explorer = this.explorBot.getExplorer();
-        const state = explorer.getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to extract data from');
         }
         const actionResult = ActionResult.fromState(state);
         if (!actionResult.html || actionResult.html.trim().length < 100) {
             tag('info').log('Capturing fresh page content...');
-            const freshResult = await explorer.createAction().capturePageState();
+            const freshResult = await explorer.capture();
             const table = await this.explorBot.agentResearcher().extractData(freshResult);
             tag('multiline').log(table);
             return;

package/dist/src/commands/context-experience-command.js

@@ -8,12 +8,12 @@ export class ContextExperienceCommand extends BaseCommand {
     description = 'Print all matching experience for current page';
     async execute(_args) {
         const explorer = this.explorBot.getExplorer();
-        const state = explorer.getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page');
         }
         const actionResult = ActionResult.fromState(state);
-        const experienceTracker = explorer.getStateManager().getExperienceTracker();
+        const experienceTracker = this.explorBot.experienceTracker();
         const experience = experienceTracker.getRelevantExperience(actionResult);
         if (experience.length === 0) {
             tag('info').log(`No experience found for: ${actionResult.url}`);