explorbot 0.3.5 → 0.4.1

package/src/ai/fisherman.ts

@@ -13,6 +13,7 @@ import { dataProtectionRules } from './rules.ts';
 
 const MAX_ITERATIONS = 15;
 const MAX_TOOL_ROUNDTRIPS = 5;
+const REPEATED_FAILURE_LIMIT = 4;
 
 export class Fisherman implements Agent {
   emoji = '🎣';
@@ -20,21 +21,22 @@ export class Fisherman implements Agent {
   private apiClient: ApiClient;
   private requestStore: RequestStore;
   private specLoader: () => Promise<any | null>;
-  private cookieProvider: () => Promise<Record<string, string>>;
+  private browserHeaderProvider: () => Promise<Record<string, string>>;
   private configHeaders: Record<string, string>;
   private sessionName?: string;
   private baseEndpoint: string;
   private spec: any | null = null;
   private mode: 'replicate' | 'achieve' | 'disabled' = 'disabled';
   private hasApiConfig: boolean;
+  private scopeDegraded = false;
 
-  constructor(provider: Provider, apiClient: ApiClient, requestStore: RequestStore, specLoader: () => Promise<any | null>, baseEndpoint: string, cookieProvider: () => Promise<Record<string, string>>, configHeaders: Record<string, string> = {}, hasApiConfig = false) {
+  constructor(provider: Provider, apiClient: ApiClient, requestStore: RequestStore, specLoader: () => Promise<any | null>, baseEndpoint: string, browserHeaderProvider: () => Promise<Record<string, string>>, configHeaders: Record<string, string> = {}, 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';
@@ -77,10 +79,11 @@ export class Fisherman implements Agent {
     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));
@@ -90,7 +93,6 @@ export class Fisherman implements Agent {
         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)'}`);
@@ -100,6 +102,19 @@ export class Fisherman implements Agent {
           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();
@@ -145,14 +160,16 @@ export class Fisherman implements Agent {
   }
 
   private async refreshAuth(): Promise<void> {
-    const cookies = await this.cookieProvider();
-    if (Object.keys(cookies).length > 0) {
-      this.apiClient.setHeaders(cookies);
-    }
+    if (this.mode === 'replicate') {
+      const xhrHeaders = this.requestStore.extractAuthHeaders();
+      if (Object.keys(xhrHeaders).length > 0) {
+        this.apiClient.setHeaders(xhrHeaders);
+      }
 
-    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) {
@@ -161,31 +178,25 @@ export class Fisherman implements Agent {
   }
 
   private buildEndpointList(scopeUrl?: string): string {
+    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 scoped = this.requestStore.toEndpointList(scopeUrl || '/');
+    if (scoped) return scoped;
 
-    const seen = new Set<string>();
-    const lines: string[] = [];
-
-    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');
+    this.scopeDegraded = true;
+    return this.requestStore.toEndpointList();
   }
 
   private buildSystemPrompt(endpointList: string, toolNames: string[], scopeUrl?: string): string {
-    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.
@@ -210,12 +221,21 @@ export class Fisherman implements Agent {
       - 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}
     `;
   }
 
+  private isStuckOnEndpoint(ledgerStart: number): boolean {
+    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);
+  }
+
   private buildTaskPrompt(instructions: string): string {
     return dedent`
       Prepare the following test data:

package/src/ai/historian/codeceptjs.ts

@@ -64,7 +64,7 @@ export function WithCodeceptJS<T extends Constructor>(Base: T) {
       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/src/ai/historian/playwright.ts

@@ -98,7 +98,7 @@ export function WithPlaywright<T extends Constructor>(Base: T) {
       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/src/ai/navigator.ts

@@ -575,7 +575,7 @@ class Navigator implements Agent {
     }
 
     const currentActionResult = actionResult || ActionResult.fromState(state);
-    const research = Researcher.getCachedResearch(state) || '';
+    const research = Researcher.getCachedResearch(currentActionResult) || '';
     const combinedHtml = await currentActionResult.combinedHtml();
 
     const history = stateManager.getStateHistory();

package/src/ai/pilot.ts

@@ -765,6 +765,7 @@ export class Pilot implements Agent {
             const parts = [c.type];
             if (c.title) 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(', ')}`;
@@ -827,7 +828,13 @@ export class Pilot implements Agent {
 
     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');
     }
@@ -1133,6 +1140,7 @@ export class Pilot implements Agent {
       Diagnostic patterns (use <state>, executed/element/skipped fields, ariaDiff):
       - Click failed + button in "disabled buttons" → required field missing. Instruct fill first.
       - "modal: none" but Tester targets a modal → modal closed; re-trigger.
+      - "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/src/ai/planner.ts

@@ -114,11 +114,15 @@ export class Planner extends PlannerBase implements Agent {
       Tests must be relevant to the page
       Tests must be achievable from UI
       Tests must be verifiable from UI
-      NEVER split one workflow into multiple tests. Each test must be a complete end-to-end flow.
+      One test verifies ONE business operation: the steps that reach it, the action itself, and its verification.
+      Steps that only reach the action — opening a form, expanding a panel, creating or locating the item to act on — belong to that test. A second operation with its own verification does not.
       Bad: "Open delete dropdown" + "Confirm deletion" — these are ONE test, not two.
       Bad: "Search for X" + "Verify search results" — searching and verifying is ONE test.
       Bad: "Leave field empty" + "Click submit" — that's one negative test, not two.
-      If two scenarios cannot run independently (one requires the other to run first), merge them into one.${featureDirective}${focusExistingDataDirective}
+      Bad: "Create a record, rename it, delete it" — three verified operations, so THREE tests, not one.
+      Good: "Rename existing record and verify the new title" — ONE test; creating is skipped, we assume record already exists, only the rename is verified.
+      You may rely on another test having run first in case we deal with empty state and no relevant data was created yet and we expect another our test creates it
+      When the page reports a record is missing or unavailable, it is not a testable surface — plan list-level or recovery behavior instead of operations on that record.${featureDirective}${focusExistingDataDirective}
     </task>
 
     ${customPrompt || ''}
@@ -195,10 +199,6 @@ export class Planner extends PlannerBase implements Agent {
         throw new Error('No tasks were created successfully');
       }
 
-      if (aiResult.object.scenarios.length === 0 && !this.currentPlan) {
-        throw new Error('No tasks were created successfully');
-      }
-
       const defaultStartUrl = this.getDefaultStartUrl(state);
       const fromPlanning = aiResult.object.scenarios.map((s: any) => new Test(s.scenario, s.priority, s.expectedOutcomes, s.startUrl || defaultStartUrl, s.steps || []));
 
@@ -335,6 +335,7 @@ export class Planner extends PlannerBase implements Agent {
       <task>
       Based on the page research, create ${this.MIN_TASKS}-${this.MAX_TASKS} exploratory testing scenarios.
       For each scenario provide specific steps and expected outcomes.
+      Exception: if the page reports the requested resource is missing, shows a failure state, or holds no content and no controls, return an empty scenarios list. Never invent tests for a page with nothing to exercise.
       </task>
 
       <rules>
@@ -348,13 +349,13 @@ export class Planner extends PlannerBase implements Agent {
       Focus on error or success messages as outcome.
       Focus on URL page change or data persistency after page reload.
       If there are subpages (pages with same URL path) plan testing of those subpages as well
-      If you plan to test CRUD operations, plan them in correct order: create, read, update.
+      Plan CRUD operations in order: create, read, update, delete.
       Do not invent specific route names, success messages, validation texts, badge counts, or welcome messages unless they are visible in research, visited pages, or prior observed flows.
       When validation placement or wording was not observed, require feedback associated with the invalid input without inventing a specific location or message.
       If exact wording is unknown, describe the expected result generically, for example "an authentication error is shown" or "the user stays on the login page" instead of guessing the literal text.
       If exact redirect destination is unknown, describe the destination by visible page identity, for example "the dashboard page opens" or "the current workspace home page opens" instead of inventing a URL slug.
       Only propose scenarios whose prerequisites are evident from page research, visited pages, or API data preparation context.
-      If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible or API preconditions can create it.
+      If a scenario needs existing records, recipients, results, notifications, or other target data, propose it only when that data is visible, API preconditions can create it, or the scenario itself creates the record as its setup.
       If the page appears read-only, degraded, demo-limited, maintenance-like, or lacks write controls, prefer read-only scenarios such as opening panels, inspecting visible lists, filtering, searching, or verifying current state.
       Do not assume hidden data exists just because a control is present.
       For scenarios that act on existing items or search/filter by existing values, use only item names or values visible in research, visited pages, or prior observed flows.

package/src/ai/provider.ts

@@ -426,10 +426,20 @@ 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: ModelMessage[] = [];
     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: ModelMessage[] = [];
+          const onStepEnd = (step: any) => {
+            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;
@@ -448,6 +458,8 @@ export class Provider {
 
       clearActivity();
 
+      withExecutedSteps(response, executedStepMessages);
+
       // Log tool usage summary
       if (response.toolCalls && response.toolCalls.length > 0) {
         responseLog(response.toolCalls);
@@ -462,12 +474,13 @@ export class Provider {
     } catch (error: any) {
       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);
@@ -703,6 +716,11 @@ function repairToolCall(options: ToolCallRepairOptions): any | null {
   return repairHarmonyChannel(options);
 }
 
+function withExecutedSteps(result: any, executed: ModelMessage[]): any {
+  if (executed.length === 0) return result;
+  return Object.defineProperty(result, 'responseMessages', { value: [...executed, ...(result.responseMessages || [])], configurable: true, enumerable: true });
+}
+
 function withInvalidRequestFeedback(messages: ModelMessage[], error: unknown): ModelMessage[] {
   if (!(error instanceof APICallError) || error.statusCode !== 400) return messages;
   tag('warning').log('Provider rejected the request as invalid — relaying its reason before the retry');

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

@@ -89,8 +89,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
 
     async researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null> {
       const focusArea = current.overlay;
-      if (!focusArea.detected || !focusArea.name) return null;
-      if (focusArea.type !== 'dialog' && focusArea.type !== 'modal') return null;
+      if (!focusArea.present || !focusArea.name) return null;
 
       const cached = getCachedResearch(pageStateHash);
       if (!cached) return null;

package/src/ai/researcher.ts

@@ -76,7 +76,8 @@ export class Researcher extends ResearcherBase implements Agent {
   }
 
   static getCachedResearch(state: WebPageState): string {
-    return getCachedResearch(state.hash || '');
+    if (state instanceof ActionResult) return getCachedResearch(state.baseHash);
+    return getCachedResearch(ActionResult.fromState(state).baseHash);
   }
 
   getSystemMessage(): string {
@@ -96,7 +97,7 @@ export class Researcher extends ResearcherBase implements Agent {
     const maxRetries = (this.config.ai?.agents?.researcher as any)?.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) {
@@ -268,7 +269,7 @@ export class Researcher extends ResearcherBase implements Agent {
 
       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/src/ai/rules.ts

@@ -154,11 +154,11 @@ export const protectionRule = dedent`
 
   Pre-existing data on the page belongs to the application, not the test.
   Items that were not created inside the current test scenario must not be deleted, removed, emptied, reset, archived, or otherwise destroyed.
-  If a scenario needs to verify destructive behaviour, the same scenario must first create a disposable target and then destroy that specific target — never operate on data that was already there when the test started.
+  If a scenario needs to verify destructive behaviour, the same scenario must first create its own target and then destroy that specific target — never operate on data that was already there when the test started.
 
   The resource that the current page URL represents is "under test".
   The test must not destroy the resource it is running against — doing so invalidates every subsequent scenario that starts on the same URL.
-  Do not propose or perform delete/remove/archive actions on the entity that owns the current URL; propose such actions only on disposable children created within the scenario itself.
+  Do not propose or perform delete/remove/archive actions on the entity that owns the current URL; propose such actions only on children created within the scenario itself.
   </important>
 `;
 
@@ -174,7 +174,7 @@ export const dataProtectionRules = dedent`
   filter, tab, or list-inspection constraint. Use visible existing data when it is available.
   If no suitable data exists, report the missing precondition instead of creating data.
 
-  Destructive actions are allowed only against disposable data created by the current scenario
+  Destructive actions are allowed only against data created by the current scenario
   or prepared for that scenario by Fisherman/API preconditions. Existing application data must
   remain unchanged.
   </data_protection_rules>

package/src/ai/tester.ts

@@ -63,6 +63,8 @@ export class Tester extends TaskAgent implements Agent {
   private seenUiMapUrls = new Set<string>();
   private lastAnalyzedStateHash: string | null = null;
   private stalledIterations = 0;
+  private previousRegionPresent: boolean | null = null;
+  private regionTransitioned = false;
   private readonly MAX_STALLED_ITERATIONS = 3;
 
   private skipResearch = (err: Error): string => {
@@ -117,6 +119,8 @@ export class Tester extends TaskAgent implements Agent {
     this.seenUiMapUrls.clear();
     this.lastAnalyzedStateHash = null;
     this.stalledIterations = 0;
+    this.previousRegionPresent = null;
+    this.regionTransitioned = false;
     this.stateManager.clearHistory();
     this.resetFailureCount();
     this.pilot?.reset();
@@ -246,6 +250,7 @@ export class Tester extends TaskAgent implements Agent {
     const codeceptjsTools = createCodeceptJSTools(this.toolDeps, task);
     let assertionPerformed = false;
     let extensions = 0;
+    let deadlineReached = false;
     let shouldContinue = true;
 
     while (shouldContinue) {
@@ -253,6 +258,12 @@ export class Tester extends TaskAgent implements Agent {
 
       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');
@@ -420,6 +431,7 @@ export class Tester extends TaskAgent implements Agent {
       );
 
       if (task.hasFinished) break;
+      if (deadlineReached) break;
 
       if (!(await this.explorer.recover()).ok) break;
 
@@ -460,6 +472,10 @@ export class Tester extends TaskAgent implements Agent {
   }
 
   private shouldAnalyzeProgress(iteration: number, currentState: ActionResult): boolean {
+    if (this.regionTransitioned) {
+      this.regionTransitioned = false;
+      return true;
+    }
     if (this.consecutiveFailures >= 3) return true;
     if (this.consecutiveEmptyResults >= 2) return true;
     if (iteration % this.progressCheckInterval !== 0) return false;
@@ -530,6 +546,12 @@ export class Tester extends TaskAgent implements Agent {
     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;
@@ -557,9 +579,11 @@ export class Tester extends TaskAgent implements Agent {
 
     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}.
@@ -567,6 +591,18 @@ export class Tester extends TaskAgent implements Agent {
       `;
     }
 
+    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) {
       const iframeInfo = currentState.iframeURL || 'iframe context active';
       context += dedent`
@@ -589,7 +625,7 @@ export class Tester extends TaskAgent implements Agent {
       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) {
@@ -627,7 +663,7 @@ export class Tester extends TaskAgent implements Agent {
       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`
@@ -1172,4 +1208,5 @@ interface TestSessionHandlers {
 
 export interface TestOptions {
   startOnCurrentPage?: boolean;
+  deadline?: number;
 }

package/src/ai/tools.ts

@@ -8,8 +8,9 @@ import { Stats } from '../stats.ts';
 import { type Task, TestResult } from '../test-plan.js';
 import { LARGE_ARIA_CHANGE_THRESHOLD } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
+import { cleanHtmlSnippet } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage } from '../utils/strings.ts';
+import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
@@ -1332,20 +1333,23 @@ export function clickFailureSuggestion(attempts: Array<{ error?: string }>): str
 }
 
 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: Error | null | undefined): Promise<Array<{ xpath: string; html: string }> | null> {
+async function extractWebElements(error: Error | null | undefined): Promise<Array<{ xpath: string; html: string; text: string }> | null> {
   if (!error || error.name !== 'MultipleElementsFound') return null;
 
-  const elements = (error as any).webElements as Array<{ toAbsoluteXPath: () => Promise<string>; toSimplifiedHTML: () => Promise<string> }> | undefined;
+  const elements = (error as any).webElements as Array<{ toAbsoluteXPath: () => Promise<string>; toOuterHTML: () => Promise<string>; getText: () => Promise<string | null> }> | undefined;
   if (!elements?.length) return null;
 
-  const result: Array<{ xpath: string; html: string }> = [];
+  const result: Array<{ xpath: string; html: string; text: string }> = [];
   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);
     }
@@ -1353,17 +1357,21 @@ async function extractWebElements(error: Error | null | undefined): Promise<Arra
   return result.length > 0 ? result : null;
 }
 
-async function formatMatchedElements(error: Error | null | undefined): Promise<string | null> {
+function formatElementList(details: Array<{ xpath: string; html: string; text: string }>): string {
+  return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+}
+
+export async function formatMatchedElements(error: Error | null | undefined): Promise<string | null> {
   const details = await extractWebElements(error);
   if (!details) return 'Could not fetch element details. Repeat the action to get better info.';
-  return details.map((el, i) => `Element ${i + 1}\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+  return formatElementList(details);
 }
 
 async function disambiguateElements(error: Error | null | undefined, explanation: string, provider: AIProvider): Promise<{ position: number; xpath: string } | null> {
   const elementDetails = await extractWebElements(error);
   if (!elementDetails) return null;
 
-  const elementList = 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/src/api/request-result.ts

@@ -85,6 +85,10 @@ export class RequestResult {
     }
   }
 
+  get isWrite(): boolean {
+    return ['POST', 'PUT', 'PATCH', 'DELETE'].includes(this.method);
+  }
+
   save(outputDir: string): void {
     const requestsDir = path.join(outputDir, 'requests');
     if (!existsSync(requestsDir)) {
@@ -169,7 +173,7 @@ export class RequestResult {
       statusText: meta.statusText || '',
       responseHeaders: meta.responseHeaders || {},
       timing: Number.parseInt(meta.timing) || 0,
-      timestamp: new Date(meta.timestamp || Date.now()),
+      timestamp: new Date(meta.timestamp || 0),
     });
 
     result.requestFile = requestFile;
@@ -178,8 +182,12 @@ export class RequestResult {
     return result;
   }
 
+  toEndpoint(): string {
+    return `${this.method} ${this.path}`;
+  }
+
   toSummary(): string {
-    return `${this.method} ${this.path} → ${this.status} (${this.timing}ms)`;
+    return `${this.toEndpoint()} → ${this.status} (${this.timing}ms)`;
   }
 
   extractIdAndTitle(): { id?: string | number; title?: string } {