explorbot 0.2.2 → 0.2.4

package/dist/src/ai/navigator.js

@@ -3,12 +3,13 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.js';
 import { normalizeUrl } from '../state-manager.js';
+import { renderAssertion } from "../playwright-recorder.js";
 import { extractCodeBlocks } from '../utils/code-extractor.js';
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
 import { RulesLoader } from "../utils/rules-loader.js";
-import { extractStatePath } from '../utils/url-matcher.js';
+import { extractStatePath, matchesNavigationUrl } from '../utils/url-matcher.js';
 import { Researcher } from "./researcher.js";
 import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
@@ -118,7 +119,7 @@ class Navigator {
             return false;
         }
         const currentUrl = this.getComparableCurrentUrl(stateManager, expectedUrl);
-        return normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
+        return matchesNavigationUrl(expectedUrl, currentUrl);
     }
     async visit(url) {
         return this.visitOnce(url);
@@ -167,11 +168,13 @@ class Navigator {
         }
     }
     async resolveState(message, actionResult, opts) {
+        if (!this.provider)
+            throw new Error('AI-assisted recovery is unavailable: no AI model is configured.');
         tag('info').log('AI Navigator resolving state at', actionResult.url);
         debugLog('Resolution message:', message);
         const action = opts?.action ?? this.explorer.action();
         const expectedUrl = opts?.expectedUrl;
-        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
+        const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
         let experience = '';
         if (!actionResult.isInsideIframe) {
             const successful = this.experienceTracker.getSuccessfulExperience(actionResult);
@@ -328,16 +331,19 @@ class Navigator {
                     // Navigation did not reach 'load' state within timeout; continue and verify URL
                 }
             }
+            if (attemptOk)
+                opts?.onAttempt?.({ code: codeBlock });
             if (!attemptOk) {
                 const raw = action.lastError?.message || 'attempt failed';
                 const firstMeaningful = raw.split('\n').find((l) => l.trim() && !l.trim().startsWith('at ')) || raw;
                 const shortErr = firstMeaningful.replace(/\s+/g, ' ').trim().slice(0, 220);
                 batchFailures.push({ code: codeBlock, error: shortErr });
+                opts?.onAttempt?.({ code: codeBlock, error: shortErr });
             }
             if (expectedUrl) {
                 if (page) {
                     try {
-                        await page.waitForURL((url) => normalizeUrl(url.pathname) === normalizeUrl(expectedUrl), { timeout: 5000 });
+                        await page.waitForURL((url) => matchesNavigationUrl(expectedUrl, `${url.pathname}${url.search}${url.hash}`), { timeout: 5000 });
                     }
                     catch {
                         // URL did not transition to expectedUrl within timeout
@@ -345,7 +351,7 @@ class Navigator {
                 }
                 const freshState = await this.explorer.capture();
                 const currentUrl = /^https?:\/\//i.test(expectedUrl) ? freshState.fullUrl || freshState.url || '' : freshState.url || '';
-                const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
+                const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && matchesNavigationUrl(expectedUrl, currentUrl);
                 const stateChanged = freshState.getStateHash() !== actionResult.getStateHash();
                 resolved = urlMatches && stateChanged;
                 if (!resolved && attemptOk) {
@@ -562,7 +568,7 @@ class Navigator {
             tag('operation').log(`Reusing cached verification: ${cachedVerification ? 'PASS' : 'FAIL'}`);
             return { verified: cachedVerification, successfulCodes: [], assertionSteps: [], totalAttempted: 0 };
         }
-        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
+        const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
         let experience = '';
         if (!actionResult.isInsideIframe) {
             experience = this.experienceTracker.renderExperienceTocFor(actionResult);
@@ -623,6 +629,7 @@ class Navigator {
         const tools = this.buildExperienceTools();
         let codeBlocks = [];
         const successfulCodes = [];
+        const results = [];
         const assertionSteps = [];
         const action = this.explorer.action();
         let failures = 0;
@@ -655,6 +662,8 @@ class Navigator {
                 }
                 await action.exitIframe();
                 const verified = await action.attempt(codeBlock, message);
+                const proof = action.assertionSteps.map(renderAssertion).filter(Boolean);
+                results.push({ code: codeBlock, passed: verified, proof });
                 if (verified) {
                     tag('success').log('Verification passed');
                     successfulCodes.push(codeBlock);
@@ -663,11 +672,6 @@ class Navigator {
                 else {
                     failures++;
                 }
-                const target = Math.min(codeBlocks.length, this.verifyAttempts);
-                const majorityNeeded = Math.floor(target / 2) + 1;
-                if (successfulCodes.length >= majorityNeeded || failures > target - majorityNeeded) {
-                    stop();
-                }
             }, {
                 maxAttempts: this.verifyAttempts,
                 observability: {
@@ -686,9 +690,14 @@ class Navigator {
         let verified = successfulCodes.length >= majorityNeeded;
         if (alreadyVerified)
             verified = true;
+        const inexpressible = !alreadyVerified && totalAttempted === 0;
+        if (inexpressible) {
+            tag('warning').log('No assertion could express this claim');
+            return { verified: false, inexpressible, results, successfulCodes, assertionSteps, totalAttempted };
+        }
         actionResult.addVerification(message, verified);
         this.stateManager.updateState(actionResult);
-        return { verified, successfulCodes, assertionSteps, totalAttempted };
+        return { verified, inexpressible, results, successfulCodes, assertionSteps, totalAttempted };
     }
     checkAlreadyVerified(aiResponse, actionResult) {
         const verifiedMatch = aiResponse.match(/ALREADY_VERIFIED:\s*(.+)/i);

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

@@ -40,6 +40,10 @@ export declare class Pilot implements Agent {
     planTest(task: Test, currentState: ActionResult): Promise<string>;
     reviewNewPage(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     analyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
+    settleExpectations(task: Test): Promise<Array<{
+        text: string;
+        status: 'passed' | 'failed' | 'unverified';
+    }>>;
     formatExpectations(task: Test): string;
     sendToPilot(userText: string, functionId: string, opts: {
         tools?: boolean;

package/dist/src/ai/pilot.js

@@ -4,13 +4,14 @@ import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { ConfigParser } from "../config.js";
 import { TestResult } from "../test-plan.js";
-import { collectInteractiveNodes, detectFocusArea, extractFocusedElement } from "../utils/aria.js";
+import { collectInteractiveNodes, detectFocusArea } from "../utils/aria.js";
 import { ErrorPageError } from "../utils/error-page.js";
 import { createDebug, tag } from "../utils/logger.js";
 const debugLog = createDebug('explorbot:pilot');
 import { truncateJson } from "../utils/strings.js";
 import { capabilityGroundingRule, dataProtectionRules } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
+import { withdrawVisionTools } from "./tools.js";
 const CHECK_TOOLS = ['verify', 'see', 'research', 'context'];
 const META_TOOLS = ['record', 'reset', 'stop', 'finish'];
 export class Pilot {
@@ -484,6 +485,50 @@ export class Pilot {
         }
         return text;
     }
+    async settleExpectations(task) {
+        const undecided = task.expected.filter((text) => !task.getCheckedExpectations().includes(text));
+        const decided = (text) => {
+            if (task.hasAchievedAny() && !task.getRemainingExpectations().includes(text))
+                return 'passed';
+            return 'failed';
+        };
+        if (!undecided.length)
+            return task.expected.map((text) => ({ text, status: decided(text) }));
+        const schema = z.object({
+            outcomes: z.array(z.object({
+                expectation: z.string().describe('The expected outcome, repeated exactly as it was given'),
+                status: z.enum(['passed', 'failed', 'unverified']).describe('passed = the log shows it happened, failed = the log shows it did not, unverified = the run never established either way'),
+            })),
+        });
+        const userContent = dedent `
+      A test run has finished. Decide, for each expected outcome, what the run established about it.
+
+      <expected_outcomes>
+      ${undecided.map((text) => `- ${text}`).join('\n')}
+      </expected_outcomes>
+
+      <run_log>
+      ${task.notesToString() || 'No steps recorded.'}
+      </run_log>
+
+      The log is written in the tester's own words, so an outcome can be satisfied by a step that describes it
+      differently. Judge by what the steps show happened, not by whether the wording matches.
+      Choose "unverified" only when the log neither shows the outcome happening nor shows it failing —
+      that is a statement about the run, not about the application.
+    `;
+        const response = await this.provider
+            .generateObject([{ role: 'user', content: userContent }], schema, this.provider.getAgenticModel('pilot'), {
+            agentName: 'pilot',
+            telemetry: { functionId: 'pilot.settleExpectations' },
+        })
+            .catch(() => null);
+        const judged = new Map((response?.object?.outcomes || []).map((outcome) => [outcome.expectation, outcome.status]));
+        return task.expected.map((text) => {
+            if (!undecided.includes(text))
+                return { text, status: decided(text) };
+            return { text, status: judged.get(text) || 'unverified' };
+        });
+    }
     formatExpectations(task) {
         const checked = task.getCheckedExpectations();
         const remaining = task.getRemainingExpectations();
@@ -547,6 +592,7 @@ export class Pilot {
             planning.learnExperience = learnExperience;
         if (askUser)
             planning.askUser = askUser;
+        withdrawVisionTools(planning);
         return planning;
     }
     buildPreconditionTool(task) {
@@ -624,7 +670,7 @@ export class Pilot {
         const lines = [];
         lines.push(`url: ${state.url}`);
         lines.push(`title: ${state.title || 'unknown'}`);
-        const focused = extractFocusedElement(state.ariaSnapshot);
+        const focused = state.focusedElement;
         if (focused) {
             const valuePart = focused.value ? ` (value: "${focused.value}")` : '';
             lines.push(`focused: ${focused.role} "${focused.name}"${valuePart}`);

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

@@ -50,6 +50,7 @@ export declare class Planner extends PlannerBase implements Agent {
     provider: Provider;
     stateManager: StateManager;
     experienceTracker: ExperienceTracker;
+    knowledgeTracker: AgentDeps['knowledgeTracker'];
     MIN_TASKS: number;
     MAX_TASKS: number;
     currentPlan: Plan | null;

package/dist/src/ai/planner.js

@@ -41,6 +41,7 @@ export class Planner extends PlannerBase {
     provider;
     stateManager;
     experienceTracker;
+    knowledgeTracker;
     MIN_TASKS = 3;
     MAX_TASKS = 12;
     currentPlan = null;
@@ -56,6 +57,7 @@ export class Planner extends PlannerBase {
         this.researcher = researcher;
         this.stateManager = deps.stateManager;
         this.experienceTracker = deps.stateManager.getExperienceTracker();
+        this.knowledgeTracker = deps.knowledgeTracker;
     }
     setFisherman(fisherman) {
         this.fisherman = fisherman;
@@ -368,6 +370,10 @@ export class Planner extends PlannerBase {
       ${plannerResearch}
       </page_research>
     `);
+        const applicationContext = this.knowledgeTracker.renderApplicationSpec(state);
+        if (applicationContext) {
+            conversation.addUserText(applicationContext);
+        }
         conversation.addUserText(dedent `
       ${this.buildApproach(style)}
 

package/dist/src/ai/provider.js

@@ -290,6 +290,7 @@ export class Provider {
         try {
             const response = await withRetry(async () => {
                 const result = await generateText({ messages, ...config });
+                this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
                 if (!result.text) {
                     debugLog(result);
                     if (result.finishReason === 'length') {
@@ -304,7 +305,6 @@ export class Provider {
             }, this.getRetryOptions(options));
             clearActivity();
             responseLog(response.text);
-            this.recordUsage(options.agentName || 'unknown', modelName, response.usage);
             return response;
         }
         catch (error) {
@@ -340,6 +340,7 @@ export class Provider {
         try {
             const response = await withRetry(async () => {
                 const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000));
+                this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
                 const hasToolCall = (result.toolCalls?.length || 0) > 0;
                 if (!result.text && !hasToolCall && result.finishReason === 'length') {
                     throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
@@ -355,7 +356,6 @@ export class Provider {
                 });
             }
             responseLog(response.text);
-            this.recordUsage(options.agentName || 'unknown', modelName, response.usage);
             return response;
         }
         catch (error) {

package/dist/src/ai/rerunner.js

@@ -21,7 +21,7 @@ import { RulesLoader } from "../utils/rules-loader.js";
 import { toolExecutionLabel } from "./conversation.js";
 import { actionRule, locatorRule, sectionContextRule } from "./rules.js";
 import { TaskAgent } from "./task-agent.js";
-import { createCodeceptJSTools } from "./tools.js";
+import { createCodeceptJSTools, withdrawVisionTools } from "./tools.js";
 const debugLog = createDebug('explorbot:rerunner');
 export class Rerunner extends TaskAgent {
     ACTION_TOOLS = ['click', 'pressKey', 'form'];
@@ -322,6 +322,7 @@ export class Rerunner extends TaskAgent {
                     },
                 }),
             };
+            withdrawVisionTools(tools);
             const conversation = this.provider.startConversation(this.getHealSystemPrompt(), 'rerunner');
             conversation.addUserText(this.getHealUserPrompt(failedCode, error));
             await loop(async ({ stop }) => {

package/dist/src/ai/researcher.js

@@ -76,7 +76,7 @@ export class Researcher extends ResearcherBase {
             const cached = getCachedResearch(stateHash);
             if (cached) {
                 debugLog('Previous research result found');
-                return `!! UI MAP IS CACHED AND MAY NOT REPRESENT CURRENT STATE; REFRESH RESEARCH IF YOU NOTICE ISSUES !!\n\n${cached}`;
+                return cached;
             }
         }
         Stats.researches++;
@@ -379,7 +379,7 @@ export class Researcher extends ResearcherBase {
         if (!this.actionResult)
             throw new Error('actionResult is not set');
         const html = await this.actionResult.combinedHtml();
-        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(this.actionResult);
+        const knowledge = this.knowledgeTracker.renderRelevantContext(this.actionResult);
         const ariaSnapshot = this.actionResult.getCompactARIA();
         return dedent `
       Analyze this web page and provide a comprehensive research report in markdown format.

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({}, {
@@ -49,7 +52,7 @@ export class TaskAgent {
         return this.provider;
     }
     getKnowledge(actionResult) {
-        return this.getKnowledgeTracker().renderRelevantKnowledge(actionResult);
+        return this.getKnowledgeTracker().renderRelevantContext(actionResult);
     }
     getExperience(actionResult) {
         return this.getExperienceTracker().renderExperienceTocFor(actionResult);

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

@@ -49,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 = {
@@ -93,7 +93,7 @@ export class Tester extends TaskAgent {
         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)) {
@@ -206,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');
@@ -351,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);
@@ -405,8 +407,7 @@ export class Tester extends TaskAgent {
         this.stalledIterations++;
         if (this.stalledIterations < this.MAX_STALLED_ITERATIONS)
             return false;
-        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) {
@@ -424,7 +425,8 @@ export class Tester extends TaskAgent {
       </rules>
     `;
         if (task.getPrintableNotes()) {
-            outcomeStatus = dedent `
+            outcomeStatus += dedent `
+
         Your current log:
         <notes>
         ${task.notesToString()}
@@ -445,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 `
@@ -526,7 +528,7 @@ export class Tester extends TaskAgent {
         </page>
 
         <page_aria>
-        ${currentState.getInteractiveARIA()}
+        ${await this.interactiveAriaWithRefs(currentState)}
         </page_aria>
         ${uiMapSection}
 
@@ -561,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);
@@ -721,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.
@@ -955,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" })
         `,
@@ -1032,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 {};