explorbot 0.1.32-beta.1 → 0.2.1

package/dist/src/ai/tools.js

@@ -3,7 +3,7 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { TestResult } from '../test-plan.js';
-import { extractFocusedElement } from "../utils/aria.js";
+import { LARGE_ARIA_CHANGE_THRESHOLD, extractFocusedElement } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
@@ -12,8 +12,7 @@ import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 const debugLog = createDebug('explorbot:tools');
 export const ASSERTION_TOOLS = ['verify'];
-export function createCodeceptJSTools(explorer, task) {
-    const stateManager = explorer.getStateManager();
+export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
     return {
         click: tool({
             description: dedent `
@@ -31,6 +30,7 @@ export function createCodeceptJSTools(explorer, 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 `
@@ -67,29 +67,24 @@ export function createCodeceptJSTools(explorer, task) {
                     return `I.click(${JSON.stringify(trimmed)})`;
                 });
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                const action = explorer.createAction();
+                const action = explorer.action();
                 const attempts = [];
                 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);
-                    attempts.push({
-                        command,
-                        success,
-                        ...(action.lastError && { error: action.lastError.toString() }),
-                    });
+                    const success = await action.attempt(command, explanation);
+                    const attempt = { 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) {
                     debugLog('Disambiguation picked element %d', disambiguated.position);
@@ -100,23 +95,17 @@ export function createCodeceptJSTools(explorer, 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 || '';
                 if (lastError.includes('was not found') || lastError.includes('not found by text')) {
@@ -173,15 +162,14 @@ export function createCodeceptJSTools(explorer, task) {
                     return `I.moveCursorTo(${JSON.stringify(trimmed)})`;
                 });
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                const action = explorer.createAction();
+                const action = explorer.action();
                 const attempts = [];
                 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, success };
+                    if (action.lastError)
+                        attempt.error = action.lastError.toString();
+                    attempts.push(attempt);
                     if (!success)
                         continue;
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
@@ -234,15 +222,12 @@ export function createCodeceptJSTools(explorer, task) {
                     const keyToUse = matchingStandardKey || key;
                     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', {
                                 ...toolResult,
                                 message: `Automatically used type() for "${key}" (not a standard key press)`,
@@ -251,10 +236,7 @@ export function createCodeceptJSTools(explorer, task) {
                             }, action);
                         }
                         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,
@@ -274,7 +256,7 @@ export function createCodeceptJSTools(explorer, task) {
                         }
                     }
                     const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                    const action = explorer.createAction();
+                    const action = explorer.action();
                     let pressKeyCommand;
                     if (modifier) {
                         const modifiers = Array.isArray(modifier) ? modifier : [modifier];
@@ -286,10 +268,7 @@ export function createCodeceptJSTools(explorer, task) {
                     await action.attempt(pressKeyCommand, 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', {
                             ...toolResult,
                             message: `Pressed key: ${key}${modifier ? ` with modifier(s): ${Array.isArray(modifier) ? modifier.join('+') : modifier}` : ''}`,
@@ -297,10 +276,7 @@ export function createCodeceptJSTools(explorer, task) {
                         }, action);
                     }
                     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,
@@ -310,7 +286,7 @@ export function createCodeceptJSTools(explorer, 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}`);
                 }
             },
@@ -370,22 +346,15 @@ export function createCodeceptJSTools(explorer, 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}`;
                             }
@@ -396,10 +365,15 @@ export function createCodeceptJSTools(explorer, task) {
                             suggestion: formSuggestion,
                         }, action.lastError);
                     }
-                    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', {
                         ...toolResult,
                         message: `Form completed successfully with ${lines.length} commands.`,
@@ -411,18 +385,14 @@ export function createCodeceptJSTools(explorer, 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}`);
                 }
             },
         }),
     };
 }
-export function createSpecialContextTools(explorer, context) {
-    const stateManager = explorer.getStateManager();
-    if (context !== 'iframe') {
-        return {};
-    }
+export function createIframeTools({ explorer, stateManager }) {
     return {
         exitIframe: tool({
             description: dedent `
@@ -442,8 +412,9 @@ export function createSpecialContextTools(explorer, context) {
                             suggestion: 'Continue interacting with the current page context.',
                         });
                     }
-                    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', {
                         ...toolResult,
@@ -453,14 +424,38 @@ export function createSpecialContextTools(explorer, context) {
                 }
                 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}`);
                 }
             },
         }),
     };
 }
-export function createAgentTools({ explorer, researcher, navigator, experienceTracker, getState, supervisor, }) {
+export function createLearnExperienceTool({ getExperienceTracker, getState }) {
+    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 }) {
     let visionDisabled = false;
     const tools = {
         see: tool({
@@ -483,7 +478,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                     return failedToolResult('see', 'Vision tools are disabled for this session. Use context() to get fresh ARIA snapshot and analyze page state from ARIA data.');
                 }
                 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');
                     }
@@ -499,7 +494,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 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}`, {
@@ -527,7 +522,6 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
             }),
             execute: async ({ reason }) => {
                 try {
-                    const stateManager = explorer.getStateManager();
                     const currentState = stateManager.getCurrentState();
                     if (!currentState) {
                         return failedToolResult('context', 'No current page state available.');
@@ -545,7 +539,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                     });
                 }
                 catch (error) {
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     return failedToolResult('context', `Context tool failed: ${errorMessage}`);
                 }
             },
@@ -565,7 +559,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
             }),
             execute: async ({ assertion }) => {
                 try {
-                    const currentState = explorer.getStateManager().getCurrentState();
+                    const currentState = stateManager.getCurrentState();
                     const verifications = currentState?.verifications;
                     if (verifications?.[assertion] !== undefined) {
                         return failedToolResult('verify', `Already verified: "${assertion}" → ${verifications[assertion] ? 'PASS' : 'FAIL'}`, {
@@ -574,7 +568,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                             suggestion: verifications[assertion] ? 'This verification already passed. Call finish() to complete the test.' : 'This verification already failed. Perform actions to change the page state, then try again.',
                         });
                     }
-                    const actionResult = await explorer.capturePageState();
+                    const actionResult = await explorer.capture();
                     const result = await navigator.verifyState(assertion, actionResult);
                     if (result.verified) {
                         return successToolResult('verify', {
@@ -588,7 +582,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 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,
                     });
@@ -618,7 +612,6 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
             }),
             execute: async ({ reason }) => {
                 try {
-                    const stateManager = explorer.getStateManager();
                     const currentState = stateManager.getCurrentState();
                     if (!currentState) {
                         return failedToolResult('research', 'No current page state available. Navigate to a page first.');
@@ -641,7 +634,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 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,
                     });
@@ -659,7 +652,6 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
             }),
             execute: async ({ instruction }) => {
                 try {
-                    const stateManager = explorer.getStateManager();
                     const currentState = stateManager.getCurrentState();
                     if (!currentState) {
                         return failedToolResult('interact', 'No current page state available. Navigate to a page first.');
@@ -681,7 +673,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 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,
                     });
@@ -708,14 +700,13 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                     return failedToolResult('visualClick', 'Vision tools are disabled for this session. Use xpathCheck() to find the element, then click() with the discovered locator.');
                 }
                 try {
-                    const stateManager = explorer.getStateManager();
                     const currentState = stateManager.getCurrentState();
                     if (!currentState) {
                         return failedToolResult('visualClick', 'No current page state available.');
                     }
                     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');
                     }
@@ -749,7 +740,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 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}`, {
@@ -768,7 +759,6 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 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();
@@ -785,27 +775,30 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                         suggestion: 'Use reset() to navigate to the starting page.',
                     });
                 }
-                const action = explorer.createAction();
+                let previousState = 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 = { 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);
             },
         }),
         getVisitedStates: tool({
             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();
                 const states = history
                     .map((t) => t.toState)
@@ -816,7 +809,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                     return true;
                 })
                     .map((s, i) => ({ index: i, url: s.url, title: s.title, h1: s.h1 }));
-                return { success: true, states };
+                return successToolResult('getVisitedStates', { states });
             },
         }),
         xpathCheck: tool({
@@ -838,7 +831,6 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 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) {
                     return failedToolResult('xpathCheck', 'No current page state available.');
@@ -858,40 +850,37 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                         suggestion: 'Try a broader expression. Examples: //*[contains(@class, "btn")], //button, //*[contains(text(), "keyword")]',
                     });
                 }
-                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;
             },
         });
     }
@@ -970,11 +959,16 @@ function transformContainsCommand(command) {
     }
     return command;
 }
-function countAriaChanges(ariaChanges) {
-    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) {
+    if (error instanceof Error)
+        return error.toString();
+    return 'Unknown error occurred';
+}
+async function commitNote(activeNote, result, toolResult, action) {
+    if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
+        activeNote.screenshot = await action.saveScreenshot();
+    }
+    activeNote.commit(result);
 }
 function successToolResult(action, data, source) {
     const result = { success: true, action, ...data };
@@ -989,7 +983,7 @@ function successToolResult(action, data, 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) {
@@ -1002,6 +996,18 @@ function successToolResult(action, data, source) {
     }
     return result;
 }
+export function isMajorPageChange(pageDiff) {
+    return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
+}
+function hasObservablePageChange(data) {
+    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, message, data, error) {
     const result = { success: false, action, message, ...data };
     if (data?.pageDiff) {
@@ -1085,7 +1091,7 @@ async function disambiguateElements(error, explanation, provider) {
             Return the position number, or null if none of them match.
           `,
             },
-        ], schema, provider.getAgenticModel(), { agentName: 'disambiguator', timeout: 15000 });
+        ], schema, provider.getModelForAgent(), { agentName: 'disambiguator', timeout: 15000 });
         const position = result?.object?.position;
         if (position && position >= 1 && position <= elementDetails.length) {
             return { position, xpath: elementDetails[position - 1].xpath };
@@ -1098,7 +1104,7 @@ async function disambiguateElements(error, explanation, provider) {
     }
 }
 function getNotFoundSuggestion(errorMessage) {
-    if (!errorMessage.includes('was not found') && !errorMessage.includes('not found by text|CSS|XPath')) {
+    if (!errorMessage.includes('not found')) {
         return null;
     }
     return dedent `

package/dist/src/command-handler.js

@@ -131,7 +131,7 @@ export class CommandHandler {
         }
     }
     async executeBrowserCommand(input) {
-        const action = this.explorBot.getExplorer().createAction();
+        const action = this.explorBot.getExplorer().action();
         await action.execute(input);
     }
     isCommand(input) {

package/dist/src/commands/compact-command.d.ts

@@ -1,4 +1,4 @@
-import type { ExperienceFile } from '../ai/experience-compactor.js';
+import type { ExperienceFile } from '../experience-tracker.js';
 import type { ExperienceTracker } from '../experience-tracker.js';
 import { BaseCommand, type Suggestion } from './base-command.js';
 export declare class CompactCommand extends BaseCommand {