explorbot 0.4.1 → 0.4.2

package/dist/src/ai/fisherman-tools.js

@@ -3,19 +3,15 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { extractEndpointDefinition } from "../api/spec-reader.js";
 import { tag } from "../utils/logger.js";
-import { RequestMap } from "../utils/request-map.js";
 import { isDynamicSegment } from "../utils/url-matcher.js";
-export function createFishermanTools(apiClient, requestStore, opts) {
+export function createFishermanTools(apiClient, requestStore, haul, opts) {
     let finished = false;
     let result = null;
-    const ledgerStart = requestStore.getMadeRequests().length;
-    const runRequests = () => requestStore.getMadeRequests().slice(ledgerStart);
-    const successfulWrites = () => runRequests().filter((r) => r.isWrite && !r.error && r.status >= 200 && r.status < 400);
-    const getResult = () => result ?? synthesizeResult(runRequests(), successfulWrites(), false);
+    const getResult = () => result ?? synthesizeResult(haul, false);
     const isFinished = () => finished;
     const finishFromText = (text) => {
         finished = true;
-        const synthesized = synthesizeResult(runRequests(), successfulWrites(), true);
+        const synthesized = synthesizeResult(haul, true);
         if (text && synthesized.success)
             synthesized.summary = text;
         result = synthesized;
@@ -142,30 +138,12 @@ export function createFishermanTools(apiClient, requestStore, opts) {
                     .describe('List of items that could not be created'),
             }),
             execute: async ({ summary, created, failed }) => {
-                const writes = successfulWrites();
-                if (writes.length === 0) {
-                    tag('warning').log('Fisherman: finish rejected — no successful write request in this run');
-                    return { finished: false, error: 'No successful write request was made in this run, so nothing was created. Keep working, or call stop if the data cannot be prepared.' };
-                }
-                const createdRequests = new RequestMap(writes);
-                const verified = [];
-                for (const item of created) {
-                    if (item.id === undefined) {
-                        verified.push(item);
-                        continue;
-                    }
-                    const request = createdRequests.get(item.id);
-                    if (!request) {
-                        tag('warning').log(`Fisherman: dropped unverified created item ${item.type} (id: ${item.id})`);
-                        continue;
-                    }
-                    verified.push({ ...item, request: request.toEndpoint() });
-                }
-                if (verified.length === 0)
-                    verified.push(...writes.map(toCreatedItem));
+                const { result: verified, error } = verifyFinish(haul, { summary, created, failed });
+                if (!verified)
+                    return { finished: false, error };
                 tag('success').log(`Fisherman done: ${summary}`);
                 finished = true;
-                result = { success: true, summary, created: verified, failed: failed || [] };
+                result = verified;
                 return { finished: true };
             },
         }),
@@ -184,8 +162,34 @@ export function createFishermanTools(apiClient, requestStore, opts) {
     };
     return { tools, getResult, isFinished, finishFromText };
 }
-function synthesizeResult(made, writes, declaredDone) {
-    const failures = made.filter((r) => r.status >= 400 || r.error);
+export function verifyFinish(haul, input) {
+    const writes = haul.successfulWrites();
+    if (writes.length === 0) {
+        tag('warning').log('Fisherman: finish rejected — no successful write request in this run');
+        return { result: null, error: 'No successful write request was made in this run, so nothing was created. Keep working, or call stop if the data cannot be prepared.' };
+    }
+    const createdRequests = haul.byId();
+    const verified = [];
+    for (const item of input.created) {
+        if (item.id === undefined) {
+            verified.push(item);
+            continue;
+        }
+        const request = createdRequests.get(String(item.id));
+        if (!request) {
+            tag('warning').log(`Fisherman: dropped unverified created item ${item.type} (id: ${item.id})`);
+            continue;
+        }
+        verified.push({ ...item, request: request.toEndpoint() });
+    }
+    if (verified.length === 0)
+        verified.push(...writes.map(toCreatedItem));
+    return { result: { success: true, summary: input.summary, created: verified, failed: input.failed || [] } };
+}
+function synthesizeResult(haul, declaredDone) {
+    const made = haul.requests();
+    const writes = haul.successfulWrites();
+    const failures = haul.failed();
     let summary = `Stopped before finishing: ${made.length} requests, ${writes.length} successful writes, ${failures.length} failed`;
     const lastFailure = failures[failures.length - 1];
     if (lastFailure)

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

@@ -1,7 +1,8 @@
 import type { ApiClient } from '../api/api-client.js';
-import type { RequestStore } from '../api/request-store.js';
+import { type RequestStore } from '../api/request-store.js';
 import type { Agent } from './agent.js';
 import { type FishermanResult } from './fisherman-tools.js';
+import { RequestHaul } from './fisherman/request-haul.js';
 import type { Provider } from './provider.js';
 export declare class Fisherman implements Agent {
     emoji: string;
@@ -26,6 +27,6 @@ export declare class Fisherman implements Agent {
     refreshAuth(): Promise<void>;
     buildEndpointList(scopeUrl?: string): string;
     buildSystemPrompt(endpointList: string, toolNames: string[], scopeUrl?: string): string;
-    isStuckOnEndpoint(ledgerStart: number): boolean;
+    isStuckOnEndpoint(haul: RequestHaul): boolean;
     buildTaskPrompt(instructions: string): string;
 }

package/dist/src/ai/fisherman.js

@@ -1,9 +1,11 @@
 import dedent from 'dedent';
+import { isFailedRequest } from "../api/request-store.js";
 import { listAllEndpoints } from "../api/spec-reader.js";
 import { createDebug, tag } from "../utils/logger.js";
 const debugLog = createDebug('explorbot:fisherman');
 import { loop } from "../utils/loop.js";
 import { createFishermanTools } from "./fisherman-tools.js";
+import { RequestHaul } from "./fisherman/request-haul.js";
 import { dataProtectionRules } from "./rules.js";
 const MAX_ITERATIONS = 15;
 const MAX_TOOL_ROUNDTRIPS = 5;
@@ -61,11 +63,11 @@ export class Fisherman {
         }
         await this.refreshAuth();
         debugLog(`auth headers: ${Object.keys(this.apiClient.getHeaders()).join(', ')}`);
-        const { tools, getResult, isFinished, finishFromText } = createFishermanTools(this.apiClient, this.requestStore, {
+        const haul = new RequestHaul(this.requestStore);
+        const { tools, getResult, isFinished, finishFromText } = createFishermanTools(this.apiClient, this.requestStore, haul, {
             spec: this.spec,
             baseEndpoint: this.baseEndpoint,
         });
-        const ledgerStart = this.requestStore.getMadeRequests().length;
         const conversation = this.provider.startConversation(this.buildSystemPrompt(endpointList, Object.keys(tools), scopeUrl), 'fisherman');
         conversation.addUserText(this.buildTaskPrompt(instructions));
         await loop(async ({ stop, iteration }) => {
@@ -85,7 +87,7 @@ export class Fisherman {
                 stop();
                 return;
             }
-            if (this.isStuckOnEndpoint(ledgerStart)) {
+            if (this.isStuckOnEndpoint(haul)) {
                 tag('warning').log('Fisherman: repeated failures on the same endpoint — stopping');
                 stop();
                 return;
@@ -190,13 +192,13 @@ export class Fisherman {
       ${dataProtectionRules}
     `;
     }
-    isStuckOnEndpoint(ledgerStart) {
-        const made = this.requestStore.getMadeRequests().slice(ledgerStart);
+    isStuckOnEndpoint(haul) {
+        const made = haul.requests();
         if (made.length < REPEATED_FAILURE_LIMIT)
             return false;
         const recent = made.slice(-REPEATED_FAILURE_LIMIT);
         const first = recent[0];
-        return recent.every((r) => (r.status >= 400 || r.error) && r.method === first.method && r.path === first.path);
+        return recent.every((r) => isFailedRequest(r) && r.method === first.method && r.path === first.path);
     }
     buildTaskPrompt(instructions) {
         return dedent `

package/dist/src/ai/pilot.js

@@ -19,6 +19,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 {
     emoji = '🧭';
     provider;
@@ -741,21 +742,21 @@ export class Pilot {
         lines.push(`h2: ${state.h2 || ''}`);
         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;
         if (tabs.length > 0) {
@@ -971,9 +972,13 @@ export class Pilot {
                 line += `\n   ${ariaDiff}`;
             if (t.output?.pageDiff?.urlChanged)
                 line += `\n   moved: ${t.output.pageDiff.previousUrl} → ${t.output.pageDiff.currentUrl}`;
-            const failedRequests = (t.output?.pageDiff?.requests ?? []).filter((r) => r.status >= 400);
-            if (failedRequests.length > 0) {
-                line += `\n   requests: ${failedRequests.map((r) => `${r.method} ${r.path} → ${r.status}`).join(', ')}`;
+            const pageRequests = t.output?.pageDiff?.requests ?? [];
+            const requests = pageRequests
+                .filter((r) => r.status >= 400)
+                .concat(pageRequests.filter((r) => r.status < 400))
+                .slice(0, PILOT_REQUEST_LIMIT);
+            if (requests.length > 0) {
+                line += `\n   requests: ${requests.map((r) => `${r.method} ${r.path} → ${r.status}`).join(', ')}`;
             }
             const messages = (t.output?.pageDiff?.messages ?? []).slice(0, PILOT_MESSAGE_LIMIT);
             if (messages.length > 0) {
@@ -1034,15 +1039,15 @@ export class Pilot {
 
       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().
       - 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.
 

package/dist/src/ai/provider.js

@@ -10,6 +10,7 @@ import { configuredModels, modelName as getModelName } from '../config.js';
 import { executionController } from "../execution-controller.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
+import { getCliName } from '../utils/cli-name.js';
 import { createDebug, tag } from '../utils/logger.js';
 import { withRetry } from '../utils/retry.js';
 import { RulesLoader } from "../utils/rules-loader.js";
@@ -43,14 +44,7 @@ export async function flushTelemetry() {
 }
 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) {
-    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, cancel, controller) {
     return new Promise((_, reject) => {
@@ -99,7 +93,7 @@ export class Provider {
     modelCallWaiters = [];
     constructor(config) {
         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();
@@ -226,8 +220,8 @@ export class Provider {
         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),
         });
@@ -387,7 +381,7 @@ export class Provider {
         let invalidRequestFeedbackAdded = false;
         const executedStepMessages = [];
         try {
-            const response = await this.withModelRequestSlot(() => withRetry(async () => {
+            let response = await this.withModelRequestSlot(() => withRetry(async () => {
                 const stepMessages = [];
                 const onStepEnd = (step) => {
                     stepMessages.push(...(step.response?.messages || []));
@@ -413,7 +407,7 @@ export class Provider {
                 return result;
             }, this.getRetryOptions(options)));
             clearActivity();
-            withExecutedSteps(response, executedStepMessages);
+            response = withExecutedSteps(response, executedStepMessages);
             // Log tool usage summary
             if (response.toolCalls && response.toolCalls.length > 0) {
                 responseLog(response.toolCalls);
@@ -585,7 +579,7 @@ export class Provider {
     }
     async processImage(prompt, image) {
         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');
         const messages = [

package/dist/src/ai/researcher/coordinates.d.ts

@@ -8,6 +8,7 @@ export declare function visuallyAnnotateContainers(page: Page, containers: Array
     css: string;
     label: string;
 }>): Promise<number>;
+export declare function removeVisualAnnotations(page: Page): Promise<void>;
 export declare function WithCoordinates<T extends Constructor>(Base: T): {
     new (...args: any[]): {
         explorer: Explorer;
@@ -20,6 +21,7 @@ export declare function WithCoordinates<T extends Constructor>(Base: T): {
                 label: string;
             }>;
         }): Promise<number>;
+        removeVisualAnnotations(): Promise<void>;
         _analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult>;
         mergeVisualData(result: ResearchResult, visualData: Map<string, {
             coordinates: string | null;

package/dist/src/ai/researcher/coordinates.js

@@ -62,6 +62,15 @@ export async function visuallyAnnotateContainers(page, containers) {
         return count;
     }, containers);
 }
+export async function removeVisualAnnotations(page) {
+    try {
+        await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+            for (const element of elements)
+                element.remove();
+        });
+    }
+    catch { }
+}
 export function WithCoordinates(Base) {
     return class extends Base {
         analyzeScreenshotForVisualProps() {
@@ -70,6 +79,9 @@ export function WithCoordinates(Base) {
         async visuallyAnnotateElements(opts) {
             return this.explorer.withPage((page) => visuallyAnnotateContainers(page, opts?.containers || []));
         }
+        async removeVisualAnnotations() {
+            await this.explorer.withPage((page) => removeVisualAnnotations(page));
+        }
         async _analyzeScreenshotForVisualProps() {
             const elements = new Map();
             const emptyResult = { elements, pagePurpose: null, primaryActions: null, focusedSection: null };
@@ -81,7 +93,7 @@ export function WithCoordinates(Base) {
             tag('step').log('Analyzing annotated screenshot for visual properties');
             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/dist/src/ai/researcher/deep-analysis.js

@@ -62,29 +62,29 @@ export function WithDeepAnalysis(Base) {
             this._appendExtendedResearch(result, expandedSections, navigationLinks);
         }
         async researchOverlay(current, previous, pageStateHash) {
-            const focusArea = current.overlay;
-            if (!focusArea.present || !focusArea.name)
+            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;
             }
             const alreadyExpanded = this._summarizeExpanded(parseResearchSections(cached)
                 .filter((s) => s.elements.length > 0)
                 .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;
             }
             const extQuery = mdq(cached).query('section1(~"Extended Research")');
@@ -97,7 +97,7 @@ export function WithDeepAnalysis(Base) {
                 updated = `${cached.trimEnd()}\n\n# Extended Research\n\n${sectionMarkdown}\n`;
             }
             saveResearch({ hash: pageStateHash }, updated);
-            tag('substep').log(`Overlay research appended: ${focusArea.name}`);
+            tag('substep').log(`Overlay research appended: ${region.name}`);
             return sectionMarkdown;
         }
         _loadPreviousExtendedSections(hash) {

package/dist/src/ai/researcher/fingerprint-worker.js

@@ -3,17 +3,7 @@ import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from "../../utils/html-diff.js";
 import { isSamePageFamily } from "../../utils/url-matcher.js";
-function diceSimilarity(a, b) {
-    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.js";
 parentPort.on('message', (data) => {
     const { html, statesDir, maxAgeMs, threshold, url } = data;
     if (!existsSync(statesDir)) {

package/dist/src/ai/researcher.js

@@ -193,7 +193,7 @@ export class Researcher extends ResearcherBase {
                 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/dist/src/ai/rules.js

@@ -318,6 +318,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/dist/src/ai/tester.js

@@ -486,14 +486,14 @@ export class Tester extends TaskAgent {
         const currentStateHash = currentState.hash;
         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) {
             const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
@@ -511,30 +511,30 @@ export class Tester extends TaskAgent {
         </no_focus>
       `;
         }
-        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>
       `;
         }
         if (currentState.isInsideIframe) {
@@ -594,7 +594,7 @@ export class Tester extends TaskAgent {
       `;
             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/dist/src/ai/tools.d.ts

@@ -12,7 +12,7 @@ interface AgentToolDeps extends ToolDeps {
     withExperience?: boolean;
 }
 export declare const ASSERTION_TOOLS: readonly ["verify"];
-export declare function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps, task: Task): {
+export declare function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task: Task): {
     click: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
         commands: any;
         explanation: any;