explorbot 0.2.0 → 0.2.1

package/dist/src/ai/driller.js

@@ -6,10 +6,11 @@ import { setActivity } from "../activity.js";
 import { Observability } from "../observability.js";
 import { Plan, Test, TestResult } from "../test-plan.js";
 import { collectInteractiveNodes } from "../utils/aria.js";
-import { HooksRunner } from "../utils/hooks-runner.js";
 import { EXPLORBOT_ATTRS, HTML_COMPOSITE_AREA_HINTS, HTML_COMPOSITE_TARGET_ROLES, HTML_EXTRACTION_LIMITS, HTML_FORM_CONTROL_ROLES, HTML_FORM_CONTROL_TAGS, HTML_INTERACTIVE_ROLES, HTML_SELECTORS, HTML_VISIBILITY_LIMITS, getComponentScopeHtmlExtractorSource, getVisibleOverlayHtmlExtractorSource, inferHtmlRole, } from "../utils/html.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop, pause } from "../utils/loop.js";
+import { annotatePageElements } from "../utils/web-annotate.js";
+import { eidxInContainer } from "../utils/web-eidx.js";
 import { WebElement } from "../utils/web-element.js";
 import { drillLocatorRule } from "./rules.js";
 import { TaskAgent, isInteractive } from "./task-agent.js";
@@ -18,36 +19,21 @@ const debugLog = createDebug('explorbot:driller');
 export class Driller extends TaskAgent {
     ACTION_TOOLS = ['click', 'pressKey', 'form'];
     emoji = 'D';
-    explorer;
-    provider;
     navigator;
-    hooksRunner;
     currentPlan;
     allResults = [];
     verifiedAction = null;
     pendingNestedContext = null;
     MAX_COMPONENT_ITERATIONS = 12;
-    constructor(explorer, provider, navigator) {
-        super();
-        this.explorer = explorer;
-        this.provider = provider;
+    constructor(deps, navigator) {
+        super(deps);
         this.navigator = navigator;
-        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;
-    }
     getSystemMessage(component) {
-        const currentUrl = this.explorer.getStateManager().getCurrentState()?.url;
+        const currentUrl = this.stateManager.getCurrentState()?.url;
         const customPrompt = this.provider.getSystemPromptForAgent('driller', currentUrl);
         return dedent `
     <role>
@@ -89,7 +75,7 @@ export class Driller extends TaskAgent {
     }
     async drill(opts = {}) {
         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)}`;
@@ -130,15 +116,15 @@ export class Driller extends TaskAgent {
     }
     async captureAnnotatedState() {
         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((_, 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}`);
@@ -150,9 +136,10 @@ export class Driller extends TaskAgent {
     }
     async collectComponents(state, maxComponents) {
         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))
@@ -246,13 +233,13 @@ export class Driller extends TaskAgent {
         const conversation = this.provider.startConversation(this.getSystemMessage(component), 'driller');
         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(async ({ stop, iteration }) => {
             debugLog(`Drilling component ${component.name}, iteration ${iteration}`);
             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);
@@ -479,7 +466,7 @@ export class Driller extends TaskAgent {
                 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 };
                 },
             }),
@@ -500,9 +487,9 @@ export class Driller extends TaskAgent {
         };
     }
     async restoreOriginalState(originalState, reason) {
-        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)`);
             return;
@@ -558,7 +545,7 @@ export class Driller extends TaskAgent {
         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);
@@ -579,8 +566,7 @@ export class Driller extends TaskAgent {
     `;
     }
     async getVisibleOverlayHtml() {
-        const page = this.explorer.playwrightHelper.page;
-        return page.evaluate(({ extractorSource, config }) => {
+        return this.explorer.withPage((page) => page.evaluate(({ extractorSource, config }) => {
             const extract = new Function(`return ${extractorSource}`)();
             return extract(config);
         }, {
@@ -591,11 +577,10 @@ export class Driller extends TaskAgent {
                 overlaySelectors: HTML_SELECTORS.semanticOverlays,
                 visibilityLimits: HTML_VISIBILITY_LIMITS,
             },
-        });
+        }));
     }
     async getComponentScopeHtml(component, originalState) {
-        const page = this.explorer.playwrightHelper.page;
-        const scopedHtml = await page.evaluate(({ eidx, extractorSource, config }) => {
+        const scopedHtml = await this.explorer.withPage((page) => page.evaluate(({ eidx, extractorSource, config }) => {
             const extract = new Function(`return ${extractorSource}`)();
             return extract(eidx, config);
         }, {
@@ -606,7 +591,7 @@ export class Driller extends TaskAgent {
                 interactiveControlSelector: HTML_SELECTORS.interactiveControl,
                 limits: HTML_EXTRACTION_LIMITS,
             },
-        });
+        }));
         if (scopedHtml)
             return scopedHtml;
         return await originalState.combinedHtml();

package/dist/src/ai/historian/codeceptjs.js

@@ -4,8 +4,8 @@ import { ActionResult } from "../../action-result.js";
 import { ConfigParser } from "../../config.js";
 import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
-import { safeFilename } from "../../utils/strings.js";
 import { CODECEPT_TOOLS, isNonReusableCode, stripComments } from "../../utils/step-analyzer.js";
+import { safeFilename } from "../../utils/strings.js";
 import { ASSERTION_TOOLS } from "../tools.js";
 import { escapeString, getExecutionLabel } from "./utils.js";
 export function WithCodeceptJS(Base) {

package/dist/src/ai/historian/playwright.d.ts

@@ -1,5 +1,6 @@
-import type { StateManager } from '../../state-manager.js';
+import type Explorer from '../../explorer.js';
 import { type PlaywrightRecorder } from '../../playwright-recorder.js';
+import type { StateManager } from '../../state-manager.js';
 import type { Plan } from '../../test-plan.js';
 import type { Conversation } from '../conversation.js';
 import type { Constructor } from './mixin.js';
@@ -11,7 +12,7 @@ export declare function WithPlaywright<T extends Constructor>(Base: T): {
     new (...args: any[]): {
         playwright: {
             recorder: PlaywrightRecorder;
-            helper: any;
+            explorer: Explorer;
         } | undefined;
         savedFiles: Set<string>;
         stateManager?: StateManager;

package/dist/src/ai/historian/playwright.js

@@ -5,8 +5,8 @@ import { ConfigParser } from "../../config.js";
 import { renderAssertion, renderCall } from "../../playwright-recorder.js";
 import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
-import { safeFilename } from "../../utils/strings.js";
 import { CODECEPT_TOOLS } from "../../utils/step-analyzer.js";
+import { safeFilename } from "../../utils/strings.js";
 import { ASSERTION_TOOLS } from "../tools.js";
 import { escapeString, getExecutionLabel } from "./utils.js";
 const PLAYWRIGHT_EMITTED_TOOLS = [...CODECEPT_TOOLS, ...ASSERTION_TOOLS];

package/dist/src/ai/historian/screencast.d.ts

@@ -1,4 +1,5 @@
 import type { ExplorbotConfig } from '../../config.js';
+import type Explorer from '../../explorer.js';
 import type { PlaywrightRecorder } from '../../playwright-recorder.js';
 import { type Constructor } from './mixin.js';
 export interface ScreencastMethods {
@@ -12,7 +13,7 @@ export declare function WithScreencast<T extends Constructor>(Base: T): {
         savedFiles: Set<string>;
         playwright: {
             recorder: PlaywrightRecorder;
-            helper: any;
+            explorer: Explorer;
         } | undefined;
         screencastPage: any;
         screencastActive: boolean;

package/dist/src/ai/historian/screencast.js

@@ -27,7 +27,7 @@ export function WithScreencast(Base) {
                 return;
             if (!this.config?.ai?.agents?.historian?.screencast)
                 return;
-            if (!this.playwright?.helper)
+            if (!this.playwright?.explorer)
                 return;
             this.onTestBefore = (test) => {
                 void this.startScreencast(test);
@@ -46,7 +46,7 @@ export function WithScreencast(Base) {
         async startScreencast(test) {
             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/dist/src/ai/historian.d.ts

@@ -1,5 +1,6 @@
 import type { ExplorbotConfig } from '../config.js';
 import type { ExperienceTracker } from '../experience-tracker.js';
+import type Explorer from '../explorer.js';
 import type { PlaywrightRecorder } from '../playwright-recorder.js';
 import type { Reporter } from '../reporter.js';
 import type { StateManager } from '../state-manager.js';
@@ -15,7 +16,7 @@ declare const HistorianBase: {
         savedFiles: Set<string>;
         playwright: {
             recorder: PlaywrightRecorder;
-            helper: any;
+            explorer: Explorer;
         };
         screencastPage: any;
         screencastActive: boolean;
@@ -36,7 +37,7 @@ declare const HistorianBase: {
     new (...args: any[]): {
         playwright: {
             recorder: PlaywrightRecorder;
-            helper: any;
+            explorer: Explorer;
         };
         savedFiles: Set<string>;
         stateManager?: StateManager;
@@ -91,12 +92,12 @@ export declare class Historian extends HistorianBase {
     config: ExplorbotConfig | undefined;
     playwright: {
         recorder: PlaywrightRecorder;
-        helper: any;
+        explorer: Explorer;
     } | undefined;
     savedFiles: Set<string>;
     constructor(provider: Provider, experienceTracker: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager, config?: ExplorbotConfig, playwright?: {
         recorder: PlaywrightRecorder;
-        helper: any;
+        explorer: Explorer;
     });
     isPlaywrightFramework(): boolean;
     getSavedFiles(): string[];

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

@@ -1,10 +1,12 @@
 import { ActionResult } from '../action-result.js';
 import type Action from '../action.js';
+import type { ExplorbotConfig } from '../config.js';
 import type { ExperienceTracker } from '../experience-tracker.js';
 import Explorer from '../explorer.js';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
+import { type StateManager } from '../state-manager.js';
 import { HooksRunner } from '../utils/hooks-runner.js';
-import type { Agent } from './agent.js';
+import type { Agent, AgentDeps } from './agent.js';
 import type { Provider } from './provider.js';
 declare class Navigator implements Agent {
     emoji: string;
@@ -16,7 +18,9 @@ declare class Navigator implements Agent {
     systemPrompt: string;
     freeSailSystemPrompt: string;
     explorer: Explorer;
-    constructor(explorer: Explorer, provider: Provider);
+    config: ExplorbotConfig;
+    stateManager: StateManager;
+    constructor(deps: AgentDeps);
     get verifyAttempts(): number;
     get verifyTimeout(): number;
     getBaseOrigin(): string | null;

package/dist/src/ai/navigator.js

@@ -59,21 +59,25 @@ class Navigator {
   </rules>
   `;
     explorer;
-    constructor(explorer, provider) {
-        this.provider = provider;
-        this.explorer = explorer;
-        this.knowledgeTracker = explorer.getKnowledgeTracker();
-        this.experienceTracker = explorer.getStateManager().getExperienceTracker();
-        this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
+    config;
+    stateManager;
+    constructor(deps) {
+        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);
     }
     get verifyAttempts() {
-        return this.explorer.getConfig().ai?.agents?.navigator?.verifyAttempts ?? 3;
+        return this.config.ai?.agents?.navigator?.verifyAttempts ?? 3;
     }
     get verifyTimeout() {
-        return this.explorer.getConfig().ai?.agents?.navigator?.verifyTimeout ?? 1500;
+        return this.config.ai?.agents?.navigator?.verifyTimeout ?? 1500;
     }
     getBaseOrigin() {
-        const baseUrl = this.explorer.getConfig().playwright.url;
+        const baseUrl = this.config.playwright.url;
         try {
             return new URL(baseUrl).origin;
         }
@@ -117,11 +121,11 @@ class Navigator {
         return normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
     }
     async visit(url) {
-        return this.explorer.runWithBrowserRecovery('navigator.visit', () => this.visitOnce(url));
+        return this.visitOnce(url);
     }
     async visitOnce(url) {
         try {
-            const action = this.explorer.createAction();
+            const action = this.explorer.action();
             await action.execute(`I.amOnPage('${url}')`);
             const currentUrl = action.stateManager.getCurrentState()?.url || '';
             if (currentUrl === 'about:blank' || currentUrl === '') {
@@ -149,7 +153,7 @@ class Navigator {
                     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) {
@@ -165,7 +169,7 @@ class Navigator {
     async resolveState(message, actionResult, opts) {
         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);
         let experience = '';
@@ -310,7 +314,7 @@ class Navigator {
             }
             codeBlockIndex++;
             totalAttempts++;
-            await this.explorer.switchToMainFrame();
+            await action.exitIframe();
             const prevActionResult = action.actionResult ?? actionResult;
             const prevHash = prevActionResult.getStateHash();
             debugLog(`Attempting resolution: ${codeBlock}`);
@@ -339,7 +343,7 @@ class Navigator {
                         // 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();
@@ -434,7 +438,7 @@ class Navigator {
     buildExperienceTools() {
         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;
@@ -442,7 +446,7 @@ class Navigator {
         return { learnExperience: createLearnExperienceTool({ getExperienceTracker: () => this.experienceTracker, getState }) };
     }
     async freeSail(opts, actionResult) {
-        const stateManager = this.explorer.getStateManager();
+        const stateManager = this.stateManager;
         const state = stateManager.getCurrentState();
         if (!state) {
             return null;
@@ -620,10 +624,10 @@ class Navigator {
         let codeBlocks = [];
         const successfulCodes = [];
         const assertionSteps = [];
-        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 {
             await loop(async ({ stop, iteration }) => {
@@ -649,7 +653,7 @@ class Navigator {
                     stop();
                     return;
                 }
-                await this.explorer.switchToMainFrame();
+                await action.exitIframe();
                 const verified = await action.attempt(codeBlock, message);
                 if (verified) {
                     tag('success').log('Verification passed');
@@ -683,7 +687,7 @@ class Navigator {
         if (alreadyVerified)
             verified = true;
         actionResult.addVerification(message, verified);
-        this.explorer.getStateManager().updateState(actionResult);
+        this.stateManager.updateState(actionResult);
         return { verified, successfulCodes, assertionSteps, totalAttempted };
     }
     checkAlreadyVerified(aiResponse, actionResult) {

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

@@ -1,7 +1,10 @@
 import { ActionResult } from '../action-result.js';
+import type { RequestStore } from '../api/request-store.js';
 import type Explorer from '../explorer.js';
+import type { PlaywrightRecorder } from '../playwright-recorder.js';
+import type { StateManager } from '../state-manager.js';
 import { type Test } from '../test-plan.js';
-import type { Agent } from './agent.js';
+import type { Agent, AgentDeps } from './agent.js';
 import type { Conversation } from './conversation.js';
 import type { Fisherman } from './fisherman.js';
 import type { Navigator } from './navigator.js';
@@ -14,8 +17,11 @@ export declare class Pilot implements Agent {
     conversation: Conversation | null;
     researcher: Researcher;
     explorer: Explorer;
+    stateManager: StateManager;
+    requestStore: RequestStore;
+    playwrightRecorder: PlaywrightRecorder;
     fisherman: Fisherman | null;
-    constructor(provider: Provider, agentTools: any, researcher: Researcher, explorer: Explorer);
+    constructor(deps: AgentDeps, agentTools: any, researcher: Researcher);
     setFisherman(fisherman: Fisherman): void;
     get stepsToReview(): number;
     reset(): void;
@@ -27,17 +33,18 @@ export declare class Pilot implements Agent {
     reviewReset(task: Test, currentState: ActionResult, reason: string, testerConversation: Conversation): Promise<boolean>;
     reviewDecision(type: 'finish' | 'stop', task: Test, currentState: ActionResult, testerConversation: Conversation, navigator?: Navigator): Promise<boolean>;
     reviewResetDecision(task: Test, currentState: ActionResult, reason: string, testerConversation: Conversation): Promise<boolean>;
-    buildSharedEvidenceRules(task: Test): string;
+    buildSharedEvidenceRules(): string;
+    buildTaskContext(task: Test): string;
     buildResetSystemPrompt(task: Test): string;
-    buildVerdictSystemPrompt(type: string, task: Test): string;
+    buildVerdictSystemPrompt(task: Test): string;
     planTest(task: Test, currentState: ActionResult): Promise<string>;
     reviewNewPage(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     analyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     formatExpectations(task: Test): string;
-    sendToPilot(userText: string, functionId: string, opts?: {
+    sendToPilot(userText: string, functionId: string, opts: {
         tools?: boolean;
         maxToolRoundtrips?: number;
-        task?: Test;
+        task: Test;
     }): Promise<string>;
     getExperienceToc(): string;
     pickPlanningTools(): Record<string, unknown>;