explorbot 0.1.32-beta.1 → 0.2.1

package/src/ai/tools.ts

@@ -1,15 +1,15 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import { ActionResult, type ToolResultMetadata } from '../action-result.ts';
+import { ActionResult, type PageDiff, 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';
+import { LARGE_ARIA_CHANGE_THRESHOLD, extractFocusedElement } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
+import type { ToolDeps } from './agent.ts';
 import { Navigator } from './navigator.ts';
 import type { AIProvider } from './provider.ts';
 import { Researcher } from './researcher.ts';
@@ -18,11 +18,16 @@ import { isInteractive } from './task-agent.ts';
 
 const debugLog = createDebug('explorbot:tools');
 
-export const ASSERTION_TOOLS = ['verify'] as const;
+interface AgentToolDeps extends ToolDeps {
+  researcher: Researcher;
+  navigator: Navigator;
+  supervisor?: boolean;
+  withExperience?: boolean;
+}
 
-export function createCodeceptJSTools(explorer: Explorer, task: Task) {
-  const stateManager = explorer.getStateManager();
+export const ASSERTION_TOOLS = ['verify'] as const;
 
+export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps, task: Task) {
   return {
     click: tool({
       description: dedent`
@@ -40,6 +45,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
         CRITICAL: All commands MUST target the SAME element using different locators.
         This is a FALLBACK list, NOT a sequence of different clicks.
         If you need to click multiple different elements, make SEPARATE click() calls.
+        Inline create/edit UIs may use icon-only confirm controls near the edited field instead of text buttons. Target the nearest actionable icon/control in the same row or form.
       `,
       inputSchema: z.object({
         commands: z.array(z.string()).describe(dedent`
@@ -80,33 +86,27 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
         });
 
         const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-        const action = explorer.createAction();
+        const action = explorer.action();
         const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
 
         for (let i = 0; i < commands.length; i++) {
           const command = transformContainsCommand(commands[i]);
-          const isLast = i === commands.length - 1;
-          const success = await action.attempt(command, explanation, isLast);
+          const success = await action.attempt(command, explanation);
 
-          attempts.push({
-            command,
-            success,
-            ...(action.lastError && { error: action.lastError.toString() }),
-          });
+          const attempt: { command: string; success: boolean; error?: string } = { command, success };
+          if (action.lastError) attempt.error = action.lastError.toString();
+          attempts.push(attempt);
 
           if (success) {
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
-            if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-              activeNote.screenshot = await action.saveScreenshot();
-            }
-            activeNote.commit(TestResult.PASSED);
+            await commitNote(activeNote, TestResult.PASSED, toolResult, action);
             return successToolResult('click', { ...toolResult, attempts, code: command }, action);
           }
         }
 
         let disambiguated = null;
         if (attempts.some((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
-          disambiguated = await disambiguateElements(action.lastError, explanation, explorer.getAIProvider());
+          disambiguated = await disambiguateElements(action.lastError, explanation, ai);
         }
 
         if (disambiguated) {
@@ -119,24 +119,18 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
           retryCommands.push(`I.click('${disambiguated.xpath.replace(/'/g, "\\'")}')`);
 
           for (const retryCmd of retryCommands) {
-            if (!(await action.attempt(retryCmd, explanation, true))) {
+            if (!(await action.attempt(retryCmd, explanation))) {
               attempts.push({ command: retryCmd, success: false, error: action.lastError?.toString() });
               continue;
             }
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, retryCmd);
-            if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-              activeNote.screenshot = await action.saveScreenshot();
-            }
-            activeNote.commit(TestResult.PASSED);
+            await commitNote(activeNote, TestResult.PASSED, toolResult, action);
             return successToolResult('click', { ...toolResult, attempts, code: retryCmd, disambiguated: true }, action);
           }
         }
 
         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, commands[0]);
-        if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-          activeNote.screenshot = await action.saveScreenshot();
-        }
-        activeNote.commit(TestResult.FAILED);
+        await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
         let suggestion = "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
         const lastError = attempts[attempts.length - 1]?.error || '';
@@ -204,16 +198,14 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
         });
 
         const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-        const action = explorer.createAction();
+        const action = explorer.action();
         const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
 
         for (const command of commands) {
-          const success = await action.attempt(command, explanation, true);
-          attempts.push({
-            command,
-            success,
-            ...(action.lastError && { error: action.lastError.toString() }),
-          });
+          const success = await action.attempt(command, explanation);
+          const attempt: { command: string; success: boolean; error?: string } = { command, success };
+          if (action.lastError) attempt.error = action.lastError.toString();
+          attempts.push(attempt);
 
           if (!success) continue;
 
@@ -276,16 +268,13 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
 
           if (!isSingleChar && !isStandardKey) {
             const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-            const action = explorer.createAction();
+            const action = explorer.action();
             const typeCommand = `I.type(${JSON.stringify(key)})`;
             await action.attempt(typeCommand, explanation);
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, key);
 
             if (!action.lastError) {
-              if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                activeNote.screenshot = await action.saveScreenshot();
-              }
-              activeNote.commit(TestResult.PASSED);
+              await commitNote(activeNote, TestResult.PASSED, toolResult, action);
               return successToolResult(
                 'pressKey',
                 {
@@ -299,10 +288,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
             }
 
             const errorMsg = `pressKey fallback to type() failed: ${action.lastError?.toString()}`;
-            if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-              activeNote.screenshot = await action.saveScreenshot();
-            }
-            activeNote.commit(TestResult.FAILED);
+            await commitNote(activeNote, TestResult.FAILED, toolResult, action);
             return failedToolResult('pressKey', errorMsg, {
               ...toolResult,
               code: typeCommand,
@@ -325,7 +311,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
           }
 
           const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-          const action = explorer.createAction();
+          const action = explorer.action();
 
           let pressKeyCommand: string;
           if (modifier) {
@@ -339,10 +325,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
           const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, key);
 
           if (!action.lastError) {
-            if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-              activeNote.screenshot = await action.saveScreenshot();
-            }
-            activeNote.commit(TestResult.PASSED);
+            await commitNote(activeNote, TestResult.PASSED, toolResult, action);
             return successToolResult(
               'pressKey',
               {
@@ -355,10 +338,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
           }
 
           const errorMsg = `pressKey() failed: ${action.lastError?.toString()}`;
-          if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-            activeNote.screenshot = await action.saveScreenshot();
-          }
-          activeNote.commit(TestResult.FAILED);
+          await commitNote(activeNote, TestResult.FAILED, toolResult, action);
           return failedToolResult('pressKey', errorMsg, {
             ...toolResult,
             code: pressKeyCommand,
@@ -367,7 +347,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
         } catch (error) {
           throwIfFatalBrowserError(error);
           activeNote.commit(TestResult.FAILED);
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           return failedToolResult('pressKey', `PressKey tool failed: ${errorMessage}`);
         }
       },
@@ -431,26 +411,18 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
 
           const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
           const formLocator = codeLines[0] || 'form';
-          const action = explorer.createAction();
-          const wasInIframe = await explorer.isInsideIframe();
+          const action = explorer.action();
           await action.attempt(codeBlock, explanation);
 
-          if (action.lastError && !wasInIframe && (await explorer.isInsideIframe())) {
-            await explorer.switchToMainFrame();
-          }
-
           const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, formLocator);
 
           if (action.lastError) {
             const message = action.lastError ? String(action.lastError) : 'Unknown error';
-            if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-              activeNote.screenshot = await action.saveScreenshot();
-            }
-            activeNote.commit(TestResult.FAILED);
+            await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
             let formSuggestion = 'Look into error message and identify which commands passed and which failed. Continue execution using step-by-step approach using click() and form() tools.';
             if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
-              const disambiguated = await disambiguateElements(action.lastError, explanation, explorer.getAIProvider());
+              const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
               if (disambiguated) {
                 formSuggestion = `Multiple elements matched. Add step.opts({ elementIndex: ${disambiguated.position} }) to the failing command. Fallback locator: ${disambiguated.xpath}`;
               }
@@ -468,10 +440,15 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
             );
           }
 
-          if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-            activeNote.screenshot = await action.saveScreenshot();
+          if (!hasObservablePageChange(toolResult)) {
+            activeNote.commit(TestResult.FAILED);
+            return failedToolResult('form', 'Form command executed, but no observable page or form-state change was captured.', {
+              ...toolResult,
+              code: codeBlock,
+              suggestion: 'Treat the field/form action as not completed. Re-locate the editable control, check whether another UI layer is active, then retry and verify the field value before submitting.',
+            });
           }
-          activeNote.commit(TestResult.PASSED);
+          await commitNote(activeNote, TestResult.PASSED, toolResult, action);
           return successToolResult(
             'form',
             {
@@ -486,7 +463,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
         } catch (error) {
           throwIfFatalBrowserError(error);
           activeNote.commit(TestResult.FAILED);
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           return failedToolResult('form', `Form tool failed: ${errorMessage}`);
         }
       },
@@ -494,13 +471,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
   };
 }
 
-export function createSpecialContextTools(explorer: Explorer, context: 'iframe') {
-  const stateManager = explorer.getStateManager();
-
-  if (context !== 'iframe') {
-    return {};
-  }
-
+export function createIframeTools({ explorer, stateManager }: ToolDeps) {
   return {
     exitIframe: tool({
       description: dedent`
@@ -522,9 +493,9 @@ export function createSpecialContextTools(explorer: Explorer, context: 'iframe')
             });
           }
 
-          await explorer.switchToMainFrame();
-
-          const nextState = await explorer.capturePageState();
+          const action = explorer.action();
+          await action.execute('I.switchTo()');
+          const nextState = action.getActionResult()!;
           const toolResult = await nextState.toToolResult(previousState, 'I.switchTo()');
 
           return successToolResult('exitIframe', {
@@ -534,7 +505,7 @@ export function createSpecialContextTools(explorer: Explorer, context: 'iframe')
           });
         } catch (error) {
           throwIfFatalBrowserError(error);
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           return failedToolResult('exitIframe', `Failed to exit iframe: ${errorMessage}`);
         }
       },
@@ -542,21 +513,32 @@ export function createSpecialContextTools(explorer: Explorer, context: 'iframe')
   };
 }
 
-export function createAgentTools({
-  explorer,
-  researcher,
-  navigator,
-  experienceTracker,
-  getState,
-  supervisor,
-}: {
-  explorer: Explorer;
-  researcher: Researcher;
-  navigator: Navigator;
-  experienceTracker?: ExperienceTracker;
-  getState?: () => ActionResult | null;
-  supervisor?: boolean;
-}): any {
+export function createLearnExperienceTool({ getExperienceTracker, getState }: { getExperienceTracker: () => ExperienceTracker; getState: () => ActionResult | null }) {
+  return tool({
+    description: dedent`
+      Read the full body of a specific experience section listed in <experience>.
+      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({
+      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 = getExperienceTracker().getExperienceSection(fileTag, sectionIndex, state);
+      if (!section) {
+        return { error: 'Section not found. Experience may have been updated; re-read the latest TOC.' };
+      }
+      return section;
+    },
+  });
+}
+
+export function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }: AgentToolDeps): any {
   let visionDisabled = false;
 
   const tools: Record<string, any> = {
@@ -581,7 +563,7 @@ export function createAgentTools({
         }
 
         try {
-          const actionResult = await explorer.capturePageWithScreenshot();
+          const actionResult = await explorer.capture({ screenshot: true });
 
           if (!actionResult.screenshot) {
             return failedToolResult('see', 'Failed to capture screenshot for analysis');
@@ -600,7 +582,7 @@ export function createAgentTools({
           });
         } catch (error) {
           throwIfFatalBrowserError(error);
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           visionDisabled = true;
           tag('warning').log('⚠️ Vision model is not available. Visual checks are disabled for this session.');
           return failedToolResult('see', `See tool failed: ${errorMessage}`, {
@@ -629,7 +611,6 @@ export function createAgentTools({
       }),
       execute: async ({ reason }) => {
         try {
-          const stateManager = explorer.getStateManager();
           const currentState = stateManager.getCurrentState();
 
           if (!currentState) {
@@ -649,7 +630,7 @@ export function createAgentTools({
             reminder: 'Context provided. Do not call context() again until you perform actions or suspect page changed.',
           });
         } catch (error) {
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           return failedToolResult('context', `Context tool failed: ${errorMessage}`);
         }
       },
@@ -670,7 +651,7 @@ export function createAgentTools({
       }),
       execute: async ({ assertion }) => {
         try {
-          const currentState = explorer.getStateManager().getCurrentState();
+          const currentState = stateManager.getCurrentState();
           const verifications = currentState?.verifications;
 
           if (verifications?.[assertion] !== undefined) {
@@ -681,7 +662,7 @@ export function createAgentTools({
             });
           }
 
-          const actionResult = await explorer.capturePageState();
+          const actionResult = await explorer.capture();
           const result = await navigator.verifyState(assertion, actionResult);
 
           if (result.verified) {
@@ -700,7 +681,7 @@ export function createAgentTools({
           });
         } catch (error) {
           throwIfFatalBrowserError(error);
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           return failedToolResult('verify', `Verify tool failed: ${errorMessage}`, {
             error: errorMessage,
           });
@@ -731,7 +712,6 @@ export function createAgentTools({
       }),
       execute: async ({ reason }) => {
         try {
-          const stateManager = explorer.getStateManager();
           const currentState = stateManager.getCurrentState();
 
           if (!currentState) {
@@ -756,7 +736,7 @@ export function createAgentTools({
           });
         } catch (error) {
           throwIfFatalBrowserError(error);
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           return failedToolResult('research', `Research tool failed: ${errorMessage}`, {
             error: errorMessage,
           });
@@ -775,7 +755,6 @@ export function createAgentTools({
       }),
       execute: async ({ instruction }) => {
         try {
-          const stateManager = explorer.getStateManager();
           const currentState = stateManager.getCurrentState();
 
           if (!currentState) {
@@ -801,7 +780,7 @@ export function createAgentTools({
           });
         } catch (error) {
           throwIfFatalBrowserError(error);
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           return failedToolResult('interact', `Interact tool failed: ${errorMessage}`, {
             error: errorMessage,
           });
@@ -830,7 +809,6 @@ export function createAgentTools({
         }
 
         try {
-          const stateManager = explorer.getStateManager();
           const currentState = stateManager.getCurrentState();
 
           if (!currentState) {
@@ -838,8 +816,8 @@ export function createAgentTools({
           }
 
           const previousState = ActionResult.fromState(currentState);
-          const action = explorer.createAction();
-          const actionResult = await explorer.capturePageWithScreenshot();
+          const action = explorer.action();
+          const actionResult = await explorer.capture({ screenshot: true });
 
           if (!actionResult.screenshot) {
             return failedToolResult('visualClick', 'Failed to capture screenshot for visual analysis');
@@ -881,7 +859,7 @@ export function createAgentTools({
           });
         } catch (error) {
           throwIfFatalBrowserError(error);
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           visionDisabled = true;
           tag('warning').log('⚠️ Vision model is not available. Visual clicks are disabled for this session.');
           return failedToolResult('visualClick', `visualClick tool failed: ${errorMessage}`, {
@@ -901,7 +879,6 @@ export function createAgentTools({
         reason: z.string().describe('Why you need to go back'),
       }),
       execute: async ({ reason }) => {
-        const stateManager = explorer.getStateManager();
         const currentState = stateManager.getCurrentState();
         const currentUrl = currentState?.fullUrl || currentState?.url;
         const history = stateManager.getStateHistory();
@@ -921,22 +898,24 @@ export function createAgentTools({
           });
         }
 
-        const action = explorer.createAction();
+        let previousState: ActionResult | null = null;
+        if (currentState) previousState = ActionResult.fromState(currentState);
+
+        const action = explorer.action();
         const success = await action.attempt(`I.amOnPage(${JSON.stringify(targetUrl)})`, `${reason} (BACK to ${targetUrl})`);
 
         if (success) {
-          const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-          const toolResult = await previousState.toToolResult(previousState, `I.amOnPage("${targetUrl}")`);
+          const newState = ActionResult.fromState(stateManager.getCurrentState()!);
+          const toolResult = await newState.toToolResult(previousState, `I.amOnPage("${targetUrl}")`);
           return successToolResult('back', {
             ...toolResult,
             message: `Navigated back to ${targetUrl}`,
           });
         }
 
-        return failedToolResult('back', `Failed to navigate back to ${targetUrl}`, {
-          suggestion: 'Try reset() to return to the starting page.',
-          ...(action.lastError && { error: action.lastError.toString() }),
-        });
+        const failData: Record<string, any> = { suggestion: 'Try reset() to return to the starting page.' };
+        if (action.lastError) failData.error = action.lastError.toString();
+        return failedToolResult('back', `Failed to navigate back to ${targetUrl}`, failData);
       },
     }),
 
@@ -944,7 +923,7 @@ export function createAgentTools({
       description: 'List all previously visited page states (deduped by URL). Use to find pages to navigate back to.',
       inputSchema: z.object({}),
       execute: async () => {
-        const history = explorer.getStateManager().getStateHistory();
+        const history = stateManager.getStateHistory();
         const seen = new Set<string>();
         const states = history
           .map((t) => t.toState)
@@ -954,7 +933,7 @@ export function createAgentTools({
             return true;
           })
           .map((s, i) => ({ index: i, url: s.url, title: s.title, h1: s.h1 }));
-        return { success: true, states };
+        return successToolResult('getVisitedStates', { states });
       },
     }),
 
@@ -977,7 +956,6 @@ export function createAgentTools({
         reason: z.string().describe('What element you are looking for and why'),
       }),
       execute: async ({ xpath, reason }) => {
-        const stateManager = explorer.getStateManager();
         const currentState = stateManager.getCurrentState();
 
         if (!currentState) {
@@ -1003,44 +981,42 @@ export function createAgentTools({
           });
         }
 
-        const action = explorer.createAction();
-        const visible = await action.attempt(`I.seeElement(${JSON.stringify(xpath)})`, 'xpathCheck visibility', false);
+        const action = explorer.action();
+        const visible = await action.attempt(`I.seeElement(${JSON.stringify(xpath)})`, 'xpathCheck visibility');
+        const liveElement = await explorer.withPage((page) => WebElement.fromPlaywrightLocator(page.locator(`xpath=${xpath}`)));
 
         const matchesSummary = result.elements.map((el, i) => `${i + 1}. <${el.tag} ${el.keyAttrs}> text="${el.text}" html: ${el.outerHTML}`).join('\n');
 
         const visibilityNote = visible ? 'Element IS visible in browser — Tester can use this XPath as locator.' : 'Element exists in DOM but is NOT visible. May need scrolling, a click to reveal, or is hidden.';
 
+        const hit = liveElement?.ourAttr('hit') || null;
+        const coveredBy = liveElement?.ourAttr('coveredBy') || null;
+        let resolvedVisibilityNote = visibilityNote;
+        if (hit === 'covered') {
+          resolvedVisibilityNote = `Element exists in DOM and is visible, but is covered by ${coveredBy || 'another UI layer'}. Dismiss or move the covering UI before interacting with it.`;
+        }
+        if (hit === 'offscreen') {
+          resolvedVisibilityNote = 'Element exists in DOM but its interaction point is outside the viewport. Scroll or reveal it before interacting.';
+        }
+
         return successToolResult('xpathCheck', {
           totalFound: result.totalFound,
           matches: matchesSummary,
-          visibilityNote,
+          visibilityNote: resolvedVisibilityNote,
+          hit,
+          coveredBy,
           xpath,
         });
       },
     }),
   };
 
-  if (experienceTracker && getState) {
-    tools.learnExperience = tool({
-      description: dedent`
-        Read the full body of a specific experience section listed in <experience>.
-        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({
-        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;
+  if (withExperience !== false) {
+    tools.learnExperience = createLearnExperienceTool({
+      getExperienceTracker: () => stateManager.getExperienceTracker(),
+      getState: () => {
+        const currentState = stateManager.getCurrentState();
+        return currentState ? ActionResult.fromState(currentState) : null;
       },
     });
   }
@@ -1131,11 +1107,16 @@ function transformContainsCommand(command: string): string {
   return command;
 }
 
-function countAriaChanges(ariaChanges: string): number {
-  const addedCount = (ariaChanges.match(/\n {4}- /g) || []).length;
-  const removedMatch = ariaChanges.match(/removed: (\d+) interactive/);
-  const removedCount = removedMatch ? Number.parseInt(removedMatch[1]) : 0;
-  return addedCount + removedCount;
+function errorText(error: unknown): string {
+  if (error instanceof Error) return error.toString();
+  return 'Unknown error occurred';
+}
+
+async function commitNote(activeNote: any, result: TestResult, toolResult: any, action: any): Promise<void> {
+  if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
+    activeNote.screenshot = await action.saveScreenshot();
+  }
+  activeNote.commit(result);
 }
 
 function successToolResult(action: string, data?: Record<string, any>, source?: { playwrightGroupId?: string | null; assertionSteps?: any[] }) {
@@ -1151,7 +1132,7 @@ function successToolResult(action: string, data?: Record<string, any>, source?:
     const ariaChanges = data.pageDiff.ariaChanges || '';
     const urlChanged = data.pageDiff.urlChanged === true;
     const hasHtmlParts = Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
-    if (countAriaChanges(ariaChanges) >= 50) {
+    if (isMajorPageChange(data.pageDiff)) {
       suggestion = `MAJOR PAGE CHANGE. Page entered a different mode. Check htmlParts and iframes in pageDiff before next action. ${suggestion}`;
     } else if (!urlChanged && !ariaChanges && !hasHtmlParts) {
       suggestion = 'Action ran without error but produced no observable change (URL, ARIA and HTML all unchanged). The locator likely matched a non-interactive ancestor or an element outside the intended control. Re-locate via xpathCheck() or verify with see() before treating this as success.';
@@ -1163,6 +1144,17 @@ function successToolResult(action: string, data?: Record<string, any>, source?:
   return result;
 }
 
+export function isMajorPageChange(pageDiff: PageDiff): boolean {
+  return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
+}
+
+function hasObservablePageChange(data?: Record<string, any>): boolean {
+  if (!data?.pageDiff) return false;
+  if (data.pageDiff.urlChanged === true) return true;
+  if (data.pageDiff.ariaChanges) return true;
+  return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
+}
+
 async function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null) {
   const result: Record<string, any> = { success: false, action, message, ...data };
   if (data?.pageDiff) {
@@ -1257,7 +1249,7 @@ async function disambiguateElements(error: Error | null | undefined, explanation
         },
       ],
       schema,
-      provider.getAgenticModel(),
+      provider.getModelForAgent(),
       { agentName: 'disambiguator', timeout: 15000 }
     );
 
@@ -1273,7 +1265,7 @@ async function disambiguateElements(error: Error | null | undefined, explanation
 }
 
 function getNotFoundSuggestion(errorMessage: string): string | null {
-  if (!errorMessage.includes('was not found') && !errorMessage.includes('not found by text|CSS|XPath')) {
+  if (!errorMessage.includes('not found')) {
     return null;
   }