explorbot 0.4.3 → 0.4.5

package/src/ai/scout/tools.ts

@@ -0,0 +1,150 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tool } from 'ai';
+import { createBashTool } from 'bash-tool';
+import dedent from 'dedent';
+import { z } from 'zod';
+import { ConfigParser } from '../../config.ts';
+import { tag } from '../../utils/logger.ts';
+import { loadMarkdownFiles } from '../../utils/markdown-files.ts';
+import { readCaptainFile } from '../captain/file-tools.ts';
+
+const MAX_FILES = 500;
+const MAX_FINDINGS = 6000;
+
+let cachedScanner: 'rg' | 'grep' | null = null;
+
+export function loadScoutCorpus(dirs: string[]): ScoutCorpus {
+  const files: ScoutCorpusFile[] = [];
+  for (const dir of dirs) {
+    if (files.length >= MAX_FILES) {
+      tag('warning').log(`Scout corpus capped at ${MAX_FILES} files — remaining directories skipped`);
+      break;
+    }
+    for (const file of loadMarkdownFiles(dir, { recursive: true })) {
+      if (files.length >= MAX_FILES) break;
+      const entry: ScoutCorpusFile = { path: file.filePath };
+      if (typeof file.data.url === 'string') entry.url = file.data.url;
+      files.push(entry);
+    }
+  }
+  return { dirs, files, excludedPaths: [] };
+}
+
+export function excludeCorpusUrls(corpus: ScoutCorpus, urls: string[]): ScoutCorpus {
+  if (urls.length === 0) return corpus;
+
+  const excludedUrls = new Set(urls);
+  const files: ScoutCorpusFile[] = [];
+  const excludedPaths = [...corpus.excludedPaths];
+  for (const file of corpus.files) {
+    if (file.url && excludedUrls.has(file.url)) {
+      excludedPaths.push(file.path);
+      continue;
+    }
+    files.push(file);
+  }
+  return { dirs: corpus.dirs, files, excludedPaths };
+}
+
+export async function createScoutTools(corpus: ScoutCorpus) {
+  const scanner = await detectScanner();
+  const projectRoot = ConfigParser.getInstance().getProjectRoot();
+
+  let result = '';
+  let searchedOrRead = false;
+
+  const getResult = () => result;
+  const finishFromText = (text?: string) => {
+    if (text && searchedOrRead) result = text.slice(0, MAX_FINDINGS);
+  };
+
+  const files: Record<string, string> = {};
+  const readableFiles = new Set<string>();
+  for (const file of corpus.files) {
+    files[toPosix(file.path)] = readFileSync(file.path, 'utf8');
+    readableFiles.add(resolve(file.path));
+  }
+
+  const toolkit = await createBashTool({
+    destination: '/',
+    files,
+    maxOutputLength: 20000,
+  });
+
+  const bashExecute = toolkit.bash.execute;
+  const bash = {
+    ...toolkit.bash,
+    execute: async (input: { command: string }) => {
+      tag('step').log(`Scout: bash ${input.command}`);
+      searchedOrRead = true;
+      return bashExecute?.(input);
+    },
+  };
+
+  const tools: Record<string, any> = {
+    bash,
+    readFile: tool({
+      description: dedent`
+        Read one documentation file from the corpus.
+        Pass the exact path returned by a search result.
+      `,
+      inputSchema: z.object({
+        path: z.string().describe('File path from a search result'),
+        startLine: z.number().optional().describe('First line to read, 1-based. Negative values count from the end of the file'),
+        endLine: z.number().optional().describe('Last line to read, 1-based and inclusive. Negative values count from the end of the file'),
+        maxChars: z.number().optional().describe('Maximum characters to return, default 12000'),
+      }),
+      execute: async (input) => {
+        tag('step').log(`Scout: read ${input.path}`);
+        const output = readCaptainFile(projectRoot, input, corpus.dirs);
+        if (!output.success) return output;
+        const resolvedPath = resolve(projectRoot || process.cwd(), output.path);
+        if (!readableFiles.has(resolvedPath)) {
+          return { success: false, message: 'File is outside the Scout corpus' };
+        }
+        searchedOrRead = true;
+        return output;
+      },
+    }),
+  };
+
+  return { tools, scanner, getResult, finishFromText };
+}
+
+async function detectScanner(): Promise<'rg' | 'grep'> {
+  if (cachedScanner) return cachedScanner;
+  if (await binaryRuns('rg')) {
+    cachedScanner = 'rg';
+    return cachedScanner;
+  }
+  if (await binaryRuns('grep')) {
+    cachedScanner = 'grep';
+    return cachedScanner;
+  }
+  throw new Error('Scout requires ripgrep or grep on PATH — neither was found');
+}
+
+async function binaryRuns(binary: 'rg' | 'grep'): Promise<boolean> {
+  try {
+    const proc = Bun.spawn([binary, '--version'], { stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+function toPosix(path: string): string {
+  return path.split('\\').join('/');
+}
+
+export interface ScoutCorpus {
+  dirs: string[];
+  files: ScoutCorpusFile[];
+  excludedPaths: string[];
+}
+
+export interface ScoutCorpusFile {
+  path: string;
+  url?: string;
+}

package/src/ai/scout.ts

@@ -0,0 +1,173 @@
+import dedent from 'dedent';
+import { tag } from '../utils/logger.ts';
+import { loop } from '../utils/loop.ts';
+import type { Agent } from './agent.ts';
+import type { Provider } from './provider.ts';
+import { type ScoutCorpus, createScoutTools, excludeCorpusUrls } from './scout/tools.ts';
+
+const MAX_ITERATIONS = 3;
+const MAX_TOOL_ROUNDTRIPS = 5;
+const CACHE_LIMIT = 40;
+const URL_LISTING_LIMIT = 40;
+
+export class Scout implements Agent {
+  emoji = '🔎';
+  private cache = new Map<string, string>();
+
+  constructor(
+    private provider: Provider,
+    private corpus: ScoutCorpus
+  ) {}
+
+  isAvailable(): boolean {
+    return this.corpus.files.length > 0;
+  }
+
+  async collectDocs(query: ScoutQuery): Promise<string> {
+    if (!this.isAvailable()) return '';
+
+    const cacheKey = `${query.url || ''}|${query.feature || ''}|${query.excludeUrls.join(',')}`;
+    const cached = this.cache.get(cacheKey);
+    if (cached !== undefined) return cached;
+
+    const corpus = excludeCorpusUrls(this.corpus, query.excludeUrls);
+    if (corpus.files.length === 0) return '';
+
+    const result = await this.runSession(corpus, query);
+    if (result === null) return '';
+
+    if (this.cache.size > CACHE_LIMIT) this.cache.clear();
+    this.cache.set(cacheKey, result);
+    return result;
+  }
+
+  private async runSession(corpus: ScoutCorpus, query: ScoutQuery): Promise<string | null> {
+    const { tools, scanner, getResult, finishFromText } = await createScoutTools(corpus);
+    const conversation = this.provider.startConversation(this.buildSystemPrompt(Object.keys(tools), corpus, query, scanner), 'scout', this.provider.getAgenticModel('scout'));
+    conversation.addUserText(this.buildTaskPrompt(query));
+
+    tag('info').log(`Scout: collecting documentation for ${query.feature || query.url || 'the current page'}`);
+
+    let failed = false;
+    await loop(
+      async ({ stop, iteration }) => {
+        const invokeResult = await this.provider.invokeConversation(conversation, tools, {
+          maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
+          agentName: 'scout',
+        });
+
+        if (!invokeResult?.toolExecutions?.length) {
+          finishFromText(invokeResult?.response?.text);
+          stop();
+          return;
+        }
+
+        if (iteration >= MAX_ITERATIONS) {
+          const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
+          finishFromText(final?.response?.text);
+          stop();
+        }
+      },
+      {
+        maxAttempts: MAX_ITERATIONS,
+        observability: { name: `scout: ${query.feature || query.url || 'docs'}`, agent: 'scout' },
+        catch: async ({ error, stop }) => {
+          failed = true;
+          tag('warning').log(`Scout error: ${(error as Error).message}`);
+          stop();
+        },
+      }
+    );
+
+    if (failed) return null;
+
+    const digest = getResult();
+    if (digest) {
+      const preview = digest.slice(0, 600);
+      const ellipsis = digest.length > 600 ? '…' : '';
+      tag('info').log(`Scout digest:\n${preview}${ellipsis}`);
+    }
+    return digest;
+  }
+
+  private buildSystemPrompt(toolNames: string[], corpus: ScoutCorpus, query: ScoutQuery, scanner: 'rg' | 'grep'): string {
+    const urls = corpus.files.map((file) => file.url).filter(Boolean) as string[];
+    const urlless = corpus.files.filter((file) => !file.url);
+    let pagesListing = '';
+    if (urls.length > 0) {
+      const listing = urls
+        .slice(0, URL_LISTING_LIMIT)
+        .map((url) => `- ${url}`)
+        .join('\n');
+      pagesListing = `Documented pages:\n${listing}`;
+      const remaining = urls.length - URL_LISTING_LIMIT;
+      if (remaining > 0) pagesListing += `\n…and ${remaining} more — find them with ${scanner}`;
+    }
+    if (urlless.length > 0) {
+      const listing = urlless
+        .slice(0, URL_LISTING_LIMIT)
+        .map((file) => `- ${toPosix(file.path)}`)
+        .join('\n');
+      pagesListing += `\nFiles with no page URL (hand-written docs):\n${listing}`;
+    }
+
+    const prompt = dedent`
+      You are Scout — a documentation retrieval agent. You find collected documentation relevant to a testing focus and report it for test planning.
+
+      You never see the application itself. The documentation corpus is your only source of truth.
+
+      CORPUS:
+      ${corpus.files.length} markdown files under:
+      - ${corpus.dirs.map(toPosix).join('\n- ')}
+      ${pagesListing}
+
+      These pages are already provided to the planner in full — do not re-report them:
+      ${query.excludeUrls.map((url) => `- ${url}`).join('\n') || '- none'}
+
+      AVAILABLE TOOLS:
+      ${toolNames.join(', ')}.
+      Use tool names exactly as listed. Do not invent aliases or combined names.
+      Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
+
+      SCANNER:
+      ${scanner} is the search command. Scan the working directory through bash() — explore freely, pipelines, globs and repeated searches are fine. Read files with readFile().
+
+      WORKFLOW:
+      1. Scan with ${scanner} using plain prose words from the focus — feature names, page purposes, capabilities
+      2. Read the files whose hits look most relevant
+      3. Report the digest as your final message — no tool call is needed to finish
+
+      RULES:
+      - Report only what the documentation states. Never fill gaps with assumptions about the application
+      - Keep verified capabilities and unverified possibilities distinguishable, the way the documentation marks them
+      - Name the page URL each item belongs to, so scenarios anchor to real routes
+      - Explore briefly: a few scans and reads are enough, then report
+      - A short accurate digest beats a long loose one; reporting that nothing relevant exists is a valid answer
+    `;
+
+    const customPrompt = this.provider.getSystemPromptForAgent('scout');
+    if (customPrompt) return `${prompt}\n\n${customPrompt}`;
+    return prompt;
+  }
+
+  private buildTaskPrompt(query: ScoutQuery): string {
+    return dedent`
+      Page URL: ${query.url || 'Unknown'}
+      Page title: ${query.title || 'Unknown'}
+      Focus: ${query.feature || 'the page as a whole'}
+
+      Report the documented capabilities, states and transitions a test planner could turn into scenarios.
+    `;
+  }
+}
+
+function toPosix(path: string): string {
+  return path.split('\\').join('/');
+}
+
+export interface ScoutQuery {
+  url?: string;
+  title?: string;
+  feature?: string;
+  excludeUrls: string[];
+}

package/src/ai/tester.ts

@@ -53,6 +53,7 @@ export class Tester extends TaskAgent implements Agent {
   MAX_ITERATIONS = 30;
   MAX_EXTENSIONS = 2;
   ASSERTION_TOOLS = ['verify'];
+  private pendingReview = '';
   researcher: Researcher;
   navigator: Navigator;
   agentTools: any;
@@ -119,6 +120,7 @@ export class Tester extends TaskAgent implements Agent {
     this.seenUiMapUrls.clear();
     this.lastAnalyzedStateHash = null;
     this.stalledIterations = 0;
+    this.pendingReview = '';
     this.previousRegionPresent = null;
     this.regionTransitioned = false;
     this.stateManager.clearHistory();
@@ -333,7 +335,7 @@ export class Tester extends TaskAgent implements Agent {
           const result = await this.provider.invokeConversation(conversation, tools, {
             maxToolRoundtrips: 3,
             toolChoice: 'required',
-            stopWhen: () => task.hasFinished,
+            stopWhen: () => task.hasFinished || !!this.pendingReview,
           });
 
           if (!result) throw new Error('Failed to get response from provider');
@@ -388,6 +390,14 @@ export class Tester extends TaskAgent implements Agent {
             }
           }
 
+          if (this.pendingReview && this.pilot) {
+            const reviewed = this.pendingReview;
+            this.pendingReview = '';
+            const reviewState = this.getCurrentState();
+            if (reviewed === 'finish') await this.pilot.reviewFinish(task, reviewState, conversation, this.navigator);
+            if (reviewed === 'stop') await this.pilot.reviewStop(task, reviewState, conversation);
+          }
+
           if (task.hasFinished) {
             stop();
             return;
@@ -579,16 +589,19 @@ export class Tester extends TaskAgent implements Agent {
 
     if (region.isModal) {
       const areaName = region.name ? ` "${region.name}"` : '';
-      let rootHint = '';
-      if (region.root) rootHint = `\nIts content lives inside \`${region.root}\` — scope locators to it.`;
+      let scoping = 'Use <page_aria> to confirm the element you target is actually inside the overlay.';
+      if (region.root) {
+        scoping = `Its root is \`${region.root}\` — build every locator as ARIA scoped to that root, e.g. I.click({ role: 'button', text: 'Continue' }, '${region.root}')`;
+      }
       context += dedent`
         <overlay>
-        An overlay${areaName} is currently open above the page.${rootHint}
-        Scope all interactions to elements inside this overlay.
-        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the overlay.
-        Use <page_aria> to confirm the element you target is actually inside the overlay.
-        </overlay>
+        You are inside an overlay${areaName} opened above the page.
+        ${scoping}
+        Elements outside the overlay are behind it and not actionable while it is open — they may share names or roles with the ones inside, so never target them by bare text.
       `;
+      const regionAria = currentState.getRegionARIA();
+      if (regionAria) context += `\nIt holds exactly these elements:\n<overlay_aria>\n${regionAria}\n</overlay_aria>`;
+      context += '\n</overlay>\n';
     }
 
     if (!region.isModal && region.isOpen && isNewState) {
@@ -1006,18 +1019,9 @@ export class Tester extends TaskAgent implements Agent {
         }),
         execute: async ({ reason }) => {
           task.addNote(`Stop requested: ${reason}`);
+          this.pendingReview = 'stop';
 
-          if (this.pilot) {
-            const currentState = this.getCurrentState();
-            await this.pilot.reviewStop(task, currentState, conversation);
-            if (!task.hasFinished) {
-              return {
-                success: false,
-                action: 'stop',
-                message: 'Stop rejected; Continue execution',
-              };
-            }
-          } else {
+          if (!this.pilot) {
             task.addNote(reason, TestResult.FAILED);
             task.finish(TestResult.FAILED);
           }
@@ -1053,18 +1057,9 @@ export class Tester extends TaskAgent implements Agent {
             return { success: true, action: 'finish', message: 'already finished' };
           }
           task.addNote(`Finish requested: ${verify}`);
+          this.pendingReview = 'finish';
 
-          if (this.pilot) {
-            const currentState = this.getCurrentState();
-            await this.pilot.reviewFinish(task, currentState, conversation, this.navigator);
-            if (!task.hasFinished) {
-              return {
-                success: false,
-                action: 'finish',
-                message: 'Finishing rejected; Continue execution',
-              };
-            }
-          } else {
+          if (!this.pilot) {
             task.addNote('Test finished successfully', TestResult.PASSED);
             task.finish(TestResult.PASSED);
           }

package/src/ai/tools.ts

@@ -12,6 +12,7 @@ import { cleanHtmlSnippet } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { pause } from '../utils/loop.js';
+import { ariaRefSelector, describeRef, refIsGone } from '../utils/aria-ref.ts';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
 import { Navigator } from './navigator.ts';
@@ -66,7 +67,6 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
           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
           After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
         `),
         explanation: z.string().describe('Why you are clicking this element'),
@@ -79,11 +79,21 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
           return failedToolResult('click', 'No commands provided');
         }
 
-        const invalidCommands = rawCommands.map((cmd) => cmd.trim()).filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
+        const trimmedCommands = rawCommands.map((cmd) => cmd.trim());
+        const coordinateCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.clickXY'));
+
+        if (coordinateCommands.length > 0) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('click', `Coordinate commands are not locators: ${coordinateCommands.join(', ')}. A coordinate click always runs, so it cannot tell you whether the element was there.`, {
+            suggestion: 'Name the element instead. Use visualClick() when you can see the target but cannot address it, or form() for a deliberate coordinate click such as dismissing a layer.',
+          });
+        }
+
+        const invalidCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
 
         if (invalidCommands.length > 0) {
           activeNote.commit(TestResult.FAILED);
-          return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() or I.clickXY() commands.`, {
+          return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() commands.`, {
             suggestion: 'Use form() tool for typing text or multiple actions, or exitIframe() to leave iframe context.',
           });
         }
@@ -111,6 +121,17 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
 
           if (success) {
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
+
+            if (!hasObservablePageChange(toolResult)) {
+              activeNote.commit(TestResult.FAILED);
+              return failedToolResult('click', 'Click executed, but no observable page change was captured.', {
+                ...toolResult,
+                attempts,
+                code: command,
+                suggestion: 'Treat the element as not clicked. It may be covered by another layer, disabled, or the locator may have matched a non-interactive ancestor. Re-locate via xpathCheck(), which reports whether the element is covered or offscreen, before retrying.',
+              });
+            }
+
             await commitNote(activeNote, TestResult.PASSED, toolResult, action);
             return successToolResult('click', { ...toolResult, attempts, code: command }, action);
           }
@@ -461,10 +482,18 @@ export function createRefTools({ explorer, stateManager }: ToolDeps, task: Task)
       }),
       execute: async ({ ref, element }) => {
         const activeNote = task.startNote(`Click ${element}`);
+
+        if (await refIsGone(explorer, ref)) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('clickRef', `Ref ${ref} names no element on the page any more.`, {
+            suggestion: 'The page has been rebuilt since you were given that ref. Call context() and use the ref it gives, or fall back to click() with a locator.',
+          });
+        }
+
         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())`;
+        const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
 
         if (!(await action.attempt(run, `Click ${element}`))) {
           activeNote.commit(TestResult.FAILED);
@@ -737,6 +766,12 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
 
           const researchResult = await researcher.research(currentState, { screenshot: true, data: true });
 
+          if (!researchResult) {
+            return failedToolResult('research', 'No UI map is available for this page.', {
+              suggestion: 'Use context() to read the page structure and act on the elements it lists.',
+            });
+          }
+
           return successToolResult('research', {
             analysis: researchResult,
             aria: cap(ActionResult.fromState(currentState).getInteractiveARIA(), ARIA_OUTPUT_CAP),
@@ -1163,21 +1198,6 @@ export async function commitNote(activeNote: any, result: TestResult, toolResult
   activeNote.commit(result);
 }
 
-async function describeRef(explorer: any, ref: string): Promise<{ role: string; text: string } | null> {
-  return Promise.resolve(
-    explorer?.withPage?.((page: any) =>
-      page.locator(`aria-ref=${ref}`).evaluate((el: any) => {
-        const tag = el.tagName.toLowerCase();
-        const roles: Record<string, string> = { 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: any): Promise<boolean> {
   return explorer.withPage((page: any) => page.evaluate(() => !!document.activeElement && document.activeElement !== document.body)).catch(() => true);
 }
@@ -1232,6 +1252,7 @@ function hasObservablePageChange(data?: Record<string, any>): boolean {
   if (data.pageDiff.urlChanged === true) return true;
   if (data.pageDiff.ariaChanges) return true;
   if (data.pageDiff.messages?.length) return true;
+  if (data.pageDiff.requests?.length) return true;
   return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
 
@@ -1242,12 +1263,11 @@ export async function failedToolResult(action: string, message: string, data?: R
   }
 
   const errorTexts = [message, ...(data?.attempts?.map((a: any) => a.error || '') || [])];
-  const hasMultipleElements = errorTexts.some((t: string) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN));
-  const multipleElementsSuggestion = hasMultipleElements ? getMultipleElementsSuggestion() : null;
-  if (multipleElementsSuggestion) {
-    result.suggestion = multipleElementsSuggestion;
+  if (errorTexts.some((t: string) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
+    const matched = await extractWebElements(error);
+    result.suggestion = getMultipleElementsSuggestion(matched);
     result.multipleElementsDetected = true;
-    result.elements = await formatMatchedElements(error);
+    result.elements = formatElementList(matched);
     return result;
   }
 
@@ -1260,11 +1280,16 @@ export async function failedToolResult(action: string, message: string, data?: R
   return result;
 }
 
-function getMultipleElementsSuggestion(): string {
+function getMultipleElementsSuggestion(matched: MatchedElement[] | null): string {
+  const visible = (matched || []).filter((element) => element.visible !== false);
+  let onlyVisible = '';
+  if (matched && visible.length === 1) onlyVisible = `\nOnly element ${matched.indexOf(visible[0]) + 1} is on screen, so that is the one to act on.`;
+
   return dedent`
     Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
-    Read the numbered elements list and click the one you meant by its number:
+    Read the numbered elements list and act on the one you meant by its number:
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    A match reported as not visible can never be acted on — pick one that is.${onlyVisible}
     If none of them is the element you want, narrow the locator with a container or its full unique text.
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
@@ -1288,7 +1313,7 @@ export function clickFailureSuggestion(attempts: Array<{ error?: string }>): str
   }
 
   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.';
+    return 'Element is in the DOM but not visible. Reveal it — scroll to it, expand its section, open the panel holding it — or, when the page carries several copies of the same control, target the one that is on screen.';
   }
 
   if (errors.some((e) => e.includes('SyntaxError'))) {
@@ -1313,19 +1338,20 @@ const MAX_DISAMBIGUATE_TEXT = 80;
 const MAX_DISAMBIGUATE_HTML = 300;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
 
-async function extractWebElements(error: Error | null | undefined): Promise<Array<{ xpath: string; html: string; text: string }> | null> {
+async function extractWebElements(error: Error | null | undefined): Promise<MatchedElement[] | null> {
   if (!error || error.name !== 'MultipleElementsFound') return null;
 
-  const elements = (error as any).webElements as Array<{ toAbsoluteXPath: () => Promise<string>; toOuterHTML: () => Promise<string>; getText: () => Promise<string | null> }> | undefined;
+  const elements = (error as any).webElements as Array<{ toAbsoluteXPath: () => Promise<string>; toOuterHTML: () => Promise<string>; getText: () => Promise<string | null>; isVisible?: () => Promise<boolean> }> | undefined;
   if (!elements?.length) return null;
 
-  const result: Array<{ xpath: string; html: string; text: string }> = [];
+  const result: MatchedElement[] = [];
   for (let i = 0; i < Math.min(elements.length, MAX_DISAMBIGUATE_ELEMENTS); i++) {
     try {
       const xpath = await elements[i].toAbsoluteXPath();
       const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
       const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
-      result.push({ xpath, html, text });
+      const visible = await Promise.resolve(elements[i].isVisible?.()).catch(() => undefined);
+      result.push({ xpath, html, text, visible });
     } catch (e) {
       debugLog('Failed to get details for element %d: %s', i, e);
     }
@@ -1333,14 +1359,20 @@ async function extractWebElements(error: Error | null | undefined): Promise<Arra
   return result.length > 0 ? result : null;
 }
 
-function formatElementList(details: Array<{ xpath: string; html: string; text: string }>): string {
-  return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+function formatElementList(matched: MatchedElement[] | null): string {
+  if (!matched) return 'Could not fetch element details. Repeat the action to get better info.';
+  return matched
+    .map((el, i) => {
+      const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
+      if (el.visible !== undefined) lines.push(`Visible: ${el.visible}`);
+      lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
+      return lines.join('\n');
+    })
+    .join('\n\n');
 }
 
 export async function formatMatchedElements(error: Error | null | undefined): Promise<string | null> {
-  const details = await extractWebElements(error);
-  if (!details) return 'Could not fetch element details. Repeat the action to get better info.';
-  return formatElementList(details);
+  return formatElementList(await extractWebElements(error));
 }
 
 function getNotFoundSuggestion(errorMessage: string): string | null {
@@ -1356,3 +1388,10 @@ function getNotFoundSuggestion(errorMessage: string): string | null {
     4. Prefer ARIA locators: { "role": "button", "text": "visible text" }
   `;
 }
+
+interface MatchedElement {
+  xpath: string;
+  html: string;
+  text: string;
+  visible?: boolean;
+}