explorbot 0.2.0 → 0.2.1

package/dist/src/explorbot.js

@@ -22,6 +22,9 @@ import { ConfigParser } from "./config.js";
 import { ExperienceTracker } from "./experience-tracker.js";
 import Explorer from "./explorer.js";
 import { KnowledgeTracker } from "./knowledge-tracker.js";
+import { PlaywrightRecorder } from "./playwright-recorder.js";
+import { Reporter } from "./reporter.js";
+import { StateManager } from "./state-manager.js";
 import { Stats } from "./stats.js";
 import { Plan } from "./test-plan.js";
 import { browserErrorMessage } from "./utils/browser-errors.js";
@@ -45,6 +48,10 @@ export class ExplorBot {
     lastReportedTestCount = 0;
     _experienceTracker;
     _knowledgeTracker;
+    _stateManager;
+    _reporter;
+    _requestStore;
+    _playwrightRecorder;
     constructor(options = {}) {
         this.options = options;
         this.configParser = ConfigParser.getInstance();
@@ -54,18 +61,25 @@ export class ExplorBot {
         }
     }
     get isExploring() {
-        return this.explorer?.isStarted;
+        return !!this.explorer;
     }
     setUserResolve(fn) {
         this.userResolveFn = fn;
     }
     async start() {
-        if (this.explorer?.isStarted) {
+        if (this.explorer) {
             return;
         }
         try {
             await this.startProviderOnly();
-            this.explorer = new Explorer(this.config, this.provider, this.options, this.experienceTracker(), this.knowledgeTracker());
+            const explorerOptions = { ...this.options, session: typeof this.options.session === 'string' ? this.options.session : undefined };
+            this.explorer = new Explorer(this.config, explorerOptions, {
+                stateManager: this.stateManager(),
+                knowledgeTracker: this.knowledgeTracker(),
+                reporter: this.reporter(),
+                requestStore: this.requestStore(),
+                playwrightRecorder: this.playwrightRecorder(),
+            });
             await this.explorer.start();
             if (!this.options.incognito) {
                 await this.agentExperienceCompactor().autocompact();
@@ -81,6 +95,8 @@ export class ExplorBot {
         if (this.provider)
             return;
         this.config = await this.configParser.loadConfig(this.options);
+        if (this.options.session === true)
+            this.options.session = path.join(this.configParser.getOutputDir(), 'session.json');
         this.provider = new AIProvider(this.config.ai);
         await this.provider.validateConnection();
     }
@@ -95,11 +111,11 @@ export class ExplorBot {
     async visit(url) {
         return this.agentNavigator().visit(url);
     }
-    async openFreshTab() {
-        await this.explorer.openFreshTab();
+    async openTab() {
+        await this.explorer.openTab();
     }
     getCurrentState() {
-        return this.explorer?.getStateManager().getCurrentState() ?? null;
+        return this._stateManager?.getCurrentState() ?? null;
     }
     getExplorer() {
         return this.explorer;
@@ -110,6 +126,18 @@ export class ExplorBot {
     experienceTracker() {
         return (this._experienceTracker ||= new ExperienceTracker(this.knowledgeTracker()));
     }
+    stateManager() {
+        return (this._stateManager ||= new StateManager(this.experienceTracker(), this.knowledgeTracker()));
+    }
+    reporter() {
+        return (this._reporter ||= new Reporter(this.config.reporter, this.stateManager()));
+    }
+    requestStore() {
+        return (this._requestStore ||= new RequestStore(this.configParser.getOutputDir()));
+    }
+    playwrightRecorder() {
+        return (this._playwrightRecorder ||= new PlaywrightRecorder());
+    }
     getConfig() {
         return this.config;
     }
@@ -124,22 +152,24 @@ export class ExplorBot {
             explorer: this.explorer,
             ai: this.provider,
             config: this.config,
+            stateManager: this.stateManager(),
+            knowledgeTracker: this.knowledgeTracker(),
+            requestStore: this.requestStore(),
+            playwrightRecorder: this.playwrightRecorder(),
         });
         const agentName = agent.constructor.name.toLowerCase();
         tag('debug').log(`Created ${agentName} agent`);
         return agent;
     }
     agentResearcher() {
-        return (this.agents.researcher ||= this.createAgent(({ ai, explorer }) => new Researcher(explorer, ai)));
+        return (this.agents.researcher ||= this.createAgent((deps) => new Researcher(deps)));
     }
     agentNavigator() {
-        return (this.agents.navigator ||= this.createAgent(({ ai, explorer }) => {
-            return new Navigator(explorer, ai);
-        }));
+        return (this.agents.navigator ||= this.createAgent((deps) => new Navigator(deps)));
     }
     agentPlanner() {
         if (!this.agents.planner) {
-            this.agents.planner = this.createAgent(({ ai, explorer }) => new Planner(explorer, ai, this.agentResearcher()));
+            this.agents.planner = this.createAgent((deps) => new Planner(deps, this.agentResearcher()));
             const fisherman = this.agentFisherman();
             if (fisherman)
                 this.agents.planner.setFisherman(fisherman);
@@ -147,25 +177,26 @@ export class ExplorBot {
         return this.agents.planner;
     }
     agentPilot() {
-        return (this.agents.pilot ||= this.createAgent(({ ai, explorer }) => {
+        return (this.agents.pilot ||= this.createAgent((deps) => {
             const researcher = this.agentResearcher();
             const navigator = this.agentNavigator();
-            const tools = createAgentTools({ explorer, researcher, navigator, supervisor: true });
-            return new Pilot(ai, tools, researcher, explorer);
+            const tools = createAgentTools({ ...deps, researcher, navigator, supervisor: true });
+            return new Pilot(deps, tools, researcher);
         }));
     }
     agentTester() {
         if (!this.agents.tester) {
-            this.agents.tester = this.createAgent(({ ai, explorer }) => {
+            this.agents.tester = this.createAgent((deps) => {
                 const researcher = this.agentResearcher();
                 const navigator = this.agentNavigator();
-                const tools = createAgentTools({ explorer, researcher, navigator });
-                return new Tester(explorer, ai, researcher, navigator, tools);
+                const tools = createAgentTools({ ...deps, researcher, navigator });
+                return new Tester(deps, researcher, navigator, tools);
             });
             const qm = this.agentQuartermaster();
             if (qm)
                 this.agents.tester.setQuartermaster(qm);
-            this.agents.tester.setHistorian(this.agentHistorian());
+            if (this.isHistorianEnabled())
+                this.agents.tester.setHistorian(this.agentHistorian());
             this.agents.tester.setPilot(this.agentPilot());
             this.agents.tester.setCaptain(this.agentCaptain());
             const fisherman = this.agentFisherman();
@@ -191,36 +222,35 @@ export class ExplorBot {
             this.agents.quartermaster = new Quartermaster(this.provider, {
                 model: config?.model,
             });
-            this.agents.quartermaster.start(this.explorer.playwrightHelper, this.explorer.getStateManager());
+            this.agents.quartermaster.start(this.explorer, this.stateManager());
         }
         return this.agents.quartermaster;
     }
     agentHistorian() {
-        return (this.agents.historian ||= this.createAgent(({ ai, explorer, config }) => {
-            const experienceTracker = explorer.getStateManager().getExperienceTracker();
-            const reporter = explorer.getReporter();
-            return new Historian(ai, experienceTracker, reporter, explorer.getStateManager(), config, {
-                recorder: explorer.getPlaywrightRecorder(),
-                helper: explorer.playwrightHelper,
+        return (this.agents.historian ||= this.createAgent(({ ai, explorer, config, stateManager, playwrightRecorder }) => {
+            return new Historian(ai, this.experienceTracker(), this.reporter(), stateManager, config, {
+                recorder: playwrightRecorder,
+                explorer,
             });
         }));
     }
     agentRerunner() {
         if (!this.agents.rerunner) {
-            this.agents.rerunner = this.createAgent(({ ai, explorer }) => {
+            this.agents.rerunner = this.createAgent((deps) => {
                 const researcher = this.agentResearcher();
                 const navigator = this.agentNavigator();
-                const tools = createAgentTools({ explorer, researcher, navigator, withExperience: false });
-                return new Rerunner(explorer, ai, tools);
+                const tools = createAgentTools({ ...deps, researcher, navigator, withExperience: false });
+                return new Rerunner(deps, tools);
             });
-            this.agents.rerunner.setHistorian(this.agentHistorian());
+            if (this.isHistorianEnabled())
+                this.agents.rerunner.setHistorian(this.agentHistorian());
         }
         return this.agents.rerunner;
     }
     agentDriller() {
-        return (this.agents.driller ||= this.createAgent(({ ai, explorer }) => {
+        return (this.agents.driller ||= this.createAgent((deps) => {
             const navigator = this.agentNavigator();
-            return new Driller(explorer, ai, navigator);
+            return new Driller(deps, navigator);
         }));
     }
     agentSessionAnalyst() {
@@ -234,7 +264,7 @@ export class ExplorBot {
         if (!this.agents.fisherman) {
             const apiConfig = this.config.api;
             const outputDir = this.configParser.getOutputDir();
-            const requestStore = this.explorer.getRequestStore() || new RequestStore(outputDir);
+            const requestStore = this.requestStore();
             const baseEndpoint = apiConfig?.baseEndpoint || this.config.playwright.url;
             const configHeaders = apiConfig?.headers || {};
             const apiClient = new ApiClient(baseEndpoint);
@@ -249,7 +279,12 @@ export class ExplorBot {
                     return null;
                 }
             };
-            const cookieProvider = () => this.explorer.extractCookies();
+            const cookieProvider = async () => {
+                const cookies = await this.explorer.withPage((page) => page.context().cookies()).catch(() => []);
+                if (!cookies.length)
+                    return {};
+                return { Cookie: cookies.map((c) => `${c.name}=${c.value}`).join('; ') };
+            };
             this.agents.fisherman = this.createAgent(({ ai }) => {
                 return new Fisherman(ai, apiClient, requestStore, specLoader, baseEndpoint, cookieProvider, configHeaders, hasApiConfig);
             });
@@ -275,7 +310,7 @@ export class ExplorBot {
             this.clearPlan();
         }
         if (!opts.extend && this.currentPlan?.url) {
-            const currentUrl = this.explorer?.getStateManager().getCurrentState()?.url;
+            const currentUrl = this._stateManager?.getCurrentState()?.url;
             if (currentUrl && currentUrl !== this.currentPlan.url) {
                 tag('info').log('Different page detected, clearing previous plan');
                 this.clearPlan();
@@ -324,7 +359,7 @@ export class ExplorBot {
         return planPath;
     }
     generatePlanFilename(feature) {
-        const state = this.explorer?.getStateManager().getCurrentState();
+        const state = this._stateManager?.getCurrentState();
         const urlPath = state?.url || '/';
         const urlPart = sanitizeFilename(urlPath) || 'root';
         const suffix = '.md';
@@ -398,7 +433,7 @@ export class ExplorBot {
             tag('multiline').log(markdown, { maxLines: 22 });
             const filePath = this.agentSessionAnalyst().writeReport(markdown);
             tag('info').log(`Session report saved: ${relativeToCwd(filePath)}`);
-            const reporter = this.explorer?.getReporter();
+            const reporter = this._reporter;
             if (reporter?.isEnabled()) {
                 let description = markdown;
                 const modelsTable = Stats.modelsTable(this.provider.getConfiguredModels());
@@ -413,4 +448,7 @@ export class ExplorBot {
             tag('warning').log(`Session analysis failed: ${message}`);
         }
     }
+    isHistorianEnabled() {
+        return this.config.ai?.agents?.historian?.enabled !== false;
+    }
 }

package/dist/src/explorer.d.ts

@@ -1,17 +1,14 @@
-import type { BrowserContextOptions } from 'playwright';
+import type { BrowserContextOptions, Page } from 'playwright';
 import { ActionResult } from './action-result.js';
 import Action from './action.js';
-import { AIProvider } from './ai/provider.js';
-import { RequestStore } from './api/request-store.js';
+import type { RequestStore } from './api/request-store.js';
 import { XhrCapture } from './api/xhr-capture.js';
 import type { ExplorbotConfig } from './config.js';
-import type { ExperienceTracker } from './experience-tracker.js';
-import { KnowledgeTracker } from './knowledge-tracker.js';
-import { PlaywrightRecorder } from './playwright-recorder.js';
-import { Reporter } from './reporter.js';
-import { StateManager } from './state-manager.js';
+import type { KnowledgeTracker } from './knowledge-tracker.js';
+import type { PlaywrightRecorder } from './playwright-recorder.js';
+import type { Reporter } from './reporter.js';
+import type { StateManager } from './state-manager.js';
 import { Test } from './test-plan.js';
-import { WebElement } from './utils/web-element.js';
 declare global {
     namespace NodeJS {
         interface Global {
@@ -24,106 +21,84 @@ declare namespace CodeceptJS {
         [key: string]: any;
     }
 }
-interface TabInfo {
-    url: string;
-    title: string;
-}
-interface BrowserExecutionErrorResult {
-    action: 'continue' | 'stop';
-    message: string;
-    recovered?: boolean;
-}
 declare class Explorer {
-    aiProvider: AIProvider;
-    playwrightHelper: any;
-    isStarted: boolean;
-    isSharedBrowser: boolean;
-    actor: CodeceptJS.I;
+    config: ExplorbotConfig;
+    options?: ExplorerOptions;
     stateManager: StateManager;
     knowledgeTracker: KnowledgeTracker;
-    config: ExplorbotConfig;
-    options?: {
-        show?: boolean;
-        headless?: boolean;
-        incognito?: boolean;
-        session?: string;
-    };
     reporter: Reporter;
-    otherTabs: TabInfo[];
-    _activeTest: Test | null;
-    xhrCapture: XhrCapture | null;
-    requestStore: RequestStore | null;
+    requestStore: RequestStore;
     playwrightRecorder: PlaywrightRecorder;
+    playwrightHelper: any;
+    _actor: CodeceptJS.I;
+    started: boolean;
+    isSharedBrowser: boolean;
+    xhrCapture: XhrCapture | null;
+    _activeTest: Test | null;
     observedTestPages: Set<any>;
     testPageErrorHandler: ((error: Error) => void) | null;
     testConsoleHandler: ((message: any) => void) | null;
     testDialogHandler: ((dialog: any) => void) | null;
-    constructor(config: ExplorbotConfig, aiProvider: AIProvider, options: {
-        show?: boolean;
-        headless?: boolean;
-        incognito?: boolean;
-        session?: string;
-    } | undefined, experienceTracker: ExperienceTracker, knowledgeTracker: KnowledgeTracker);
+    constructor(config: ExplorbotConfig, options: ExplorerOptions | undefined, deps: ExplorerDeps);
+    get actor(): CodeceptJS.I;
+    get page(): Page | null;
+    get activeTest(): Test | null;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    action(): Action;
+    visit(url: string, opts?: CaptureOpts): Promise<ActionResult>;
+    capture(opts?: CaptureOpts): Promise<ActionResult>;
+    withPage<T>(fn: (page: Page) => Promise<T>): Promise<T>;
+    recover(error?: unknown): Promise<Recovery>;
+    beginTest(test: Test): Promise<TestRun>;
+    openTab(): Promise<void>;
     initializeContainer(): void;
     convertToCodeceptConfig(config: ExplorbotConfig): any;
-    getConfig(): ExplorbotConfig;
-    getAIProvider(): AIProvider;
-    getStateManager(): StateManager;
-    getKnowledgeTracker(): KnowledgeTracker;
-    getReporter(): Reporter;
-    getRequestStore(): RequestStore | null;
-    extractCookies(): Promise<Record<string, string>>;
-    setupXhrCapture(reuseRequestStore?: boolean): void;
-    start(): Promise<any>;
     connectOrLaunchBrowser(): Promise<void>;
     createBrowserContextOptions(): BrowserContextOptions;
-    createAction(): Action;
-    runWithBrowserRecovery<T>(label: string, operation: () => Promise<T>): Promise<T>;
-    capturePageState(opts?: {
-        includeScreenshot?: boolean;
-    }): Promise<ActionResult>;
-    capturePageWithScreenshot(): Promise<ActionResult>;
-    executeAction(code: string): Promise<Action>;
-    attemptAction(code: string, originalMessage?: string): Promise<boolean>;
-    getPlaywrightRecorder(): PlaywrightRecorder;
-    visit(url: string): Promise<Action>;
+    attachXhrCapture(): void;
+    runWithRecovery<T>(label: string, operation: () => Promise<T>): Promise<T>;
     visitOnce(url: string): Promise<Action>;
-    annotateElements(): Promise<WebElement[]>;
-    visuallyAnnotateElements(opts?: {
-        containers?: Array<{
-            css: string;
-            label: string;
-        }>;
-    }): Promise<number>;
-    getEidxInContainer(containerCss: string | null): Promise<string[]>;
-    getEidxByLocator(locator: string, container?: string | null): Promise<string | null>;
-    resolveBrowserUrl(url?: string): string | null;
-    isFatalBrowserError(error: unknown): boolean;
-    recoverFromBrowserError(): Promise<boolean>;
+    recoverFromExecutionError(error: unknown): Promise<Recovery>;
+    recoverOrRestart(): Promise<boolean>;
+    recoverPage(): Promise<boolean>;
+    activateNewPage(context: any): Promise<void>;
+    stopCaptures(): Promise<void>;
+    closeBrowserContext(): Promise<void>;
     restartBrowser(): Promise<boolean>;
-    switchToMainFrame(): Promise<void>;
+    resolveBrowserUrl(url?: string): string | null;
     waitForPageReadiness(): Promise<boolean>;
-    isInsideIframe(): Promise<boolean>;
-    getCurrentIframeInfo(): string | null;
-    hasOtherTabs(): boolean;
-    getOtherTabsInfo(): TabInfo[];
-    clearOtherTabsInfo(): void;
     listenToStateChanged(): void;
-    stop(): Promise<void>;
-    get activeTest(): Test | null;
-    startTest(test: Test): Promise<boolean>;
-    ensurePageAvailable(): Promise<boolean>;
-    handleExecutionError(error: unknown): Promise<BrowserExecutionErrorResult>;
-    watchActiveTestPage(page?: any): void;
-    stopTest(test: Test, meta?: Record<string, string>): Promise<void>;
-    unwatchActiveTestPages(): void;
-    playwrightLocatorCount(locatorFn: (page: any) => any): Promise<number>;
     bindFrameNavigated(page: any): void;
-    openFreshTab(): Promise<void>;
     closeOtherTabs(): Promise<void>;
+    finishTest(test: Test, meta?: Record<string, string>): Promise<void>;
+    watchActiveTestPage(page?: any): void;
+    unwatchActiveTestPages(): void;
+}
+export interface ExplorerOptions {
+    show?: boolean;
+    headless?: boolean;
+    incognito?: boolean;
+    session?: string;
+}
+export interface ExplorerDeps {
+    stateManager: StateManager;
+    knowledgeTracker: KnowledgeTracker;
+    reporter: Reporter;
+    requestStore: RequestStore;
+    playwrightRecorder: PlaywrightRecorder;
+}
+export interface Recovery {
+    ok: boolean;
+    action: 'continue' | 'stop';
+    message: string;
+    recovered?: boolean;
+}
+export interface TestRun {
+    started: boolean;
+    stop(meta?: Record<string, string>): Promise<void>;
+}
+export interface CaptureOpts {
+    screenshot?: boolean;
 }
-export declare function annotatePageElements(page: any): Promise<{
-    ariaSnapshot: string;
-    elements: WebElement[];
-}>;
 export default Explorer;