explorbot 0.3.4 → 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');
@@ -1005,6 +1016,8 @@ export class Pilot {
       state), instruct Tester to verify() and finish(). If goal was already true at the start, propose
       different input data so the test is meaningful. If Tester repeats the same successful action, STOP.
 
+      If needed you should pick the exact item the scenario should act on (from the page, or precondition() one) and pass it to tester
+
       Action classification: GOAL-ADVANCING actions mutate the scenario's subject data (create/edit/delete/submit/verify).
       VIEW-ONLY actions toggle filters/tabs/sort/collapse without changing data. One VIEW-ONLY to reveal a
       target is fine; ≥2 consecutive VIEW-ONLY actions with no GOAL-ADVANCING action in between is thrashing
@@ -1022,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/planner.js

@@ -24,7 +24,7 @@ const TasksSchema = z.object({
     planName: z.string().describe('Short descriptive name for the test plan (e.g., "User Authentication Testing", "Product Catalog Navigation", "Form Validation Tests")'),
     scenarios: z
         .array(z.object({
-        scenario: z.string().describe('A single sentence describing what to test'),
+        scenario: z.string().describe('A single sentence describing the behavior to test.'),
         priority: z.enum(['critical', 'important', 'high', 'normal', 'low']).describe('Priority of the task based on business importance'),
         startUrl: z.string().nullable().describe('Start URL for the test if different from plan URL. Use only stable feature/list/detail pages, not transient create/edit/modal URLs unless the scenario specifically starts inside that form.'),
         steps: z.array(z.string()).describe('List of steps to perform for this scenario. Each step should be a specific action (e.g., "Open the form", "Enter required data", "Submit the form"). Keep steps atomic and actionable.'),

package/dist/src/ai/provider.js

@@ -2,7 +2,8 @@ import { OpenTelemetry } from '@ai-sdk/otel';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { generateObject, generateText, isStepCount, registerTelemetry, tool } from 'ai';
+import dedent from 'dedent';
+import { APICallError, generateObject, generateText, isStepCount, registerTelemetry, tool } from 'ai';
 import { z } from 'zod';
 import { clearActivity, setActivity } from "../activity.js";
 import { configuredModels, modelName as getModelName } from '../config.js';
@@ -382,9 +383,28 @@ export class Provider {
         if (extraStop)
             stopConditions.push(extraStop);
         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, ...config, abortSignal: signal }), config.timeout || 30000));
+                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;
+                        attemptMessages = amended;
+                    }
+                    throw error;
+                }));
                 this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
                 const hasToolCall = (result.toolCalls?.length || 0) > 0;
                 if (!result.text && !hasToolCall && result.finishReason === 'length') {
@@ -393,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);
@@ -406,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);
@@ -620,6 +642,27 @@ 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;
+    tag('warning').log('Provider rejected the request as invalid — relaying its reason before the retry');
+    return [
+        ...messages,
+        {
+            role: 'user',
+            content: dedent `
+        The previous request was rejected by the provider as invalid:
+        "${error.message}"
+        Fix what it describes and re-issue the request.
+      `,
+        },
+    ];
+}
 function repairChannelMarker({ toolCall, tools }) {
     const markerIndex = toolCall.toolName.indexOf('<|channel|>');
     if (markerIndex <= 0)

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 {};