explorbot 0.2.0 → 0.2.1

package/src/ai/driller.ts

@@ -3,13 +3,9 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.ts';
 import { setActivity } from '../activity.ts';
-import type { ExperienceTracker } from '../experience-tracker.ts';
-import type Explorer from '../explorer.ts';
-import type { KnowledgeTracker } from '../knowledge-tracker.ts';
 import { Observability } from '../observability.ts';
 import { Plan, Test, TestResult } from '../test-plan.ts';
 import { collectInteractiveNodes } from '../utils/aria.ts';
-import { HooksRunner } from '../utils/hooks-runner.ts';
 import {
   EXPLORBOT_ATTRS,
   HTML_COMPOSITE_AREA_HINTS,
@@ -26,8 +22,10 @@ import {
 } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop, pause } from '../utils/loop.ts';
+import { annotatePageElements } from '../utils/web-annotate.ts';
+import { eidxInContainer } from '../utils/web-eidx.ts';
 import { WebElement } from '../utils/web-element.ts';
-import type { Agent } from './agent.ts';
+import type { Agent, AgentDeps } from './agent.ts';
 import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import { drillLocatorRule } from './rules.ts';
@@ -79,10 +77,7 @@ interface DrillOptions {
 export class Driller extends TaskAgent implements Agent {
   protected readonly ACTION_TOOLS = ['click', 'pressKey', 'form'];
   emoji = 'D';
-  private explorer: Explorer;
-  private provider: Provider;
   private navigator: Navigator;
-  private hooksRunner: HooksRunner;
   private currentPlan?: Plan;
   private allResults: InteractionResult[] = [];
   private verifiedAction: { componentId: string; toolName: string; code?: string; canonicalCode?: string } | null = null;
@@ -90,32 +85,17 @@ export class Driller extends TaskAgent implements Agent {
 
   MAX_COMPONENT_ITERATIONS = 12;
 
-  constructor(explorer: Explorer, provider: Provider, navigator: Navigator) {
-    super();
-    this.explorer = explorer;
-    this.provider = provider;
+  constructor(deps: AgentDeps, navigator: Navigator) {
+    super(deps);
     this.navigator = navigator;
-    this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
   }
 
   protected getNavigator(): Navigator {
     return this.navigator;
   }
 
-  protected getExperienceTracker(): ExperienceTracker {
-    return this.explorer.getStateManager().getExperienceTracker();
-  }
-
-  protected getKnowledgeTracker(): KnowledgeTracker {
-    return this.explorer.getKnowledgeTracker();
-  }
-
-  protected getProvider(): Provider {
-    return this.provider;
-  }
-
   getSystemMessage(component?: ComponentInfo): string {
-    const currentUrl = this.explorer.getStateManager().getCurrentState()?.url;
+    const currentUrl = this.stateManager.getCurrentState()?.url;
     const customPrompt = this.provider.getSystemPromptForAgent('driller', currentUrl);
 
     return dedent`
@@ -159,7 +139,7 @@ export class Driller extends TaskAgent implements Agent {
 
   async drill(opts: DrillOptions = {}): Promise<Plan> {
     const { knowledgePath, maxComponents = 30, interactive = isInteractive() } = opts;
-    const currentState = this.explorer.getStateManager().getCurrentState();
+    const currentState = this.stateManager.getCurrentState();
     if (!currentState) throw new Error('No page state available');
 
     const sessionName = `driller_${Date.now().toString(36)}`;
@@ -207,15 +187,15 @@ export class Driller extends TaskAgent implements Agent {
 
   private async captureAnnotatedState(): Promise<ActionResult> {
     setActivity(`${this.emoji} Capturing annotated page state...`, 'action');
-    const action = this.explorer.createAction();
+    const action = this.explorer.action();
     try {
       const annotated = await Promise.race([
-        this.explorer.annotateElements(),
+        this.explorer.withPage(annotatePageElements),
         new Promise<never>((_, reject) => {
           setTimeout(() => reject(new Error('annotateElements timeout')), 15000);
         }),
       ]);
-      return action.capturePageState({ ariaSnapshot: annotated.ariaSnapshot });
+      return action.capturePageState();
     } catch (error) {
       tag('warning').log(`Annotated capture failed, falling back to plain page state: ${error instanceof Error ? error.message : error}`);
       return action.capturePageState();
@@ -226,9 +206,10 @@ export class Driller extends TaskAgent implements Agent {
 
   private async collectComponents(state: ActionResult, maxComponents: number): Promise<ComponentInfo[]> {
     setActivity(`${this.emoji} Collecting components...`, 'action');
-    const page = this.explorer.playwrightHelper.page;
-    const eidxList = await this.explorer.getEidxInContainer(null);
-    const webElements = await WebElement.fromEidxList(page, eidxList);
+    const webElements = await this.explorer.withPage(async (page) => {
+      const eidxList = await eidxInContainer(page, null);
+      return WebElement.fromEidxList(page, eidxList);
+    });
     const ariaNodes = collectInteractiveNodes(state.ariaSnapshot);
     const scored = webElements
       .filter((element) => isDrillableElement(element))
@@ -324,7 +305,7 @@ export class Driller extends TaskAgent implements Agent {
     conversation.addUserText(await this.buildComponentPrompt(originalState, component));
 
     let finished = false;
-    const actionTools = this.createVerifiedActionTools(createCodeceptJSTools(this.explorer, test), component);
+    const actionTools = this.createVerifiedActionTools(createCodeceptJSTools(this.toolDeps, test), component);
     const tools = { ...actionTools, ...this.createDrillFlowTools(originalState, test, interactive) };
 
     await loop(
@@ -333,7 +314,7 @@ export class Driller extends TaskAgent implements Agent {
         setActivity(`${this.emoji} Drilling ${component.name}...`, 'action');
 
         if (iteration > 1) {
-          const currentState = ActionResult.fromState(this.explorer.getStateManager().getCurrentState() || originalState);
+          const currentState = ActionResult.fromState(this.stateManager.getCurrentState() || originalState);
           conversation.addUserText(await this.buildContextUpdate(currentState, component));
           if (this.pendingNestedContext) {
             conversation.addUserText(this.pendingNestedContext);
@@ -577,7 +558,7 @@ export class Driller extends TaskAgent implements Agent {
         execute: async ({ reason }) => {
           await this.restoreOriginalState(originalState, reason);
           await this.captureAnnotatedState();
-          const currentState = this.explorer.getStateManager().getCurrentState();
+          const currentState = this.stateManager.getCurrentState();
           return { success: true, url: currentState?.url || originalState.url };
         },
       }),
@@ -598,9 +579,9 @@ export class Driller extends TaskAgent implements Agent {
   }
 
   private async restoreOriginalState(originalState: ActionResult, reason: string): Promise<void> {
-    const currentState = this.explorer.getStateManager().getCurrentState();
+    const currentState = this.stateManager.getCurrentState();
     const targetUrl = originalState.fullUrl || originalState.url;
-    const action = this.explorer.createAction();
+    const action = this.explorer.action();
 
     if (currentState?.url !== originalState.url) {
       await action.attempt(`I.amOnPage(${JSON.stringify(targetUrl)})`, `${reason} (restore URL)`);
@@ -665,7 +646,7 @@ export class Driller extends TaskAgent implements Agent {
     const overlayHtml = await this.getVisibleOverlayHtml();
     if (!overlayHtml) return null;
 
-    const state = this.explorer.getStateManager().getCurrentState();
+    const state = this.stateManager.getCurrentState();
     if (!state) return null;
     const currentState = ActionResult.fromState(state);
     return dedent`
@@ -686,40 +667,42 @@ export class Driller extends TaskAgent implements Agent {
   }
 
   private async getVisibleOverlayHtml(): Promise<string> {
-    const page = this.explorer.playwrightHelper.page;
-    return page.evaluate(
-      ({ extractorSource, config }) => {
-        const extract = new Function(`return ${extractorSource}`)() as (config: any) => string;
-        return extract(config);
-      },
-      {
-        extractorSource: getVisibleOverlayHtmlExtractorSource(),
-        config: {
-          interactiveContentSelector: HTML_SELECTORS.interactiveContent,
-          limits: HTML_EXTRACTION_LIMITS,
-          overlaySelectors: HTML_SELECTORS.semanticOverlays,
-          visibilityLimits: HTML_VISIBILITY_LIMITS,
+    return this.explorer.withPage((page) =>
+      page.evaluate(
+        ({ extractorSource, config }) => {
+          const extract = new Function(`return ${extractorSource}`)() as (config: any) => string;
+          return extract(config);
         },
-      }
+        {
+          extractorSource: getVisibleOverlayHtmlExtractorSource(),
+          config: {
+            interactiveContentSelector: HTML_SELECTORS.interactiveContent,
+            limits: HTML_EXTRACTION_LIMITS,
+            overlaySelectors: HTML_SELECTORS.semanticOverlays,
+            visibilityLimits: HTML_VISIBILITY_LIMITS,
+          },
+        }
+      )
     );
   }
 
   private async getComponentScopeHtml(component: ComponentInfo, originalState: ActionResult): Promise<string> {
-    const page = this.explorer.playwrightHelper.page;
-    const scopedHtml = await page.evaluate(
-      ({ eidx, extractorSource, config }) => {
-        const extract = new Function(`return ${extractorSource}`)() as (eidx: string, config: any) => string;
-        return extract(eidx, config);
-      },
-      {
-        eidx: component.eidx,
-        extractorSource: getComponentScopeHtmlExtractorSource(),
-        config: {
-          eidxAttr: EXPLORBOT_ATTRS.eidx,
-          interactiveControlSelector: HTML_SELECTORS.interactiveControl,
-          limits: HTML_EXTRACTION_LIMITS,
+    const scopedHtml = await this.explorer.withPage((page) =>
+      page.evaluate(
+        ({ eidx, extractorSource, config }) => {
+          const extract = new Function(`return ${extractorSource}`)() as (eidx: string, config: any) => string;
+          return extract(eidx, config);
         },
-      }
+        {
+          eidx: component.eidx,
+          extractorSource: getComponentScopeHtmlExtractorSource(),
+          config: {
+            eidxAttr: EXPLORBOT_ATTRS.eidx,
+            interactiveControlSelector: HTML_SELECTORS.interactiveControl,
+            limits: HTML_EXTRACTION_LIMITS,
+          },
+        }
+      )
     );
 
     if (scopedHtml) return scopedHtml;

package/src/ai/historian/codeceptjs.ts

@@ -6,8 +6,8 @@ import type { StateManager } from '../../state-manager.ts';
 import type { Plan } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
-import { safeFilename } from '../../utils/strings.ts';
 import { CODECEPT_TOOLS, isNonReusableCode, stripComments } from '../../utils/step-analyzer.ts';
+import { safeFilename } from '../../utils/strings.ts';
 import type { Conversation } from '../conversation.ts';
 import { ASSERTION_TOOLS } from '../tools.ts';
 import type { Constructor } from './mixin.ts';

package/src/ai/historian/playwright.ts

@@ -2,13 +2,14 @@ import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { ActionResult } from '../../action-result.ts';
 import { ConfigParser } from '../../config.ts';
-import type { StateManager } from '../../state-manager.ts';
+import type Explorer from '../../explorer.ts';
 import { type PlaywrightRecorder, type TraceCall, renderAssertion, renderCall } from '../../playwright-recorder.ts';
+import type { StateManager } from '../../state-manager.ts';
 import type { Plan } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
-import { safeFilename } from '../../utils/strings.ts';
 import { CODECEPT_TOOLS } from '../../utils/step-analyzer.ts';
+import { safeFilename } from '../../utils/strings.ts';
 import type { Conversation } from '../conversation.ts';
 import { ASSERTION_TOOLS } from '../tools.ts';
 import type { Constructor } from './mixin.ts';
@@ -23,7 +24,7 @@ export interface PlaywrightMethods {
 
 export function WithPlaywright<T extends Constructor>(Base: T) {
   return class extends Base {
-    declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
+    declare playwright: { recorder: PlaywrightRecorder; explorer: Explorer } | undefined;
     declare savedFiles: Set<string>;
     declare stateManager?: StateManager;
 

package/src/ai/historian/screencast.ts

@@ -4,6 +4,7 @@ import { join } from 'node:path';
 import * as codeceptjs from 'codeceptjs';
 import { outputPath } from '../../config.ts';
 import type { ExplorbotConfig } from '../../config.ts';
+import type Explorer from '../../explorer.ts';
 import type { PlaywrightRecorder } from '../../playwright-recorder.ts';
 import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
@@ -22,7 +23,7 @@ export function WithScreencast<T extends Constructor>(Base: T) {
   return class extends Base {
     declare config: ExplorbotConfig | undefined;
     declare savedFiles: Set<string>;
-    declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
+    declare playwright: { recorder: PlaywrightRecorder; explorer: Explorer } | undefined;
 
     private screencastPage: any = null;
     private screencastActive = false;
@@ -41,7 +42,7 @@ export function WithScreencast<T extends Constructor>(Base: T) {
     attachScreencast(): void {
       if (this.screencastListenersInstalled) return;
       if (!this.config?.ai?.agents?.historian?.screencast) return;
-      if (!this.playwright?.helper) return;
+      if (!this.playwright?.explorer) return;
 
       this.onTestBefore = (test: any) => {
         void this.startScreencast(test);
@@ -62,7 +63,7 @@ export function WithScreencast<T extends Constructor>(Base: T) {
 
     private async startScreencast(test: any): Promise<void> {
       if (this.screencastActive) return;
-      const page = this.playwright?.helper?.page;
+      const page = this.playwright?.explorer?.page;
       if (!page?.screencast?.start) return;
 
       const task = test?._explorbotTest;

package/src/ai/historian.ts

@@ -1,6 +1,7 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import type { ExplorbotConfig } from '../config.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
+import type Explorer from '../explorer.ts';
 import type { PlaywrightRecorder } from '../playwright-recorder.ts';
 import type { Reporter } from '../reporter.ts';
 import type { StateManager } from '../state-manager.ts';
@@ -23,10 +24,10 @@ export class Historian extends HistorianBase {
   declare reporter: Reporter | undefined;
   declare stateManager: StateManager | undefined;
   declare config: ExplorbotConfig | undefined;
-  declare playwright: { recorder: PlaywrightRecorder; helper: any } | undefined;
+  declare playwright: { recorder: PlaywrightRecorder; explorer: Explorer } | undefined;
   declare savedFiles: Set<string>;
 
-  constructor(provider: Provider, experienceTracker: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager, config?: ExplorbotConfig, playwright?: { recorder: PlaywrightRecorder; helper: any }) {
+  constructor(provider: Provider, experienceTracker: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager, config?: ExplorbotConfig, playwright?: { recorder: PlaywrightRecorder; explorer: Explorer }) {
     super();
     this.provider = provider;
     this.experienceTracker = experienceTracker;

package/src/ai/navigator.ts

@@ -3,17 +3,18 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.js';
 import type Action from '../action.ts';
+import type { ExplorbotConfig } from '../config.ts';
 import type { ExperienceTracker } from '../experience-tracker.js';
 import Explorer from '../explorer.ts';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
-import { normalizeUrl } from '../state-manager.js';
+import { type StateManager, normalizeUrl } from '../state-manager.js';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { extractStatePath } from '../utils/url-matcher.js';
-import type { Agent } from './agent.js';
+import type { Agent, AgentDeps } from './agent.js';
 import type { Conversation } from './conversation.js';
 import type { Provider } from './provider.js';
 import { Researcher } from './researcher.ts';
@@ -70,25 +71,29 @@ class Navigator implements Agent {
   </rules>
   `;
   private explorer: Explorer;
-
-  constructor(explorer: Explorer, provider: Provider) {
-    this.provider = provider;
-    this.explorer = explorer;
-    this.knowledgeTracker = explorer.getKnowledgeTracker();
-    this.experienceTracker = explorer.getStateManager().getExperienceTracker();
-    this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
+  private config: ExplorbotConfig;
+  private stateManager: StateManager;
+
+  constructor(deps: AgentDeps) {
+    this.provider = deps.ai;
+    this.explorer = deps.explorer;
+    this.config = deps.config;
+    this.stateManager = deps.stateManager;
+    this.knowledgeTracker = deps.knowledgeTracker;
+    this.experienceTracker = deps.stateManager.getExperienceTracker();
+    this.hooksRunner = new HooksRunner(deps.explorer, deps.config);
   }
 
   private get verifyAttempts(): number {
-    return this.explorer.getConfig().ai?.agents?.navigator?.verifyAttempts ?? 3;
+    return this.config.ai?.agents?.navigator?.verifyAttempts ?? 3;
   }
 
   private get verifyTimeout(): number {
-    return this.explorer.getConfig().ai?.agents?.navigator?.verifyTimeout ?? 1500;
+    return this.config.ai?.agents?.navigator?.verifyTimeout ?? 1500;
   }
 
   private getBaseOrigin(): string | null {
-    const baseUrl = this.explorer.getConfig().playwright.url;
+    const baseUrl = this.config.playwright.url;
     try {
       return new URL(baseUrl).origin;
     } catch {
@@ -133,12 +138,12 @@ class Navigator implements Agent {
   }
 
   async visit(url: string): Promise<void> {
-    return this.explorer.runWithBrowserRecovery('navigator.visit', () => this.visitOnce(url));
+    return this.visitOnce(url);
   }
 
   private async visitOnce(url: string): Promise<void> {
     try {
-      const action = this.explorer.createAction();
+      const action = this.explorer.action();
 
       await action.execute(`I.amOnPage('${url}')`);
 
@@ -171,7 +176,7 @@ class Navigator implements Agent {
           throw new Error(`Navigation to ${url} failed: ${action.lastError?.message}`);
         }
       }
-      await this.explorer.capturePageWithScreenshot();
+      await this.explorer.capture({ screenshot: true });
       await this.hooksRunner.runAfterHook('navigator', url);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
@@ -188,7 +193,7 @@ class Navigator implements Agent {
     tag('info').log('AI Navigator resolving state at', actionResult.url);
     debugLog('Resolution message:', message);
 
-    const action = opts?.action ?? this.explorer.createAction();
+    const action = opts?.action ?? this.explorer.action();
     const expectedUrl = opts?.expectedUrl;
 
     const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
@@ -341,7 +346,7 @@ class Navigator implements Agent {
         codeBlockIndex++;
         totalAttempts++;
 
-        await this.explorer.switchToMainFrame();
+        await action.exitIframe();
 
         const prevActionResult = action.actionResult ?? actionResult;
         const prevHash = prevActionResult.getStateHash();
@@ -373,7 +378,7 @@ class Navigator implements Agent {
               // URL did not transition to expectedUrl within timeout
             }
           }
-          const freshState = await this.explorer.capturePageState();
+          const freshState = await this.explorer.capture();
           const currentUrl = /^https?:\/\//i.test(expectedUrl) ? freshState.fullUrl || freshState.url || '' : freshState.url || '';
           const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
           const stateChanged = freshState.getStateHash() !== actionResult.getStateHash();
@@ -473,7 +478,7 @@ class Navigator implements Agent {
 
   private buildExperienceTools(): { learnExperience: unknown } | undefined {
     if (!this.experienceTracker) return undefined;
-    const stateManager = this.explorer.getStateManager();
+    const stateManager = this.stateManager;
     const getState = () => {
       const s = stateManager.getCurrentState();
       return s ? ActionResult.fromState(s) : null;
@@ -482,7 +487,7 @@ class Navigator implements Agent {
   }
 
   async freeSail(opts?: { strategy?: 'deep' | 'shallow'; scope?: string; visitedUrls?: Set<string> }, actionResult?: ActionResult): Promise<{ target: string; reason: string } | null> {
-    const stateManager = this.explorer.getStateManager();
+    const stateManager = this.stateManager;
     const state = stateManager.getCurrentState();
     if (!state) {
       return null;
@@ -690,11 +695,11 @@ class Navigator implements Agent {
     const successfulCodes: string[] = [];
     const assertionSteps: Array<{ name: string; args: any[] }> = [];
 
-    const action = this.explorer.createAction();
+    const action = this.explorer.action();
     let failures = 0;
 
-    const page = this.explorer.playwrightHelper?.page;
-    const originalTimeout = this.explorer.playwrightHelper?.options?.timeout ?? 3000;
+    const page = this.explorer.page;
+    const originalTimeout = this.config.playwright.timeout ?? 3000;
     page?.setDefaultTimeout(this.verifyTimeout);
 
     try {
@@ -726,7 +731,7 @@ class Navigator implements Agent {
             return;
           }
 
-          await this.explorer.switchToMainFrame();
+          await action.exitIframe();
 
           const verified = await action.attempt(codeBlock, message);
 
@@ -764,7 +769,7 @@ class Navigator implements Agent {
     if (alreadyVerified) verified = true;
 
     actionResult.addVerification(message, verified);
-    this.explorer.getStateManager().updateState(actionResult);
+    this.stateManager.updateState(actionResult);
 
     return { verified, successfulCodes, assertionSteps, totalAttempted };
   }