explorbot 0.2.0 → 0.2.2

package/dist/src/ai/pilot.js

@@ -20,12 +20,18 @@ export class Pilot {
     conversation = null;
     researcher;
     explorer;
+    stateManager;
+    requestStore;
+    playwrightRecorder;
     fisherman = null;
-    constructor(provider, agentTools, researcher, explorer) {
-        this.provider = provider;
+    constructor(deps, agentTools, researcher) {
+        this.provider = deps.ai;
         this.agentTools = agentTools;
         this.researcher = researcher;
-        this.explorer = explorer;
+        this.explorer = deps.explorer;
+        this.stateManager = deps.stateManager;
+        this.requestStore = deps.requestStore;
+        this.playwrightRecorder = deps.playwrightRecorder;
     }
     setFisherman(fisherman) {
         this.fisherman = fisherman;
@@ -71,7 +77,7 @@ export class Pilot {
         let screenshotState = null;
         if (type === 'finish' && this.provider.hasVision()) {
             try {
-                screenshotState = await this.explorer.capturePageWithScreenshot();
+                screenshotState = await this.explorer.capture({ screenshot: true });
                 if (screenshotState.screenshot) {
                     visualAnalysis = (await this.researcher.answerQuestionAboutScreenshot(screenshotState, `Describe current page state relevant to: ${task.scenario}`)) || '';
                 }
@@ -130,7 +136,7 @@ export class Pilot {
         const messages = [
             {
                 role: 'system',
-                content: this.buildVerdictSystemPrompt(type, task),
+                content: this.buildVerdictSystemPrompt(task),
             },
             { role: 'user', content: userContent },
         ];
@@ -148,7 +154,7 @@ export class Pilot {
                 tag('substep').log(`Pilot requesting verification: ${result.requestVerification}`);
                 const verifyResult = await navigator.verifyState(result.requestVerification, currentState).catch(() => null);
                 if (verifyResult?.verified && verifyResult.assertionSteps?.length) {
-                    this.explorer.getPlaywrightRecorder().recordVerification(verifyResult.assertionSteps);
+                    this.playwrightRecorder.recordVerification(verifyResult.assertionSteps);
                 }
             }
             tag('info').log(`Pilot: ${result.decision} - ${result.reason}`);
@@ -258,10 +264,8 @@ export class Pilot {
             return true;
         }
     }
-    buildSharedEvidenceRules(task) {
+    buildSharedEvidenceRules() {
         return dedent `
-      SCENARIO: ${task.scenario}
-
       EVIDENCE PRIORITY (strict):
       1) Final observable state proving the scenario goal
       2) verify()/see() results in the LAST few actions before stop/finish
@@ -294,6 +298,11 @@ export class Pilot {
 
       Expected results are MILESTONES, not the goal. Never fail because a milestone (toast, icon, styling)
       didn't match if the scenario goal IS accomplished.
+    `;
+    }
+    buildTaskContext(task) {
+        return dedent `
+      SCENARIO: ${task.scenario}
 
       ${this.buildDeletionScope(task)}
 
@@ -307,7 +316,7 @@ export class Pilot {
       iteration's work, but server-side side effects (records created, forms submitted) persist.
       Unnecessary resets create duplicate data and infinite loops.
 
-      ${this.buildSharedEvidenceRules(task)}
+      ${this.buildSharedEvidenceRules()}
 
       DECISION:
       - "allow": current page cannot host the scenario, irrecoverable error, or no path back.
@@ -324,16 +333,18 @@ export class Pilot {
       to verify, how to record. Do not suggest repeating actions that already succeeded.
       If progress is blocked only because the page lacks target data for the scenario, prefer precondition()
       over repeated UI attempts.
+
+      ${this.buildTaskContext(task)}
     `;
     }
-    buildVerdictSystemPrompt(type, task) {
+    buildVerdictSystemPrompt(task) {
         return dedent `
-      You are Pilot — final decision maker for test pass/fail. Tester requested ${type}. Review the
-      evidence and commit to a verdict; "continue" only when evidence is genuinely insufficient.
+      You are Pilot — final decision maker for test pass/fail. Review the evidence and commit to a
+      verdict; "continue" only when evidence is genuinely insufficient.
 
       ${capabilityGroundingRule}
 
-      ${this.buildSharedEvidenceRules(task)}
+      ${this.buildSharedEvidenceRules()}
 
       DECISION:
       - "pass": scenario goal is fully accomplished. Set requestVerification to a one-sentence claim about
@@ -352,6 +363,8 @@ export class Pilot {
       reason field: one short sentence, maximum 120 characters. Do NOT restate the decision
       ("scenario goal achieved/not achieved"). State what happened: what was verified, what failed,
       or what evidence was found.
+
+      ${this.buildTaskContext(task)}
     `;
     }
     async planTest(task, currentState) {
@@ -418,8 +431,6 @@ export class Pilot {
             .filter((t) => t.wasSuccessful)
             .slice(-this.stepsToReview);
         const actionsContext = this.formatActions(toolCalls);
-        this.conversation.cleanupTag('page_summary', '...trimmed...', 1);
-        this.conversation.cleanupTag('recent_actions', '...trimmed...', 2);
         return this.sendToPilot(dedent `
         Navigated to new page.
         START URL: ${task.startUrl}
@@ -439,7 +450,7 @@ export class Pilot {
         ${this.formatExpectations(task)}
 
         First: evaluate whether this navigation makes sense for the scenario goal. If the page is unrelated, instruct Tester to back() or reset(). Then plan next steps.
-      `, 'pilot.reviewNewPage');
+      `, 'pilot.reviewNewPage', { task });
     }
     async analyzeProgress(task, currentState, testerConversation) {
         tag('substep').log('Pilot analyzing progress...');
@@ -451,7 +462,6 @@ export class Pilot {
         const toolCalls = testerConversation.getToolExecutions().slice(-this.stepsToReview);
         const actionsContext = this.formatActions(toolCalls);
         const stateContext = this.buildStateContext(currentState);
-        this.conversation.cleanupTag('recent_actions', '...trimmed...', 2);
         const hasFailures = toolCalls.length === 0 || toolCalls.some((t) => !t.wasSuccessful);
         const text = await this.sendToPilot(dedent `
         START URL: ${task.startUrl}
@@ -479,7 +489,7 @@ export class Pilot {
         const remaining = task.getRemainingExpectations();
         return `CHECKED: ${checked.length > 0 ? checked.join(', ') : 'none'}\nREMAINING: ${remaining.length > 0 ? remaining.join(', ') : 'none'}`;
     }
-    async sendToPilot(userText, functionId, opts = {}) {
+    async sendToPilot(userText, functionId, opts) {
         debugLog(`sendToPilot: ${functionId}, tools: ${!!opts.tools}, roundtrips: ${opts.maxToolRoundtrips ?? 0}`);
         let finalUserText = userText;
         if (opts.tools) {
@@ -489,17 +499,12 @@ export class Pilot {
             }
         }
         this.conversation.addUserText(finalUserText);
-        let tools;
-        if (opts.tools) {
-            tools = this.pickPlanningTools();
-        }
-        if (opts.tools && opts.task) {
-            tools = { ...tools, ...this.buildPreconditionTool(opts.task) };
-        }
+        const tools = { ...this.pickPlanningTools(), ...this.buildPreconditionTool(opts.task) };
         const result = await this.provider.invokeConversation(this.conversation, tools, {
             maxToolRoundtrips: opts.maxToolRoundtrips ?? 0,
+            toolChoice: opts.tools ? 'auto' : 'none',
             agentName: 'pilot',
-            stopWhen: opts.task ? () => opts.task.hasFinished : undefined,
+            stopWhen: () => opts.task.hasFinished,
             telemetry: { functionId },
         });
         const text = result?.response?.text || '';
@@ -518,10 +523,10 @@ export class Pilot {
     `;
     }
     getExperienceToc() {
-        const state = this.explorer.getStateManager().getCurrentState();
+        const state = this.stateManager.getCurrentState();
         if (!state)
             return '';
-        return this.explorer.getStateManager().getExperienceTracker().renderExperienceTocFor(ActionResult.fromState(state));
+        return this.stateManager.getExperienceTracker().renderExperienceTocFor(ActionResult.fromState(state));
     }
     pickPlanningTools() {
         const { see, context, verify, research, getVisitedStates, xpathCheck, learnExperience, askUser } = this.agentTools ?? {};
@@ -589,7 +594,7 @@ export class Pilot {
     async checkDataAvailability(task, requestedData, fishermanReason) {
         if (!this.provider.hasVision())
             return null;
-        const screenshotState = await this.explorer.capturePageWithScreenshot().catch(() => null);
+        const screenshotState = await this.explorer.capture({ screenshot: true }).catch(() => null);
         if (!screenshotState?.screenshot)
             return null;
         const question = dedent `
@@ -635,8 +640,8 @@ export class Pilot {
         else {
             lines.push('modal: none');
         }
-        if (this.explorer.hasOtherTabs()) {
-            const tabs = this.explorer.getOtherTabsInfo();
+        const tabs = this.stateManager.otherTabs;
+        if (tabs.length > 0) {
             lines.push(`other tabs: ${tabs.length} (${tabs.map((t) => `${t.url} - ${t.title}`).join(', ')})`);
         }
         else {
@@ -658,7 +663,7 @@ export class Pilot {
         else {
             lines.push('console errors: none');
         }
-        const failedRequests = this.explorer.getRequestStore()?.getFailedRequests() ?? [];
+        const failedRequests = this.requestStore.getFailedRequests();
         if (failedRequests.length > 0) {
             const sample = failedRequests
                 .slice(-5)
@@ -733,7 +738,7 @@ export class Pilot {
     }
     formatSessionLog(testerConversation) {
         const executions = testerConversation.getToolExecutions().filter((t) => !META_TOOLS.includes(t.toolName));
-        const stateHistory = this.explorer.getStateManager().getStateHistory();
+        const stateHistory = this.stateManager.getStateHistory();
         const initialUrl = stateHistory[0]?.toState?.url || '';
         let currentUrl = initialUrl;
         const groups = new Map();
@@ -875,16 +880,6 @@ export class Pilot {
         return dedent `
       You are Pilot — a supervisor that detects problems and intervenes only when needed.
 
-      SCENARIO: ${task.scenario}
-      START URL: ${initialState.url}
-      PAGE: ${initialState.title || ''} | ${initialState.h1 || ''}
-
-      EXPECTED RESULTS:
-      ${task.expected.map((e) => `- ${e}`).join('\n')}
-
-      PLANNED STEPS:
-      ${stepsText}
-
       Your job: plan, review new pages, detect stuck patterns, suggest concrete next steps. Track which
       expectations are checked. When things go well, encourage briefly and let Tester continue. The current
       page is usually richer than the page summary lists — prefer exploring it before navigating away.
@@ -954,6 +949,16 @@ export class Pilot {
       NEXT: <specific actionable instruction for Tester>
 
       Keep user-facing reasons concise: one short sentence, maximum 120 characters, evidence only, no repeated verdict wording.
+
+      SCENARIO: ${task.scenario}
+      START URL: ${initialState.url}
+      PAGE: ${initialState.title || ''} | ${initialState.h1 || ''}
+
+      EXPECTED RESULTS:
+      ${task.expected.map((e) => `- ${e}`).join('\n')}
+
+      PLANNED STEPS:
+      ${stepsText}
     `;
     }
 }

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

@@ -4,7 +4,7 @@ import type Explorer from '../explorer.js';
 import type { StateManager } from '../state-manager.js';
 import { Suite } from '../suite.js';
 import { Plan, Test } from '../test-plan.js';
-import type { Agent } from './agent.js';
+import type { Agent, AgentDeps } from './agent.js';
 import { Conversation } from './conversation.js';
 import type { Fisherman } from './fisherman.js';
 import type { Provider } from './provider.js';
@@ -58,7 +58,7 @@ export declare class Planner extends PlannerBase implements Agent {
     lastSuite: Suite | null;
     researcher: Researcher;
     fisherman: Fisherman | null;
-    constructor(explorer: Explorer, provider: Provider, researcher: Researcher);
+    constructor(deps: AgentDeps, researcher: Researcher);
     setFisherman(fisherman: Fisherman): void;
     get sectionOrder(): string[];
     getDefaultStartUrl(state: {
@@ -75,5 +75,6 @@ export declare class Planner extends PlannerBase implements Agent {
     cleanExperienceFlows(text: string): string | null;
     buildApproach(style?: string): string;
     buildConversation(state: ActionResult, style?: string, parentPlan?: Plan, feature?: string): Promise<Conversation>;
+    getTasksMessage(): string;
 }
 export {};

package/dist/src/ai/planner.js

@@ -49,13 +49,13 @@ export class Planner extends PlannerBase {
     lastSuite = null;
     researcher;
     fisherman = null;
-    constructor(explorer, provider, researcher) {
+    constructor(deps, researcher) {
         super();
-        this.explorer = explorer;
-        this.provider = provider;
+        this.explorer = deps.explorer;
+        this.provider = deps.ai;
         this.researcher = researcher;
-        this.stateManager = explorer.getStateManager();
-        this.experienceTracker = explorer.getStateManager().getExperienceTracker();
+        this.stateManager = deps.stateManager;
+        this.experienceTracker = deps.stateManager.getExperienceTracker();
     }
     setFisherman(fisherman) {
         this.fisherman = fisherman;
@@ -334,15 +334,9 @@ export class Planner extends PlannerBase {
       ${dataProtectionRules}
       ${fileUploadRule}
       </rules>
-
-      ${this.buildApproach(style)}
-
-      <context>
-      URL: ${state.url || 'Unknown'}
-      Title: ${state.title || 'Unknown'}
-      </context>
     `;
         conversation.addUserText(planningPrompt);
+        conversation.addUserText(this.getTasksMessage());
         const currentState = this.stateManager.getCurrentState();
         const research = await this.researcher.research(currentState || state, {
             deep: true,
@@ -373,6 +367,14 @@ export class Planner extends PlannerBase {
 
       ${plannerResearch}
       </page_research>
+    `);
+        conversation.addUserText(dedent `
+      ${this.buildApproach(style)}
+
+      <context>
+      URL: ${state.url || 'Unknown'}
+      Title: ${state.title || 'Unknown'}
+      </context>
     `);
         if (this.fisherman) {
             await this.fisherman.ensureReady(state.url);
@@ -517,8 +519,10 @@ export class Planner extends PlannerBase {
         </parent_page_context>
       `);
         }
-        const hasCurrentPlan = !!this.currentPlan;
-        const tasksMessage = dedent `
+        return conversation;
+    }
+    getTasksMessage() {
+        return dedent `
     <task>
       Provide testing scenarios as structured data with the following requirements:
       1. Create a short, descriptive plan name that summarizes what will be tested (e.g., "User Authentication Testing", "Product Catalog Navigation", "Form Validation Tests")
@@ -564,10 +568,8 @@ export class Planner extends PlannerBase {
          - Do not wrap text in ** or * quotes, ( or ) brackets.
          - Avoid using emojis or special characters.
       7. Only tests that can be tested from web UI should be proposed.
-      ${hasCurrentPlan ? '8. CRITICAL: Return ONLY NEW scenarios not in the existing tests list. Return empty array if no new tests needed.' : `8. At least ${this.MIN_TASKS} tests should be proposed.`}
+      8. For a fresh plan propose at least ${this.MIN_TASKS} tests; when expanding an existing plan return ONLY new scenarios not in the tested list, and an empty array if none remain.
     </task>
     `;
-        conversation.addUserText(tasksMessage);
-        return conversation;
     }
 }

package/dist/src/ai/provider.js

@@ -87,7 +87,6 @@ export class Provider {
             await generateText({
                 model: this.config.model,
                 prompt: 'hi',
-                maxOutputTokens: 1,
             });
         }
         catch (error) {

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

@@ -1,4 +1,5 @@
 import type { ActionResult } from '../action-result.js';
+import type Explorer from '../explorer.js';
 import type { StateManager, StateTransition, WebPageState } from '../state-manager.js';
 import type { Task } from '../test-plan.js';
 import type { Conversation, ToolExecution } from './conversation.js';
@@ -9,12 +10,12 @@ export declare class Quartermaster {
     outputDir: string;
     pageAnalyses: Map<string, PageAnalysis>;
     unsubscribe: (() => void) | null;
-    playwrightHelper: any;
+    explorer: Explorer | null;
     pendingAnalyses: Promise<void>[];
     constructor(provider: Provider, options?: {
         model?: any;
     });
-    start(playwrightHelper: any, stateManager: StateManager): void;
+    start(explorer: Explorer, stateManager: StateManager): void;
     stop(): void;
     onPageChange(event: StateTransition): void;
     runAxeAnalysis(state: WebPageState): Promise<void>;

package/dist/src/ai/quartermaster.js

@@ -11,15 +11,15 @@ export class Quartermaster {
     outputDir;
     pageAnalyses = new Map();
     unsubscribe = null;
-    playwrightHelper = null;
+    explorer = null;
     pendingAnalyses = [];
     constructor(provider, options) {
         this.provider = provider;
         this.model = options?.model;
         this.outputDir = outputPath('a11y');
     }
-    start(playwrightHelper, stateManager) {
-        this.playwrightHelper = playwrightHelper;
+    start(explorer, stateManager) {
+        this.explorer = explorer;
         mkdirSync(this.outputDir, { recursive: true });
         this.unsubscribe = stateManager.onStateChange((event) => {
             this.onPageChange(event);
@@ -45,7 +45,7 @@ export class Quartermaster {
         this.pendingAnalyses.push(analysisPromise);
     }
     async runAxeAnalysis(state) {
-        const page = this.playwrightHelper?.page;
+        const page = this.explorer?.page;
         if (!page || !state.hash) {
             debugLog('No page available for axe analysis');
             return;

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

@@ -1,16 +1,10 @@
-import type { ExperienceTracker } from '../experience-tracker.js';
-import type Explorer from '../explorer.js';
-import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import { Test } from '../test-plan.js';
-import type { Agent } from './agent.js';
+import type { Agent, AgentDeps } from './agent.js';
 import type { Navigator } from './navigator.js';
-import { Provider } from './provider.js';
 import { TaskAgent } from './task-agent.js';
 export declare class Rerunner extends TaskAgent implements Agent {
     readonly ACTION_TOOLS: string[];
     emoji: string;
-    explorer: Explorer;
-    provider: Provider;
     agentTools: any;
     healedSteps: Array<{
         original: string;
@@ -18,11 +12,8 @@ export declare class Rerunner extends TaskAgent implements Agent {
     }>;
     traceDir: string;
     static pluginsWired: boolean;
-    constructor(explorer: Explorer, provider: Provider, agentTools?: any);
+    constructor(deps: AgentDeps, agentTools?: any);
     getNavigator(): Navigator;
-    getExperienceTracker(): ExperienceTracker;
-    getKnowledgeTracker(): KnowledgeTracker;
-    getProvider(): Provider;
     get rerunnerConfig(): Record<string, any>;
     get healLimit(): number;
     get healMaxIterations(): number;

package/dist/src/ai/rerunner.js

@@ -26,32 +26,19 @@ const debugLog = createDebug('explorbot:rerunner');
 export class Rerunner extends TaskAgent {
     ACTION_TOOLS = ['click', 'pressKey', 'form'];
     emoji = '🔄';
-    explorer;
-    provider;
     agentTools;
     healedSteps = [];
     traceDir = '';
     static pluginsWired = false;
-    constructor(explorer, provider, agentTools) {
-        super();
-        this.explorer = explorer;
-        this.provider = provider;
+    constructor(deps, agentTools) {
+        super(deps);
         this.agentTools = agentTools;
     }
     getNavigator() {
         throw new Error('Rerunner does not use Navigator');
     }
-    getExperienceTracker() {
-        return this.explorer.getStateManager().getExperienceTracker();
-    }
-    getKnowledgeTracker() {
-        return this.explorer.getKnowledgeTracker();
-    }
-    getProvider() {
-        return this.provider;
-    }
     get rerunnerConfig() {
-        return this.explorer.getConfig().ai?.agents?.rerunner || {};
+        return this.config.ai?.agents?.rerunner || {};
     }
     get healLimit() {
         return this.rerunnerConfig.healLimit ?? 3;
@@ -282,7 +269,7 @@ export class Rerunner extends TaskAgent {
                 },
             });
             const healTask = new Task(`Heal: ${failedCode}`);
-            const codeceptTools = createCodeceptJSTools(this.explorer, healTask);
+            const codeceptTools = createCodeceptJSTools(this.toolDeps, healTask);
             let healed = false;
             let healedCommand = '';
             const tools = {
@@ -300,9 +287,9 @@ export class Rerunner extends TaskAgent {
                             healTask.addNote(note);
                             tag('substep').log(note);
                         }
-                        const action = this.explorer.createAction();
+                        const action = this.explorer.action();
                         await action.execute(`I.wait(${seconds})`);
-                        const state = this.explorer.getStateManager().getCurrentState();
+                        const state = this.stateManager.getCurrentState();
                         const ar = state ? ActionResult.fromState(state) : null;
                         return {
                             success: true,
@@ -383,8 +370,8 @@ export class Rerunner extends TaskAgent {
         };
     }
     getHealSystemPrompt() {
-        const customRules = this.provider.getSystemPromptForAgent('rerunner', this.explorer.getStateManager().getCurrentState()?.url) || '';
-        const currentUrl = this.explorer.getStateManager().getCurrentState()?.url || '';
+        const customRules = this.provider.getSystemPromptForAgent('rerunner', this.stateManager.getCurrentState()?.url) || '';
+        const currentUrl = this.stateManager.getCurrentState()?.url || '';
         const approach = RulesLoader.loadRules('rerunner', ['healing-approach'], currentUrl);
         return dedent `
       <role>
@@ -417,7 +404,7 @@ export class Rerunner extends TaskAgent {
     `;
     }
     getHealUserPrompt(failedCode, error) {
-        const state = this.explorer.getStateManager().getCurrentState();
+        const state = this.stateManager.getCurrentState();
         const actionResult = state ? ActionResult.fromState(state) : null;
         const headings = formatHeadings(state || {});
         return dedent `

package/dist/src/ai/researcher/coordinates.js

@@ -1,6 +1,7 @@
 import dedent from 'dedent';
 import { tag } from '../../utils/logger.js';
 import { mdq } from "../../utils/markdown-query.js";
+import { eidxByLocator } from "../../utils/web-eidx.js";
 import { WebElement } from "../../utils/web-element.js";
 import { debugLog } from "./mixin.js";
 import { parseResearchSections } from "./parser.js";
@@ -67,7 +68,7 @@ export function WithCoordinates(Base) {
             return this._analyzeScreenshotForVisualProps();
         }
         async visuallyAnnotateElements(opts) {
-            return this.explorer.visuallyAnnotateElements(opts);
+            return this.explorer.withPage((page) => visuallyAnnotateContainers(page, opts?.containers || []));
         }
         async _analyzeScreenshotForVisualProps() {
             const elements = new Map();
@@ -160,7 +161,7 @@ export function WithCoordinates(Base) {
                     if (!eidx) {
                         const locator = el.css || el.xpath || (el.aria ? `role=${el.aria.role}[name="${el.aria.text}"]` : null);
                         if (locator)
-                            eidx = await this.explorer.getEidxByLocator(locator, section.containerCss);
+                            eidx = await this.explorer.withPage((page) => eidxByLocator(page, locator, section.containerCss));
                     }
                     if (!eidx)
                         continue;
@@ -187,7 +188,7 @@ export function WithCoordinates(Base) {
             }
             if (eidxWithoutCoords.length === 0)
                 return;
-            const webElements = await this.explorer.runWithBrowserRecovery('backfillCoordinates', () => WebElement.fromEidxList(this.explorer.playwrightHelper.page, eidxWithoutCoords));
+            const webElements = await this.explorer.withPage((page) => WebElement.fromEidxList(page, eidxWithoutCoords));
             if (webElements.length === 0)
                 return;
             const rectMap = new Map(webElements.map((w) => [w.eidx, w]));

package/dist/src/ai/researcher/deep-analysis.d.ts

@@ -1,4 +1,5 @@
 import { ActionResult, type Diff } from '../../action-result.js';
+import type { ExplorbotConfig } from '../../config.js';
 import type Explorer from '../../explorer.js';
 import type { StateManager } from '../../state-manager.js';
 import { WebPageState } from '../../state-manager.js';
@@ -11,6 +12,7 @@ export declare function WithDeepAnalysis<T extends Constructor>(Base: T): {
         explorer: Explorer;
         provider: Provider;
         stateManager: StateManager;
+        config: ExplorbotConfig;
         actionResult: ActionResult | undefined;
         performDeepAnalysis(state: WebPageState, result: ResearchResult): Promise<void>;
         researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null>;

package/dist/src/ai/researcher/deep-analysis.js

@@ -14,7 +14,7 @@ export function WithDeepAnalysis(Base) {
         async performDeepAnalysis(state, result) {
             tag('info').log('Starting deep analysis of expandable elements');
             await this.navigateTo(state.fullUrl || state.url);
-            const maxClicks = this.explorer.getConfig().ai?.agents?.researcher?.maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
+            const maxClicks = this.config.ai?.agents?.researcher?.maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
             const expandedSections = [];
             const navigationLinks = [];
             let verifiedCodes = [];
@@ -311,9 +311,9 @@ export function WithDeepAnalysis(Base) {
                     const isCoordinateClick = el.commands[0].startsWith('I.clickXY(');
                     if (!isCoordinateClick) {
                         const hoverCmd = el.commands[0].replace('I.click(', 'I.moveCursorTo(');
-                        await this.explorer.attemptAction(hoverCmd, undefined);
+                        await this.explorer.action().attempt(hoverCmd);
                         await new Promise((r) => setTimeout(r, 500));
-                        await this.explorer.capturePageState();
+                        await this.explorer.capture();
                         const hoverAR = ActionResult.fromState(this.stateManager.getCurrentState());
                         const hoverDiff = await hoverAR.diff(previousState);
                         const hoverHtmlSize = hoverDiff.htmlParts.reduce((sum, p) => sum + p.subtree.length, 0);
@@ -351,7 +351,7 @@ export function WithDeepAnalysis(Base) {
         async _executeAndAnalyze(commands, description, state, originalAria, alreadyExpanded) {
             const previousState = ActionResult.fromState(this.stateManager.getCurrentState());
             let clickCode = null;
-            const action = this.explorer.createAction();
+            const action = this.explorer.action();
             for (const cmd of commands) {
                 if (await action.attempt(cmd, undefined)) {
                     clickCode = cmd;
@@ -365,7 +365,7 @@ export function WithDeepAnalysis(Base) {
             await new Promise((r) => setTimeout(r, 500));
             let diff;
             try {
-                await this.explorer.createAction().capturePageState();
+                await this.explorer.capture();
                 const currAR = ActionResult.fromState(this.stateManager.getCurrentState());
                 diff = await currAR.diff(previousState);
             }
@@ -394,7 +394,7 @@ export function WithDeepAnalysis(Base) {
         async _restorePageState(url, originalAria) {
             try {
                 await this.cancelInUi();
-                await this.explorer.capturePageState();
+                await this.explorer.capture();
                 const currentAria = this.stateManager.getCurrentState()?.ariaSnapshot || '';
                 if (!diffAriaSnapshots(originalAria, currentAria).text)
                     return;

package/dist/src/ai/researcher/locators.d.ts

@@ -12,9 +12,13 @@ export declare function WithLocators<T extends Constructor>(Base: T): {
         explorer: Explorer;
         provider: Provider;
         actionResult: ActionResult | undefined;
-        testLocators(locators: Locator[]): Promise<void>;
+        testLocators(locators: Locator[], opts?: {
+            scope?: boolean;
+        }): Promise<void>;
         fixBrokenSections(result: ResearchResult, conversation: Conversation): Promise<void>;
         backfillBrokenLocators(result: ResearchResult): Promise<void>;
+        resolveContainers(result: ResearchResult): Promise<Locator[]>;
+        recoverContainerFromChildren(result: ResearchResult, css: string): Promise<boolean>;
         validateContainers(result: ResearchResult): Promise<void>;
         updateSectionContainer(result: ResearchResult, section: ReturnType<typeof parseResearchSections>[0], newCss: string | null): void;
     };
@@ -30,7 +34,10 @@ export interface Locator {
     pwLocator: string | null;
 }
 export interface LocatorMethods {
-    testLocators(locators: Locator[]): Promise<void>;
+    testLocators(locators: Locator[], opts?: {
+        scope?: boolean;
+    }): Promise<void>;
     fixBrokenSections(result: ResearchResult, conversation: Conversation): Promise<void>;
     backfillBrokenLocators(result: ResearchResult): Promise<void>;
+    resolveContainers(result: ResearchResult): Promise<Locator[]>;
 }