explorbot 0.2.3 → 0.2.4

package/dist/src/ai/rules.js

@@ -2,13 +2,18 @@ import dedent from 'dedent';
 export const recommendedCodeceptCommands = ['I.click', 'I.type', 'I.fillField', 'I.see', 'I.seeElement'];
 const locatorPriorityRule = dedent `
   <locator_priority>
+  When the page context shows the element a ref, such as [ref=e14], there is no locator to select: click it with clickRef
+  and that ref. A ref names one exact element, so it never matches the wrong one and never has to be narrowed. Everything
+  below is for elements the context gives no ref for.
+
   Use the following priority when selecting locators:
 
   1. ARIA locators (first choice) - target browser's accessibility tree, most reliable
      Use JSON format: { "role": "button", "text": "Login" }
-     Best for: buttons, links, inputs, form controls, dropdowns, checkboxes, radio buttons
+     Copy role and text VERBATIM from the ARIA snapshot or UI map — never guess the pair.
+     If the element is absent from the snapshot, do not invent one; use text or CSS instead.
 
-  2. Text locators (second choice) - use only when text is unique on the page
+  2. Text locators (second choice) - exact visible text, use only when unique on the page
      Example: 'Login', 'Submit', 'Username'
      Skip if the same text appears multiple times on the page
 
@@ -23,10 +28,10 @@ const locatorPriorityRule = dedent `
 `;
 const contextSimplificationRule = dedent `
   <context_simplification>
-  When container is available from UI map sections:
-  - Text + container is simplest and PREFERRED: I.click('Save', '.modal')
-  - ARIA + container for disambiguation: I.click({"role":"button","text":"Save"}, '.modal')
-  - ALWAYS use context parameter unless locator is XPath or unique ID
+  - Add a container when the target may match several elements, or the UI map gives a verified
+    section container: I.click('Save', '.modal')
+  - Skip the container when the locator is already unique (XPath, unique ID, unique text)
+  - A wrong or stale container guarantees failure: always add one fallback command WITHOUT a container
   - No need for complex ARIA when container narrows scope sufficiently
   </context_simplification>
 `;
@@ -55,7 +60,7 @@ const locatorStrategyRule = dedent `
 
   <good_aria_locator_example>
   { "role": "button", "text": "Login" },
-  { "role": "input", "text": "Name" },
+  { "role": "textbox", "text": "Name" },
   { "role": "link", "text": "Forgot your password?" },
   { "role": "link", "text": "Sign Up" },
   { "role": "button", "text": "Sign In" },
@@ -101,7 +106,7 @@ const locatorStrategyRule = dedent `
   </xpath_rules>
 
   <good locator example>
-    'div[role=input][placeholder="Name"]'
+    'input[placeholder="Name"]'
     '[aria-label="Name"]'
     'form#user_form input[name="name"]'
     '#content-top #user_name'
@@ -231,7 +236,8 @@ export const unexpectedPopupRule = dedent `
 `;
 export const sectionContextRule = dedent `
   <section_context_rule>
-  Context parameter is DEFAULT for all interactions. ALWAYS use container from UI map sections unless locator is XPath or unique ID.
+  Use a container from UI map sections when the target may match several elements. A container that is
+  wrong or stale guarantees failure, so prefer a verified one and keep a containerless fallback.
 
   1. Identify which section contains the target element
   2. Get the Context Locator from that section in the UI map
@@ -249,9 +255,10 @@ export const sectionContextRule = dedent `
   For CSS locators - prepend section context:
   - I.click('.main button.submit')  // instead of I.click('button.submit')
 
-  Only omit context when:
+  Omit context when the locator already resolves to one element:
   - Locator is XPath (already includes path context)
   - Locator is a unique ID (#specific-element)
+  - Text or ARIA that appears only once on the page
   </section_context_rule>
 
   ${unexpectedPopupRule}

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

@@ -1,6 +1,9 @@
+import { executionController } from "../execution-controller.js";
 import { HooksRunner } from "../utils/hooks-runner.js";
 export function isInteractive() {
-    return process.env.INK_RUNNING === 'true';
+    if (process.env.INK_RUNNING === 'true')
+        return true;
+    return executionController.hasInputCallback();
 }
 function createNullProxy() {
     return new Proxy({}, {

package/dist/src/ai/tester.d.ts

@@ -31,7 +31,6 @@ export declare class Tester extends TaskAgent implements Agent {
     seenUiMapUrls: Set<string>;
     lastAnalyzedStateHash: string | null;
     stalledIterations: number;
-    hasSuccessfulAssertion: boolean;
     readonly MAX_STALLED_ITERATIONS = 3;
     constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any);
     getNavigator(): Navigator;
@@ -50,6 +49,7 @@ export declare class Tester extends TaskAgent implements Agent {
     shouldStopForStalledExecution(task: Test, previousState: ActionResult, toolExecutions: any[]): boolean;
     prepareInstructionsForNextStep(task: Test): Promise<string>;
     reinjectContextIfNeeded(iteration: number, currentState: ActionResult): Promise<string>;
+    interactiveAriaWithRefs(state: ActionResult): Promise<string>;
     finishTest(task: Test): void;
     abortStartedTestOnErrorPage(task: Test, actionResult: ActionResult): Promise<{
         success: boolean;

package/dist/src/ai/tester.js

@@ -8,13 +8,13 @@ import { clearActivity, setActivity } from "../activity.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
 import { TestResult } from "../test-plan.js";
-import { detectFocusArea, extractFocusedElement } from "../utils/aria.js";
+import { compactAriaSnapshot, detectFocusArea } from "../utils/aria.js";
 import { ErrorPageError, isErrorPage } from "../utils/error-page.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
 import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from "./rules.js";
 import { TaskAgent } from "./task-agent.js";
-import { createCodeceptJSTools, createIframeTools } from "./tools.js";
+import { createCodeceptJSTools, createIframeTools, withdrawVisionTools } from "./tools.js";
 const debugLog = createDebug('explorbot:tester');
 const SAMPLE_FILES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../../assets/sample-files');
 const SAMPLE_FILES = {
@@ -48,7 +48,6 @@ export class Tester extends TaskAgent {
     seenUiMapUrls = new Set();
     lastAnalyzedStateHash = null;
     stalledIterations = 0;
-    hasSuccessfulAssertion = false;
     MAX_STALLED_ITERATIONS = 3;
     constructor(deps, researcher, navigator, agentTools) {
         super(deps);
@@ -88,14 +87,13 @@ export class Tester extends TaskAgent {
         this.seenUiMapUrls.clear();
         this.lastAnalyzedStateHash = null;
         this.stalledIterations = 0;
-        this.hasSuccessfulAssertion = false;
         this.stateManager.clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
         const requestStore = this.requestStore;
         requestStore.clear();
         const offFailedRequest = requestStore.onFailedRequest((r) => {
-            task.addNote(`Network error: ${r.method} ${r.path} → ${r.status}`, TestResult.FAILED);
+            task.addObservation(`Network error: ${r.method} ${r.path} → ${r.status}`);
         });
         const initialState = ActionResult.fromState(state);
         if (isErrorPage(initialState)) {
@@ -208,6 +206,7 @@ export class Tester extends TaskAgent {
                 if (currentState.isInsideIframe) {
                     Object.assign(tools, createIframeTools(this.toolDeps));
                 }
+                withdrawVisionTools(tools);
                 debugLog(`Test ${task.scenario} iteration ${iteration}`);
                 if (this.stateManager.isInDeadLoop()) {
                     task.addNote('Dead loop detected. Stopped');
@@ -268,15 +267,8 @@ export class Tester extends TaskAgent {
                 const allToolNames = result?.toolExecutions?.map((execution) => execution.toolName) || [];
                 const successfulToolNames = result?.toolExecutions?.filter((execution) => execution.wasSuccessful)?.map((execution) => execution.toolName) || [];
                 const actionPerformed = !!allToolNames.find((toolName) => this.ACTION_TOOLS.includes(toolName));
-                const successfulActionPerformed = !!successfulToolNames.find((toolName) => this.ACTION_TOOLS.includes(toolName));
                 assertionPerformed = !!successfulToolNames.find((toolName) => this.ASSERTION_TOOLS.includes(toolName));
                 const wasSuccessful = result?.toolExecutions?.every((execution) => execution.wasSuccessful);
-                if (successfulActionPerformed) {
-                    this.hasSuccessfulAssertion = false;
-                }
-                if (assertionPerformed) {
-                    this.hasSuccessfulAssertion = true;
-                }
                 this.trackToolExecutions(result?.toolExecutions || []);
                 if (this.consecutiveEmptyResults >= 5) {
                     task.addNote('AI model is not responding with actions. Stopped');
@@ -360,6 +352,7 @@ export class Tester extends TaskAgent {
             if (extensions >= this.MAX_EXTENSIONS)
                 break;
             extensions++;
+            this.stalledIterations = 0;
             tag('info').log(`Pilot extending test (${extensions}/${this.MAX_EXTENSIONS})`);
             conversation.cleanupTag('page_aria', '...trimmed...', 1);
             conversation.cleanupTag('page_html', '...trimmed...', 0);
@@ -414,12 +407,7 @@ export class Tester extends TaskAgent {
         this.stalledIterations++;
         if (this.stalledIterations < this.MAX_STALLED_ITERATIONS)
             return false;
-        if (this.hasSuccessfulAssertion) {
-            task.addNote('No further browser progress after successful verification; requesting final review');
-            return true;
-        }
-        task.addNote('No browser progress after repeated attempts on unchanged page', TestResult.FAILED);
-        task.finish(TestResult.FAILED);
+        task.addNote('No further browser progress on unchanged page; requesting final review');
         return true;
     }
     async prepareInstructionsForNextStep(task) {
@@ -437,7 +425,8 @@ export class Tester extends TaskAgent {
       </rules>
     `;
         if (task.getPrintableNotes()) {
-            outcomeStatus = dedent `
+            outcomeStatus += dedent `
+
         Your current log:
         <notes>
         ${task.notesToString()}
@@ -458,7 +447,7 @@ export class Tester extends TaskAgent {
         this.previousStateHash = currentStateHash;
         let context = '';
         const focusArea = detectFocusArea(currentState.ariaSnapshot);
-        const focusedElement = extractFocusedElement(currentState.ariaSnapshot);
+        const focusedElement = currentState.focusedElement;
         if (focusedElement) {
             const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
             context += dedent `
@@ -539,7 +528,7 @@ export class Tester extends TaskAgent {
         </page>
 
         <page_aria>
-        ${currentState.getInteractiveARIA()}
+        ${await this.interactiveAriaWithRefs(currentState)}
         </page_aria>
         ${uiMapSection}
 
@@ -574,26 +563,32 @@ export class Tester extends TaskAgent {
       </page>
 
       <page_aria>
-      ${currentState.getInteractiveARIA()}
+      ${await this.interactiveAriaWithRefs(currentState)}
       </page_aria>
     `;
     }
+    async interactiveAriaWithRefs(state) {
+        const withRefs = await Promise.resolve(this.explorer?.withPage?.((page) => page.locator('body').ariaSnapshot({ mode: 'ai' }))).catch(() => null);
+        if (!withRefs)
+            return state.getInteractiveARIA();
+        return compactAriaSnapshot(withRefs, false);
+    }
     finishTest(task) {
-        if (!task.hasFinished) {
-            task.finish(TestResult.FAILED);
+        if (!task.result) {
+            if (task.hasAchievedAll())
+                task.finish(TestResult.PASSED);
+            else
+                task.finish(TestResult.FAILED);
         }
         if (task.isSuccessful) {
             tag('success').log(`Successful test: ${task.scenario}`);
+            return;
         }
-        else if (task.isSkipped) {
+        if (task.isSkipped) {
             tag('warning').log(`Skipped test: ${task.scenario}`);
+            return;
         }
-        else if (task.hasFailed) {
-            tag('error').log(`Failed test: ${task.scenario}`);
-        }
-        else {
-            tag('warning').log(`Test with no result: ${task.scenario}`);
-        }
+        tag('error').log(`Failed test: ${task.scenario}`);
     }
     async abortStartedTestOnErrorPage(task, actionResult) {
         const error = new ErrorPageError(actionResult.url || task.startUrl || '', actionResult.title, actionResult.httpStatus);
@@ -734,6 +729,9 @@ export class Tester extends TaskAgent {
       ${task.expected.map((e) => `- ${e}`).join('\n')}
       </expected_results>
 
+      An expected result counts as settled only when you record it back word for word as it is written above.
+      A note in your own wording is a general note and leaves that result unsettled.
+
       Your goal is to perform actions on the web page and verify the expected outcomes.
       Try to achieve as many goals as possible.
       If goal is not achievable, log that and skip to next one.
@@ -968,6 +966,9 @@ export class Tester extends TaskAgent {
           - You unsuccessfully tried multiple iterations and failed
           - If the expected result was expected to fail, use status="success" instead
 
+          When a note settles one of the expected results, that note must repeat the expected result word
+          for word. Paraphrasing it leaves the expected result unsettled and it is reported as unverified.
+
           Example:
           - record({ notes: ["clicked login button", "login form appeared", "fill credentials"], status: "success" })
         `,
@@ -1045,8 +1046,7 @@ export class Tester extends TaskAgent {
         this.stalledIterations++;
         if (this.stalledIterations < this.MAX_STALLED_ITERATIONS)
             return false;
-        task.addNote('No browser progress after repeated execution errors', TestResult.FAILED);
-        task.finish(TestResult.FAILED);
+        task.addNote('No browser progress after repeated execution errors; requesting final review');
         return true;
     }
     async cleanupStartedTest(task) {

package/dist/src/ai/tools.d.ts

@@ -16,6 +16,10 @@ export declare function createCodeceptJSTools({ explorer, stateManager, ai }: To
         commands: any;
         explanation: any;
     }, Record<string, any>, import("@ai-sdk/provider-utils").Context>>;
+    clickRef: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
+        ref: any;
+        element: any;
+    }, Record<string, any>, import("@ai-sdk/provider-utils").Context>>;
     hover: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
         commands: any;
         explanation: any;
@@ -49,5 +53,15 @@ export declare function createLearnExperienceTool({ getExperienceTracker, getSta
     error: string;
 }, import("@ai-sdk/provider-utils").Context>>;
 export declare function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }: AgentToolDeps): any;
+export declare function commitNote(activeNote: any, result: TestResult, toolResult: any, action: any): Promise<void>;
+export declare function successToolResult(action: string, data?: Record<string, any>, source?: {
+    playwrightGroupId?: string | null;
+    assertionSteps?: any[];
+}): Record<string, any>;
 export declare function isMajorPageChange(pageDiff: PageDiff): boolean;
+export declare function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null): Promise<Record<string, any>>;
+export declare function withdrawVisionTools(tools: Record<string, any>): void;
+export declare function clickFailureSuggestion(attempts: Array<{
+    error?: string;
+}>): string;
 export {};

package/dist/src/ai/tools.js

@@ -2,8 +2,9 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
+import { Stats } from "../stats.js";
 import { TestResult } from '../test-plan.js';
-import { LARGE_ARIA_CHANGE_THRESHOLD, extractFocusedElement } from "../utils/aria.js";
+import { LARGE_ARIA_CHANGE_THRESHOLD } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
@@ -18,6 +19,10 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
             description: dedent `
         Click an element by trying multiple CodeceptJS commands in order until one succeeds.
 
+        Use this only for elements the page context gives you no ref for. When the element shows a ref such as [ref=e14],
+        call clickRef with that ref instead — composing a locator for an element that already has a ref is wasted work,
+        and a locator can match several elements where a ref cannot.
+
         Follow <locator_priority> from system prompt for locator selection.
 
         I.click(locator) - click element matching locator
@@ -36,14 +41,13 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 commands: z.array(z.string()).describe(dedent `
           FALLBACK LOCATORS for ONE element. All commands must click the SAME element.
           Never mix different elements — use separate click() calls instead.
+          REQUIRED: include at least one command WITHOUT a container — a wrong or stale container always fails.
           Order by reliability:
-          1. I.click(text, container) - PREFERRED when container is known - e.g. I.click("Save", ".modal")
+          1. I.click(text, container) - when the container is verified - e.g. I.click("Save", ".modal")
           2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
           5. I.clickXY(x, y) - coordinates fallback
-          IMPORTANT: Always include at least one command WITHOUT a container as fallback,
-          in case the element moved to a different section (e.g. I.click("Save") without container).
         `),
                 explanation: z.string().describe('Why you are clicking this element'),
             }),
@@ -106,14 +110,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 }
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
                 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')) {
-                    suggestion = 'Element was not found in the DOM. Use xpathCheck() to locate it, context() to refresh snapshot, or visualClick() to click by visual appearance.';
-                }
-                else if (lastError.includes('Timeout') || lastError.includes('intercept')) {
-                    suggestion = 'Element exists but could not be clicked (possibly covered by overlay or not interactable). Try closing overlapping panels first, or use visualClick().';
-                }
+                const suggestion = clickFailureSuggestion(attempts);
                 return failedToolResult('click', 'All click commands failed', {
                     ...toolResult,
                     attempts,
@@ -121,6 +118,38 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 }, action.lastError);
             },
         }),
+        clickRef: tool({
+            description: dedent `
+        Click an element by the ref the page context gave it, e.g. [ref=e14].
+
+        Prefer this over click() whenever the element you want carries a ref. A ref names one exact element, so it
+        cannot match several by mistake and never needs disambiguating — it is the fastest way to click.
+        Only pass a ref that appears in the page context you were given. Never invent or guess one.
+        If it reports the ref is gone, the page has been rebuilt: get fresh context and use the new ref.
+      `,
+            inputSchema: z.object({
+                ref: z.string().describe('The ref exactly as it appears in the page context, e.g. "e14"'),
+                element: z.string().describe('Role and name of the element you are clicking, for the record'),
+            }),
+            execute: async ({ ref, element }) => {
+                const activeNote = task.startNote(`Click ${element}`);
+                const previousState = ActionResult.fromState(stateManager.getCurrentState());
+                const action = explorer.action();
+                const named = await describeRef(explorer, ref);
+                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+                if (!(await action.attempt(run, `Click ${element}`))) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
+                        suggestion: 'The ref may belong to an older version of the page. Get fresh context and use the ref it gives, or fall back to click() with a locator.',
+                    });
+                }
+                // a ref belongs to this session only, so the run is reported as the locator a later test can replay
+                const code = named ? `I.click(${JSON.stringify(named)})` : run;
+                const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, code);
+                await commitNote(activeNote, TestResult.PASSED, toolResult, action);
+                return successToolResult('clickRef', { ...toolResult, code }, action);
+            },
+        }),
         hover: tool({
             description: dedent `
         Move the mouse cursor to an element to reveal hover-only controls.
@@ -245,15 +274,11 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     }
                     const focusFreeKeys = new Set(['Escape', 'Esc', 'Tab', 'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12']);
                     const needsFocus = !focusFreeKeys.has(keyToUse) && !modifier;
-                    if (needsFocus) {
-                        const currentAriaState = stateManager.getCurrentState()?.ariaSnapshot;
-                        const focused = extractFocusedElement(currentAriaState ?? null);
-                        if (!focused) {
-                            activeNote.commit(TestResult.FAILED);
-                            return failedToolResult('pressKey', `No element is focused. Key '${keyToUse}' requires a focused element.`, {
-                                suggestion: 'Click the target element first, then press the key.',
-                            });
-                        }
+                    if (needsFocus && !(await hasFocusedElement(explorer))) {
+                        activeNote.commit(TestResult.FAILED);
+                        return failedToolResult('pressKey', `No element is focused. Key '${keyToUse}' requires a focused element.`, {
+                            suggestion: 'Click the target element first, then press the key.',
+                        });
                     }
                     const previousState = ActionResult.fromState(stateManager.getCurrentState());
                     const action = explorer.action();
@@ -296,6 +321,8 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
         Execute raw CodeceptJS code block with multiple commands.
         USE THIS TOOL for typing text into fields: I.fillField, I.type
 
+        Do not put a click on a ref-bearing element in here — clickRef with its ref is cheaper and cannot mis-target.
+
         Follow <actions> from system prompt for available commands.
         Follow <locator_priority> from system prompt for locator selection.
 
@@ -456,25 +483,25 @@ export function createLearnExperienceTool({ getExperienceTracker, getState }) {
     });
 }
 export function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }) {
-    let visionDisabled = false;
     const tools = {
         see: tool({
             description: dedent `
-        Check the page contents based on current page state and screenshot.
-        This tool will trigger visual research to check the page contents on request.
-        Use it to verify the actions were performed correctly and the page is in the expected state.
+        Answer a question about the page from a screenshot, for things its structure cannot express:
+        layout and position, what an image or canvas depicts, colour, and whether something is covered or cut off.
+        This runs a second model and is the slowest tool here, so reach for it only when the question is genuinely visual.
+        Do NOT use it to confirm an action landed — every action already reports what changed on the page.
         Input schema has exactly one field: request. Do not pass text, reason, assertion, or other fields.
 
         <example>
-        request: "Check current state of the Login form"
-        result: "Login form is visible with username and password fields, username is filled with 'testuser' and password is empty' 
+        request: "Is the save button covered by anything, and does the chart show any plotted data?"
+        result: "The save button is partly behind a cookie banner at the bottom. The chart area is empty apart from its axes."
         </example>
       `,
             inputSchema: z.object({
                 request: z.string().describe('LLM-friendly description of the page contents to look for. 1-3 sentences. No more than 100 words.'),
             }),
             execute: async ({ request }) => {
-                if (visionDisabled) {
+                if (Stats.visionDisabled) {
                     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 {
@@ -495,8 +522,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                 catch (error) {
                     throwIfFatalBrowserError(error);
                     const errorMessage = errorText(error);
-                    visionDisabled = true;
-                    tag('warning').log('⚠️ Vision model is not available. Visual checks are disabled for this session.');
+                    disableVision();
                     return failedToolResult('see', `See tool failed: ${errorMessage}`, {
                         suggestion: 'Vision is now disabled. Use context() to get fresh ARIA snapshot and analyze page state from ARIA data.',
                     });
@@ -576,6 +602,12 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                             code: result.successfulCodes.join('\n'),
                         }, { assertionSteps: result.assertionSteps });
                     }
+                    if (result.inexpressible) {
+                        return failedToolResult('verify', `No assertion could express this claim: ${assertion}`, {
+                            inexpressible: true,
+                            suggestion: 'This is not evidence the page is wrong — the claim could not be turned into an assertion. Restate it in terms of what is visible or of a control state, or check it with see().',
+                        });
+                    }
                     return failedToolResult('verify', `Verification failed: ${assertion}`, {
                         suggestion: 'The assertion could not be verified. Check if the condition is actually present on the page or try a different assertion.',
                     });
@@ -696,7 +728,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                 context: z.string().describe('What you already tried and why it failed - helps with accurate identification'),
             }),
             execute: async ({ element, context }) => {
-                if (visionDisabled) {
+                if (Stats.visionDisabled) {
                     return failedToolResult('visualClick', 'Vision tools are disabled for this session. Use xpathCheck() to find the element, then click() with the discovered locator.');
                 }
                 try {
@@ -741,8 +773,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                 catch (error) {
                     throwIfFatalBrowserError(error);
                     const errorMessage = errorText(error);
-                    visionDisabled = true;
-                    tag('warning').log('⚠️ Vision model is not available. Visual clicks are disabled for this session.');
+                    disableVision();
                     return failedToolResult('visualClick', `visualClick tool failed: ${errorMessage}`, {
                         suggestion: 'Vision is now disabled. Use xpathCheck() to find the element, then click() with the discovered locator.',
                     });
@@ -875,6 +906,11 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
             },
         }),
     };
+    const disableVision = () => {
+        Stats.visionDisabled = true;
+        withdrawVisionTools(tools);
+        tag('warning').log('⚠️ Vision model is not available. Visual tools are disabled for this session.');
+    };
     if (withExperience !== false) {
         tools.learnExperience = createLearnExperienceTool({
             getExperienceTracker: () => stateManager.getExperienceTracker(),
@@ -921,6 +957,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
             },
         });
     }
+    withdrawVisionTools(tools);
     return tools;
 }
 const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';
@@ -964,13 +1001,27 @@ function errorText(error) {
         return error.toString();
     return 'Unknown error occurred';
 }
-async function commitNote(activeNote, result, toolResult, action) {
+export 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) {
+async function describeRef(explorer, ref) {
+    return Promise.resolve(explorer?.withPage?.((page) => page.locator(`aria-ref=${ref}`).evaluate((el) => {
+        const tag = el.tagName.toLowerCase();
+        const roles = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
+        const role = el.getAttribute('role') || roles[tag] || tag;
+        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
+        if (!text)
+            return null;
+        return { role, text };
+    }))).catch(() => null);
+}
+async function hasFocusedElement(explorer) {
+    return explorer.withPage((page) => page.evaluate(() => !!document.activeElement && document.activeElement !== document.body)).catch(() => true);
+}
+export function successToolResult(action, data, source) {
     const result = { success: true, action, ...data };
     if (source?.playwrightGroupId) {
         result.playwrightGroupId = source.playwrightGroupId;
@@ -1008,7 +1059,7 @@ function hasObservablePageChange(data) {
         return true;
     return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
-async function failedToolResult(action, message, data, error) {
+export async function failedToolResult(action, message, data, error) {
     const result = { success: false, action, message, ...data };
     if (data?.pageDiff) {
         result.suggestion = data.suggestion ? `${data.suggestion} ${PAGE_DIFF_SUGGESTION}` : PAGE_DIFF_SUGGESTION;
@@ -1040,6 +1091,32 @@ function getMultipleElementsSuggestion() {
     6. Use visualClick() to click the right element by visual appearance
   `;
 }
+export function withdrawVisionTools(tools) {
+    if (!Stats.visionDisabled)
+        return;
+    Reflect.deleteProperty(tools, 'see');
+    Reflect.deleteProperty(tools, 'visualClick');
+}
+export function clickFailureSuggestion(attempts) {
+    const errors = attempts.map((a) => a.error || '');
+    if (errors.some((e) => e.includes('not enabled'))) {
+        return 'Element exists but is DISABLED — clicking it again cannot work. A precondition is unmet: a required field is empty, nothing is selected, or a dialog is blocking. Satisfy it, then retry.';
+    }
+    if (errors.some((e) => e.includes('intercepts pointer events'))) {
+        return 'Element exists but another element covers it. Close the overlapping panel or dialog, then retry.';
+    }
+    if (errors.some((e) => e.includes('is not visible'))) {
+        return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
+    }
+    const notFound = errors.filter((e) => e.includes('was not found'));
+    if (notFound.length && notFound.every((e) => e.includes('was not found inside element'))) {
+        return 'Element was not found inside that container — the container is wrong or stale, and the element may exist elsewhere on the page. Retry the same locator WITHOUT a container, or verify the container with xpathCheck().';
+    }
+    if (notFound.length) {
+        return 'Element was not found in the DOM. Use xpathCheck() to locate it, context() to refresh snapshot, or visualClick() to click by visual appearance.';
+    }
+    return "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
+}
 const MAX_DISAMBIGUATE_ELEMENTS = 10;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
 async function extractWebElements(error) {

package/dist/src/config.d.ts

@@ -172,6 +172,7 @@ interface HtmlConfig {
 interface ActionConfig {
     delay?: number;
     retries?: number;
+    timeout?: number;
 }
 interface ReporterConfig {
     enabled?: boolean;