explorbot 0.1.4 → 0.1.6

package/dist/src/ai/researcher.js

@@ -20,6 +20,7 @@ import { detectFocusFromAria, hasFocusedSection, markSectionAsFocused, pickDefau
 import { WithLocators } from "./researcher/locators.js";
 import { extractValidContainers, formatResearchSummary, parseResearchSections } from "./researcher/parser.js";
 import { ResearchResult } from "./researcher/research-result.js";
+import { WithSections } from "./researcher/sections.js";
 import { locatorRule as generalLocatorRuleText } from './rules.js';
 import { RulesLoader } from "../utils/rules-loader.js";
 import { TaskAgent } from "./task-agent.js";
@@ -33,7 +34,7 @@ export const POSSIBLE_SECTIONS = {
     menu: 'page menu (toolbar, context actions, filters, dropdowns)',
     navigation: 'main navigation (top bar, sidebar, breadcrumbs)',
 };
-const ResearcherBase = WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent)));
+const ResearcherBase = WithSections(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent))));
 export class Researcher extends ResearcherBase {
     ACTION_TOOLS = ['click'];
     emoji = '🔍';
@@ -71,10 +72,6 @@ export class Researcher extends ResearcherBase {
     You are senior QA focused on exploritary testig of web application.
     </role>
 
-    <wording>
-    In the UI map and all descriptions, name concrete UI parts (visible labels, headings, regions, ARIA roles). Do not use vague placeholders like "the page", "the element", "the button", "the input", "the link", "the form", "the table", "the list", or "the item". Do not use filler such as "comprehensive", "All required", "All elements", or "All necessary".
-    </wording>
-
     ${customPrompt || ''}
     `;
     }
@@ -134,9 +131,13 @@ export class Researcher extends ResearcherBase {
             const conversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
             const prompt = await this.buildResearchPrompt();
             conversation.addUserText(prompt);
-            let invocationResult;
+            let researchText;
+            let activeConversation = conversation;
             try {
-                invocationResult = await this.provider.invokeConversation(conversation, undefined, { agentName: 'researcher' });
+                const invocationResult = await this.provider.invokeConversation(conversation, undefined, { agentName: 'researcher' });
+                if (!invocationResult)
+                    throw new Error('Failed to get response from provider');
+                researchText = invocationResult.response.text;
             }
             catch (error) {
                 if (!(error instanceof ContextLengthError) || retriesLeft <= 0) {
@@ -145,29 +146,12 @@ export class Researcher extends ResearcherBase {
                     }
                     throw error;
                 }
-                tag('warning').log('Output truncated, retrying with focused instructions...');
                 retriesLeft = 0;
-                conversation.addUserText(this.buildFocusedRetryPrompt());
-                invocationResult = await this.provider.invokeConversation(conversation, undefined, { agentName: 'researcher' });
+                researchText = await this.researchBySections();
+                activeConversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
             }
-            if (!invocationResult)
-                throw new Error('Failed to get response from provider');
-            const result = new ResearchResult(invocationResult.response.text, state.url);
+            const result = new ResearchResult(researchText, state.url);
             debugLog(`Original research response length: ${result.text.length} chars`);
-            const errorSection = mdq(result.text).query('section("Error Page Detected")');
-            if (errorSection.count() > 0) {
-                if (result.text.length < 500) {
-                    if (!opts._skipErrorPageRetry && (await this.waitForPageLoad(screenshot))) {
-                        return this.research(state, { ...opts, force: true, _skipErrorPageRetry: true });
-                    }
-                    tag('warning').log(`AI detected error page at ${state.url}`);
-                    if (stateHash)
-                        saveResearch(stateHash, result.text);
-                    await this.hooksRunner.runAfterHook('researcher', state.url);
-                    return result.text;
-                }
-                result.text = errorSection.replace('');
-            }
             const interrupted = () => executionController.isInterrupted();
             // Stage 2: Test containers + locators
             result.parseLocators();
@@ -204,7 +188,7 @@ export class Researcher extends ResearcherBase {
             }
             // Stage 3: Fix broken sections via AI conversation continuation
             if (!interrupted() && fix && result.locators.some((l) => l.valid === false)) {
-                await this.fixBrokenSections(result, conversation);
+                await this.fixBrokenSections(result, activeConversation);
             }
             // Focused section: parse AI declaration, then ARIA fallback
             const focusMatch = result.text.match(/^>\s*Focused:\s*(.+)/m);
@@ -357,32 +341,29 @@ export class Researcher extends ResearcherBase {
     }
     researchRules() {
         const sections = this.getConfiguredSections();
+        const currentUrl = this.stateManager.getCurrentState()?.url || '';
         return dedent `
       <task>
-      Examine the provided page and explain its main purpose from the user perspective.
-      Identify the main user actions of this page.
-      Break down the page by sections and identify structural patterns.
-      Provide a comprehensive UI map report in markdown format.
+      Examine the page and explain its main purpose from the user perspective.
+      Identify the primary user actions and break the page into sections.
+      Provide a UI map report in markdown.
       </task>
 
       <rules>
       - Explain what the user can achieve on this page.
       - Focus on primary user actions and interactive elements only.
       - Research all menus and navigational areas.
-      - Ignore purely decorative sidebars, footer-only links, and external links.
+      - Ignore decorative sidebars, footer-only links, and external links.
       - Detect layout patterns: list/detail split, 2-pane, or 3-pane layouts.
-      - If multiple elements match, pick the element inside the most relevant section and closest to recent UI context.
-      - UI map table must include ARIA and CSS for every element.
-      - Every element MUST have a CSS selector. NEVER leave CSS as "-".
-      - For icon-only buttons with empty aria-label, set ARIA to "-" but ALWAYS provide CSS.
-      - NEVER skip elements that have an eidx attribute. Every element with eidx MUST appear in the UI map table, even if it has no text or accessible name. Describe icon-only elements using their SVG class (e.g., md-icon-dots-horizontal → "More actions (ellipsis)") or their visual appearance.
-      - ARIA locator must be JSON with role and text keys (NOT "name").
-      - Note elements likely to have hover interactions (elements with title attribute, aria-describedby, navigation menu items with submenus) and mark them with "(hover)" in the UI map.
+      - Every element with an eidx attribute MUST appear in the UI map — describe icon-only buttons by their visual role.
+      - Every UI map row needs a CSS selector; ARIA may be "-" for icon-only buttons, CSS must never be "-".
+      - ARIA locator JSON uses keys "role" and "text" (NOT "name").
+      - Mark elements with likely hover interactions (title, aria-describedby, menu items with submenus) as "(hover)".
       </rules>
 
       ${generalLocatorRuleText}
 
-      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element'], this.stateManager.getCurrentState()?.url || '')}
+      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl)}
 
       <section_identification>
       Identify page sections in this priority order:
@@ -390,23 +371,12 @@ export class Researcher extends ResearcherBase {
             .map(([name, description]) => `* ${name}: ${description}`)
             .join('\n')}
 
-      - Sections can overlap, prefer more detailed sections over broader ones.
-      - Never name a section "Focus" or "Focused" — describe what the section actually contains (e.g., "Detail", "Modal", "Form", "Content", "List").
-      - If a proposed section is not relevant or not detected, do not include it.
-      - Each section must have a container CSS locator.
-      - UI map CSS locators must be relative to the section container.
+      - Sections can overlap; prefer more detailed sections over broader ones.
+      - Never name a section "Focus" or "Focused" — use what it contains (Detail, Modal, Form, Content, List).
+      - Omit sections that are not present or not relevant.
+      - Each section needs a container CSS locator; UI map CSS locators are relative to it.
       </section_identification>
 
-      <container_rules>
-      CRITICAL: Container CSS must be a SINGLE selector — one class, one ID, or one attribute.
-      No spaces, no >, no combinators, no nesting.
-      - INVALID: '.filterbar-filter-btn-div button', 'div.static nav', 'div > .content'
-      - INVALID: 'div', 'section', 'nav', 'div:first' (bare tags are not containers)
-      - INVALID: Tailwind/Bootstrap utility classes that describe layout or styling (e.g. flex-none, d-flex, col-md-6, items-center, mt-4, p-2, bg-white, text-sm, rounded-lg). These are visual, not semantic.
-      - VALID: Semantic class names that describe WHAT the section IS — e.g. '.product-list', '.sidebar-menu', '.user-profile', '[role="dialog"]', '.search-results'
-      Container must uniquely identify a semantic wrapper, not a path through the DOM.
-      </container_rules>
-
       <section_format>
       ## Section Name
 
@@ -416,40 +386,16 @@ export class Researcher extends ResearcherBase {
 
       | Element | ARIA | CSS | eidx |
       </section_format>
-      <section_example>
-      ## List
-
-      Product catalog showing available items with sorting and filtering.
-
-      > Container: '.product-list'
-
-      | Element | ARIA | CSS | eidx |
-      | 'Sort by price' | { role: 'button', text: 'Sort by price' } | '.sort-btn' | 3 |
-      | 'Add to cart' | { role: 'button', text: 'Add to cart' } | '.add-btn' | 4 |
-      | 'Product name' | { role: 'link', text: 'Widget Pro' } | 'a.product-link' | 5 |
-      </section_example>
 
       <focused_section>
-      At the very end of your output, add a single line declaring which section is the user's primary focus area:
+      At the end of your output, declare the primary focus area on a single line:
 
       > Focused: <exact section name>
 
-      Rules for determining the focused section:
-      - If the page has a dialog, modal, drawer, or overlay — that section is focused
-      - If no overlay exists, pick the section where the user performs the main business action of this page (e.g., a list section for a catalog page, a detail section for an item page, a content section for an article page)
-      - Navigation is NEVER focused — it exists on every page
-      - Menu/toolbar is NEVER focused — it contains actions, not the main content
-      - The focused section is the one the user came to this page to interact with
+      - If a dialog/modal/drawer/overlay exists, it is focused.
+      - Otherwise pick the section where the main business action happens (list for catalog, detail for item page, content for article).
+      - Navigation and menu/toolbar are never focused.
       </focused_section>
-
-      <css_selector_rules>
-      CSS selectors MUST point to the actual interactive element (input, button, a, select), NOT to container divs.
-      - If a submit button is inside a wrapper div, target the input/button directly
-      - Bad: '#submit-wrapper' (div container)
-      - Good: '#submit-wrapper input[type="submit"]' or 'input[type="submit"][value="Submit"]'
-      - For buttons with similar text, include distinguishing attributes like type, value, or form context
-
-      </css_selector_rules>
     `;
     }
     async buildResearchPrompt() {
@@ -475,17 +421,6 @@ export class Researcher extends ResearcherBase {
         return dedent `
       Analyze this web page and provide a comprehensive research report in markdown format.
 
-      <error_detection>
-      IMPORTANT: First check if this looks like an error page (404, 500, access denied,
-      not found, server error, forbidden, or similar). If so, respond ONLY with:
-
-      ## Error Page Detected
-      Type: [error type]
-      Reason: [what indicates this is an error page]
-
-      Then stop - do not provide normal research output for error pages.
-      </error_detection>
-
       ${this.researchRules()}
 
       URL: ${this.actionResult.url || 'Unknown'}
@@ -534,14 +469,6 @@ export class Researcher extends ResearcherBase {
       </output_rules>
 
 
-    `;
-    }
-    buildFocusedRetryPrompt() {
-        return dedent `
-      Your previous response was truncated and could not be parsed.
-
-      Please retry with a shorter output. Focus ONLY on the main interactive section of the page.
-      Skip navigation, sidebar, and footer sections. Output ONE section only with max 15 elements.
     `;
     }
     async textContent(state) {

package/dist/src/ai/task-agent.js

@@ -1,4 +1,5 @@
 import dedent from 'dedent';
+import { renderExperienceToc } from '../experience-tracker.js';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 const debugLog = createDebug('explorbot:task-agent');
 export function isInteractive() {
@@ -34,34 +35,13 @@ export class TaskAgent {
     }
     getExperience(actionResult) {
         const tracker = this.getExperienceTracker();
-        const relevantExperience = tracker.getRelevantExperience(actionResult);
-        if (relevantExperience.length === 0)
+        const toc = tracker.getExperienceTableOfContents(actionResult);
+        if (toc.length === 0)
             return '';
-        const allContent = relevantExperience
-            .map((e) => e.content)
-            .filter((e) => !!e)
-            .join('\n\n---\n\n');
-        const totalChars = allContent.length;
-        let experienceContent;
-        if (totalChars <= 10_000) {
-            debugLog(`injecting all experience (${Math.round(totalChars / 1000)}k chars)`);
-            experienceContent = allContent;
-        }
-        else {
-            experienceContent = tracker.getSuccessfulExperience(actionResult).join('\n\n---\n\n');
-            debugLog(`injecting success-only experience (${Math.round(experienceContent.length / 1000)}k chars, filtered from ${Math.round(totalChars / 1000)}k)`);
-        }
-        if (!experienceContent)
-            return '';
-        tag('substep').log(`Found ${relevantExperience.length} experience ${pluralize(relevantExperience.length, 'file')}`);
-        return dedent `
-      <experience>
-      Here is past experience of interacting with this page.
-      Use successful solutions first. Avoid repeating failed actions.
-
-      ${experienceContent}
-      </experience>
-    `;
+        const totalSections = toc.reduce((sum, entry) => sum + entry.sections.length, 0);
+        debugLog(`injecting experience TOC (${toc.length} files, ${totalSections} sections)`);
+        tag('substep').log(`Found ${toc.length} experience ${pluralize(toc.length, 'file')} (${totalSections} sections)`);
+        return renderExperienceToc(toc);
     }
     setHistorian(historian) {
         this._historian = historian;

package/dist/src/ai/tester.js

@@ -8,7 +8,7 @@ import { setActivity } from "../activity.js";
 import { ConfigParser } from "../config.js";
 import { Stats } from "../stats.js";
 import { TestResult } from "../test-plan.js";
-import { extractFocusedElement } from "../utils/aria.js";
+import { detectFocusArea, extractFocusedElement } from "../utils/aria.js";
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
@@ -44,6 +44,8 @@ export class Tester extends TaskAgent {
     executionLogFile = null;
     previousUrl = null;
     previousStateHash = null;
+    pageStateHash = null;
+    pageActionResult = null;
     hooksRunner;
     constructor(explorer, provider, researcher, navigator, agentTools) {
         super();
@@ -90,6 +92,8 @@ export class Tester extends TaskAgent {
         setActivity(`🧪 Testing: ${task.scenario}`, 'action');
         this.previousUrl = null;
         this.previousStateHash = null;
+        this.pageStateHash = null;
+        this.pageActionResult = null;
         this.explorer.getStateManager().clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
@@ -369,7 +373,8 @@ export class Tester extends TaskAgent {
         }
         if (isNewUrl) {
             const research = await this.researcher.research(currentState);
-            const experience = this.getExperience(currentState);
+            this.pageStateHash = currentStateHash;
+            this.pageActionResult = currentState;
             let uiMapSection = '';
             if (research) {
                 uiMapSection = dedent `
@@ -394,8 +399,6 @@ export class Tester extends TaskAgent {
         </page_aria>
         ${uiMapSection}
 
-        ${experience}
-
         Use <page_ui_map> to understand the page structure and its main elements.
         However, <page_ui_map> is not always up to date, use <page_aria> and <page_html> to understand the ACTUAL state of the page
         Do not interact with elements that are not listed in <page_aria> and <page_html>
@@ -403,6 +406,18 @@ export class Tester extends TaskAgent {
       `;
             return context;
         }
+        const focusArea = detectFocusArea(currentState.ariaSnapshot);
+        if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
+            const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash);
+            if (overlaySection) {
+                context += dedent `
+
+          <page_ui_map_overlay>
+          ${overlaySection}
+          </page_ui_map_overlay>
+        `;
+            }
+        }
         // if (isStateChanged) {
         //   const combinedHtml = await currentState.combinedHtml();
         //   context += dedent`

package/dist/src/ai/tools.js

@@ -389,9 +389,9 @@ export function createSpecialContextTools(explorer, context) {
         }),
     };
 }
-export function createAgentTools({ explorer, researcher, navigator, }) {
+export function createAgentTools({ explorer, researcher, navigator, experienceTracker, getState, }) {
     let visionDisabled = false;
-    return {
+    const tools = {
         see: tool({
             description: dedent `
         Check the page contents based on current page state and screenshot.
@@ -830,6 +830,31 @@ export function createAgentTools({ explorer, researcher, navigator, }) {
             },
         }),
     };
+    if (experienceTracker && getState) {
+        tools.learn_experience = tool({
+            description: dedent `
+        Read the full body of a specific experience section listed in <experience>.
+        The TOC shows entries like "A.1 ## Successful Flow: ...". Pass the fileTag and sectionIndex.
+        Only call when a TOC entry looks directly relevant to the current step.
+      `,
+            inputSchema: z.object({
+                fileTag: z.string().describe('File tag from the TOC, e.g. "A", "B", "AA"'),
+                sectionIndex: z.number().int().positive().describe('1-based section index within that file'),
+            }),
+            execute: async ({ fileTag, sectionIndex }) => {
+                const state = getState();
+                if (!state) {
+                    return { error: 'No current page state available.' };
+                }
+                const section = experienceTracker.getExperienceSection(fileTag, sectionIndex, state);
+                if (!section) {
+                    return { error: 'Section not found. Experience may have been updated; re-read the latest TOC.' };
+                }
+                return section;
+            },
+        });
+    }
+    return tools;
 }
 const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';
 function transformContainsCommand(command) {

package/dist/src/commands/explore-command.js

@@ -1,8 +1,6 @@
-import { existsSync, readdirSync } from 'node:fs';
 import figureSet from 'figures';
 import path from 'node:path';
 import { getStyles } from '../ai/planner/styles.js';
-import { ConfigParser } from "../config.js";
 import { getCliName } from "../utils/cli-name.js";
 import { jsonToTable } from '../utils/markdown-parser.js';
 import { tag } from '../utils/logger.js';
@@ -110,14 +108,11 @@ export class ExploreCommand extends BaseCommand {
         }
     }
     printRerunSuggestions() {
-        const testsDir = ConfigParser.getInstance().getTestsDir();
-        if (!existsSync(testsDir))
+        const savedFiles = this.explorBot.agentHistorian().getSavedFiles();
+        if (savedFiles.length === 0)
             return;
-        const testFiles = readdirSync(testsDir).filter((f) => f.endsWith('.js'));
-        if (testFiles.length === 0)
-            return;
-        for (const file of testFiles) {
-            tag('info').log(`Generated: ${file}`);
+        for (const filePath of savedFiles) {
+            tag('info').log(`Generated: ${path.basename(filePath)}`);
         }
         tag('info').log(`List tests: ${getCliName()} runs`);
         tag('info').log(`Re-run with healing: ${getCliName()} rerun <filename> [index]`);

package/dist/src/experience-tracker.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import matter from 'gray-matter';
+import { marked } from 'marked';
 import { ConfigParser } from './config.js';
 import { KnowledgeTracker } from './knowledge-tracker.js';
 import { createDebug, tag } from './utils/logger.js';
@@ -290,4 +291,128 @@ ${filteredCode}
         }
         return results;
     }
+    getExperienceTableOfContents(state, options) {
+        const records = this.getRelevantExperience(state, options);
+        if (records.length === 0)
+            return [];
+        const sorted = [...records].sort((a, b) => {
+            const aHash = basename(a.filePath, '.md');
+            const bHash = basename(b.filePath, '.md');
+            return aHash.localeCompare(bHash);
+        });
+        const toc = [];
+        for (let i = 0; i < sorted.length; i++) {
+            const record = sorted[i];
+            const fileHash = basename(record.filePath, '.md');
+            const url = record.data?.url || '';
+            const sections = listTocHeadings(record.content);
+            if (sections.length === 0)
+                continue;
+            toc.push({
+                fileTag: indexToLetters(i),
+                fileHash,
+                url,
+                sections,
+            });
+        }
+        return toc;
+    }
+    getExperienceSection(fileTag, sectionIndex, state, options) {
+        const toc = this.getExperienceTableOfContents(state, options);
+        const entry = toc.find((e) => e.fileTag === fileTag);
+        if (!entry)
+            return null;
+        const filePath = this.findExperienceFileByHash(entry.fileHash);
+        if (!filePath)
+            return null;
+        const { content } = this.readExperienceFile(entry.fileHash);
+        const extracted = extractHeadingSection(content, sectionIndex);
+        if (!extracted)
+            return null;
+        return { title: extracted.title, url: entry.url, content: extracted.body };
+    }
+    findExperienceFileByHash(fileHash) {
+        for (const dir of this.getExperienceDirectories()) {
+            const candidate = join(dir, `${fileHash}.md`);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        return null;
+    }
+}
+function listTocHeadings(content) {
+    const tokens = marked.lexer(content);
+    const result = [];
+    let index = 0;
+    for (const token of tokens) {
+        if (token.type !== 'heading')
+            continue;
+        const heading = token;
+        if (heading.depth !== 2 && heading.depth !== 3)
+            continue;
+        index++;
+        result.push({ index, level: heading.depth, title: heading.text });
+    }
+    return result;
+}
+function extractHeadingSection(content, sectionIndex) {
+    const tokens = marked.lexer(content);
+    const matching = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type !== 'heading')
+            continue;
+        const heading = token;
+        if (heading.depth !== 2 && heading.depth !== 3)
+            continue;
+        matching.push({ tokenIdx: i, depth: heading.depth, text: heading.text });
+    }
+    if (sectionIndex < 1 || sectionIndex > matching.length)
+        return null;
+    const target = matching[sectionIndex - 1];
+    let endTokenIdx = tokens.length;
+    for (let j = target.tokenIdx + 1; j < tokens.length; j++) {
+        const token = tokens[j];
+        if (token.type !== 'heading')
+            continue;
+        if (token.depth <= target.depth) {
+            endTokenIdx = j;
+            break;
+        }
+    }
+    const body = tokens
+        .slice(target.tokenIdx, endTokenIdx)
+        .map((t) => t.raw || '')
+        .join('');
+    return { title: target.text, body };
+}
+function indexToLetters(index) {
+    let n = index;
+    let result = '';
+    while (true) {
+        result = String.fromCharCode(65 + (n % 26)) + result;
+        n = Math.floor(n / 26);
+        if (n === 0)
+            break;
+        n -= 1;
+    }
+    return result;
+}
+export function renderExperienceToc(toc) {
+    if (toc.length === 0)
+        return '';
+    const lines = [];
+    lines.push('<experience>');
+    lines.push('Past experience for this page. Call learn_experience({ fileTag, sectionIndex }) to read a section.');
+    lines.push('');
+    for (const entry of toc) {
+        lines.push(`File ${entry.fileTag} ${entry.url}:`);
+        for (const section of entry.sections) {
+            const prefix = '#'.repeat(section.level);
+            lines.push(`  ${entry.fileTag}.${section.index} ${prefix} ${section.title}`);
+        }
+        lines.push('');
+    }
+    lines.push('</experience>');
+    return lines.join('\n');
 }

package/dist/src/explorbot.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { ActionResult } from "./action-result.js";
 import { ApiClient } from "./api/api-client.js";
 import { RequestStore } from "./api/request-store.js";
 import { loadSpec } from "./api/spec-reader.js";
@@ -144,8 +145,14 @@ export class ExplorBot {
         return (this.agents.pilot ||= this.createAgent(({ ai, explorer }) => {
             const researcher = this.agentResearcher();
             const navigator = this.agentNavigator();
-            const tools = createAgentTools({ explorer, researcher, navigator });
-            return new Pilot(ai, tools, researcher, explorer);
+            const stateManager = explorer.getStateManager();
+            const experienceTracker = stateManager.getExperienceTracker();
+            const getState = () => {
+                const state = stateManager.getCurrentState();
+                return state ? ActionResult.fromState(state) : null;
+            };
+            const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState });
+            return new Pilot(ai, tools, researcher, explorer, experienceTracker);
         }));
     }
     agentTester() {

package/dist/src/explorer.js

@@ -18,6 +18,7 @@ import { createDebug, log, tag } from './utils/logger.js';
 import { WebElement, extractElementData } from "./utils/web-element.js";
 const debugLog = createDebug('explorbot:explorer');
 const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
+const RECOVERABLE_NAVIGATION_ERRORS = /net::ERR_ABORTED|page\.screenshot.*Timeout|waiting for fonts to load/i;
 class Explorer {
     aiProvider;
     playwrightHelper;
@@ -228,7 +229,17 @@ class Explorer {
             await action.execute(`I.executeScript(() => { window.history.pushState({}, '', ${serializedUrl}); window.dispatchEvent(new PopStateEvent('popstate')); })`);
         }
         else {
-            await action.execute(`I.amOnPage(${serializedUrl})`);
+            try {
+                await action.execute(`I.amOnPage(${serializedUrl})`);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (!RECOVERABLE_NAVIGATION_ERRORS.test(msg))
+                    throw err;
+                tag('warning').log(`Navigation warning (continuing after load): ${msg.split('\n')[0]}`);
+                await this.playwrightHelper.page.waitForLoadState('domcontentloaded', { timeout: 10000 }).catch(() => { });
+                await action.capturePageState();
+            }
         }
         if (wait !== undefined) {
             debugLog('Waiting for', wait);

package/dist/src/utils/aria.js

@@ -333,8 +333,40 @@ const parseAriaSnapshot = (snapshot, keepNamed = false) => {
     }
     return pruneNodes(roots, keepNamed);
 };
+const CLOSE_OVERLAY_BUTTON_RE = /^close\s+(modal|dialog|popup|drawer|panel|sheet)\b/i;
+const findOverlayByCloseButton = (nodeList) => {
+    const closeIdx = nodeList.findIndex((n) => n.role === 'button' && CLOSE_OVERLAY_BUTTON_RE.test(n.name || ''));
+    if (closeIdx !== -1) {
+        let heading;
+        for (let i = closeIdx - 1; i >= 0; i--) {
+            if (nodeList[i].role === 'heading' && nodeList[i].name) {
+                heading = nodeList[i];
+                break;
+            }
+        }
+        if (!heading) {
+            for (let i = closeIdx + 1; i < nodeList.length; i++) {
+                if (nodeList[i].role === 'heading' && nodeList[i].name) {
+                    heading = nodeList[i];
+                    break;
+                }
+            }
+        }
+        return {
+            detected: true,
+            type: 'dialog',
+            name: heading?.name || null,
+        };
+    }
+    for (const node of nodeList) {
+        const inner = findOverlayByCloseButton(node.children);
+        if (inner)
+            return inner;
+    }
+    return null;
+};
 export const detectFocusArea = (snapshot) => {
-    const nodes = parseAriaSnapshot(snapshot);
+    const nodes = parseAriaSnapshot(snapshot, true);
     const findFocusArea = (nodeList) => {
         for (const node of nodeList) {
             if (node.role === 'dialog' || node.role === 'alertdialog') {
@@ -359,7 +391,12 @@ export const detectFocusArea = (snapshot) => {
         return null;
     };
     const result = findFocusArea(nodes);
-    return result || { detected: false, type: null, name: null };
+    if (result)
+        return result;
+    const fallback = findOverlayByCloseButton(nodes);
+    if (fallback && fallback.name)
+        return fallback;
+    return { detected: false, type: null, name: null };
 };
 export const collectInteractiveNodes = (snapshot) => {
     const nodes = parseAriaSnapshot(snapshot);