explorbot 0.4.1 → 0.4.3

package/src/ai/pilot.ts

@@ -18,6 +18,7 @@ import { truncateJson } from '../utils/strings.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import type { Conversation } from './conversation.ts';
 import type { Fisherman } from './fisherman.ts';
+import { createAskApiTool } from './fisherman/tools.ts';
 import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import type { Researcher } from './researcher.ts';
@@ -31,6 +32,7 @@ const META_TOOLS = ['record', 'reset', 'stop', 'finish'];
 const PILOT_REASONING_LIMIT = 500;
 const PILOT_MESSAGE_LIMIT = 2;
 const PILOT_MESSAGE_MAX_LENGTH = 160;
+const PILOT_REQUEST_LIMIT = 5;
 
 export class Pilot implements Agent {
   emoji = '🧭';
@@ -451,7 +453,8 @@ export class Pilot implements Agent {
 
         Plan the test execution for this scenario.
 
-        FIRST: Decide if precondition() is needed.
+        FIRST: Decide if precondition() is needed. When the page does not settle whether suitable data
+        already exists, call askApi() to find out before creating any.
 
         Call precondition() WHEN:
         - The scenario edits/deletes/modifies an item, and you want a DISPOSABLE item to act on safely
@@ -687,7 +690,7 @@ export class Pilot implements Agent {
     }
     this.conversation!.addUserText(finalUserText);
 
-    const tools = { ...this.pickPlanningTools(), ...this.buildPreconditionTool(opts.task) };
+    const tools = { ...this.pickPlanningTools(), ...this.buildFishermanTools(opts.task) };
 
     const result = await this.provider.invokeConversation(this.conversation!, tools, {
       maxToolRoundtrips: opts.maxToolRoundtrips ?? 0,
@@ -733,7 +736,12 @@ export class Pilot implements Agent {
     return planning;
   }
 
-  private buildPreconditionTool(task: Test) {
+  private fishermanStatus(): string {
+    if (this.fisherman?.isAvailable()) return 'available';
+    return 'none';
+  }
+
+  private buildFishermanTools(task: Test) {
     const unavailable = 'Data was not created and cannot be created automatically. Do not call precondition again for this test — continue with what the page already shows.';
     return {
       precondition: tool({
@@ -744,7 +752,7 @@ export class Pilot implements Agent {
         execute: async ({ description }) => {
           task.addNote(`Precondition: ${description}`);
           tag('info').log(`Precondition: ${description}`);
-          debugLog(`precondition: ${description}, fisherman: ${this.fisherman?.isAvailable() ? 'available' : 'none'}`);
+          debugLog(`precondition: ${description}, fisherman: ${this.fishermanStatus()}`);
 
           if (!this.fisherman || !this.fisherman.isAvailable()) {
             const skipReason = await this.checkDataAvailability(task, description, 'Fisherman not available');
@@ -775,6 +783,7 @@ export class Pilot implements Agent {
           return { noted: true, prepared: true, created: result.created };
         },
       }),
+      ...createAskApiTool(this.fisherman, task),
     };
   }
 
@@ -826,17 +835,17 @@ export class Pilot implements Agent {
     lines.push(`h3: ${state.h3 || ''}`);
     lines.push(`h4: ${state.h4 || ''}`);
 
-    const focusArea = state.overlay;
-    if (focusArea.detected) {
-      let line = `modal: ${focusArea.name || focusArea.type}`;
-      if (focusArea.root) line += ` (root: ${focusArea.root})`;
+    const region = state.overlay;
+    if (region.isModal) {
+      let line = `overlay: ${region.name || region.type}`;
+      if (region.root) line += ` (root: ${region.root})`;
       lines.push(line);
-    } else if (focusArea.present) {
-      let line = `region: ${focusArea.name || 'unnamed'} (inline`;
-      if (focusArea.root) line += `, root: ${focusArea.root}`;
+    } else if (region.isOpen) {
+      let line = `region: ${region.name || 'unnamed'} (inline`;
+      if (region.root) line += `, root: ${region.root}`;
       lines.push(`${line})`);
     } else {
-      lines.push('modal: none');
+      lines.push('overlay: none');
     }
 
     const tabs = this.stateManager.otherTabs;
@@ -1071,9 +1080,13 @@ export class Pilot implements Agent {
 
         if (t.output?.pageDiff?.urlChanged) line += `\n   moved: ${t.output.pageDiff.previousUrl} → ${t.output.pageDiff.currentUrl}`;
 
-        const failedRequests = (t.output?.pageDiff?.requests ?? []).filter((r: any) => r.status >= 400);
-        if (failedRequests.length > 0) {
-          line += `\n   requests: ${failedRequests.map((r: any) => `${r.method} ${r.path} → ${r.status}`).join(', ')}`;
+        const pageRequests = t.output?.pageDiff?.requests ?? [];
+        const requests = pageRequests
+          .filter((r: any) => r.status >= 400)
+          .concat(pageRequests.filter((r: any) => r.status < 400))
+          .slice(0, PILOT_REQUEST_LIMIT);
+        if (requests.length > 0) {
+          line += `\n   requests: ${requests.map((r: any) => `${r.method} ${r.path} → ${r.status}`).join(', ')}`;
         }
 
         const messages = (t.output?.pageDiff?.messages ?? []).slice(0, PILOT_MESSAGE_LIMIT);
@@ -1139,15 +1152,15 @@ export class Pilot implements Agent {
 
       Diagnostic patterns (use <state>, executed/element/skipped fields, ariaDiff):
       - Click failed + button in "disabled buttons" → required field missing. Instruct fill first.
-      - "modal: none" but Tester targets a modal → modal closed; re-trigger.
+      - "overlay: none" but Tester targets an overlay → overlay closed; re-trigger.
       - "region:" in <state> → a large area appeared in place without navigation (subview, wizard step, panel). Direct Tester to act inside it; the rest of the page is still usable.
       - Action SUCCESS but ariaDiff empty → may have worked without visible DOM change; check result message.
-      - MultipleElementsFound → xpathCheck() to identify the right one, then precise locator or visualClick().
+      - MultipleElementsFound → nothing was clicked. Tell Tester to reuse the same locator with step.opts({ elementIndex: N }) from the numbered elements list.
       - Wrong page (settings vs feature) → getVisitedStates() then back() or reset(). Don't try breadcrumbs (SPA back-nav is unreliable).
       - Click SUCCESS but executed locator ≠ explanation intent, or "skipped" attempts present → wrong element clicked.
       - form(I.type()) SUCCESS but "element" shows a button/link → keys went to wrong element; click the input first.
       - ariaDiff shows 5+ added/removed → page entered new mode (editor/modal); call context() before guessing selectors.
-      - Empty dropdown/list when items expected → missing data; call precondition() to create it.
+      - Empty dropdown/list when items expected → wait explicitly, then check the state changed: ariaDiff and any GET that loaded data. If still nothing loaded, confirm the empty state with verify(), or askApi() for whether the data exists at all.
       - Search-and-select needs SEQUENCE: focus trigger → type to filter → click option. Tell Tester to split into separate tool calls.
       - Multi-action explanation in one tool call → instruct Tester to split.
 
@@ -1163,8 +1176,13 @@ export class Pilot implements Agent {
 
       ${capabilityGroundingRule}
 
-      YOUR Pilot-only tool: precondition(description) — create FRESH disposable test data via API. Never
-      request users. Use when:
+      YOUR Pilot-only tools, both over the API:
+
+      askApi(question) — ask what data already exists. It changes nothing. Use it to check whether
+      suitable data is already there before creating any, and to get the exact name or id of an existing
+      record a step must act on.
+
+      precondition(description) — create FRESH disposable test data. Never request users. Use when:
 
       - Scenario edits/deletes/modifies an item → create a disposable target ("1 post").
       - Scenario needs auxiliary data (labels, categories, statuses for filtering).

package/src/ai/provider.ts

@@ -11,6 +11,7 @@ import { type AIConfig, configuredModels, modelName as getModelName } from '../c
 import { executionController } from '../execution-controller.ts';
 import { Observability } from '../observability.ts';
 import { Stats } from '../stats.ts';
+import { getCliName } from '../utils/cli-name.js';
 import { createDebug, tag } from '../utils/logger.js';
 import { type RetryOptions, withRetry } from '../utils/retry.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
@@ -51,12 +52,7 @@ export async function flushTelemetry(): Promise<void> {
 const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
 
 function extractCachedTokens(usage: any): number {
-  if (!usage) return 0;
-  const direct = usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens;
-  if (typeof direct === 'number') return direct;
-  const raw = usage.raw;
-  const fromRaw = raw?.prompt_tokens_details?.cached_tokens ?? raw?.promptTokensDetails?.cachedTokens;
-  return typeof fromRaw === 'number' ? fromRaw : 0;
+  return usage?.inputTokenDetails?.cacheReadTokens ?? 0;
 }
 
 function abortAfterIdle(ms: number, cancel: { cancelled: boolean }, controller: AbortController): Promise<never> {
@@ -110,7 +106,7 @@ export class Provider {
 
   constructor(config: AIConfig) {
     if (!config?.model) {
-      throw new AiError('AI model is not configured. Set ai.model in your config file.');
+      throw new AiError(`AI model is not configured. Set ai.model in your config file, or pick one with ${getCliName()} recommended-models`);
     }
     this.config = config;
     this.initLangfuse();
@@ -243,8 +239,8 @@ export class Provider {
   private recordUsage(agentName: string, modelName: string, usage: any): void {
     if (!usage) return;
     Stats.recordTokens(agentName, modelName, {
-      input: usage.inputTokens ?? usage.promptTokens ?? 0,
-      output: usage.outputTokens ?? usage.completionTokens ?? 0,
+      input: usage.inputTokens ?? 0,
+      output: usage.outputTokens ?? 0,
       total: usage.totalTokens ?? 0,
       cached: extractCachedTokens(usage),
     });
@@ -428,7 +424,7 @@ export class Provider {
     let invalidRequestFeedbackAdded = false;
     const executedStepMessages: ModelMessage[] = [];
     try {
-      const response = await this.withModelRequestSlot(() =>
+      let response = await this.withModelRequestSlot(() =>
         withRetry(async () => {
           const stepMessages: ModelMessage[] = [];
           const onStepEnd = (step: any) => {
@@ -458,7 +454,7 @@ export class Provider {
 
       clearActivity();
 
-      withExecutedSteps(response, executedStepMessages);
+      response = withExecutedSteps(response, executedStepMessages);
 
       // Log tool usage summary
       if (response.toolCalls && response.toolCalls.length > 0) {
@@ -651,7 +647,7 @@ export class Provider {
 
   async processImage(prompt: string, image: string): Promise<any> {
     if (!this.config.visionModel) {
-      throw new Error('Vision model not configured. Please set ai.visionModel in your config.');
+      throw new Error(`Vision model not configured. Set ai.visionModel in your config; ${getCliName()} recommended-models lists the providers that serve one`);
     }
 
     setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');

package/src/ai/researcher/coordinates.ts

@@ -71,6 +71,14 @@ export async function visuallyAnnotateContainers(page: Page, containers: Array<{
   }, containers);
 }
 
+export async function removeVisualAnnotations(page: Page): Promise<void> {
+  try {
+    await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+      for (const element of elements) element.remove();
+    });
+  } catch {}
+}
+
 export function WithCoordinates<T extends Constructor>(Base: T) {
   return class extends Base {
     declare explorer: Explorer;
@@ -85,6 +93,10 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
       return this.explorer.withPage((page) => visuallyAnnotateContainers(page, opts?.containers || []));
     }
 
+    async removeVisualAnnotations(): Promise<void> {
+      await this.explorer.withPage((page) => removeVisualAnnotations(page));
+    }
+
     private async _analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult> {
       const elements = new Map<string, { coordinates: string | null; color: string | null; icon: string | null }>();
       const emptyResult: VisualAnalysisResult = { elements, pagePurpose: null, primaryActions: null, focusedSection: null };
@@ -96,7 +108,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
 
       const prompt = dedent`
         This screenshot has two types of annotations:
-        - **Section containers**: dashed bordered boxes (no labels on them). A legend at the bottom-left maps dashed line colors to section names. Ignore containers for this task.
+        - **Section containers**: dashed bordered boxes (no labels on them). A legend at the bottom-right maps dashed line colors to section names. Ignore containers for this task.
         - **Interactive elements**: solid bordered boxes with eidx numbers in the top-right corner above the box. Adjacent elements use different colors.
 
         For each interactive element (solid border, eidx number), report:

package/src/ai/researcher/deep-analysis.ts

@@ -88,22 +88,22 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     }
 
     async researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null> {
-      const focusArea = current.overlay;
-      if (!focusArea.present || !focusArea.name) return null;
+      const region = current.overlay;
+      if (!region.isOpen || !region.name) return null;
 
       const cached = getCachedResearch(pageStateHash);
       if (!cached) return null;
 
-      const escaped = focusArea.name.replace(/"/g, '\\"');
+      const escaped = region.name.replace(/"/g, '\\"');
       if (mdq(cached).query(`section3(~"${escaped}")`).count() > 0) {
-        debugLog(`Overlay "${focusArea.name}" already in cached research, skipping`);
+        debugLog(`Overlay "${region.name}" already in cached research, skipping`);
         return null;
       }
 
       const diff = await current.diff(previous);
 
       if (!diff.ariaChanged && diff.htmlParts.length === 0) {
-        debugLog(`No diff between current and previous state for overlay "${focusArea.name}"`);
+        debugLog(`No diff between current and previous state for overlay "${region.name}"`);
         return null;
       }
 
@@ -113,10 +113,10 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
           .map((s) => s.rawMarkdown)
       );
 
-      tag('substep').log(`Researching overlay: ${focusArea.name}`);
-      const sectionMarkdown = await this._analyzeExpandedAction('', focusArea.name, diff, alreadyExpanded);
+      tag('substep').log(`Researching overlay: ${region.name}`);
+      const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded);
       if (!sectionMarkdown) {
-        debugLog(`Overlay "${focusArea.name}" produced no meaningful expansion`);
+        debugLog(`Overlay "${region.name}" produced no meaningful expansion`);
         return null;
       }
 
@@ -130,7 +130,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       }
 
       saveResearch({ hash: pageStateHash }, updated);
-      tag('substep').log(`Overlay research appended: ${focusArea.name}`);
+      tag('substep').log(`Overlay research appended: ${region.name}`);
       return sectionMarkdown;
     }
 

package/src/ai/researcher/fingerprint-worker.ts

@@ -3,16 +3,7 @@ import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from '../../utils/html-diff.ts';
 import { isSamePageFamily } from '../../utils/url-matcher.ts';
-
-function diceSimilarity(a: Set<string>, b: Set<string>): number {
-  let intersection = 0;
-  for (const item of a) {
-    if (b.has(item)) intersection++;
-  }
-  const total = a.size + b.size;
-  if (total === 0) return 100;
-  return Math.round(((2 * intersection) / total) * 100);
-}
+import { diceSimilarity } from '../../utils/similarity.ts';
 
 parentPort!.on('message', (data: FingerprintRequest) => {
   const { html, statesDir, maxAgeMs, threshold, url } = data;

package/src/ai/researcher.ts

@@ -236,7 +236,7 @@ export class Researcher extends ResearcherBase implements Agent {
         const containers = validContainers.filter((c) => !freshBroken.includes(c.css));
         await this.visuallyAnnotateElements({ containers });
         this.actionResult = await this.explorer.capture({ screenshot: true });
-        const visualResult = await this.analyzeScreenshotForVisualProps();
+        const visualResult = await this.analyzeScreenshotForVisualProps().finally(() => this.removeVisualAnnotations());
         if (visualResult.elements.size > 0) {
           await this.mergeVisualData(result, visualResult.elements);
           result.parseLocators();

package/src/ai/rules.ts

@@ -173,6 +173,8 @@ export const dataProtectionRules = dedent`
   Do not use Fisherman or API data preparation to bypass a no-mutation, read-only, search,
   filter, tab, or list-inspection constraint. Use visible existing data when it is available.
   If no suitable data exists, report the missing precondition instead of creating data.
+  Reading through the API to establish what already exists is not a mutation and stays allowed
+  under a read-only constraint.
 
   Destructive actions are allowed only against data created by the current scenario
   or prepared for that scenario by Fisherman/API preconditions. Existing application data must
@@ -335,6 +337,14 @@ export const actionRule = dedent`
   If locator doesn't work, try CSS or XPath locators.
   If nothing works, use I.clickXY(x, y) as last resort.
 
+  When a click result reports several matches, pick one from its numbered list by position rather than guessing a new locator.
+  Reuse the same locator with step.opts({ elementIndex: N }) as the LAST argument. N is the "Element N" number.
+
+  <example>
+    I.click('Remove', step.opts({ elementIndex: 2 }));
+    I.click({ role: 'link', text: 'Details' }, '.panel', step.opts({ elementIndex: 1 }));
+  </example>
+
   For checkboxes, prefer I.checkOption/I.uncheckOption over I.click.
 
 

package/src/ai/tester.ts

@@ -548,17 +548,17 @@ export class Tester extends TaskAgent implements Agent {
     const isNewUrl = this.previousUrl !== currentUrl;
     const isNewState = !isNewUrl && this.previousStateHash !== null && this.previousStateHash !== currentStateHash;
 
-    if (this.previousRegionPresent !== null && this.previousRegionPresent !== currentState.overlay.present) {
+    if (this.previousRegionPresent !== null && this.previousRegionPresent !== currentState.overlay.isOpen) {
       this.regionTransitioned = true;
     }
-    this.previousRegionPresent = currentState.overlay.present;
+    this.previousRegionPresent = currentState.overlay.isOpen;
 
     this.previousUrl = currentUrl;
     this.previousStateHash = currentStateHash;
 
     let context = '';
 
-    const focusArea = currentState.overlay;
+    const region = currentState.overlay;
 
     const focusedElement = currentState.focusedElement;
     if (focusedElement) {
@@ -577,29 +577,29 @@ export class Tester extends TaskAgent implements Agent {
       `;
     }
 
-    if (focusArea.detected) {
-      const areaName = focusArea.name ? ` "${focusArea.name}"` : '';
+    if (region.isModal) {
+      const areaName = region.name ? ` "${region.name}"` : '';
       let rootHint = '';
-      if (focusArea.root) rootHint = `\nIts content lives inside \`${focusArea.root}\` — scope locators to it.`;
+      if (region.root) rootHint = `\nIts content lives inside \`${region.root}\` — scope locators to it.`;
       context += dedent`
-        <focus_scope>
-        A ${focusArea.type}${areaName} is currently open above the page.${rootHint}
-        Scope all interactions to elements inside this ${focusArea.type}.
-        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 ${focusArea.type}.
-        Use <page_aria> to confirm the element you target is actually inside the ${focusArea.type}.
-        </focus_scope>
+        <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>
       `;
     }
 
-    if (!focusArea.detected && focusArea.present && isNewState) {
+    if (!region.isModal && region.isOpen && isNewState) {
       let rootHint = '';
-      if (focusArea.root) rootHint = `\nIt lives inside \`${focusArea.root}\`.`;
+      if (region.root) rootHint = `\nIt lives inside \`${region.root}\`.`;
       context += dedent`
-        <area_of_interest>
-        A large new area "${focusArea.name || 'unnamed area'}" appeared on this page without navigation.${rootHint}
+        <region>
+        A large new region "${region.name || 'unnamed region'}" appeared on this page without navigation.${rootHint}
         The scenario most likely continues inside this area — prefer its elements for your next actions.
         The rest of the page (navigation, menus, filters) is still interactive and remains available.
-        </area_of_interest>
+        </region>
       `;
     }
 
@@ -663,7 +663,7 @@ export class Tester extends TaskAgent implements Agent {
       return context;
     }
 
-    if (focusArea.present && focusArea.name && this.pageStateHash && this.pageActionResult) {
+    if (region.isOpen && region.name && this.pageStateHash && this.pageActionResult) {
       const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash).catch(this.skipResearch);
       if (overlaySection) {
         context += dedent`

package/src/ai/tools.ts

@@ -15,7 +15,6 @@ import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
 import { Navigator } from './navigator.ts';
-import type { AIProvider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { sectionContextRule } from './rules.ts';
 import { isInteractive } from './task-agent.ts';
@@ -31,7 +30,7 @@ interface AgentToolDeps extends ToolDeps {
 
 export const ASSERTION_TOOLS = ['verify'] as const;
 
-export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps, task: Task) {
+export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task: Task) {
   return {
     click: tool({
       description: dedent`
@@ -44,6 +43,12 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           Container narrows search area. Use when page has multiple matching elements.
           Example: Page has 3 "Delete" buttons in different rows:
           I.click("Delete", ".row-1") - clicks Delete inside element with class row-1
+        I.click(locator, step.opts({ elementIndex: N })) - click the Nth element the locator matches
+          Use after a result reported several matches. N is the "Element N" number from that list.
+          step.opts() always goes LAST, after the container when there is one.
+          Example: the result listed 3 "Delete" buttons and you want the second:
+          I.click("Delete", step.opts({ elementIndex: 2 }))
+          I.click("Delete", ".table", step.opts({ elementIndex: 2 })) - same, narrowed to a container
 
         IMPORTANT: This tool ONLY accepts click commands. For typing text, use form() tool.
         CRITICAL: All commands MUST target the SAME element using different locators.
@@ -62,6 +67,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           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'),
       }),
@@ -91,6 +97,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
         const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
         const action = explorer.action();
         const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
+        let ambiguityError: Error | null = null;
 
         for (let i = 0; i < commands.length; i++) {
           const command = transformContainsCommand(commands[i]);
@@ -100,6 +107,8 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           if (action.lastError) attempt.error = errorText(action.lastError);
           attempts.push(attempt);
 
+          if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound') ambiguityError = action.lastError;
+
           if (success) {
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
             await commitNote(activeNote, TestResult.PASSED, toolResult, action);
@@ -107,31 +116,6 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           }
         }
 
-        let disambiguated = null;
-        if (attempts.some((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
-          disambiguated = await disambiguateElements(action.lastError, explanation, ai);
-        }
-
-        if (disambiguated) {
-          debugLog('Disambiguation picked element %d', disambiguated.position);
-          const failedCommand = attempts.find((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))?.command;
-          const retryCommands = [];
-          if (failedCommand) {
-            retryCommands.push(failedCommand.replace(/\)$/, `, step.opts({ elementIndex: ${disambiguated.position} }))`));
-          }
-          retryCommands.push(`I.click('${disambiguated.xpath.replace(/'/g, "\\'")}')`);
-
-          for (const retryCmd of retryCommands) {
-            if (!(await action.attempt(retryCmd, explanation))) {
-              attempts.push({ command: retryCmd, success: false, error: errorText(action.lastError) });
-              continue;
-            }
-            const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, retryCmd);
-            await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-            return successToolResult('click', { ...toolResult, attempts, code: retryCmd, disambiguated: true }, action);
-          }
-        }
-
         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, commands[0]);
         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
@@ -145,7 +129,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
             attempts,
             suggestion,
           },
-          action.lastError
+          ambiguityError || action.lastError
         );
       },
     }),
@@ -413,13 +397,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
             const message = errorText(action.lastError);
             await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
-            let formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
-            if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
-              const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
-              if (disambiguated) {
-                formSuggestion = `Multiple elements matched. Add step.opts({ elementIndex: ${disambiguated.position} }) to the failing command. Fallback locator: ${disambiguated.xpath}`;
-              }
-            }
+            const formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
 
             return failedToolResult(
               'form',
@@ -1284,13 +1262,11 @@ export async function failedToolResult(action: string, message: string, data?: R
 
 function getMultipleElementsSuggestion(): string {
   return dedent`
-    Multiple elements matched your locator. To fix this:
-    1. Use container context: I.click({ "role": "button", "text": "Submit" }, '.form-container')
-    2. Use more specific CSS: target the actual element (input, button, a) not wrapper divs
-    3. Add distinguishing attributes: input[type="submit"], button[type="submit"], [value="..."]
-    4. If buttons have similar text like "Create" and "Create Demo", use the FULL unique text
-    5. Use xpathCheck() to inspect matched elements and pick the correct one
-    6. Use visualClick() to click the right element by visual appearance
+    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:
+    reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    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.
   `;
 }
 
@@ -1367,50 +1343,6 @@ export async function formatMatchedElements(error: Error | null | undefined): Pr
   return formatElementList(details);
 }
 
-async function disambiguateElements(error: Error | null | undefined, explanation: string, provider: AIProvider): Promise<{ position: number; xpath: string } | null> {
-  const elementDetails = await extractWebElements(error);
-  if (!elementDetails) return null;
-
-  const elementList = formatElementList(elementDetails);
-
-  const schema = z.object({
-    position: z.number().nullable().describe('1-based position of the correct element, or null if none match'),
-  });
-
-  try {
-    const result = await provider.generateObject(
-      [
-        {
-          role: 'user' as const,
-          content: dedent`
-            A click action failed because multiple elements matched the locator.
-            The intended action was: ${explanation}
-
-            Here are the matched elements:
-
-            ${elementList}
-
-            Which element (1-${elementDetails.length}) best matches the intended action?
-            Return the position number, or null if none of them match.
-          `,
-        },
-      ],
-      schema,
-      provider.getModelForAgent(),
-      { agentName: 'disambiguator', timeout: 15000 }
-    );
-
-    const position = result?.object?.position;
-    if (position && position >= 1 && position <= elementDetails.length) {
-      return { position, xpath: elementDetails[position - 1].xpath };
-    }
-    return null;
-  } catch (e) {
-    debugLog('Element disambiguation AI call failed: %s', e);
-    return null;
-  }
-}
-
 function getNotFoundSuggestion(errorMessage: string): string | null {
   if (!errorMessage.includes('not found')) {
     return null;

package/src/api/request-result.ts

@@ -124,7 +124,8 @@ export class RequestResult {
     }
 
     writeFileSync(this.requestFile, yaml, 'utf8');
-    writeFileSync(this.responseFile, this._rawResponseBody || '', 'utf8');
+    if (!this._rawResponseBody) return;
+    writeFileSync(this.responseFile, this._rawResponseBody, 'utf8');
   }
 
   static load(requestFile: string): RequestResult {