explorbot 0.1.8 → 0.1.10

package/src/ai/navigator.ts

@@ -1,6 +1,7 @@
 import dedent from 'dedent';
 import { ActionResult } from '../action-result.js';
-import { ExperienceTracker } from '../experience-tracker.js';
+import type Action from '../action.ts';
+import { ExperienceTracker, renderExperienceToc } from '../experience-tracker.js';
 import Explorer from '../explorer.ts';
 import { KnowledgeTracker } from '../knowledge-tracker.js';
 import { type WebPageState, normalizeUrl } from '../state-manager.js';
@@ -8,14 +9,15 @@ import { extractCodeBlocks } from '../utils/code-extractor.js';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
+import { RulesLoader } from '../utils/rules-loader.ts';
 import type { Agent } from './agent.js';
 import type { Conversation } from './conversation.js';
 import { ExperienceCompactor } from './experience-compactor.js';
 import type { Provider } from './provider.js';
 import { Researcher } from './researcher.ts';
 import { actionRule, locatorRule } from './rules.js';
-import { RulesLoader } from '../utils/rules-loader.ts';
 import { isInteractive } from './task-agent.js';
+import { createAgentTools } from './tools.ts';
 
 const debugLog = createDebug('explorbot:navigator');
 
@@ -25,8 +27,6 @@ class Navigator implements Agent {
   private experienceCompactor: ExperienceCompactor;
   private knowledgeTracker: KnowledgeTracker;
   private experienceTracker: ExperienceTracker;
-  private currentAction: any = null;
-  private currentUrl: string | null = null;
   private hooksRunner: HooksRunner;
 
   private MAX_ATTEMPTS = Number.parseInt(process.env.MAX_ATTEMPTS || '5');
@@ -102,9 +102,7 @@ class Navigator implements Agent {
         const actionResult = action.actionResult || ActionResult.fromState(action.stateManager.getCurrentState()!);
         const originalMessage = `Navigate to: ${url}. Current page: ${actualPath}`;
 
-        this.currentAction = action;
-        this.currentUrl = url;
-        const resolved = await this.resolveState(originalMessage, actionResult);
+        const resolved = await this.resolveState(originalMessage, actionResult, { action, expectedUrl: url });
         if (!resolved) {
           throw new Error(`Navigation to ${url} failed: redirected to ${actualPath} and could not resolve`);
         }
@@ -116,9 +114,7 @@ class Navigator implements Agent {
           But I got error: ${action.lastError?.message || 'Navigation failed'}.
         `.trim();
 
-        this.currentAction = action;
-        this.currentUrl = url;
-        const resolved = await this.resolveState(originalMessage, actionResult);
+        const resolved = await this.resolveState(originalMessage, actionResult, { action, expectedUrl: url });
         if (!resolved) {
           throw new Error(`Navigation to ${url} failed: ${action.lastError?.message}`);
         }
@@ -136,10 +132,13 @@ class Navigator implements Agent {
     }
   }
 
-  async resolveState(message: string, actionResult: ActionResult): Promise<boolean> {
+  async resolveState(message: string, actionResult: ActionResult, opts?: { action?: Action; expectedUrl?: string }): Promise<boolean> {
     tag('info').log('AI Navigator resolving state at', actionResult.url);
     debugLog('Resolution message:', message);
 
+    const action = opts?.action ?? this.explorer.createAction();
+    const expectedUrl = opts?.expectedUrl;
+
     let knowledge = '';
     let experience = '';
 
@@ -153,26 +152,13 @@ class Navigator implements Agent {
       </hint>`;
     }
 
-    const relevantExperience = this.experienceTracker.getRelevantExperience(actionResult).map((experience) => experience.content);
-
-    if (relevantExperience.length > 0) {
-      const experienceContent = relevantExperience.join('\n\n---\n\n');
-      experience = await this.experienceCompactor.compactExperience(experienceContent);
-      tag('substep').log(`Found ${relevantExperience.length} experience ${pluralize(relevantExperience.length, 'file')} for: ${actionResult.url}`);
-
-      experience = dedent`
-      <experience>
-      Here is the experience of interacting with the page.
-      Learn from it AND DO NOT REPEAT THE SAME MISTAKES.
-      If there was found successful solution to an issue, propose it as a first solution.
-      If there are no successful solutions, analyze failed intentions and actions to avoid them.
-      Do not try again same failed solutions
-
-      Focus on successful solutions and avoid actions and locators that caused errors in past.
-
-      ${experienceContent}
-
-      </experience>`;
+    if (!actionResult.isInsideIframe) {
+      const toc = this.experienceTracker.getExperienceTableOfContents(actionResult);
+      if (toc.length > 0) {
+        const totalSections = toc.reduce((sum, entry) => sum + entry.sections.length, 0);
+        tag('substep').log(`Found ${toc.length} experience ${pluralize(toc.length, 'file')} (${totalSections} sections) for: ${actionResult.url}`);
+        experience = renderExperienceToc(toc);
+      }
     }
 
     const prompt = dedent`
@@ -210,6 +196,8 @@ class Navigator implements Agent {
     const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
     conversation.addUserText(prompt);
 
+    const tools = this.buildExperienceTools();
+
     let codeBlocks: string[] = [];
     let htmlContextAdded = false;
     let codeBlockIndex = 0;
@@ -219,11 +207,11 @@ class Navigator implements Agent {
     await loop(
       async ({ stop }) => {
         if (codeBlocks.length === 0) {
-          const result = await this.provider.invokeConversation(conversation);
+          const result = await this.provider.invokeConversation(conversation, tools);
           if (!result) return;
           const aiResponse = result?.response?.text;
           debugLog('AI:', aiResponse?.split('\n')[0]);
-          debugLog('Received AI response:', aiResponse.length, 'characters');
+          debugLog('Received AI response:', aiResponse?.length ?? 0, 'characters');
           codeBlocks = extractCodeBlocks(aiResponse ?? '');
           codeBlockIndex = 0;
         }
@@ -256,24 +244,26 @@ class Navigator implements Agent {
         codeBlockIndex++;
         totalAttempts++;
 
+        await this.explorer.switchToMainFrame();
+
         debugLog(`Attempting resolution: ${codeBlock}`);
-        resolved = await this.currentAction.attempt(codeBlock, message);
+        resolved = await action.attempt(codeBlock, message);
 
-        if (this.currentUrl) {
-          await this.currentAction.getActor().wait(2);
-          const freshState = await this.currentAction.capturePageState();
+        if (expectedUrl) {
+          await (action.getActor() as any).wait(2);
+          const freshState = await action.capturePageState();
 
-          if (normalizeUrl(freshState.url || '') === normalizeUrl(this.currentUrl)) {
+          if (normalizeUrl(freshState.url || '') === normalizeUrl(expectedUrl)) {
             resolved = true;
           } else if (resolved) {
-            tag('warning').log(`URL verification failed: expected ${this.currentUrl}, got ${freshState.url}`);
+            tag('warning').log(`URL verification failed: expected ${expectedUrl}, got ${freshState.url}`);
             resolved = false;
           }
         }
 
         if (resolved) {
           tag('success').log('Navigation resolved successfully');
-          await this.experienceTracker.saveSuccessfulResolution(actionResult, message, codeBlock);
+          this.experienceTracker.writeAction(actionResult, { title: message, code: codeBlock });
           stop();
           return;
         }
@@ -290,9 +280,9 @@ class Navigator implements Agent {
       }
     );
 
-    if (!resolved && this.currentUrl) {
-      await this.currentAction.getActor().wait(1);
-      if (this.isOnExpectedPage(this.currentUrl, this.currentAction.stateManager)) {
+    if (!resolved && expectedUrl) {
+      await (action.getActor() as any).wait(1);
+      if (this.isOnExpectedPage(expectedUrl, action.stateManager)) {
         resolved = true;
         tag('success').log('Navigation resolved after delayed redirect');
       }
@@ -303,13 +293,13 @@ class Navigator implements Agent {
     }
 
     if (!resolved && isInteractive()) {
-      const userInput = await pause(`Navigator failed to resolve. Current: ${this.currentAction.stateManager.getCurrentState()?.url}\n` + `Target: ${this.currentUrl}\nEnter CodeceptJS commands (or press Enter to skip):`);
+      const userInput = await pause(`Navigator failed to resolve. Current: ${action.stateManager.getCurrentState()?.url}\n` + `Target: ${expectedUrl ?? '(none)'}\nEnter CodeceptJS commands (or press Enter to skip):`);
 
       if (userInput?.trim()) {
-        resolved = await this.currentAction.attempt(userInput, message);
-        if (resolved && this.currentUrl) {
-          await this.currentAction.getActor().wait(1);
-          if (!this.isOnExpectedPage(this.currentUrl, this.currentAction.stateManager)) {
+        resolved = await action.attempt(userInput, message);
+        if (resolved && expectedUrl) {
+          await (action.getActor() as any).wait(1);
+          if (!this.isOnExpectedPage(expectedUrl, action.stateManager)) {
             resolved = false;
           }
         }
@@ -319,6 +309,23 @@ class Navigator implements Agent {
     return resolved;
   }
 
+  private buildExperienceTools(): { learn_experience: unknown } | undefined {
+    const stateManager = this.explorer.getStateManager();
+    const getState = () => {
+      const s = stateManager.getCurrentState();
+      return s ? ActionResult.fromState(s) : null;
+    };
+    const { learn_experience } = createAgentTools({
+      explorer: this.explorer,
+      researcher: null as unknown as Researcher,
+      navigator: this,
+      experienceTracker: this.experienceTracker,
+      getState,
+    });
+    if (!learn_experience) return undefined;
+    return { learn_experience };
+  }
+
   async freeSail(opts?: { strategy?: 'deep' | 'shallow'; scope?: string; visitedUrls?: Set<string> }, actionResult?: ActionResult): Promise<{ target: string; reason: string } | null> {
     const stateManager = this.explorer.getStateManager();
     const state = stateManager.getCurrentState();
@@ -465,22 +472,13 @@ class Navigator implements Agent {
       </hint>`;
     }
 
-    const relevantExperience = this.experienceTracker.getRelevantExperience(actionResult).map((exp) => exp.content);
-
-    if (relevantExperience.length > 0) {
-      const experienceContent = relevantExperience.join('\n\n---\n\n');
-      experience = await this.experienceCompactor.compactExperience(experienceContent);
-      tag('substep').log(`Found ${relevantExperience.length} experience ${pluralize(relevantExperience.length, 'file')} for: ${actionResult.url}`);
-
-      experience = dedent`
-      <experience>
-      Here is the experience of interacting with the page.
-      Learn from it AND DO NOT REPEAT THE SAME MISTAKES.
-      If there was found successful solution to an issue, propose it as a first solution.
-
-      ${experienceContent}
-
-      </experience>`;
+    if (!actionResult.isInsideIframe) {
+      const toc = this.experienceTracker.getExperienceTableOfContents(actionResult);
+      if (toc.length > 0) {
+        const totalSections = toc.reduce((sum, entry) => sum + entry.sections.length, 0);
+        tag('substep').log(`Found ${toc.length} experience ${pluralize(toc.length, 'file')} (${totalSections} sections) for: ${actionResult.url}`);
+        experience = renderExperienceToc(toc);
+      }
     }
 
     const prompt = dedent`
@@ -522,6 +520,8 @@ class Navigator implements Agent {
     const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
     conversation.addUserText(prompt);
 
+    const tools = this.buildExperienceTools();
+
     let codeBlocks: string[] = [];
     const successfulCodes: string[] = [];
 
@@ -530,10 +530,10 @@ class Navigator implements Agent {
     await loop(
       async ({ stop, iteration }) => {
         if (codeBlocks.length === 0) {
-          const result = await this.provider.invokeConversation(conversation);
+          const result = await this.provider.invokeConversation(conversation, tools);
           if (!result) return;
           const aiResponse = result?.response?.text;
-          debugLog('Received AI response:', aiResponse.length, 'characters');
+          debugLog('Received AI response:', aiResponse?.length ?? 0, 'characters');
           tag('step').log('Verifying assertion...');
           codeBlocks = extractCodeBlocks(aiResponse ?? '');
         }
@@ -548,6 +548,8 @@ class Navigator implements Agent {
           return;
         }
 
+        await this.explorer.switchToMainFrame();
+
         const verified = await action.attempt(codeBlock, message, false);
 
         if (verified) {

package/src/ai/pilot.ts

@@ -487,6 +487,28 @@ export class Pilot implements Agent {
       lines.push(`verifications: ${verifyLines.join(', ')}`);
     }
 
+    const consoleErrors = (state.browserLogs ?? []).filter((l: any) => (l.type || l.level) === 'error');
+    if (consoleErrors.length > 0) {
+      const sample = consoleErrors
+        .slice(0, 3)
+        .map((e: any) => e.text || e.message || String(e))
+        .join(' | ');
+      lines.push(`console errors: ${consoleErrors.length} (${sample})`);
+    } else {
+      lines.push('console errors: none');
+    }
+
+    const failedRequests = this.explorer.getRequestStore()?.getFailedRequests() ?? [];
+    if (failedRequests.length > 0) {
+      const sample = failedRequests
+        .slice(-5)
+        .map((r) => `${r.method} ${r.path} → ${r.status}`)
+        .join(', ');
+      lines.push(`network errors: ${sample}`);
+    } else {
+      lines.push('network errors: none');
+    }
+
     const interactiveNodes = collectInteractiveNodes(state.ariaSnapshot);
     const disabledButtons = interactiveNodes.filter((n) => n.role === 'button' && n.disabled === true && n.name).map((n) => n.name);
     lines.push(`disabled buttons: ${disabledButtons.length > 0 ? disabledButtons.join(', ') : 'none'}`);

package/src/ai/planner/subpages.ts

@@ -1,10 +1,10 @@
 import dedent from 'dedent';
 import { z } from 'zod';
-import { ConfigParser } from '../../config.ts';
 import { normalizeUrl } from '../../state-manager.ts';
 import type { StateManager } from '../../state-manager.ts';
 import type { Plan } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
+import { isDynamicSegment } from '../../utils/url-matcher.ts';
 import type { Provider } from '../provider.ts';
 import type { Constructor } from '../researcher/mixin.ts';
 
@@ -38,29 +38,6 @@ function buildKey(url: string, feature?: string): string {
   return normalized;
 }
 
-export function isDynamicSegment(segment: string): boolean {
-  try {
-    const configRegex = ConfigParser.getInstance().getConfig().dynamicPageRegex;
-    if (configRegex) return new RegExp(configRegex, 'i').test(segment);
-  } catch {
-    /* config not loaded yet */
-  }
-
-  // numeric: /users/123
-  if (/^\d+$/.test(segment)) return true;
-  // UUID: /items/550e8400-e29b-41d4-a716-446655440000
-  if (/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(segment)) return true;
-  // ULID: /items/01ARZ3NDEKTSV4RRFFQ69G5FAV
-  if (/^[0-9A-HJKMNP-TV-Z]{26}$/.test(segment)) return true;
-  // hex ID (4+ chars): /suite/70dae98a
-  if (/^[a-f0-9]{4,}$/i.test(segment)) return true;
-  // hex-prefixed slug (8+ hex before dash): /suite/95ef0c94-mobile
-  if (/^[a-f0-9]{8,}-/i.test(segment)) return true;
-  // short mixed alphanumeric (digits + letters, ≤8 chars, no dash): /item/x7f2
-  if (segment.length <= 8 && !segment.includes('-') && /\d/.test(segment) && /[a-z]/i.test(segment)) return true;
-  return false;
-}
-
 export function isTemplateMatch(urlA: string, urlB: string): boolean {
   const partsA = normalizeUrl(urlA).split('/');
   const partsB = normalizeUrl(urlB).split('/');

package/src/ai/planner.ts

@@ -8,22 +8,22 @@ import type Explorer from '../explorer.ts';
 import { Observability } from '../observability.ts';
 import type { StateManager } from '../state-manager.js';
 import { Stats } from '../stats.ts';
+import { Suite } from '../suite.ts';
 import { Plan, Test } from '../test-plan.ts';
-import { planToCompactAiContext } from '../utils/test-plan-markdown.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { jsonToTable } from '../utils/markdown-parser.ts';
 import { mdq } from '../utils/markdown-query.js';
+import { planToCompactAiContext } from '../utils/test-plan-markdown.ts';
 import type { Agent } from './agent.js';
 import { Conversation } from './conversation.ts';
 import type { Fisherman } from './fisherman.ts';
-import { getActiveStyle, getStyles } from './planner/styles.ts';
 import { WithSessionDedup } from './planner/session-dedup.ts';
+import { getActiveStyle, getStyles } from './planner/styles.ts';
 import { WithSubPages, getPlannedByStateHash, getRegisteredPlan, registerPlan } from './planner/subpages.ts';
-import { findSimilarStateHash } from './researcher/cache.ts';
 import type { Provider } from './provider.js';
-import { hasFocusedSection } from './researcher/focus.ts';
 import { POSSIBLE_SECTIONS, Researcher } from './researcher.ts';
-import { Suite } from '../suite.ts';
+import { findSimilarStateHash } from './researcher/cache.ts';
+import { hasFocusedSection } from './researcher/focus.ts';
 import { fileUploadRule, protectionRule } from './rules.ts';
 
 const debugLog = createDebug('explorbot:planner');

package/src/ai/provider.ts

@@ -4,12 +4,12 @@ import { generateObject, generateText } from 'ai';
 import type { ModelMessage } from 'ai';
 import { clearActivity, setActivity } from '../activity.ts';
 import type { AIConfig } from '../config.js';
-import { RulesLoader } from '../utils/rules-loader.ts';
 import { executionController } from '../execution-controller.ts';
 import { Observability } from '../observability.ts';
 import { Stats } from '../stats.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { type RetryOptions, withRetry } from '../utils/retry.js';
+import { RulesLoader } from '../utils/rules-loader.ts';
 import { Conversation } from './conversation.js';
 
 const debugLog = createDebug('explorbot:provider');

package/src/ai/rerunner.ts

@@ -7,8 +7,8 @@ import { highlight } from 'cli-highlight';
 import * as codeceptjs from 'codeceptjs';
 import heal from 'codeceptjs/lib/heal';
 import aiTracePlugin from 'codeceptjs/lib/plugin/aiTrace';
-import figureSet from 'figures';
 import dedent from 'dedent';
+import figureSet from 'figures';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.ts';
 import { setActivity } from '../activity.ts';
@@ -19,14 +19,14 @@ import { Stats } from '../stats.ts';
 import { Task, Test, TestResult } from '../test-plan.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
+import { RulesLoader } from '../utils/rules-loader.ts';
 import { loadTestSuites, printTestList } from '../utils/test-files.ts';
 import type { Agent } from './agent.ts';
 import { toolExecutionLabel } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
 import { Provider } from './provider.ts';
-import { locatorRule, actionRule, sectionContextRule } from './rules.ts';
+import { actionRule, locatorRule, sectionContextRule } from './rules.ts';
 import { TaskAgent } from './task-agent.ts';
-import { RulesLoader } from '../utils/rules-loader.ts';
 import { createCodeceptJSTools } from './tools.ts';
 
 const debugLog = createDebug('explorbot:rerunner');

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

@@ -1,10 +1,10 @@
 import dedent from 'dedent';
 import { ActionResult, type Diff } from '../../action-result.js';
+import { executionController } from '../../execution-controller.ts';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
 import { WebPageState } from '../../state-manager.js';
 import { detectFocusArea, diffAriaSnapshots } from '../../utils/aria.ts';
-import { executionController } from '../../execution-controller.ts';
 import { tag } from '../../utils/logger.js';
 import { mdq } from '../../utils/markdown-query.ts';
 import type { Provider } from '../provider.js';

package/src/ai/researcher/fingerprint-worker.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from '../../utils/html-diff.ts';

package/src/ai/researcher/locators.ts

@@ -1,15 +1,15 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../../action-result.js';
-import type Explorer from '../../explorer.ts';
 import { executionController } from '../../execution-controller.ts';
+import type Explorer from '../../explorer.ts';
 import { parseAriaLocator } from '../../utils/aria.ts';
 import { tag } from '../../utils/logger.js';
 import { mdq } from '../../utils/markdown-query.ts';
 import { WebElement } from '../../utils/web-element.ts';
-import { FOCUSED_MARKER } from './focus.ts';
 import type { Conversation } from '../conversation.ts';
 import type { Provider } from '../provider.js';
 import { locatorRule as generalLocatorRuleText } from '../rules.js';
+import { FOCUSED_MARKER } from './focus.ts';
 import { type Constructor, debugLog } from './mixin.ts';
 import { parseResearchSections } from './parser.ts';
 import type { ResearchResult } from './research-result.ts';

package/src/ai/researcher/sections.ts

@@ -37,7 +37,13 @@ export function WithSections<T extends Constructor>(Base: T) {
       const parts: string[] = [];
       for (const [name, description] of targets) {
         if (executionController.isInterrupted()) break;
-        const text = await this._researchSingleSection(name, description, ariaSnapshot, focusCss);
+        let text = '';
+        try {
+          text = await this._researchSingleSection(name, description, ariaSnapshot, focusCss);
+        } catch (err) {
+          tag('warning').log(`Section "${name}" research failed, skipping: ${err instanceof Error ? err.message : err}`);
+          continue;
+        }
         if (!text) continue;
         const trimmed = text.trim();
         if (trimmed === 'NOT_PRESENT' || trimmed.startsWith('NOT_PRESENT')) continue;

package/src/ai/researcher.ts

@@ -3,6 +3,7 @@ import dedent from 'dedent';
 import { ActionResult } from '../action-result.js';
 import { setActivity } from '../activity.ts';
 import { ConfigParser, outputPath } from '../config.ts';
+import { executionController } from '../execution-controller.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
 import type { KnowledgeTracker } from '../knowledge-tracker.ts';
@@ -11,13 +12,13 @@ import type { StateManager } from '../state-manager.js';
 import { WebPageState } from '../state-manager.js';
 import { Stats } from '../stats.ts';
 import { diffAriaSnapshots } from '../utils/aria.ts';
-import { isErrorPage } from '../utils/error-page.ts';
+import { ErrorPageError, isErrorPage } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { isBodyEmpty } from '../utils/html.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { mdq } from '../utils/markdown-query.ts';
 import { withRetry } from '../utils/retry.ts';
-import { executionController } from '../execution-controller.ts';
+import { RulesLoader } from '../utils/rules-loader.ts';
 import type { Agent } from './agent.js';
 import type { Navigator } from './navigator.ts';
 import { ContextLengthError, type Provider } from './provider.js';
@@ -30,7 +31,6 @@ import { extractValidContainers, formatResearchSummary, parseResearchSections }
 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';
 
 export type { Locator } from './researcher/locators.ts';
@@ -136,14 +136,7 @@ export class Researcher extends ResearcherBase implements Agent {
         const recovered = await this.waitForPageLoad(screenshot);
         if (!recovered) {
           tag('warning').log(`Detected error page at ${state.url}`);
-          return dedent`
-            ## Error Page Detected
-
-            URL: ${state.url}
-            Title: ${this.actionResult!.title || 'N/A'}
-
-            Research skipped. Navigate to a valid page to continue.
-          `;
+          throw new ErrorPageError(state.url, this.actionResult!.title);
         }
       }
 

package/src/ai/task-agent.ts

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../action-result.js';
-import { renderExperienceToc, type ExperienceTracker } from '../experience-tracker.js';
+import { type ExperienceTracker, renderExperienceToc } from '../experience-tracker.js';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 

package/src/ai/tools.ts

@@ -10,9 +10,9 @@ import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
 import { Navigator } from './navigator.ts';
+import type { AIProvider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { sectionContextRule } from './rules.ts';
-import type { AIProvider } from './provider.ts';
 import { isInteractive } from './task-agent.ts';
 
 const debugLog = createDebug('explorbot:tools');
@@ -289,14 +289,16 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
     form: tool({
       description: dedent`
         Execute raw CodeceptJS code block with multiple commands.
-        USE THIS TOOL for all keyboard interactions: I.fillField, I.type, I.pressKey
+        USE THIS TOOL for typing text into fields: I.fillField, I.type
 
         Follow <actions> from system prompt for available commands.
         Follow <locator_priority> from system prompt for locator selection.
 
+        I.type(text) types the literal characters of its argument into the focused element.
+        To press key combination or special keys (Ctrl, Meta, Esc) use I.pressKey instead.
+
         Use cases:
         - Typing into input fields (I.fillField, I.type)
-        - Pressing keyboard keys (I.pressKey)
         - Working with iframes (switch context with I.switchTo)
         - Performing multiple form actions in a single batch
         - Complex interactions requiring sequential commands
@@ -957,7 +959,7 @@ export function createAgentTools({
     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.
+        The TOC shows entries like "A.1 ## FLOW: ..." or "A.2 ## ACTION: ...". Pass the fileTag and sectionIndex.
         Only call when a TOC entry looks directly relevant to the current step.
       `,
       inputSchema: z.object({

package/src/api/request-store.ts

@@ -7,6 +7,8 @@ const AUTH_HEADERS = ['authorization', 'cookie', 'x-api-key', 'x-csrf-token'];
 export class RequestStore {
   private capturedRequests: RequestResult[] = [];
   private madeRequests: RequestResult[] = [];
+  private failedRequests: RequestResult[] = [];
+  private onFailedListeners: Array<(r: RequestResult) => void> = [];
   private outputDir: string;
 
   constructor(outputDir: string) {
@@ -18,6 +20,25 @@ export class RequestStore {
     result.save(this.outputDir);
   }
 
+  addFailedRequest(result: RequestResult): void {
+    this.failedRequests.push(result);
+    for (const cb of this.onFailedListeners) {
+      cb(result);
+    }
+  }
+
+  getFailedRequests(): RequestResult[] {
+    return this.failedRequests;
+  }
+
+  onFailedRequest(cb: (r: RequestResult) => void): () => void {
+    this.onFailedListeners.push(cb);
+    return () => {
+      const idx = this.onFailedListeners.indexOf(cb);
+      if (idx !== -1) this.onFailedListeners.splice(idx, 1);
+    };
+  }
+
   addMadeRequest(result: RequestResult): void {
     this.madeRequests.push(result);
     result.save(this.outputDir);
@@ -122,6 +143,7 @@ export class RequestStore {
   clear(): void {
     this.capturedRequests = [];
     this.madeRequests = [];
+    this.failedRequests = [];
   }
 }
 

package/src/api/xhr-capture.ts

@@ -38,15 +38,33 @@ export class XhrCapture {
     if (resourceType !== 'xhr' && resourceType !== 'fetch') return;
 
     const method = request.method();
-    if (!WRITE_METHODS.has(method)) return;
-
     const url = request.url();
     if (!url.startsWith(this.baseOrigin)) return;
 
+    const status = response.status();
+
+    if (status >= 400) {
+      const failedUrl = new URL(url);
+      const failure = new RequestResult({
+        id: generateRequestId(method, failedUrl.pathname, 'fail_'),
+        method,
+        path: failedUrl.pathname,
+        fullUrl: failedUrl.pathname + failedUrl.search,
+        requestHeaders: {},
+        status,
+        statusText: response.statusText(),
+        responseHeaders: {},
+        timing: 0,
+        timestamp: new Date(),
+      });
+      this.store.addFailedRequest(failure);
+    }
+
+    if (!WRITE_METHODS.has(method)) return;
+
     const contentType = response.headers()['content-type'] || '';
     if (!JSON_CONTENT_TYPES.test(contentType)) return;
 
-    const status = response.status();
     if (status === 304) return;
 
     const parsedUrl = new URL(url);