explorbot 0.2.2 → 0.2.4

package/src/action-result.ts

@@ -30,6 +30,7 @@ interface ActionResultData extends WebPageState {
   iframeSnapshots?: Array<{ src: string; html: string; id?: string }>;
   ariaSnapshot?: string | null;
   ariaSnapshotFile?: string;
+  focusedElement?: FocusedElement | null;
   iframeURL?: string;
   links?: Link[];
 }
@@ -74,6 +75,7 @@ export class ActionResult implements ActionResultData {
   private snapshotCache = new TTLCache<string>();
   readonly logFile: string | undefined = undefined;
   readonly ariaSnapshotFile: string | undefined = undefined;
+  readonly focusedElement: FocusedElement | null = null;
   private _ariaSnapshot: string | null | undefined = undefined;
   private _lastExtractedHtml: string | undefined = undefined;
   notes: string[] = [];
@@ -107,6 +109,9 @@ export class ActionResult implements ActionResultData {
     if (data.ariaSnapshotFile !== undefined) {
       this.ariaSnapshotFile = data.ariaSnapshotFile;
     }
+    if (data.focusedElement !== undefined) {
+      this.focusedElement = data.focusedElement;
+    }
 
     // Store HTML in a private property if provided
     if (data.html !== undefined) {
@@ -643,3 +648,9 @@ export class Diff {
     this._ariaChangeCount = ariaDiff.count;
   }
 }
+
+export interface FocusedElement {
+  role: string;
+  name: string;
+  value?: string;
+}

package/src/action.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { context, trace } from '@opentelemetry/api';
 import { container, recorder } from 'codeceptjs';
 import * as codeceptjs from 'codeceptjs';
-import { ActionResult } from './action-result.js';
+import { ActionResult, type FocusedElement } from './action-result.js';
 import { clearActivity, setActivity } from './activity.ts';
 import { ConfigParser, outputPath } from './config.js';
 import type { ExplorbotConfig } from './config.js';
@@ -19,6 +19,8 @@ import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCo
 
 const debugLog = createDebug('explorbot:action');
 const CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS = 3;
+const DEFAULT_ACTION_TIMEOUT = 3000;
+const DEFAULT_PAGE_TIMEOUT = 3000;
 
 class Action {
   private actor: CodeceptJS.I;
@@ -32,6 +34,7 @@ class Action {
   public playwrightHelper: any;
   public playwrightGroupId: string | null = null;
   public assertionSteps: Array<{ name: string; args: any[] }> = [];
+  public lastValue: unknown;
   private recorder?: PlaywrightRecorder;
   private recovery: RecoveryRunner;
   private mainDocumentStatus: number | undefined = undefined;
@@ -65,8 +68,8 @@ class Action {
     return this.recovery(() => this.captureOnce(opts));
   }
 
-  async execute(code: string): Promise<Action> {
-    return this.recovery(() => this.executeOnce(code));
+  async execute(code: string, opts: ExecuteOptions = {}): Promise<Action> {
+    return this.recovery(() => this.executeOnce(code, opts.verbatim));
   }
 
   private async captureOnce({ includeScreenshot = false, codeBlock }: { includeScreenshot?: boolean; codeBlock?: string } = {}): Promise<ActionResult> {
@@ -133,10 +136,12 @@ class Action {
 
       let ariaSnapshot: string | null = null;
       let ariaSnapshotFile: string | undefined = undefined;
+      let focusedElement: FocusedElement | null = null;
 
       try {
         const page = this.playwrightHelper.page;
         ariaSnapshot = await page.locator('body').ariaSnapshot();
+        focusedElement = await page.evaluate(readFocusedElement);
       } catch (err) {
         debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
       }
@@ -160,6 +165,7 @@ class Action {
         iframeSnapshots,
         ariaSnapshot,
         ariaSnapshotFile,
+        focusedElement,
         iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
       });
       this.stateManager.updateState(result, codeBlock);
@@ -270,7 +276,7 @@ class Action {
     }
   }
 
-  private async executeOnce(code: string): Promise<Action> {
+  private async executeOnce(code: string, verbatim = false): Promise<Action> {
     let error: Error | null = null;
 
     setActivity('🔎 Browsing...', 'action');
@@ -287,8 +293,8 @@ class Action {
     const tracer = trace.getTracer('ai');
     const stepSpan = activeSpan ? tracer.startSpan('codeceptjs.step', undefined, trace.setSpan(context.active(), activeSpan)) : null;
     setStepSpanParent(stepSpan);
-    const sanitizedCode = sanitizeCodeBlock(codeString);
-    const isPlaywright = hasPlaywrightCommands(sanitizedCode);
+    const sanitizedCode = verbatim ? codeString : sanitizeCodeBlock(codeString);
+    const isPlaywright = !verbatim && hasPlaywrightCommands(sanitizedCode);
 
     try {
       debugLog('Executing action:', codeString);
@@ -297,16 +303,21 @@ class Action {
         throw new Error('No valid I.* or page.* commands found in code block');
       }
 
+      this.playwrightHelper?.page?.setDefaultTimeout(this.config.action?.timeout ?? DEFAULT_ACTION_TIMEOUT);
+
       if (isPlaywright) {
         const page = this.playwrightHelper.page;
         await playwrightSandbox(page, sanitizedCode);
         await sleep(this.config.action?.delay || 500);
       } else {
-        codeceptJSSandbox(this.actor, sanitizedCode);
+        const returned = codeceptJSSandbox(this.actor, sanitizedCode);
         await recorder.add(() => sleep(this.config.action?.delay || 500));
         await recorder.promise();
+        this.lastValue = await returned;
       }
 
+      this.restorePageTimeout();
+
       if (executedSteps.length > 0) {
         codeString = executedSteps.join('\n');
       }
@@ -325,6 +336,7 @@ class Action {
       this.assertionSteps = [];
       throw err;
     } finally {
+      this.restorePageTimeout();
       detachMainDocumentResponse();
       if (groupId) await this.recorder!.endAction();
       detachStepLogger(stepListener);
@@ -374,6 +386,10 @@ class Action {
     return this.actionResult;
   }
 
+  private restorePageTimeout(): void {
+    this.playwrightHelper?.page?.setDefaultTimeout(this.config.playwright.timeout ?? DEFAULT_PAGE_TIMEOUT);
+  }
+
   private async waitForPageReadiness(page: any): Promise<void> {
     await waitForPageReadiness(page, {
       timeout: this.config.playwright.waitForTimeout,
@@ -386,6 +402,10 @@ export default Action;
 
 export type RecoveryRunner = <T>(fn: () => Promise<T>) => Promise<T>;
 
+export interface ExecuteOptions {
+  verbatim?: boolean;
+}
+
 function errorToString(error: any): string {
   if (error.cliMessage) {
     return error.cliMessage();
@@ -438,3 +458,23 @@ const detachStepLogger = (listener: StepListener) => {
   codeceptjs.event.dispatcher.off(codeceptjs.event.step.passed, listener);
   codeceptjs.event.dispatcher.off(codeceptjs.event.step.failed, listener);
 };
+
+const readFocusedElement = () => {
+  const el = document.activeElement as any;
+  if (!el || el === document.body) return null;
+
+  const tag = el.tagName.toLowerCase();
+  const textish = new Set(['text', 'search', 'email', 'password', 'url', 'tel', 'number']);
+  let role = el.getAttribute('role') || tag;
+  if (tag === 'textarea' || el.isContentEditable) role = 'textbox';
+  if (tag === 'input' && textish.has(el.type)) role = 'textbox';
+  if (tag === 'select') role = 'combobox';
+  if (tag === 'a') role = 'link';
+
+  const label = el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.labels?.[0]?.textContent || el.textContent || '';
+  const focused: { role: string; name: string; value?: string } = { role, name: label.trim().slice(0, 80) };
+
+  const value = el.value ?? el.textContent;
+  if (typeof value === 'string' && value) focused.value = value.slice(0, 200);
+  return focused;
+};

package/src/ai/captain/mixin.ts

@@ -16,7 +16,7 @@ export interface ModeContext {
 }
 
 export function resolveProjectRoot(): string | null {
-  const configPath = ConfigParser.getInstance().getConfigPath();
-  if (!configPath) return null;
-  return dirname(configPath);
+  const configParser = ConfigParser.getInstance();
+  if (!configParser.getConfigPath()) return null;
+  return configParser.getProjectRoot();
 }

package/src/ai/captain/web-mode.ts

@@ -18,7 +18,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
       });
       const { see, context, visualClick, learnExperience } = agentTools;
 
-      return {
+      const tools: Record<string, any> = {
         navigate: tool({
           description: 'Navigate to a URL or page description using AI-powered navigation.',
           inputSchema: z.object({
@@ -27,7 +27,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
           execute: async ({ destination }) => {
             try {
               debugLog('navigate', destination);
-              await ctx.explorBot.agentNavigator().visit(destination);
+              await ctx.explorBot.visit(destination);
               const stateManager = ctx.explorBot.stateManager();
               const state = stateManager.getCurrentState();
               return { success: true, url: state?.url, title: state?.title };
@@ -123,11 +123,14 @@ export function WithWebMode<T extends Constructor>(Base: T) {
         }),
 
         ...codeceptTools,
-        see,
         context,
-        visualClick,
         learnExperience,
       };
+
+      if (see) tools.see = see;
+      if (visualClick) tools.visualClick = visualClick;
+
+      return tools;
     }
 
     webModePrompt(): string {

package/src/ai/captain.ts

@@ -21,6 +21,7 @@ import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { TaskAgent } from './task-agent.ts';
+import { withdrawVisionTools } from './tools.ts';
 
 const MAX_STEPS = 15;
 
@@ -437,6 +438,8 @@ export class Captain extends CaptainBase implements Agent {
           return;
         }
 
+        withdrawVisionTools(tools);
+
         const currentState = stateManager.getCurrentState();
         if (!currentState && this.getMode() !== 'idle') {
           stop();

package/src/ai/navigator.ts

@@ -8,12 +8,13 @@ import type { ExperienceTracker } from '../experience-tracker.js';
 import Explorer from '../explorer.ts';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import { type StateManager, normalizeUrl } from '../state-manager.js';
+import { renderAssertion } from '../playwright-recorder.ts';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
-import { extractStatePath } from '../utils/url-matcher.js';
+import { extractStatePath, matchesNavigationUrl } from '../utils/url-matcher.js';
 import type { Agent, AgentDeps } from './agent.js';
 import type { Conversation } from './conversation.js';
 import type { Provider } from './provider.js';
@@ -134,7 +135,7 @@ class Navigator implements Agent {
       return false;
     }
     const currentUrl = this.getComparableCurrentUrl(stateManager, expectedUrl);
-    return normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
+    return matchesNavigationUrl(expectedUrl, currentUrl);
   }
 
   async visit(url: string): Promise<void> {
@@ -189,14 +190,16 @@ class Navigator implements Agent {
     }
   }
 
-  async resolveState(message: string, actionResult: ActionResult, opts?: { action?: Action; expectedUrl?: string }): Promise<boolean> {
+  async resolveState(message: string, actionResult: ActionResult, opts?: { action?: Action; expectedUrl?: string; onAttempt?: (attempt: { code: string; error?: string }) => void }): Promise<boolean> {
+    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) {
@@ -363,24 +366,27 @@ class Navigator implements Agent {
           }
         }
 
+        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: URL) => normalizeUrl(url.pathname) === normalizeUrl(expectedUrl), { timeout: 5000 });
+              await page.waitForURL((url: URL) => matchesNavigationUrl(expectedUrl, `${url.pathname}${url.search}${url.hash}`), { timeout: 5000 });
             } catch {
               // URL did not transition to expectedUrl within timeout
             }
           }
           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;
 
@@ -615,7 +621,7 @@ class Navigator implements Agent {
     return suggestion;
   }
 
-  async verifyState(message: string, actionResult: ActionResult): Promise<{ verified: boolean; successfulCodes: string[]; assertionSteps: Array<{ name: string; args: any[] }>; totalAttempted: number }> {
+  async verifyState(message: string, actionResult: ActionResult): Promise<{ verified: boolean; inexpressible: boolean; results: AssertionResult[]; successfulCodes: string[]; assertionSteps: Array<{ name: string; args: any[] }>; totalAttempted: number }> {
     tag('info').log('AI Navigator verifying state at', actionResult.url);
     debugLog('Verification message:', message);
 
@@ -625,7 +631,7 @@ class Navigator implements Agent {
       return { verified: cachedVerification, successfulCodes: [], assertionSteps: [], totalAttempted: 0 };
     }
 
-    const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
+    const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
     let experience = '';
 
     if (!actionResult.isInsideIframe) {
@@ -693,6 +699,7 @@ class Navigator implements Agent {
 
     let codeBlocks: string[] = [];
     const successfulCodes: string[] = [];
+    const results: AssertionResult[] = [];
     const assertionSteps: Array<{ name: string; args: any[] }> = [];
 
     const action = this.explorer.action();
@@ -734,6 +741,8 @@ class Navigator implements Agent {
           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');
@@ -742,12 +751,6 @@ class Navigator implements Agent {
           } 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,
@@ -768,10 +771,16 @@ class Navigator implements Agent {
     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 };
   }
 
   private checkAlreadyVerified(aiResponse: string, actionResult: ActionResult): boolean {
@@ -782,4 +791,6 @@ class Navigator implements Agent {
   }
 }
 
+export type AssertionResult = { code: string; passed: boolean; proof: string[] };
+
 export { Navigator };

package/src/ai/pilot.ts

@@ -8,7 +8,7 @@ import type Explorer from '../explorer.ts';
 import type { PlaywrightRecorder } from '../playwright-recorder.ts';
 import type { StateManager } from '../state-manager.ts';
 import { type Test, TestResult } from '../test-plan.ts';
-import { collectInteractiveNodes, detectFocusArea, extractFocusedElement } from '../utils/aria.ts';
+import { collectInteractiveNodes, detectFocusArea } from '../utils/aria.ts';
 import { ErrorPageError } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 
@@ -22,6 +22,7 @@ import type { Provider } from './provider.ts';
 import type { Researcher } from './researcher.ts';
 import { capabilityGroundingRule, dataProtectionRules } from './rules.ts';
 import { isInteractive } from './task-agent.ts';
+import { withdrawVisionTools } from './tools.ts';
 
 const CHECK_TOOLS = ['verify', 'see', 'research', 'context'];
 const META_TOOLS = ['record', 'reset', 'stop', 'finish'];
@@ -561,6 +562,55 @@ export class Pilot implements Agent {
     return text;
   }
 
+  async settleExpectations(task: Test): Promise<Array<{ text: string; status: 'passed' | 'failed' | 'unverified' }>> {
+    const undecided = task.expected.filter((text) => !task.getCheckedExpectations().includes(text));
+    const decided = (text: string): 'passed' | 'failed' => {
+      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' as const, content: userContent }], schema, this.provider.getAgenticModel('pilot'), {
+        agentName: 'pilot',
+        telemetry: { functionId: 'pilot.settleExpectations' },
+      })
+      .catch(() => null);
+
+    const judged = new Map((response?.object?.outcomes || []).map((outcome: any) => [outcome.expectation, outcome.status]));
+    return task.expected.map((text) => {
+      if (!undecided.includes(text)) return { text, status: decided(text) };
+      return { text, status: (judged.get(text) as 'passed' | 'failed' | 'unverified') || 'unverified' };
+    });
+  }
+
   private formatExpectations(task: Test): string {
     const checked = task.getCheckedExpectations();
     const remaining = task.getRemainingExpectations();
@@ -620,6 +670,7 @@ export class Pilot implements Agent {
     if (xpathCheck) planning.xpathCheck = xpathCheck;
     if (learnExperience) planning.learnExperience = learnExperience;
     if (askUser) planning.askUser = askUser;
+    withdrawVisionTools(planning);
     return planning;
   }
 
@@ -703,7 +754,7 @@ export class Pilot implements Agent {
     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/src/ai/planner.ts

@@ -53,6 +53,7 @@ export class Planner extends PlannerBase implements Agent {
   provider: Provider;
   stateManager: StateManager;
   private experienceTracker: ExperienceTracker;
+  private knowledgeTracker: AgentDeps['knowledgeTracker'];
 
   MIN_TASKS = 3;
   MAX_TASKS = 12;
@@ -70,6 +71,7 @@ export class Planner extends PlannerBase implements Agent {
     this.researcher = researcher;
     this.stateManager = deps.stateManager;
     this.experienceTracker = deps.stateManager.getExperienceTracker();
+    this.knowledgeTracker = deps.knowledgeTracker;
   }
 
   setFisherman(fisherman: Fisherman): void {
@@ -411,6 +413,11 @@ export class Planner extends PlannerBase implements Agent {
       </page_research>
     `);
 
+    const applicationContext = this.knowledgeTracker.renderApplicationSpec(state);
+    if (applicationContext) {
+      conversation.addUserText(applicationContext);
+    }
+
     conversation.addUserText(dedent`
       ${this.buildApproach(style)}
 

package/src/ai/provider.ts

@@ -326,6 +326,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') {
@@ -342,8 +343,6 @@ export class Provider {
       clearActivity();
       responseLog(response.text);
 
-      this.recordUsage(options.agentName || 'unknown', modelName, response.usage);
-
       return response;
     } catch (error: any) {
       clearActivity();
@@ -378,6 +377,7 @@ export class Provider {
     try {
       const response = await withRetry(async () => {
         const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
+        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.');
@@ -397,8 +397,6 @@ export class Provider {
 
       responseLog(response.text);
 
-      this.recordUsage(options.agentName || 'unknown', modelName, response.usage);
-
       return response;
     } catch (error: any) {
       clearActivity();

package/src/ai/rerunner.ts

@@ -24,7 +24,7 @@ import type { Navigator } from './navigator.ts';
 import { Provider } from './provider.ts';
 import { actionRule, locatorRule, sectionContextRule } from './rules.ts';
 import { TaskAgent } from './task-agent.ts';
-import { createCodeceptJSTools } from './tools.ts';
+import { createCodeceptJSTools, withdrawVisionTools } from './tools.ts';
 
 const debugLog = createDebug('explorbot:rerunner');
 
@@ -361,6 +361,7 @@ export class Rerunner extends TaskAgent implements Agent {
           },
         }),
       };
+      withdrawVisionTools(tools);
 
       const conversation = this.provider.startConversation(this.getHealSystemPrompt(), 'rerunner');
       conversation.addUserText(this.getHealUserPrompt(failedCode, error));

package/src/ai/researcher.ts

@@ -102,7 +102,7 @@ export class Researcher extends ResearcherBase implements Agent {
       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;
       }
     }
 
@@ -438,7 +438,7 @@ export class Researcher extends ResearcherBase implements Agent {
     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();
 

package/src/ai/rules.ts

@@ -4,13 +4,18 @@ export const recommendedCodeceptCommands = ['I.click', 'I.type', 'I.fillField',
 
 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
 
@@ -26,10 +31,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>
 `;
@@ -59,7 +64,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" },
@@ -105,7 +110,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'
@@ -245,7 +250,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
@@ -263,9 +269,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}