explorbot 0.2.0 → 0.2.2

package/src/ai/tester.ts

@@ -5,18 +5,17 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.ts';
 import { clearActivity, setActivity } from '../activity.ts';
-import type { ExperienceTracker } from '../experience-tracker.ts';
-import type Explorer from '../explorer.ts';
+import type { RequestStore } from '../api/request-store.ts';
+import type { TestRun } from '../explorer.ts';
 import { Observability } from '../observability.ts';
 import type { StateTransition } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Test, TestResult, type TestResultType } from '../test-plan.ts';
 import { detectFocusArea, extractFocusedElement } from '../utils/aria.ts';
 import { ErrorPageError, isErrorPage } from '../utils/error-page.ts';
-import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
-import type { Agent } from './agent.ts';
+import type { Agent, AgentDeps } from './agent.ts';
 import type { Captain } from './captain.ts';
 import type { Conversation } from './conversation.ts';
 import { Navigator } from './navigator.ts';
@@ -44,8 +43,8 @@ export class Tester extends TaskAgent implements Agent {
   protected readonly ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
   protected readonly SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
   emoji = '🧪';
-  private explorer: Explorer;
-  private provider: Provider;
+  private requestStore: RequestStore;
+  private testRun: TestRun | null = null;
   private currentConversation: Conversation | null = null;
   private pilot: Pilot | null = null;
   private captain: Captain | null = null;
@@ -60,38 +59,23 @@ export class Tester extends TaskAgent implements Agent {
   private previousStateHash: string | null = null;
   private pageStateHash: string | null = null;
   private pageActionResult: ActionResult | null = null;
-  private hooksRunner: HooksRunner;
   private seenUiMapUrls = new Set<string>();
   private lastAnalyzedStateHash: string | null = null;
   private stalledIterations = 0;
   private readonly MAX_STALLED_ITERATIONS = 3;
 
-  constructor(explorer: Explorer, provider: Provider, researcher: Researcher, navigator: Navigator, agentTools?: any) {
-    super();
-    this.explorer = explorer;
-    this.provider = provider;
+  constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any) {
+    super(deps);
+    this.requestStore = deps.requestStore;
     this.researcher = researcher;
     this.navigator = navigator;
     this.agentTools = agentTools;
-    this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
   }
 
   protected getNavigator(): Navigator {
     return this.navigator;
   }
 
-  protected getExperienceTracker(): ExperienceTracker {
-    return this.explorer.getStateManager().getExperienceTracker();
-  }
-
-  protected getKnowledgeTracker() {
-    return this.explorer.getKnowledgeTracker();
-  }
-
-  protected getProvider(): Provider {
-    return this.provider;
-  }
-
   setPilot(pilot: Pilot): void {
     this.pilot = pilot;
   }
@@ -101,11 +85,11 @@ export class Tester extends TaskAgent implements Agent {
   }
 
   private getCurrentState(): ActionResult {
-    return ActionResult.fromState(this.explorer.getStateManager().getCurrentState()!);
+    return ActionResult.fromState(this.stateManager.getCurrentState()!);
   }
 
   private get progressCheckInterval(): number {
-    return (this.explorer.getConfig().ai?.agents?.tester as any)?.progressCheckInterval ?? 3;
+    return (this.config.ai?.agents?.tester as any)?.progressCheckInterval ?? 3;
   }
 
   getConversation(): Conversation | null {
@@ -114,7 +98,7 @@ export class Tester extends TaskAgent implements Agent {
 
   async test(task: Test): Promise<{ success: boolean }> {
     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');
@@ -126,20 +110,20 @@ export class Tester extends TaskAgent implements Agent {
     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);
     }
@@ -196,7 +180,8 @@ export class Tester extends TaskAgent implements Agent {
 
     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 };
@@ -214,7 +199,7 @@ export class Tester extends TaskAgent implements Agent {
       }
     }
 
-    const startState = this.explorer.getStateManager().getCurrentState();
+    const startState = this.stateManager.getCurrentState();
     if (startState) {
       task.addUrlNote(startState);
       const startActionResult = ActionResult.fromState(startState);
@@ -226,14 +211,14 @@ export class Tester extends TaskAgent implements Agent {
     const currentUrl = startState?.url || task.startUrl || '';
     await this.hooksRunner.runBeforeHook('tester', currentUrl);
 
-    const offStateChange = this.explorer.getStateManager().onStateChange((event: StateTransition) => {
+    const offStateChange = this.stateManager.onStateChange((event: StateTransition) => {
       if (task.hasFinished) return;
       if (event.toState?.url === event.fromState?.url) return;
       if (event.toState) 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;
@@ -244,7 +229,7 @@ export class Tester extends TaskAgent implements Agent {
       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();
@@ -258,12 +243,12 @@ export class Tester extends TaskAgent implements Agent {
             ...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;
@@ -412,7 +397,7 @@ export class Tester extends TaskAgent implements Agent {
 
       if (task.hasFinished) break;
 
-      if (!(await this.explorer.ensurePageAvailable())) break;
+      if (!(await this.explorer.recover()).ok) break;
 
       const finalState = this.getCurrentState();
       const wantsContinue = await this.pilot!.finalReview(task, finalState, conversation, this.navigator);
@@ -431,7 +416,7 @@ export class Tester extends TaskAgent implements Agent {
       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);
@@ -443,7 +428,7 @@ export class Tester extends TaskAgent implements Agent {
     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,
@@ -559,7 +544,7 @@ export class Tester extends TaskAgent implements Agent {
     }
 
     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}
@@ -568,10 +553,10 @@ export class Tester extends TaskAgent implements Agent {
       `;
     }
 
-    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) {
@@ -675,7 +660,7 @@ export class Tester extends TaskAgent implements Agent {
     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 };
   }
@@ -790,7 +775,7 @@ export class Tester extends TaskAgent implements Agent {
 
     ${dataProtectionRules}
 
-    ${this.provider.getSystemPromptForAgent('tester', this.explorer.getStateManager().getCurrentState()?.url) || ''}
+    ${this.provider.getSystemPromptForAgent('tester', this.stateManager.getCurrentState()?.url) || ''}
     `;
   }
 
@@ -837,7 +822,7 @@ export class Tester extends TaskAgent implements Agent {
   }
 
   private buildAvailableFiles(): string {
-    const userFiles = this.explorer.getConfig().files || {};
+    const userFiles = this.config.files || {};
     const codeceptDir = (global as any).codecept_dir || process.cwd();
     const lines: string[] = [];
 
@@ -895,11 +880,9 @@ export class Tester extends TaskAgent implements Agent {
           reason: z.string().optional().describe('Explanation why reset is the only option'),
         }),
         execute: async ({ reason }) => {
-          if (this.getCurrentState().isInsideIframe) {
-            await this.explorer.switchToMainFrame();
-          }
+          await this.explorer.action().exitIframe();
 
-          const currentState = this.explorer.getStateManager().getCurrentState();
+          const currentState = this.stateManager.getCurrentState();
           const currentUrl = currentState?.fullUrl || currentState?.url;
           if (currentUrl === resetUrl!) {
             return {
@@ -927,7 +910,7 @@ export class Tester extends TaskAgent implements Agent {
           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) {
@@ -1076,7 +1059,7 @@ export class Tester extends TaskAgent implements Agent {
             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);
@@ -1117,7 +1100,7 @@ export class Tester extends TaskAgent implements Agent {
     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);
 
@@ -1152,7 +1135,7 @@ export class Tester extends TaskAgent implements Agent {
 
   private async cleanupStartedTest(task: Test): Promise<void> {
     await this.finishTest(task);
-    await this.explorer.stopTest(task, {
+    await this.testRun?.stop({
       startUrl: task.startUrl,
       style: task.style,
       sessionName: task.sessionName,

package/src/ai/tools.ts

@@ -3,13 +3,13 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
-import type Explorer from '../explorer.ts';
 import { type Task, TestResult } from '../test-plan.js';
 import { LARGE_ARIA_CHANGE_THRESHOLD, extractFocusedElement } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
+import type { ToolDeps } from './agent.ts';
 import { Navigator } from './navigator.ts';
 import type { AIProvider } from './provider.ts';
 import { Researcher } from './researcher.ts';
@@ -18,11 +18,16 @@ import { isInteractive } from './task-agent.ts';
 
 const debugLog = createDebug('explorbot:tools');
 
-export const ASSERTION_TOOLS = ['verify'] as const;
+interface AgentToolDeps extends ToolDeps {
+  researcher: Researcher;
+  navigator: Navigator;
+  supervisor?: boolean;
+  withExperience?: boolean;
+}
 
-export function createCodeceptJSTools(explorer: Explorer, task: Task) {
-  const stateManager = explorer.getStateManager();
+export const ASSERTION_TOOLS = ['verify'] as const;
 
+export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps, task: Task) {
   return {
     click: tool({
       description: dedent`
@@ -81,7 +86,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
         });
 
         const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-        const action = explorer.createAction();
+        const action = explorer.action();
         const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
 
         for (let i = 0; i < commands.length; i++) {
@@ -101,7 +106,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: 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) {
@@ -193,7 +198,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
         });
 
         const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-        const action = explorer.createAction();
+        const action = explorer.action();
         const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
 
         for (const command of commands) {
@@ -263,7 +268,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
 
           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);
@@ -306,7 +311,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
           }
 
           const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-          const action = explorer.createAction();
+          const action = explorer.action();
 
           let pressKeyCommand: string;
           if (modifier) {
@@ -406,14 +411,9 @@ export function createCodeceptJSTools(explorer: Explorer, task: 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) {
@@ -422,7 +422,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
 
             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}`;
               }
@@ -471,9 +471,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
   };
 }
 
-export function createIframeTools(explorer: Explorer) {
-  const stateManager = explorer.getStateManager();
-
+export function createIframeTools({ explorer, stateManager }: ToolDeps) {
   return {
     exitIframe: tool({
       description: dedent`
@@ -495,9 +493,9 @@ export function createIframeTools(explorer: Explorer) {
             });
           }
 
-          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', {
@@ -540,19 +538,7 @@ export function createLearnExperienceTool({ getExperienceTracker, getState }: {
   });
 }
 
-export function createAgentTools({
-  explorer,
-  researcher,
-  navigator,
-  supervisor,
-  withExperience,
-}: {
-  explorer: Explorer;
-  researcher: Researcher;
-  navigator: Navigator;
-  supervisor?: boolean;
-  withExperience?: boolean;
-}): any {
+export function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }: AgentToolDeps): any {
   let visionDisabled = false;
 
   const tools: Record<string, any> = {
@@ -577,7 +563,7 @@ export function createAgentTools({
         }
 
         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');
@@ -625,7 +611,6 @@ export function createAgentTools({
       }),
       execute: async ({ reason }) => {
         try {
-          const stateManager = explorer.getStateManager();
           const currentState = stateManager.getCurrentState();
 
           if (!currentState) {
@@ -666,7 +651,7 @@ export function createAgentTools({
       }),
       execute: async ({ assertion }) => {
         try {
-          const currentState = explorer.getStateManager().getCurrentState();
+          const currentState = stateManager.getCurrentState();
           const verifications = currentState?.verifications;
 
           if (verifications?.[assertion] !== undefined) {
@@ -677,7 +662,7 @@ export function createAgentTools({
             });
           }
 
-          const actionResult = await explorer.capturePageState();
+          const actionResult = await explorer.capture();
           const result = await navigator.verifyState(assertion, actionResult);
 
           if (result.verified) {
@@ -727,7 +712,6 @@ export function createAgentTools({
       }),
       execute: async ({ reason }) => {
         try {
-          const stateManager = explorer.getStateManager();
           const currentState = stateManager.getCurrentState();
 
           if (!currentState) {
@@ -771,7 +755,6 @@ export function createAgentTools({
       }),
       execute: async ({ instruction }) => {
         try {
-          const stateManager = explorer.getStateManager();
           const currentState = stateManager.getCurrentState();
 
           if (!currentState) {
@@ -826,7 +809,6 @@ export function createAgentTools({
         }
 
         try {
-          const stateManager = explorer.getStateManager();
           const currentState = stateManager.getCurrentState();
 
           if (!currentState) {
@@ -834,8 +816,8 @@ export function createAgentTools({
           }
 
           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');
@@ -897,7 +879,6 @@ export function createAgentTools({
         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();
@@ -920,7 +901,7 @@ export function createAgentTools({
         let previousState: ActionResult | null = 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) {
@@ -942,7 +923,7 @@ export function createAgentTools({
       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<string>();
         const states = history
           .map((t) => t.toState)
@@ -975,7 +956,6 @@ export function createAgentTools({
         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) {
@@ -1001,9 +981,9 @@ export function createAgentTools({
           });
         }
 
-        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');
 
@@ -1033,9 +1013,8 @@ export function createAgentTools({
 
   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;
       },
@@ -1270,7 +1249,7 @@ async function disambiguateElements(error: Error | null | undefined, explanation
         },
       ],
       schema,
-      provider.getAgenticModel(),
+      provider.getModelForAgent(),
       { agentName: 'disambiguator', timeout: 15000 }
     );
 

package/src/command-handler.ts

@@ -178,7 +178,7 @@ export class CommandHandler implements InputManager {
   }
 
   private async executeBrowserCommand(input: string): Promise<void> {
-    const action = this.explorBot.getExplorer().createAction();
+    const action = this.explorBot.getExplorer().action();
     await action.execute(input);
   }
 

package/src/commands/context-aria-command.ts

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

package/src/commands/context-command.ts

@@ -1,9 +1,11 @@
 import { ActionResult } from '../action-result.js';
 import { Researcher } from '../ai/researcher.js';
+import { visuallyAnnotateContainers } from '../ai/researcher/coordinates.js';
 import { outputPath } from '../config.js';
 import { type ContextData, type ContextMode, 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, type Suggestion } from './base-command.js';
 
 export class ContextCommand extends BaseCommand {
@@ -25,7 +27,7 @@ export class ContextCommand extends BaseCommand {
 
   async execute(args: string): Promise<void> {
     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');
@@ -34,16 +36,16 @@ export class ContextCommand extends BaseCommand {
     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: ContextMode = 'compact';

package/src/commands/context-data-command.ts

@@ -8,7 +8,7 @@ export class ContextDataCommand extends BaseCommand {
 
   async execute(_args: string): Promise<void> {
     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');
@@ -18,7 +18,7 @@ export class ContextDataCommand extends BaseCommand {
 
     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;