explorbot 0.3.5 → 0.4.0

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

@@ -3,11 +3,23 @@ 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) {
     let finished = false;
-    let result = { success: false, summary: '', created: [], failed: [] };
-    const getResult = () => result;
+    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 isFinished = () => finished;
+    const finishFromText = (text) => {
+        finished = true;
+        const synthesized = synthesizeResult(runRequests(), successfulWrites(), true);
+        if (text && synthesized.success)
+            synthesized.summary = text;
+        result = synthesized;
+    };
     const tools = {
         getEndpointSpec: tool({
             description: dedent `
@@ -69,7 +81,7 @@ export function createFishermanTools(apiClient, requestStore, opts) {
         request: tool({
             description: dedent `
         Make an HTTP request to the API.
-        Returns status, timing, and auto-extracted IDs and names from the response.
+        Returns status, plus IDs and names auto-extracted from the response under 'extracted'.
       `,
             inputSchema: z.object({
                 method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
@@ -106,7 +118,7 @@ export function createFishermanTools(apiClient, requestStore, opts) {
                 return {
                     success: true,
                     status: reqResult.status,
-                    ...extracted,
+                    extracted,
                 };
             },
         }),
@@ -130,9 +142,30 @@ 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));
                 tag('success').log(`Fisherman done: ${summary}`);
                 finished = true;
-                result = { success: true, summary, created, failed: failed || [] };
+                result = { success: true, summary, created: verified, failed: failed || [] };
                 return { finished: true };
             },
         }),
@@ -149,7 +182,20 @@ export function createFishermanTools(apiClient, requestStore, opts) {
             },
         }),
     };
-    return { tools, getResult, isFinished };
+    return { tools, getResult, isFinished, finishFromText };
+}
+function synthesizeResult(made, writes, declaredDone) {
+    const failures = made.filter((r) => r.status >= 400 || r.error);
+    let summary = `Stopped before finishing: ${made.length} requests, ${writes.length} successful writes, ${failures.length} failed`;
+    const lastFailure = failures[failures.length - 1];
+    if (lastFailure)
+        summary += `; last failure: ${lastFailure.toSummary()}`;
+    return { success: declaredDone && writes.length > 0, summary, created: writes.map(toCreatedItem), failed: [] };
+}
+function toCreatedItem(write) {
+    const { id, title } = write.extractIdAndTitle();
+    const segments = write.path.split('/').filter((s) => s && !isDynamicSegment(s));
+    return { type: segments[segments.length - 1] || 'item', id, title, request: write.toEndpoint() };
 }
 function responseCategory(status) {
     if (status === 400 || status === 422)

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

@@ -9,14 +9,15 @@ export declare class Fisherman implements Agent {
     apiClient: ApiClient;
     requestStore: RequestStore;
     specLoader: () => Promise<any | null>;
-    cookieProvider: () => Promise<Record<string, string>>;
+    browserHeaderProvider: () => Promise<Record<string, string>>;
     configHeaders: Record<string, string>;
     sessionName?: string;
     baseEndpoint: string;
     spec: any | null;
     mode: 'replicate' | 'achieve' | 'disabled';
     hasApiConfig: boolean;
-    constructor(provider: Provider, apiClient: ApiClient, requestStore: RequestStore, specLoader: () => Promise<any | null>, baseEndpoint: string, cookieProvider: () => Promise<Record<string, string>>, configHeaders?: Record<string, string>, hasApiConfig?: boolean);
+    scopeDegraded: boolean;
+    constructor(provider: Provider, apiClient: ApiClient, requestStore: RequestStore, specLoader: () => Promise<any | null>, baseEndpoint: string, browserHeaderProvider: () => Promise<Record<string, string>>, configHeaders?: Record<string, string>, hasApiConfig?: boolean);
     isAvailable(): boolean;
     ensureReady(scopeUrl?: string): Promise<void>;
     getEndpointList(scopeUrl?: string): string;
@@ -25,5 +26,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;
     buildTaskPrompt(instructions: string): string;
 }

package/dist/src/ai/fisherman.js

@@ -7,26 +7,28 @@ import { createFishermanTools } from "./fisherman-tools.js";
 import { dataProtectionRules } from "./rules.js";
 const MAX_ITERATIONS = 15;
 const MAX_TOOL_ROUNDTRIPS = 5;
+const REPEATED_FAILURE_LIMIT = 4;
 export class Fisherman {
     emoji = '🎣';
     provider;
     apiClient;
     requestStore;
     specLoader;
-    cookieProvider;
+    browserHeaderProvider;
     configHeaders;
     sessionName;
     baseEndpoint;
     spec = null;
     mode = 'disabled';
     hasApiConfig;
-    constructor(provider, apiClient, requestStore, specLoader, baseEndpoint, cookieProvider, configHeaders = {}, hasApiConfig = false) {
+    scopeDegraded = false;
+    constructor(provider, apiClient, requestStore, specLoader, baseEndpoint, browserHeaderProvider, configHeaders = {}, hasApiConfig = false) {
         this.provider = provider;
         this.apiClient = apiClient;
         this.requestStore = requestStore;
         this.specLoader = specLoader;
         this.baseEndpoint = baseEndpoint;
-        this.cookieProvider = cookieProvider;
+        this.browserHeaderProvider = browserHeaderProvider;
         this.configHeaders = configHeaders;
         this.hasApiConfig = hasApiConfig;
         this.mode = hasApiConfig ? 'achieve' : 'replicate';
@@ -59,17 +61,17 @@ export class Fisherman {
         }
         await this.refreshAuth();
         debugLog(`auth headers: ${Object.keys(this.apiClient.getHeaders()).join(', ')}`);
-        const { tools, getResult, isFinished } = createFishermanTools(this.apiClient, this.requestStore, {
+        const { tools, getResult, isFinished, finishFromText } = createFishermanTools(this.apiClient, this.requestStore, {
             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 }) => {
             debugLog(`iteration ${iteration}`);
             const invokeResult = await this.provider.invokeConversation(conversation, tools, {
                 maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
-                toolChoice: 'required',
                 agentName: 'fisherman',
             });
             debugLog(`iteration ${iteration} done, text: ${invokeResult?.response?.text?.slice(0, 200) || '(none)'}`);
@@ -77,6 +79,17 @@ export class Fisherman {
                 stop();
                 return;
             }
+            if (!invokeResult?.toolExecutions?.length) {
+                debugLog('no tool call in this turn — treating as finish');
+                finishFromText(invokeResult?.response?.text);
+                stop();
+                return;
+            }
+            if (this.isStuckOnEndpoint(ledgerStart)) {
+                tag('warning').log('Fisherman: repeated failures on the same endpoint — stopping');
+                stop();
+                return;
+            }
             if (iteration >= MAX_ITERATIONS) {
                 tag('warning').log('Fisherman: max iterations reached');
                 stop();
@@ -114,41 +127,40 @@ export class Fisherman {
         this.mode = 'disabled';
     }
     async refreshAuth() {
-        const cookies = await this.cookieProvider();
-        if (Object.keys(cookies).length > 0) {
-            this.apiClient.setHeaders(cookies);
-        }
-        const xhrHeaders = this.requestStore.extractAuthHeaders();
-        if (Object.keys(xhrHeaders).length > 0) {
-            this.apiClient.setHeaders(xhrHeaders);
+        if (this.mode === 'replicate') {
+            const xhrHeaders = this.requestStore.extractAuthHeaders();
+            if (Object.keys(xhrHeaders).length > 0) {
+                this.apiClient.setHeaders(xhrHeaders);
+            }
+            const browserHeaders = await this.browserHeaderProvider();
+            if (Object.keys(browserHeaders).length > 0) {
+                this.apiClient.setHeaders(browserHeaders);
+            }
         }
         if (Object.keys(this.configHeaders).length > 0) {
             this.apiClient.setHeaders(this.configHeaders);
         }
     }
     buildEndpointList(scopeUrl) {
+        this.scopeDegraded = false;
         if (this.mode === 'achieve' && this.spec) {
             const specEndpoints = listAllEndpoints(this.spec, this.baseEndpoint);
             if (specEndpoints)
                 return specEndpoints;
         }
-        let writeRequests = this.requestStore.getWriteRequestsForScope(scopeUrl || '/');
-        if (writeRequests.length === 0) {
-            writeRequests = this.requestStore.getWriteRequestsForScope('/');
-        }
-        const seen = new Set();
-        const lines = [];
-        for (const req of writeRequests) {
-            const key = `${req.method} ${req.path}`;
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            lines.push(key);
-        }
-        return lines.join('\n');
+        const scoped = this.requestStore.toEndpointList(scopeUrl || '/');
+        if (scoped)
+            return scoped;
+        this.scopeDegraded = true;
+        return this.requestStore.toEndpointList();
     }
     buildSystemPrompt(endpointList, toolNames, scopeUrl) {
-        const scopeBlock = scopeUrl ? `\n\nSCOPE: You are operating within ${scopeUrl}.\nAll created items must belong to this scope.` : '';
+        let scopeBlock = '';
+        if (scopeUrl) {
+            scopeBlock = `\n\nSCOPE: You are operating within ${scopeUrl}.\nAll created items must belong to this scope.`;
+            if (this.scopeDegraded)
+                scopeBlock += '\nThe endpoint list could not be narrowed to this scope and may include endpoints belonging to other scopes. Before writing, confirm the target belongs to this scope.';
+        }
         return dedent `
       You are Fisherman — a data preparation agent. You create test data by making API requests.
 
@@ -172,11 +184,20 @@ export class Fisherman {
       - Chain requests logically — create parent resources before children
       - Use the response category and error text to decide what failed: validation requires corrected data, authorization requires valid access, not_found requires a valid path or parent, and conflict requires resolving the conflicting state
       - Retry temporary or server failures once. Retry other failures only when the specification or error text gives a concrete correction
+      - Create only the resource types that were requested. If no endpoint creates a requested type, call stop — never create a different type as a substitute
       - Use realistic but unique data for each item (vary names, titles)
 
       ${dataProtectionRules}
     `;
     }
+    isStuckOnEndpoint(ledgerStart) {
+        const made = this.requestStore.getMadeRequests().slice(ledgerStart);
+        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);
+    }
     buildTaskPrompt(instructions) {
         return dedent `
       Prepare the following test data:

package/dist/src/ai/historian/codeceptjs.js

@@ -45,7 +45,7 @@ export function WithCodeceptJS(Base) {
             lines.push('');
             lines.push(`Feature('${escapeString(plan.title)}')`);
             lines.push('');
-            const startUrl = plan.url || plan.tests[0]?.startUrl;
+            const startUrl = plan.startUrl;
             if (startUrl) {
                 lines.push('Before(({ I }) => {');
                 lines.push(`  I.amOnPage('${escapeString(startUrl)}');`);

package/dist/src/ai/historian/playwright.js

@@ -78,7 +78,7 @@ export function WithPlaywright(Base) {
             lines.push(`import { test, expect } from '@playwright/test';`);
             lines.push('');
             lines.push(`test.describe('${escapeString(plan.title)}', () => {`);
-            const startUrl = plan.url || plan.tests[0]?.startUrl;
+            const startUrl = plan.startUrl;
             if (startUrl) {
                 lines.push('  test.beforeEach(async ({ page }) => {');
                 lines.push(`    await page.goto('${escapeString(startUrl)}');`);

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

@@ -71,6 +71,7 @@ export declare class Pilot implements Agent {
                 type: string;
                 id?: string | number;
                 title?: string;
+                request?: string;
             }[];
             skipped?: undefined;
             reason?: undefined;

package/dist/src/ai/pilot.js

@@ -687,6 +687,8 @@ export class Pilot {
                             parts.push(`"${c.title}"`);
                         if (c.id)
                             parts.push(`(id: ${c.id})`);
+                        if (c.request)
+                            parts.push(`via ${c.request}`);
                         return parts.join(' ');
                     });
                     const stepText = `Precondition: created ${items.join(', ')}`;
@@ -741,7 +743,16 @@ export class Pilot {
         lines.push(`h4: ${state.h4 || ''}`);
         const focusArea = state.overlay;
         if (focusArea.detected) {
-            lines.push(`modal: ${focusArea.name || focusArea.type}`);
+            let line = `modal: ${focusArea.name || focusArea.type}`;
+            if (focusArea.root)
+                line += ` (root: ${focusArea.root})`;
+            lines.push(line);
+        }
+        else if (focusArea.present) {
+            let line = `region: ${focusArea.name || 'unnamed'} (inline`;
+            if (focusArea.root)
+                line += `, root: ${focusArea.root}`;
+            lines.push(`${line})`);
         }
         else {
             lines.push('modal: none');
@@ -1024,6 +1035,7 @@ 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.
+      - "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().
       - Wrong page (settings vs feature) → getVisitedStates() then back() or reset(). Don't try breadcrumbs (SPA back-nav is unreliable).

package/dist/src/ai/provider.js

@@ -385,9 +385,19 @@ export class Provider {
         const config = this.buildGenerateConfig({ tools: toolsWithCommentary, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
         let attemptMessages = messages;
         let invalidRequestFeedbackAdded = false;
+        const executedStepMessages = [];
         try {
             const response = await this.withModelRequestSlot(() => withRetry(async () => {
-                const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages: attemptMessages, ...config, abortSignal: signal }), config.timeout || 30000).catch((error) => {
+                const stepMessages = [];
+                const onStepEnd = (step) => {
+                    stepMessages.push(...(step.response?.messages || []));
+                };
+                const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages: attemptMessages, ...config, abortSignal: signal, onStepEnd }), config.timeout || 30000).catch((error) => {
+                    if (stepMessages.length > 0) {
+                        tag('warning').log(`Keeping ${stepMessages.length} messages from tool steps that already ran before the failure`);
+                        executedStepMessages.push(...stepMessages);
+                        attemptMessages = [...attemptMessages, ...stepMessages];
+                    }
                     if (!invalidRequestFeedbackAdded) {
                         const amended = withInvalidRequestFeedback(attemptMessages, error);
                         invalidRequestFeedbackAdded = amended !== attemptMessages;
@@ -403,6 +413,7 @@ export class Provider {
                 return result;
             }, this.getRetryOptions(options)));
             clearActivity();
+            withExecutedSteps(response, executedStepMessages);
             // Log tool usage summary
             if (response.toolCalls && response.toolCalls.length > 0) {
                 responseLog(response.toolCalls);
@@ -416,14 +427,15 @@ export class Provider {
         catch (error) {
             clearActivity();
             if (error?.message?.includes('Tool choice is required')) {
-                return { text: '', toolCalls: [], toolResults: [], response: { messages: [] }, usage: null };
+                return { text: '', toolCalls: [], toolResults: [], responseMessages: executedStepMessages, usage: null };
             }
             if (error?.name === 'AbortError')
                 throw error;
             if (error instanceof ContextLengthError)
                 throw error;
             if (Provider.isContextLengthError(error)) {
-                return this.recoverFromContextLength(error, messages, options, (m, o) => this.generateWithTools(m, model, tools, o));
+                const recovered = await this.recoverFromContextLength(error, attemptMessages, options, (m, o) => this.generateWithTools(m, model, tools, o));
+                return withExecutedSteps(recovered, executedStepMessages);
             }
             if (error.constructor?.name === 'AI_APICallError') {
                 responseLog(error.message);
@@ -630,6 +642,11 @@ function repairToolCall(options) {
         return repairChannelMarker(options);
     return repairHarmonyChannel(options);
 }
+function withExecutedSteps(result, executed) {
+    if (executed.length === 0)
+        return result;
+    return Object.defineProperty(result, 'responseMessages', { value: [...executed, ...(result.responseMessages || [])], configurable: true, enumerable: true });
+}
 function withInvalidRequestFeedback(messages, error) {
     if (!(error instanceof APICallError) || error.statusCode !== 400)
         return messages;

package/dist/src/ai/researcher/deep-analysis.js

@@ -63,9 +63,7 @@ export function WithDeepAnalysis(Base) {
         }
         async researchOverlay(current, previous, pageStateHash) {
             const focusArea = current.overlay;
-            if (!focusArea.detected || !focusArea.name)
-                return null;
-            if (focusArea.type !== 'dialog' && focusArea.type !== 'modal')
+            if (!focusArea.present || !focusArea.name)
                 return null;
             const cached = getCachedResearch(pageStateHash);
             if (!cached)

package/dist/src/ai/researcher.js

@@ -53,7 +53,7 @@ export class Researcher extends ResearcherBase {
         throw new Error('not implemented');
     }
     static getCachedResearch(state) {
-        return getCachedResearch(state.hash || '');
+        return getCachedResearch(ActionResult.fromState(state).baseHash);
     }
     getSystemMessage() {
         const currentUrl = this.stateManager.getCurrentState()?.url;
@@ -71,7 +71,7 @@ export class Researcher extends ResearcherBase {
         const maxRetries = this.config.ai?.agents?.researcher?.retries ?? 2;
         let retriesLeft = opts._retriesLeft ?? maxRetries;
         this.actionResult = ActionResult.fromState(state);
-        const stateHash = state.hash || this.actionResult.getStateHash();
+        const stateHash = this.actionResult.baseHash;
         const researchState = { ...state, hash: stateHash };
         if (!force && stateHash) {
             const cached = getCachedResearch(stateHash);
@@ -223,7 +223,7 @@ export class Researcher extends ResearcherBase {
             }
             if (!interrupted() && deep) {
                 try {
-                    await this.performDeepAnalysis(state, result);
+                    await this.performDeepAnalysis(researchState, result);
                 }
                 catch (err) {
                     tag('warning').log(`Deep analysis failed, continuing with best-effort research: ${err instanceof Error ? err.message : err}`);

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

@@ -32,6 +32,8 @@ export declare class Tester extends TaskAgent implements Agent {
     seenUiMapUrls: Set<string>;
     lastAnalyzedStateHash: string | null;
     stalledIterations: number;
+    previousRegionPresent: boolean | null;
+    regionTransitioned: boolean;
     readonly MAX_STALLED_ITERATIONS = 3;
     skipResearch: (err: Error) => string;
     constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any);
@@ -96,5 +98,6 @@ interface TestSessionHandlers {
 }
 export interface TestOptions {
     startOnCurrentPage?: boolean;
+    deadline?: number;
 }
 export {};

package/dist/src/ai/tester.js

@@ -50,6 +50,8 @@ export class Tester extends TaskAgent {
     seenUiMapUrls = new Set();
     lastAnalyzedStateHash = null;
     stalledIterations = 0;
+    previousRegionPresent = null;
+    regionTransitioned = false;
     MAX_STALLED_ITERATIONS = 3;
     skipResearch = (err) => {
         if (err.name === 'AbortError')
@@ -95,6 +97,8 @@ export class Tester extends TaskAgent {
         this.seenUiMapUrls.clear();
         this.lastAnalyzedStateHash = null;
         this.stalledIterations = 0;
+        this.previousRegionPresent = null;
+        this.regionTransitioned = false;
         this.stateManager.clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
@@ -214,10 +218,17 @@ export class Tester extends TaskAgent {
         const codeceptjsTools = createCodeceptJSTools(this.toolDeps, task);
         let assertionPerformed = false;
         let extensions = 0;
+        let deadlineReached = false;
         let shouldContinue = true;
         while (shouldContinue) {
             shouldContinue = false;
             await loop(async ({ stop, pause, iteration, userInput }) => {
+                if (opts.deadline != null && Date.now() >= opts.deadline) {
+                    deadlineReached = true;
+                    task.addNote('Time budget reached. Stopped');
+                    stop();
+                    return;
+                }
                 debugLog('iteration', iteration);
                 if (!(await this.explorer.recover()).ok) {
                     task.addNote('Browser page is unavailable');
@@ -369,6 +380,8 @@ export class Tester extends TaskAgent {
             });
             if (task.hasFinished)
                 break;
+            if (deadlineReached)
+                break;
             if (!(await this.explorer.recover()).ok)
                 break;
             const finalState = this.getCurrentState();
@@ -403,6 +416,10 @@ export class Tester extends TaskAgent {
         };
     }
     shouldAnalyzeProgress(iteration, currentState) {
+        if (this.regionTransitioned) {
+            this.regionTransitioned = false;
+            return true;
+        }
         if (this.consecutiveFailures >= 3)
             return true;
         if (this.consecutiveEmptyResults >= 2)
@@ -468,6 +485,11 @@ export class Tester extends TaskAgent {
         const currentUrl = currentState.url;
         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) {
+            this.regionTransitioned = true;
+        }
+        this.previousRegionPresent = currentState.overlay.present;
         this.previousUrl = currentUrl;
         this.previousStateHash = currentStateHash;
         let context = '';
@@ -491,13 +513,28 @@ export class Tester extends TaskAgent {
         }
         if (focusArea.detected) {
             const areaName = focusArea.name ? ` "${focusArea.name}"` : '';
+            let rootHint = '';
+            if (focusArea.root)
+                rootHint = `\nIts content lives inside \`${focusArea.root}\` — scope locators to it.`;
             context += dedent `
         <focus_scope>
-        A ${focusArea.type}${areaName} is currently open above the page.
+        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>
+      `;
+        }
+        if (!focusArea.detected && focusArea.present && isNewState) {
+            let rootHint = '';
+            if (focusArea.root)
+                rootHint = `\nIt lives inside \`${focusArea.root}\`.`;
+            context += dedent `
+        <area_of_interest>
+        A large new area "${focusArea.name || 'unnamed area'}" 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>
       `;
         }
         if (currentState.isInsideIframe) {
@@ -520,7 +557,7 @@ export class Tester extends TaskAgent {
             if (!alreadySeenUiMap) {
                 research = await this.researcher.research(currentState).catch(this.skipResearch);
             }
-            this.pageStateHash = currentStateHash;
+            this.pageStateHash = currentState.baseHash;
             this.pageActionResult = currentState;
             let uiMapSection = '';
             if (research) {
@@ -557,7 +594,7 @@ export class Tester extends TaskAgent {
       `;
             return context;
         }
-        if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
+        if (focusArea.present && focusArea.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

@@ -69,4 +69,5 @@ export declare function withdrawVisionTools(tools: Record<string, any>): void;
 export declare function clickFailureSuggestion(attempts: Array<{
     error?: string;
 }>): string;
+export declare function formatMatchedElements(error: Error | null | undefined): Promise<string | null>;
 export {};

package/dist/src/ai/tools.js

@@ -7,8 +7,9 @@ import { Stats } from "../stats.js";
 import { TestResult } from '../test-plan.js';
 import { LARGE_ARIA_CHANGE_THRESHOLD } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
+import { cleanHtmlSnippet } from "../utils/html.js";
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage } from "../utils/strings.js";
+import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
@@ -1161,6 +1162,8 @@ export function clickFailureSuggestion(attempts) {
     return "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
 }
 const MAX_DISAMBIGUATE_ELEMENTS = 10;
+const MAX_DISAMBIGUATE_TEXT = 80;
+const MAX_DISAMBIGUATE_HTML = 300;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
 async function extractWebElements(error) {
     if (!error || error.name !== 'MultipleElementsFound')
@@ -1172,8 +1175,9 @@ async function extractWebElements(error) {
     for (let i = 0; i < Math.min(elements.length, MAX_DISAMBIGUATE_ELEMENTS); i++) {
         try {
             const xpath = await elements[i].toAbsoluteXPath();
-            const html = await elements[i].toSimplifiedHTML();
-            result.push({ xpath, html });
+            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 });
         }
         catch (e) {
             debugLog('Failed to get details for element %d: %s', i, e);
@@ -1181,17 +1185,20 @@ async function extractWebElements(error) {
     }
     return result.length > 0 ? result : null;
 }
-async function formatMatchedElements(error) {
+function formatElementList(details) {
+    return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+}
+export async function formatMatchedElements(error) {
     const details = await extractWebElements(error);
     if (!details)
         return 'Could not fetch element details. Repeat the action to get better info.';
-    return details.map((el, i) => `Element ${i + 1}\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+    return formatElementList(details);
 }
 async function disambiguateElements(error, explanation, provider) {
     const elementDetails = await extractWebElements(error);
     if (!elementDetails)
         return null;
-    const elementList = elementDetails.map((el, i) => `Element ${i + 1}:\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+    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'),
     });

package/dist/src/api/request-result.d.ts

@@ -33,8 +33,10 @@ export declare class RequestResult {
     get rawResponseBody(): string;
     set rawResponseBodyValue(value: string);
     get responseBody(): any;
+    get isWrite(): boolean;
     save(outputDir: string): void;
     static load(requestFile: string): RequestResult;
+    toEndpoint(): string;
     toSummary(): string;
     extractIdAndTitle(): {
         id?: string | number;