explorbot 0.1.32-beta.1 → 0.2.1

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

@@ -1,22 +1,20 @@
 import { ActionResult } from '../action-result.js';
-import type { ExperienceTracker } from '../experience-tracker.js';
-import type Explorer from '../explorer.js';
+import type { RequestStore } from '../api/request-store.js';
+import type { TestRun } from '../explorer.js';
 import { type Test } from '../test-plan.js';
-import { HooksRunner } from '../utils/hooks-runner.js';
-import type { Agent } from './agent.js';
+import type { Agent, AgentDeps } from './agent.js';
 import type { Captain } from './captain.js';
 import type { Conversation } from './conversation.js';
 import { Navigator } from './navigator.js';
 import type { Pilot } from './pilot.js';
-import { Provider } from './provider.js';
 import { Researcher } from './researcher.js';
 import { TaskAgent } from './task-agent.js';
 export declare class Tester extends TaskAgent implements Agent {
     readonly ACTION_TOOLS: string[];
     readonly SPECIAL_CONTEXT_ACTION_TOOLS: string[];
     emoji: string;
-    explorer: Explorer;
-    provider: Provider;
+    requestStore: RequestStore;
+    testRun: TestRun | null;
     currentConversation: Conversation | null;
     pilot: Pilot | null;
     captain: Captain | null;
@@ -26,21 +24,16 @@ export declare class Tester extends TaskAgent implements Agent {
     researcher: Researcher;
     navigator: Navigator;
     agentTools: any;
-    executionLogFile: string | null;
     previousUrl: string | null;
     previousStateHash: string | null;
     pageStateHash: string | null;
     pageActionResult: ActionResult | null;
-    hooksRunner: HooksRunner;
     seenUiMapUrls: Set<string>;
     lastAnalyzedStateHash: string | null;
     stalledIterations: number;
     readonly MAX_STALLED_ITERATIONS = 3;
-    constructor(explorer: Explorer, provider: Provider, researcher: Researcher, navigator: Navigator, agentTools?: any);
+    constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any);
     getNavigator(): Navigator;
-    getExperienceTracker(): ExperienceTracker;
-    getKnowledgeTracker(): import("../knowledge-tracker.js").KnowledgeTracker;
-    getProvider(): Provider;
     setPilot(pilot: Pilot): void;
     setCaptain(captain: Captain): void;
     getCurrentState(): ActionResult;
@@ -56,7 +49,6 @@ export declare class Tester extends TaskAgent implements Agent {
     shouldStopForStalledExecution(task: Test, previousState: ActionResult, toolExecutions: any[]): boolean;
     prepareInstructionsForNextStep(task: Test): Promise<string>;
     reinjectContextIfNeeded(iteration: number, currentState: ActionResult): Promise<string>;
-    promptLogStep(task: Test): Promise<string>;
     finishTest(task: Test): void;
     abortStartedTestOnErrorPage(task: Test, actionResult: ActionResult): Promise<{
         success: boolean;

package/dist/src/ai/tester.js

@@ -5,18 +5,16 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { clearActivity, setActivity } from "../activity.js";
-import { ConfigParser } from "../config.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
 import { TestResult } from "../test-plan.js";
 import { detectFocusArea, extractFocusedElement } from "../utils/aria.js";
 import { ErrorPageError, isErrorPage } from "../utils/error-page.js";
-import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
 import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from "./rules.js";
 import { TaskAgent } from "./task-agent.js";
-import { createCodeceptJSTools, createSpecialContextTools } from "./tools.js";
+import { createCodeceptJSTools, createIframeTools } from "./tools.js";
 const debugLog = createDebug('explorbot:tester');
 const SAMPLE_FILES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../../assets/sample-files');
 const SAMPLE_FILES = {
@@ -32,8 +30,8 @@ export class Tester extends TaskAgent {
     ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
     SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
     emoji = '🧪';
-    explorer;
-    provider;
+    requestStore;
+    testRun = null;
     currentConversation = null;
     pilot = null;
     captain = null;
@@ -43,37 +41,24 @@ export class Tester extends TaskAgent {
     researcher;
     navigator;
     agentTools;
-    executionLogFile = null;
     previousUrl = null;
     previousStateHash = null;
     pageStateHash = null;
     pageActionResult = null;
-    hooksRunner;
     seenUiMapUrls = new Set();
     lastAnalyzedStateHash = null;
     stalledIterations = 0;
     MAX_STALLED_ITERATIONS = 3;
-    constructor(explorer, provider, researcher, navigator, agentTools) {
-        super();
-        this.explorer = explorer;
-        this.provider = provider;
+    constructor(deps, researcher, navigator, agentTools) {
+        super(deps);
+        this.requestStore = deps.requestStore;
         this.researcher = researcher;
         this.navigator = navigator;
         this.agentTools = agentTools;
-        this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
     }
     getNavigator() {
         return this.navigator;
     }
-    getExperienceTracker() {
-        return this.explorer.getStateManager().getExperienceTracker();
-    }
-    getKnowledgeTracker() {
-        return this.explorer.getKnowledgeTracker();
-    }
-    getProvider() {
-        return this.provider;
-    }
     setPilot(pilot) {
         this.pilot = pilot;
     }
@@ -81,17 +66,17 @@ export class Tester extends TaskAgent {
         this.captain = captain;
     }
     getCurrentState() {
-        return ActionResult.fromState(this.explorer.getStateManager().getCurrentState());
+        return ActionResult.fromState(this.stateManager.getCurrentState());
     }
     get progressCheckInterval() {
-        return this.explorer.getConfig().ai?.agents?.tester?.progressCheckInterval ?? 3;
+        return this.config.ai?.agents?.tester?.progressCheckInterval ?? 3;
     }
     getConversation() {
         return this.currentConversation;
     }
     async test(task) {
         Stats.tests++;
-        const state = this.explorer.getStateManager().getCurrentState();
+        const state = this.stateManager.getCurrentState();
         if (!state)
             throw new Error('No state found');
         setActivity(`🧪 Testing: ${task.scenario}`, 'action');
@@ -102,27 +87,24 @@ export class Tester extends TaskAgent {
         this.seenUiMapUrls.clear();
         this.lastAnalyzedStateHash = null;
         this.stalledIterations = 0;
-        this.explorer.getStateManager().clearHistory();
+        this.stateManager.clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
-        const requestStore = this.explorer.getRequestStore();
-        requestStore?.clear();
-        const offFailedRequest = requestStore?.onFailedRequest((r) => {
+        const requestStore = this.requestStore;
+        requestStore.clear();
+        const offFailedRequest = requestStore.onFailedRequest((r) => {
             task.addNote(`Network error: ${r.method} ${r.path} → ${r.status}`, TestResult.FAILED);
         });
         const initialState = ActionResult.fromState(state);
         if (isErrorPage(initialState)) {
             task.start();
-            await this.explorer.startTest(task);
+            this.testRun = await this.explorer.beginTest(task);
             offFailedRequest?.();
             return await this.abortStartedTestOnErrorPage(task, initialState);
         }
         const conversation = this.provider.startConversation(this.getSystemMessage(), 'tester');
         conversation.markLastMessageCacheable();
         this.currentConversation = conversation;
-        const outputDir = ConfigParser.getInstance().getOutputDir();
-        this.executionLogFile = join(outputDir, `tester_${task.sessionName}.md`);
-        // Note: Markdown saving functionality removed from Conversation class
         const scenarioBlock = this.buildScenarioBlock(task, initialState);
         conversation.addUserText(scenarioBlock);
         conversation.markLastMessageCacheable();
@@ -163,7 +145,8 @@ export class Tester extends TaskAgent {
             }
         }
         debugLog('Starting test execution with tools');
-        if (!(await this.explorer.startTest(task))) {
+        this.testRun = await this.explorer.beginTest(task);
+        if (!this.testRun.started) {
             offFailedRequest?.();
             await this.cleanupStartedTest(task);
             return { success: task.isSuccessful };
@@ -180,7 +163,7 @@ export class Tester extends TaskAgent {
                 return { success: task.isSuccessful };
             }
         }
-        const startState = this.explorer.getStateManager().getCurrentState();
+        const startState = this.stateManager.getCurrentState();
         if (startState) {
             task.addUrlNote(startState);
             const startActionResult = ActionResult.fromState(startState);
@@ -191,7 +174,7 @@ export class Tester extends TaskAgent {
         }
         const currentUrl = startState?.url || task.startUrl || '';
         await this.hooksRunner.runBeforeHook('tester', currentUrl);
-        const offStateChange = this.explorer.getStateManager().onStateChange((event) => {
+        const offStateChange = this.stateManager.onStateChange((event) => {
             if (task.hasFinished)
                 return;
             if (event.toState?.url === event.fromState?.url)
@@ -200,7 +183,7 @@ export class Tester extends TaskAgent {
                 task.addUrlNote(event.toState, event.fromState || undefined);
             task.states.push(event.toState);
         });
-        const codeceptjsTools = createCodeceptJSTools(this.explorer, task);
+        const codeceptjsTools = createCodeceptJSTools(this.toolDeps, task);
         let assertionPerformed = false;
         let extensions = 0;
         let shouldContinue = true;
@@ -208,7 +191,7 @@ export class Tester extends TaskAgent {
             shouldContinue = false;
             await loop(async ({ stop, pause, iteration, userInput }) => {
                 debugLog('iteration', iteration);
-                if (!(await this.explorer.ensurePageAvailable())) {
+                if (!(await this.explorer.recover()).ok) {
                     task.addNote('Browser page is unavailable');
                     task.finish(TestResult.FAILED);
                     stop();
@@ -217,12 +200,14 @@ export class Tester extends TaskAgent {
                 const currentState = this.getCurrentState();
                 const tools = {
                     ...codeceptjsTools,
-                    ...(currentState.isInsideIframe ? createSpecialContextTools(this.explorer, 'iframe') : {}),
                     ...this.createTestFlowTools(task, currentState, conversation),
                     ...this.agentTools,
                 };
+                if (currentState.isInsideIframe) {
+                    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;
@@ -357,7 +342,7 @@ export class Tester extends TaskAgent {
             });
             if (task.hasFinished)
                 break;
-            if (!(await this.explorer.ensurePageAvailable()))
+            if (!(await this.explorer.recover()).ok)
                 break;
             const finalState = this.getCurrentState();
             const wantsContinue = await this.pilot.finalReview(task, finalState, conversation, this.navigator);
@@ -375,7 +360,7 @@ export class Tester extends TaskAgent {
             conversation.compactToolResults(1);
             shouldContinue = true;
         }
-        const finalUrl = this.explorer.getStateManager().getCurrentState()?.url || currentUrl;
+        const finalUrl = this.stateManager.getCurrentState()?.url || currentUrl;
         await this.hooksRunner.runAfterHook('tester', finalUrl);
         await this.getHistorian().saveSession(task, initialState, conversation);
         if (task.plan) {
@@ -385,7 +370,7 @@ export class Tester extends TaskAgent {
         offStateChange();
         offFailedRequest?.();
         await this.finishTest(task);
-        await this.explorer.stopTest(task, this.buildStopTestMeta(task));
+        await this.testRun?.stop(this.buildStopTestMeta(task));
         return {
             success: task.isSuccessful,
             ...task,
@@ -456,7 +441,6 @@ export class Tester extends TaskAgent {
         const currentUrl = currentState.url;
         const currentStateHash = currentState.hash;
         const isNewUrl = this.previousUrl !== currentUrl;
-        const isStateChanged = !isNewUrl && this.previousStateHash !== currentStateHash;
         this.previousUrl = currentUrl;
         this.previousStateHash = currentStateHash;
         let context = '';
@@ -490,7 +474,7 @@ export class Tester extends TaskAgent {
       `;
         }
         if (currentState.isInsideIframe) {
-            const iframeInfo = currentState.iframeURL || this.explorer.getCurrentIframeInfo() || 'iframe context active';
+            const iframeInfo = currentState.iframeURL || 'iframe context active';
             context += dedent `
         <iframe_context>
         INSIDE IFRAME: ${iframeInfo}
@@ -498,10 +482,10 @@ export class Tester extends TaskAgent {
         </iframe_context>
       `;
         }
-        if (this.explorer.hasOtherTabs()) {
-            const otherTabs = this.explorer.getOtherTabsInfo();
+        const otherTabs = this.stateManager.otherTabs;
+        if (otherTabs.length > 0) {
             context += multipleTabsRule(otherTabs);
-            this.explorer.clearOtherTabsInfo();
+            this.stateManager.otherTabs = [];
         }
         if (isNewUrl) {
             const alreadySeenUiMap = this.seenUiMapUrls.has(currentUrl);
@@ -564,23 +548,6 @@ export class Tester extends TaskAgent {
         `;
             }
         }
-        // if (isStateChanged) {
-        //   const combinedHtml = await currentState.combinedHtml();
-        //   context += dedent`
-        //     Context (state changed):
-        //     <page>
-        //     CURRENT URL: ${currentState.url}
-        //     CURRENT TITLE: ${currentState.title}
-        //     </page>
-        //     <page_html>
-        //     ${combinedHtml}
-        //     </page_html>
-        //     <page_aria>
-        //     ${currentState.ariaSnapshot}
-        //     </page_aria>
-        //   `;
-        //   return context;
-        // }
         if (context)
             return context;
         if (iteration % 5)
@@ -598,34 +565,6 @@ export class Tester extends TaskAgent {
       </page_aria>
     `;
     }
-    async promptLogStep(task) {
-        let logPrompt = dedent `
-      <task>
-        Add a note explaining what you achieved with previous action.
-        Use tools to interact with the page to achieve the scenario goal or expected outcomes.
-        Call record tool to explain the last action
-        Format: record([<action performed>, <what has changed>, <what you expect to do next>]) 
-      </task>
-    `;
-        if (task.getPrintableNotes()) {
-            logPrompt = dedent `
-        Your interaction log notes:
-        <notes>
-        ${task.getPrintableNotes()}
-        </notes>
-
-        <rules>
-        Use your previous interaction notes to guide your next actions.
-        Do not perform the same checks.
-        </rules>
-      `;
-        }
-        const remaining = task.getRemainingExpectations();
-        if (remaining.length > 0) {
-            logPrompt += `\nExpected steps to check: ${remaining.join(', ')}`;
-        }
-        return logPrompt;
-    }
     finishTest(task) {
         if (!task.hasFinished) {
             task.finish(TestResult.FAILED);
@@ -649,7 +588,7 @@ export class Tester extends TaskAgent {
         task.addNote(error.message, TestResult.FAILED, actionResult.screenshotFile, actionResult.fullUrl || actionResult.url);
         task.finish(TestResult.FAILED);
         this.finishTest(task);
-        await this.explorer.stopTest(task, this.buildStopTestMeta(task));
+        await this.testRun?.stop(this.buildStopTestMeta(task));
         clearActivity(true);
         return { success: false };
     }
@@ -725,11 +664,13 @@ export class Tester extends TaskAgent {
     - Before retrying your actions check maybe they already achived expected results. Use see() tool for that
     - If the current URL is already a create/edit/new form and the scenario is about creating/editing that entity, fill and submit that form. Do not click the list-page "New" button again from inside the form.
     - If the scenario is about search/filter/sort/tabs/list inspection and the current URL is a create/edit/new form, go back or reset to the stable list page before interacting with list controls.
-    - When selecting related entities from a list, do not choose rows/options/cards marked as "0 items", "0 tests", or otherwise empty if the scenario requires selecting real content.
-    - In selection pickers, counters such as "Selected 0", "Matched tests 0", or disabled Save/Apply mean the selection did not register. Choose a non-empty item or change filters before submitting.
+    - When selecting related entities from a list, do not choose rows/options/cards marked as "0 items", "0 results", or otherwise empty if the scenario requires selecting real content.
+    - In selection pickers, counters such as "Selected 0", "Matched 0", or disabled Save/Apply mean the selection did not register. Choose a non-empty item or change filters before submitting.
     - A passed form/click command only means the command executed. If a required field remains empty, submit stays disabled, or the expected text is not visible, treat the action as not completed and correct the missing field/state.
-    - For filter/tab scenarios, success requires BOTH: the requested filter/tab is visibly active/selected AND the list content matches that filter. Do not finish from only one of these signals.
-    - Empty-state text such as "No matched items" only proves a filter when the requested filter/tab is active and the empty state belongs to the filtered list.
+    - For filter/tab scenarios, success requires BOTH: the requested state is evidenced by a selected control, URL/query, or another explicit state indicator AND the list content matches that state. Do not finish from only one of these signals.
+    - Once the requested control state and matching content are both visible, finish the scenario instead of repeating the interaction. Do not require an aggregate count change unless a baseline was observed immediately before the action.
+    - Empty-state text such as "No matched items" only proves a filter when the requested filter state is explicit and the empty state belongs to the filtered list.
+    - Associate validation feedback with a field only through explicit evidence such as the field label in the message, an accessibility relationship, focus on the invalid control, or visual confirmation. Do not infer the affected field from DOM order or proximity alone.
     - When filling complex form with lot of actions performed, use see() to look which fields were filled and which are not
     - When verify() fails, use see() to visually confirm the result — visual confirmation is equally valid evidence
     - For visual state verification (active tabs, selected items, counts, colors), prefer see() over DOM-based verify()
@@ -762,7 +703,7 @@ export class Tester extends TaskAgent {
 
     ${dataProtectionRules}
 
-    ${this.provider.getSystemPromptForAgent('tester', this.explorer.getStateManager().getCurrentState()?.url) || ''}
+    ${this.provider.getSystemPromptForAgent('tester', this.stateManager.getCurrentState()?.url) || ''}
     `;
     }
     buildScenarioBlock(task, actionResult) {
@@ -788,10 +729,6 @@ export class Tester extends TaskAgent {
       When creating or editing items via form() or type() you should include ${task.sessionName} in the value (if it is not restricted by the application logic)
       Initial page URL: ${actionResult.url}
 
-      ${capabilityGroundingRule}
-
-      ${dataProtectionRules}
-
       ${this.buildDeletionScope(task)}
 
       ${this.buildAvailableFiles()}
@@ -810,7 +747,7 @@ export class Tester extends TaskAgent {
             .map((t) => t.sessionName);
     }
     buildAvailableFiles() {
-        const userFiles = this.explorer.getConfig().files || {};
+        const userFiles = this.config.files || {};
         const codeceptDir = global.codecept_dir || process.cwd();
         const lines = [];
         for (const [description, filename] of Object.entries(SAMPLE_FILES)) {
@@ -864,10 +801,8 @@ export class Tester extends TaskAgent {
                     reason: z.string().optional().describe('Explanation why reset is the only option'),
                 }),
                 execute: async ({ reason }) => {
-                    if (this.getCurrentState().isInsideIframe) {
-                        await this.explorer.switchToMainFrame();
-                    }
-                    const currentState = this.explorer.getStateManager().getCurrentState();
+                    await this.explorer.action().exitIframe();
+                    const currentState = this.stateManager.getCurrentState();
                     const currentUrl = currentState?.fullUrl || currentState?.url;
                     if (currentUrl === resetUrl) {
                         return {
@@ -892,7 +827,7 @@ export class Tester extends TaskAgent {
                     const explanation = reason ? `${reason} (RESET)` : 'Resetting to initial page';
                     const targetUrl = resetUrl;
                     task.addNote(explanation);
-                    const resetAction = this.explorer.createAction();
+                    const resetAction = this.explorer.action();
                     const success = await resetAction.attempt(`I.amOnPage(${JSON.stringify(targetUrl)})`, explanation);
                     if (success) {
                         return {
@@ -1035,7 +970,7 @@ export class Tester extends TaskAgent {
                     else if (input.status === 'fail') {
                         mappedStatus = TestResult.FAILED;
                     }
-                    const screenshotFile = this.explorer.getStateManager().getCurrentState()?.screenshotFile;
+                    const screenshotFile = this.stateManager.getCurrentState()?.screenshotFile;
                     for (const noteText of input.notes) {
                         task.addNote(noteText, mappedStatus, screenshotFile);
                         if (input.status === 'success') {
@@ -1072,7 +1007,7 @@ export class Tester extends TaskAgent {
         const message = error instanceof Error ? error.message : String(error);
         if (!task.hasFinished)
             task.addNote(`Execution error: ${message}`);
-        const result = await this.explorer.handleExecutionError(error);
+        const result = await this.explorer.recover(error);
         tag('info').log(`Browser supervisor: ${result.action} - ${result.message}`);
         task.addNote(result.message);
         if (result.action === 'stop') {
@@ -1103,7 +1038,7 @@ export class Tester extends TaskAgent {
     }
     async cleanupStartedTest(task) {
         await this.finishTest(task);
-        await this.explorer.stopTest(task, {
+        await this.testRun?.stop({
             startUrl: task.startUrl,
             style: task.style,
             sessionName: task.sessionName,

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

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