explorbot 0.1.4 → 0.1.6

package/src/ai/researcher.ts

@@ -28,6 +28,7 @@ import { detectFocusFromAria, hasFocusedSection, markSectionAsFocused, pickDefau
 import { type LocatorMethods, WithLocators } from './researcher/locators.ts';
 import { extractValidContainers, formatResearchSummary, parseResearchSections } from './researcher/parser.ts';
 import { ResearchResult } from './researcher/research-result.ts';
+import { type SectionMethods, WithSections } from './researcher/sections.ts';
 import { locatorRule as generalLocatorRuleText } from './rules.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { TaskAgent } from './task-agent.ts';
@@ -46,9 +47,9 @@ export const POSSIBLE_SECTIONS = {
   navigation: 'main navigation (top bar, sidebar, breadcrumbs)',
 };
 
-const ResearcherBase = WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent as unknown as new (...args: any[]) => TaskAgent)));
+const ResearcherBase = WithSections(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent as unknown as new (...args: any[]) => TaskAgent))));
 
-export interface Researcher extends LocatorMethods, CoordinateMethods, DeepAnalysisMethods {}
+export interface Researcher extends LocatorMethods, CoordinateMethods, DeepAnalysisMethods, SectionMethods {}
 
 export class Researcher extends ResearcherBase implements Agent {
   protected readonly ACTION_TOOLS = ['click'];
@@ -98,15 +99,11 @@ export class Researcher extends ResearcherBase implements Agent {
     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 || ''}
     `;
   }
 
-  async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; _retriesLeft?: number; _skipErrorPageRetry?: boolean } = {}): Promise<string> {
+  async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; _retriesLeft?: number } = {}): Promise<string> {
     const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
     const maxRetries = (this.explorer.getConfig().ai?.agents?.researcher as any)?.retries ?? 2;
     let retriesLeft = opts._retriesLeft ?? maxRetries;
@@ -174,9 +171,12 @@ export class Researcher extends ResearcherBase implements Agent {
       const prompt = await this.buildResearchPrompt();
       conversation.addUserText(prompt);
 
-      let invocationResult: Awaited<ReturnType<typeof this.provider.invokeConversation>>;
+      let researchText: string;
+      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) {
           if (error instanceof ContextLengthError) {
@@ -184,30 +184,14 @@ export class Researcher extends ResearcherBase implements Agent {
           }
           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
@@ -251,7 +235,7 @@ export class Researcher extends ResearcherBase implements Agent {
 
       // 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
@@ -417,32 +401,29 @@ export class Researcher extends ResearcherBase implements Agent {
 
   private researchRules(): string {
     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:
@@ -450,23 +431,12 @@ export class Researcher extends ResearcherBase implements Agent {
         .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
 
@@ -476,40 +446,16 @@ export class Researcher extends ResearcherBase implements Agent {
 
       | 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>
     `;
   }
 
@@ -540,17 +486,6 @@ export class Researcher extends ResearcherBase implements Agent {
     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'}
@@ -602,15 +537,6 @@ export class Researcher extends ResearcherBase implements Agent {
     `;
   }
 
-  private buildFocusedRetryPrompt(): string {
-    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: WebPageState): Promise<string> {
     const actionResult = ActionResult.fromState(state);
     const html = await actionResult.combinedHtml();

package/src/ai/task-agent.ts

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../action-result.js';
-import type { ExperienceTracker } from '../experience-tracker.js';
+import { renderExperienceToc, type ExperienceTracker } from '../experience-tracker.js';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 
@@ -56,37 +56,13 @@ export abstract class TaskAgent {
 
   protected getExperience(actionResult: ActionResult): string {
     const tracker = this.getExperienceTracker();
-    const relevantExperience = tracker.getRelevantExperience(actionResult);
+    const toc = tracker.getExperienceTableOfContents(actionResult);
+    if (toc.length === 0) return '';
 
-    if (relevantExperience.length === 0) return '';
-
-    const allContent = relevantExperience
-      .map((e) => e.content)
-      .filter((e) => !!e)
-      .join('\n\n---\n\n');
-
-    const totalChars = allContent.length;
-    let experienceContent: string;
-
-    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: Historian): void {

package/src/ai/tester.ts

@@ -11,7 +11,7 @@ import type Explorer from '../explorer.ts';
 import type { StateTransition, WebPageState } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Note, type Test, TestResult, type TestResultType } from '../test-plan.ts';
-import { extractFocusedElement } from '../utils/aria.ts';
+import { detectFocusArea, extractFocusedElement } from '../utils/aria.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { codeToMarkdown } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -59,6 +59,8 @@ export class Tester extends TaskAgent implements Agent {
   executionLogFile: string | null = null;
   private previousUrl: string | null = null;
   private previousStateHash: string | null = null;
+  private pageStateHash: string | null = null;
+  private pageActionResult: ActionResult | null = null;
   private hooksRunner: HooksRunner;
 
   constructor(explorer: Explorer, provider: Provider, researcher: Researcher, navigator: Navigator, agentTools?: any) {
@@ -117,6 +119,8 @@ export class Tester extends TaskAgent implements Agent {
 
     this.previousUrl = null;
     this.previousStateHash = null;
+    this.pageStateHash = null;
+    this.pageActionResult = null;
     this.explorer.getStateManager().clearHistory();
     this.resetFailureCount();
     this.pilot?.reset();
@@ -441,7 +445,8 @@ export class Tester extends TaskAgent implements Agent {
 
     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`
@@ -467,8 +472,6 @@ export class Tester extends TaskAgent implements Agent {
         </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>
@@ -477,6 +480,19 @@ export class Tester extends TaskAgent implements Agent {
       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/src/ai/tools.ts

@@ -2,6 +2,7 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult, type ToolResultMetadata } from '../action-result.ts';
+import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
 import { type Task, TestResult } from '../test-plan.js';
 import { extractFocusedElement } from '../utils/aria.ts';
@@ -449,14 +450,18 @@ export function createAgentTools({
   explorer,
   researcher,
   navigator,
+  experienceTracker,
+  getState,
 }: {
   explorer: Explorer;
   researcher: Researcher;
   navigator: Navigator;
+  experienceTracker?: ExperienceTracker;
+  getState?: () => ActionResult | null;
 }): any {
   let visionDisabled = false;
 
-  return {
+  const tools: Record<string, any> = {
     see: tool({
       description: dedent`
         Check the page contents based on current page state and screenshot.
@@ -947,6 +952,33 @@ export function createAgentTools({
       },
     }),
   };
+
+  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.';

package/src/commands/explore-command.ts

@@ -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.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import type { Plan } from '../test-plan.js';
 import { jsonToTable } from '../utils/markdown-parser.js';
@@ -116,14 +114,11 @@ export class ExploreCommand extends BaseCommand {
   }
 
   private printRerunSuggestions(): void {
-    const testsDir = ConfigParser.getInstance().getTestsDir();
-    if (!existsSync(testsDir)) return;
+    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/src/config.ts

@@ -69,6 +69,7 @@ interface ResearcherAgentConfig extends AgentConfig {
   maxExpandableClicks?: number;
   retries?: number;
   sections?: string[];
+  focusSections?: string[];
   errorPageTimeout?: number;
 }
 

package/src/experience-tracker.ts

@@ -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, type Tokens } from 'marked';
 import type { ActionResult } from './action-result.js';
 import { ConfigParser } from './config.js';
 import { KnowledgeTracker } from './knowledge-tracker.js';
@@ -332,6 +333,133 @@ ${filteredCode}
 
     return results;
   }
+
+  getExperienceTableOfContents(state: ActionResult, options?: { includeDescendantExperience?: boolean }): ExperienceTocEntry[] {
+    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: ExperienceTocEntry[] = [];
+    for (let i = 0; i < sorted.length; i++) {
+      const record = sorted[i];
+      const fileHash = basename(record.filePath, '.md');
+      const url = (record.data as WebPageState)?.url || '';
+      const sections = listTocHeadings(record.content);
+      if (sections.length === 0) continue;
+      toc.push({
+        fileTag: indexToLetters(i),
+        fileHash,
+        url,
+        sections,
+      });
+    }
+    return toc;
+  }
+
+  getExperienceSection(fileTag: string, sectionIndex: number, state: ActionResult, options?: { includeDescendantExperience?: boolean }): { title: string; url: string; content: string } | null {
+    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 };
+  }
+
+  private findExperienceFileByHash(fileHash: string): string | null {
+    for (const dir of this.getExperienceDirectories()) {
+      const candidate = join(dir, `${fileHash}.md`);
+      if (existsSync(candidate)) return candidate;
+    }
+    return null;
+  }
+}
+
+function listTocHeadings(content: string): { index: number; level: 2 | 3; title: string }[] {
+  const tokens = marked.lexer(content);
+  const result: { index: number; level: 2 | 3; title: string }[] = [];
+  let index = 0;
+  for (const token of tokens) {
+    if (token.type !== 'heading') continue;
+    const heading = token as Tokens.Heading;
+    if (heading.depth !== 2 && heading.depth !== 3) continue;
+    index++;
+    result.push({ index, level: heading.depth as 2 | 3, title: heading.text });
+  }
+  return result;
+}
+
+function extractHeadingSection(content: string, sectionIndex: number): { title: string; body: string } | null {
+  const tokens = marked.lexer(content);
+  const matching: { tokenIdx: number; depth: number; text: string }[] = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.type !== 'heading') continue;
+    const heading = token as Tokens.Heading;
+    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 as Tokens.Heading).depth <= target.depth) {
+      endTokenIdx = j;
+      break;
+    }
+  }
+
+  const body = tokens
+    .slice(target.tokenIdx, endTokenIdx)
+    .map((t) => (t as any).raw || '')
+    .join('');
+  return { title: target.text, body };
+}
+
+function indexToLetters(index: number): string {
+  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: ExperienceTocEntry[]): string {
+  if (toc.length === 0) return '';
+
+  const lines: string[] = [];
+  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');
 }
 
 export interface SessionStep {
@@ -348,3 +476,10 @@ export interface SessionExperienceEntry {
   steps: SessionStep[];
   relatedUrls?: string[];
 }
+
+export interface ExperienceTocEntry {
+  fileTag: string;
+  fileHash: string;
+  url: string;
+  sections: { index: number; level: 2 | 3; title: string }[];
+}

package/src/explorbot.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { ActionResult } from './action-result.ts';
 import { ApiClient } from './api/api-client.ts';
 import { RequestStore } from './api/request-store.ts';
 import { loadSpec } from './api/spec-reader.ts';
@@ -182,8 +183,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);
     }));
   }
 

package/src/explorer.ts

@@ -37,6 +37,7 @@ declare namespace CodeceptJS {
 
 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;
 
 interface TabInfo {
   url: string;
@@ -289,7 +290,15 @@ class Explorer {
     if (statePush) {
       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) {