explorbot 0.1.28 → 0.1.30

package/dist/src/ai/planner.js

@@ -19,7 +19,7 @@ import { WithSubPages, getPlannedByStateHash, getRegisteredPlan, registerPlan }
 import { POSSIBLE_SECTIONS, Researcher } from "./researcher.js";
 import { findSimilarStateHash } from "./researcher/cache.js";
 import { hasFocusedSection } from "./researcher/focus.js";
-import { fileUploadRule, protectionRule } from "./rules.js";
+import { capabilityGroundingRule, dataProtectionRules, fileUploadRule } from "./rules.js";
 const debugLog = createDebug('explorbot:planner');
 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")'),
@@ -27,7 +27,7 @@ const TasksSchema = z.object({
         .array(z.object({
         scenario: z.string().describe('A single sentence describing what 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 (only for tests on visited subpages)'),
+        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.'),
         expectedOutcomes: z
             .array(z.string())
@@ -73,6 +73,9 @@ export class Planner extends PlannerBase {
         const featureDirective = feature
             ? `\n    IMPORTANT: The user requested to focus specifically on: "${feature}"\n    ALL scenarios MUST be directly related to this feature. Do not propose generic page tests unrelated to it.\n    Use the user's exact wording to guide scenario names — do not substitute different entities (e.g., do not plan "suite" actions when user said "test").`
             : '';
+        const focusExistingDataDirective = feature
+            ? '\n    If this focus asks for search, filter, tabs, sorting, or list behavior involving existing items, only use item names/values visible in the provided page research. If no concrete visible item names/values are present, do NOT propose scenarios that require an existing known item; propose no-match search, empty-state, clear-search, tab/filter empty-list, or other read-only list behavior instead.'
+            : '';
         return dedent `
     <role>
     You are ISTQB certified senior manual QA planning exploratory testing session of a web application.
@@ -96,7 +99,7 @@ export class Planner extends PlannerBase {
       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}
+      If two scenarios cannot run independently (one requires the other to run first), merge them into one.${featureDirective}${focusExistingDataDirective}
     </task>
 
     ${customPrompt || ''}
@@ -301,6 +304,11 @@ export class Planner extends PlannerBase {
       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 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.
+      If the list is empty or no concrete item names are visible, do not invent "known" or "existing" items. Prefer empty-state, no-match search, clear-search, or read-only list behavior scenarios.
+      Search, filter, sorting, tab, and list scenarios must start from a stable page where those controls are visible; avoid transient create/edit/new URLs unless the scenario tests that form.
+      For option values and list items, use only visible or previously observed data; do not add create/update/delete setup unless the user explicitly requests that workflow.
+      Detail-view scenarios must target visible data entities from list rows, cards, tree nodes, or detail links; do not use filter tabs, counters, status tabs, breadcrumbs, or navigation controls as detail targets.
       DO NOT propose "verification-only" tests that merely open a UI element (modal, dropdown, panel) and check it exists.
       Every test must complete a meaningful action that changes application state or produces a business outcome.
       Opening a modal is NOT a test — performing an action INSIDE the modal IS a test.
@@ -311,7 +319,8 @@ export class Planner extends PlannerBase {
       Tests that only switch views, toggle filters, or paginate are LESS valuable — propose them only after data-changing tests are covered.
       If multiple ways to create or modify data exist (different types, different forms), propose a separate test for each.
       </priority_order>
-      ${protectionRule}
+      ${capabilityGroundingRule}
+      ${dataProtectionRules}
       ${fileUploadRule}
       </rules>
 
@@ -466,7 +475,9 @@ export class Planner extends PlannerBase {
                 .join('\n')}
 
         You MAY propose tests starting from these pages if they are relevant to the plan "${this.currentPlan.title}".
-        Set startUrl for such tests. Ignore pages that belong to a different feature area.
+        Set startUrl for such tests only when the page is a stable feature/list/detail page.
+        Do not use create/edit/new/modal URLs as startUrl for scenarios that need the underlying page.
+        Ignore pages that belong to a different feature area.
         </context_from_previous_tests>
 
         Propose ONLY new scenarios that are NOT in the existing tests list.

package/dist/src/ai/provider.js

@@ -1,6 +1,7 @@
+import { OpenTelemetry } from '@ai-sdk/otel';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
-import { generateObject, generateText, stepCountIs } from 'ai';
+import { generateObject, generateText, isStepCount, registerTelemetry } from 'ai';
 import { clearActivity, setActivity } from "../activity.js";
 import { executionController } from "../execution-controller.js";
 import { Observability } from "../observability.js";
@@ -16,10 +17,11 @@ class AiError extends Error {
 }
 export class ContextLengthError extends Error {
 }
+let telemetryRegistered = false;
 function extractCachedTokens(usage) {
     if (!usage)
         return 0;
-    const direct = usage.cachedInputTokens ?? usage.inputTokenDetails?.cacheReadTokens;
+    const direct = usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens;
     if (typeof direct === 'number')
         return direct;
     const raw = usage.raw;
@@ -78,7 +80,7 @@ export class Provider {
             await generateText({
                 model: this.config.model,
                 prompt: 'hi',
-                maxTokens: 1,
+                maxOutputTokens: 1,
             });
         }
         catch (error) {
@@ -100,6 +102,18 @@ export class Provider {
         }
         return this.config.agenticModel || this.config.model;
     }
+    getConfiguredModels() {
+        const models = { model: this.getModelName(this.config.model) };
+        if (this.config.agenticModel)
+            models.agenticModel = this.getModelName(this.config.agenticModel);
+        if (this.config.visionModel)
+            models.visionModel = this.getModelName(this.config.visionModel);
+        for (const [agent, agentConfig] of Object.entries(this.config.agents || {})) {
+            if (agentConfig?.model)
+                models[agent] = this.getModelName(agentConfig.model);
+        }
+        return models;
+    }
     getSystemPromptForAgent(agentName, currentUrl) {
         const agentConfig = this.config.agents?.[agentName];
         const parts = [];
@@ -116,6 +130,12 @@ export class Provider {
         const agentConfig = this.config.agents?.[agentName];
         return agentConfig?.providerOptions;
     }
+    getReasoningForAgent(agentName) {
+        if (!agentName)
+            return undefined;
+        const agentConfig = this.config.agents?.[agentName];
+        return agentConfig?.reasoning;
+    }
     getRetryOptions(options = {}) {
         return {
             ...this.defaultRetryOptions,
@@ -133,6 +153,13 @@ export class Provider {
             providerOptions: { ...config.providerOptions, ...agentOptions },
         };
     }
+    finalizeConfig(config, options, telemetry) {
+        if (telemetry)
+            config.telemetry = telemetry;
+        const reasoning = this.getReasoningForAgent(options.agentName);
+        if (reasoning)
+            config.reasoning ??= reasoning;
+    }
     initLangfuse() {
         const langfuseConfig = this.config.langfuse;
         const publicKey = langfuseConfig?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
@@ -152,6 +179,10 @@ export class Provider {
             instrumentations: [],
         });
         void this.otelSdk.start();
+        if (!telemetryRegistered) {
+            registerTelemetry(new OpenTelemetry());
+            telemetryRegistered = true;
+        }
         this.telemetryEnabled = true;
     }
     getTelemetry(options) {
@@ -159,18 +190,18 @@ export class Provider {
             return undefined;
         }
         const runTelemetry = Observability.getTelemetry();
-        if (!options.experimental_telemetry) {
-            return runTelemetry || { isEnabled: true };
+        if (!options.telemetry) {
+            return runTelemetry;
         }
         if (!runTelemetry) {
-            return options.experimental_telemetry;
+            return options.telemetry;
         }
         return {
             ...runTelemetry,
-            ...options.experimental_telemetry,
+            ...options.telemetry,
             metadata: {
                 ...runTelemetry.metadata,
-                ...options.experimental_telemetry.metadata,
+                ...options.telemetry.metadata,
             },
         };
     }
@@ -210,13 +241,14 @@ export class Provider {
         promptLog(`Using model: ${modelName}`);
         const telemetry = this.getTelemetry(options);
         const config = this.mergeProviderOptions({
-            maxTokens: 16384,
+            maxOutputTokens: 16384,
+            allowSystemInMessages: true,
             ...(this.config.config || {}),
             ...options,
-            ...(telemetry ? { experimental_telemetry: telemetry } : {}),
             model,
             abortSignal: executionController.getAbortSignal(),
         }, options.agentName);
+        this.finalizeConfig(config, options, telemetry);
         promptLog(messages[messages.length - 1].content);
         try {
             const response = await withRetry(async () => {
@@ -224,7 +256,7 @@ export class Provider {
                 if (!result.text) {
                     debugLog(result);
                     if (result.finishReason === 'length') {
-                        throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxTokens in config or use a model with higher output capacity.');
+                        throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
                     }
                     throw new Error('No response text from AI');
                 }
@@ -277,21 +309,22 @@ export class Provider {
         const telemetry = this.getTelemetry(options);
         const maxRoundtrips = options.maxToolRoundtrips ?? 5;
         const extraStop = options.stopWhen;
-        const stopConditions = [stepCountIs(maxRoundtrips)];
+        const stopConditions = [isStepCount(maxRoundtrips)];
         if (extraStop)
             stopConditions.push(extraStop);
         const { stopWhen: _ignoredStopWhen, ...optionsWithoutStop } = options;
         const config = this.mergeProviderOptions({
             tools,
-            maxTokens: 16384,
+            maxOutputTokens: 16384,
             toolChoice: 'auto',
+            allowSystemInMessages: true,
             ...(this.config.config || {}),
             ...optionsWithoutStop,
             stopWhen: stopConditions,
-            ...(telemetry ? { experimental_telemetry: telemetry } : {}),
             model,
             abortSignal: executionController.getAbortSignal(),
         }, options.agentName);
+        this.finalizeConfig(config, options, telemetry);
         try {
             const response = await withRetry(async () => {
                 const timeout = config.timeout || 30000;
@@ -306,7 +339,7 @@ export class Provider {
                     ]));
                     const hasToolCall = (result.toolCalls?.length || 0) > 0;
                     if (!result.text && !hasToolCall && result.finishReason === 'length') {
-                        throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxTokens in config or use a model with higher output capacity.');
+                        throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
                     }
                     return result;
                 }
@@ -365,12 +398,13 @@ export class Provider {
         const telemetry = this.getTelemetry(options);
         const config = this.mergeProviderOptions({
             schema,
+            allowSystemInMessages: true,
             ...(this.config.config || {}),
             ...options,
-            ...(telemetry ? { experimental_telemetry: telemetry } : {}),
             model: modelToUse,
             abortSignal: executionController.getAbortSignal(),
         }, options.agentName);
+        this.finalizeConfig(config, options, telemetry);
         try {
             promptLog(messages[messages.length - 1].content);
             const response = await withRetry(async () => {
@@ -552,12 +586,13 @@ export class Provider {
         ];
         const telemetry = this.getTelemetry({});
         const config = {
-            maxTokens: 16384,
+            maxOutputTokens: 16384,
             ...(this.config.config || {}),
-            ...(telemetry ? { experimental_telemetry: telemetry } : {}),
             model: this.config.visionModel,
             abortSignal: executionController.getAbortSignal(),
         };
+        if (telemetry)
+            config.telemetry = telemetry;
         try {
             promptLog(`Processing image with prompt: ${prompt}`);
             const response = await withRetry(async () => {

package/dist/src/ai/quartermaster.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { z } from 'zod';
 import { ConfigParser } from "../config.js";
 import { createDebug, tag } from "../utils/logger.js";
-import { CODECEPT_TOOLS } from "./tools.js";
+import { isCodeceptToolName } from "../utils/step-analyzer.js";
 const debugLog = createDebug('explorbot:quartermaster');
 export class Quartermaster {
     provider;
@@ -88,7 +88,7 @@ export class Quartermaster {
             const stateHash = initialState.getStateHash();
             const pageAnalysis = this.pageAnalyses.get(stateHash);
             const toolExecutions = conversation.getToolExecutions();
-            const codeceptExecutions = toolExecutions.filter((e) => CODECEPT_TOOLS.includes(e.toolName));
+            const codeceptExecutions = toolExecutions.filter((e) => isCodeceptToolName(e.toolName));
             if (codeceptExecutions.length === 0 && !pageAnalysis?.axeViolations.length) {
                 debugLog('No interactions or violations to analyze');
                 return null;

package/dist/src/ai/researcher.js

@@ -47,6 +47,12 @@ export class Researcher extends ResearcherBase {
         this.stateManager = explorer.getStateManager();
         this.experienceTracker = this.stateManager.getExperienceTracker();
         this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
+        const ai = explorer.getConfig().ai;
+        if (ai) {
+            ai.agents ??= {};
+            ai.agents.researcher ??= {};
+            ai.agents.researcher.reasoning ??= 'low';
+        }
     }
     getNavigator() {
         throw new Error('not implemented');
@@ -139,7 +145,7 @@ export class Researcher extends ResearcherBase {
             catch (error) {
                 if (!(error instanceof ContextLengthError) || retriesLeft <= 0) {
                     if (error instanceof ContextLengthError) {
-                        tag('warning').log('Output truncated. Try lowering reasoning effort or increasing maxTokens in ai.config.');
+                        tag('warning').log('Output truncated. Try lowering reasoning effort or increasing maxOutputTokens in ai.config.');
                     }
                     throw error;
                 }

package/dist/src/ai/rules.js

@@ -147,6 +147,50 @@ export const protectionRule = dedent `
   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.
   </important>
 `;
+export const dataProtectionRules = dedent `
+  <data_protection_rules>
+  ${protectionRule}
+
+  If the user request, scenario, focus, or test instructions explicitly prohibit creating,
+  editing, updating, deleting, removing, or otherwise mutating data, do not perform those
+  actions through the UI, API preconditions, cleanup, fallback steps, or Fisherman.
+
+  Do not use Fisherman or API data preparation to bypass a no-mutation, read-only, search,
+  filter, tab, or list-inspection constraint. Use visible existing data when it is available.
+  If no suitable data exists, report the missing precondition instead of creating data.
+
+  Destructive actions are allowed only against disposable data created by the current scenario
+  or prepared for that scenario by Fisherman/API preconditions. Existing application data must
+  remain unchanged.
+  </data_protection_rules>
+`;
+export const capabilityGroundingRule = dedent `
+  <capability_grounding>
+  When a scenario depends on a named action, menu item, status, option, workflow, or feature,
+  that capability must be visible or explicitly confirmed in the current research/page context
+  for the same target entity type.
+
+  Do not transfer capabilities between similar entities, rows, lists, detail pages, or menus.
+  Do not replace a requested action with a synonym or related action unless the UI explicitly
+  shows that action for the target entity.
+
+  When an action is described as applying to an item, row, card, record, node, or entity,
+  the target must be grounded as that kind of data entity in the current context. Do not use
+  navigation links, filter tabs, counters, breadcrumbs, headings, toolbar controls, or other
+  page controls as the subject of row/entity actions.
+
+  When a scenario asks to open, view, inspect, or navigate to an entity detail view, success
+  requires evidence of that entity detail context. An active filter, selected tab, visible count,
+  or filtered list is not enough to prove an entity detail view opened.
+
+  Do not rewrite a scenario goal to match a similar outcome that happened accidentally. If the
+  requested entity detail/action/workflow was not achieved, report that mismatch instead of
+  passing the test for a related filter, tab, navigation, or status view.
+
+  If the required capability is not available for the target entity after reasonable discovery,
+  record the missing capability and stop instead of repeatedly trying unrelated locators.
+  </capability_grounding>
+`;
 export const focusedElementRule = dedent `
   <focused_element_actions>
   When a text input element is focused (textbox, combobox, contenteditable):

package/dist/src/ai/tester.js

@@ -14,7 +14,7 @@ import { ErrorPageError, isErrorPage } from "../utils/error-page.js";
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
-import { actionRule, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, protectionRule, sectionContextRule } from "./rules.js";
+import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from "./rules.js";
 import { TaskAgent } from "./task-agent.js";
 import { createCodeceptJSTools, createSpecialContextTools } from "./tools.js";
 const debugLog = createDebug('explorbot:tester');
@@ -29,7 +29,7 @@ const SAMPLE_FILES = {
     'MP3 audio': 'sample.mp3',
 };
 export class Tester extends TaskAgent {
-    ACTION_TOOLS = ['click', 'pressKey', 'form'];
+    ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
     SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
     emoji = '🧪';
     explorer;
@@ -51,6 +51,8 @@ export class Tester extends TaskAgent {
     hooksRunner;
     seenUiMapUrls = new Set();
     lastAnalyzedStateHash = null;
+    stalledIterations = 0;
+    MAX_STALLED_ITERATIONS = 3;
     constructor(explorer, provider, researcher, navigator, agentTools) {
         super();
         this.explorer = explorer;
@@ -99,6 +101,7 @@ export class Tester extends TaskAgent {
         this.pageActionResult = null;
         this.seenUiMapUrls.clear();
         this.lastAnalyzedStateHash = null;
+        this.stalledIterations = 0;
         this.explorer.getStateManager().clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
@@ -293,6 +296,10 @@ export class Tester extends TaskAgent {
                         task.addNote(`Failed to ${execution.input.explanation} (${execution.toolName})`, TestResult.FAILED);
                     });
                 }
+                if (this.shouldStopForStalledExecution(task, currentState, result?.toolExecutions || [])) {
+                    stop();
+                    return;
+                }
                 if (assertionPerformed) {
                     const message = result?.toolExecutions?.find((execution) => execution.toolName === 'verify')?.output?.message || '';
                     task.addNote(message, wasSuccessful ? TestResult.PASSED : TestResult.FAILED);
@@ -395,6 +402,28 @@ export class Tester extends TaskAgent {
             return false;
         return true;
     }
+    shouldStopForStalledExecution(task, previousState, toolExecutions) {
+        if (task.hasFinished)
+            return false;
+        const currentState = this.getCurrentState();
+        const stateChanged = previousState.url !== currentState.url || previousState.hash !== currentState.hash;
+        const actionTools = [...this.ACTION_TOOLS, ...this.SPECIAL_CONTEXT_ACTION_TOOLS];
+        const hasSuccessfulAction = toolExecutions.some((execution) => execution.wasSuccessful && actionTools.includes(execution.toolName));
+        const hasSuccessfulAssertion = toolExecutions.some((execution) => execution.wasSuccessful && this.ASSERTION_TOOLS.includes(execution.toolName));
+        if (stateChanged || hasSuccessfulAction || hasSuccessfulAssertion) {
+            this.stalledIterations = 0;
+            return false;
+        }
+        const hasNoBrowserProgress = toolExecutions.length === 0 || toolExecutions.every((execution) => !actionTools.includes(execution.toolName) || !execution.wasSuccessful);
+        if (!hasNoBrowserProgress)
+            return false;
+        this.stalledIterations++;
+        if (this.stalledIterations < this.MAX_STALLED_ITERATIONS)
+            return false;
+        task.addNote('No browser progress after repeated attempts on unchanged page', TestResult.FAILED);
+        task.finish(TestResult.FAILED);
+        return true;
+    }
     async prepareInstructionsForNextStep(task) {
         let outcomeStatus = dedent `
       <task>
@@ -403,6 +432,8 @@ export class Tester extends TaskAgent {
   
       <rules>
       Use tools ${this.ACTION_TOOLS.join(', ')} to interact with the page.
+      Use tool names exactly as listed in this prompt. Do not invent combined tool names, aliases, or names with channel markers such as "commentary".
+      Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
       Do not do unsuccesful clicks again.
       Do not run same tool calls with same parameters again.
       </rules>
@@ -665,6 +696,7 @@ export class Tester extends TaskAgent {
     <rules>
     - Refer to UI Map from <page_ui_map> to understand the page structure and its main elements
     - Use only elements that exist in the provided ARIA tree or HTML, <page_aria> and <page_html>
+    - Use tool input schemas exactly as documented. Do not invent parameter names or add fields not listed by the tool schema.
     - Use click() for buttons, links, and clickable elements ONLY - do NOT include I.fillField() or I.type() commands in click() tool
     - click() commands array is for FALLBACK LOCATORS of the SAME element, NOT for clicking different elements in sequence. If you need to click two different elements, make two separate click() calls.
     - Use form() for text input (I.fillField, I.type), dropdown selection (I.selectOption), file uploads (I.attachFile), and multi-step form interactions
@@ -677,6 +709,7 @@ export class Tester extends TaskAgent {
     - NEVER call record(status: "success") if your last verify() or see() call FAILED. A failed check means the outcome is NOT confirmed — use record(status: "fail") instead, or retry with a different approach.
     - Use finish() to complete the test, not record(). record() is for intermediate notes.
     - Call finish(verify) when all goals are achieved — provide an assertion to verify
+    - NEVER call finish() with a negative assertion that says the goal did NOT happen. If the goal cannot be achieved after real attempts, record the blocker and call stop().
     - ONLY call stop() if the scenario itself is completely irrelevant to this page and no expectations can be achieved
     - Use reset() ONLY as a last resort when the current page cannot host the scenario. Never reset after a successful flow just because an assertion or milestone did not match — verify differently or record() the finding instead. Reset is destructive and does not undo server-side side effects.
     - Be precise with locators (CSS or XPath)
@@ -690,6 +723,13 @@ export class Tester extends TaskAgent {
     - When you interact with form with inputs, ensure that you click corresponding button to save its data
     - Follow <locator_priority> rules when selecting locators for all tools
     - Before retrying your actions check maybe they already achived expected results. Use see() tool for that
+    - If the current URL is already a create/edit/new form and the scenario is about creating/editing that entity, fill and submit that form. Do not click the list-page "New" button again from inside the form.
+    - If the scenario is about search/filter/sort/tabs/list inspection and the current URL is a create/edit/new form, go back or reset to the stable list page before interacting with list controls.
+    - When selecting related entities from a list, do not choose rows/options/cards marked as "0 items", "0 tests", or otherwise empty if the scenario requires selecting real content.
+    - In selection pickers, counters such as "Selected 0", "Matched tests 0", or disabled Save/Apply mean the selection did not register. Choose a non-empty item or change filters before submitting.
+    - A passed form/click command only means the command executed. If a required field remains empty, submit stays disabled, or the expected text is not visible, treat the action as not completed and correct the missing field/state.
+    - For filter/tab scenarios, success requires BOTH: the requested filter/tab is visibly active/selected AND the list content matches that filter. Do not finish from only one of these signals.
+    - Empty-state text such as "No matched items" only proves a filter when the requested filter/tab is active and the empty state belongs to the filtered list.
     - When filling complex form with lot of actions performed, use see() to look which fields were filled and which are not
     - When verify() fails, use see() to visually confirm the result — visual confirmation is equally valid evidence
     - For visual state verification (active tabs, selected items, counts, colors), prefer see() over DOM-based verify()
@@ -718,11 +758,16 @@ export class Tester extends TaskAgent {
 
     ${formRequirementsRule}
 
+    ${capabilityGroundingRule}
+
+    ${dataProtectionRules}
+
     ${this.provider.getSystemPromptForAgent('tester', this.explorer.getStateManager().getCurrentState()?.url) || ''}
     `;
     }
     buildScenarioBlock(task, actionResult) {
         const knowledge = this.getKnowledge(actionResult);
+        const experience = this.getExperience(actionResult);
         return dedent `
       <task>
       SCENARIO GOAL: ${task.scenario}
@@ -739,16 +784,21 @@ export class Tester extends TaskAgent {
       Try to achieve as many goals as possible.
       If goal is not achievable, log that and skip to next one.
       Do not hallucinate that goal was achieved when it was not.
+      If the scenario action could not be completed, do not finish with a verification of the failure state.
       When creating or editing items via form() or type() you should include ${task.sessionName} in the value (if it is not restricted by the application logic)
       Initial page URL: ${actionResult.url}
 
-      ${protectionRule}
+      ${capabilityGroundingRule}
+
+      ${dataProtectionRules}
 
       ${this.buildDeletionScope(task)}
 
       ${this.buildAvailableFiles()}
 
       ${knowledge}
+
+      ${experience}
     `;
     }
     getDeletableSessionNames(task) {
@@ -867,12 +917,13 @@ export class Tester extends TaskAgent {
             }),
             stop: tool({
                 description: dedent `
-          Stop the current test because the scenario is fundamentally incompatible with the page.
-          Use this ONLY when the scenario cannot be executed on the current page or application.
-          Do NOT use this for failures — use reset() and retry instead.
+          Stop the current test because it cannot be completed in the current session.
+          Use this when the scenario is incompatible, required UI/data is absent, or repeated varied attempts
+          show that automation cannot complete the workflow.
+          Do NOT use this immediately after the first failed action — retry with a materially different approach first.
         `,
                 inputSchema: z.object({
-                    reason: z.string().describe('Explanation why the scenario is incompatible'),
+                    reason: z.string().describe('Explanation why the scenario cannot be completed'),
                 }),
                 execute: async ({ reason }) => {
                     task.addNote(`Stop requested: ${reason}`);
@@ -906,6 +957,7 @@ export class Tester extends TaskAgent {
           Provide a specific assertion to verify the final state.
           The assertion MUST prove that YOUR ACTIONS changed the page state.
           Do NOT verify something that was already true before you started testing.
+          Do NOT provide an assertion that verifies absence, failure, an empty state, or that the goal did not happen.
 
           Examples of good assertions:
           - "New user 'john@example.com' is visible in the users list"
@@ -1031,10 +1083,24 @@ export class Tester extends TaskAgent {
             this.resetFailureCount();
             this.previousUrl = null;
             this.previousStateHash = null;
+            this.stalledIterations = 0;
+        }
+        else if (this.shouldStopAfterStalledLoopError(task)) {
+            return 'stop';
         }
         this.currentConversation?.addUserText(result.message);
         return 'continue';
     }
+    shouldStopAfterStalledLoopError(task) {
+        if (task.hasFinished)
+            return false;
+        this.stalledIterations++;
+        if (this.stalledIterations < this.MAX_STALLED_ITERATIONS)
+            return false;
+        task.addNote('No browser progress after repeated execution errors', TestResult.FAILED);
+        task.finish(TestResult.FAILED);
+        return true;
+    }
     async cleanupStartedTest(task) {
         await this.finishTest(task);
         await this.explorer.stopTest(task, {

package/dist/src/ai/tools.js

@@ -11,7 +11,6 @@ import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 const debugLog = createDebug('explorbot:tools');
-export const CODECEPT_TOOLS = ['click', 'pressKey', 'form'];
 export const ASSERTION_TOOLS = ['verify'];
 export function createCodeceptJSTools(explorer, task) {
     const stateManager = explorer.getStateManager();
@@ -133,6 +132,71 @@ export function createCodeceptJSTools(explorer, task) {
                 }, action.lastError);
             },
         }),
+        hover: tool({
+            description: dedent `
+        Move the mouse cursor to an element to reveal hover-only controls.
+
+        Use this before clicking row actions, icon buttons, menus, or toolbars that appear only
+        when the user hovers a list item, table row, card, or tree node.
+
+        This tool ONLY accepts I.moveCursorTo(locator) commands. It does not click.
+        After hovering, use context(), see(), or click() the revealed control.
+      `,
+            inputSchema: z.object({
+                commands: z.array(z.string()).describe(dedent `
+          FALLBACK LOCATORS for ONE element to hover.
+          Order by reliability:
+          1. I.moveCursorTo(text, container)
+          2. I.moveCursorTo(ARIA, container)
+          3. I.moveCursorTo(CSS, container)
+          4. I.moveCursorTo(CSS) or I.moveCursorTo(XPath)
+        `),
+                explanation: z.string().describe('Why you are hovering this element'),
+            }),
+            execute: async ({ commands: rawCommands, explanation }) => {
+                const activeNote = task.startNote(explanation);
+                if (rawCommands.length === 0) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('hover', 'No commands provided');
+                }
+                const invalidCommands = rawCommands.map((cmd) => cmd.trim()).filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.moveCursorTo'));
+                if (invalidCommands.length > 0) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('hover', `Invalid commands: ${invalidCommands.join(', ')}. Hover tool only accepts I.moveCursorTo() commands.`, {
+                        suggestion: 'Use click() to click elements, or form() for typing/selecting.',
+                    });
+                }
+                const commands = rawCommands.map((cmd) => {
+                    const trimmed = cmd.trim();
+                    if (trimmed.startsWith('I.moveCursorTo'))
+                        return trimmed;
+                    return `I.moveCursorTo(${JSON.stringify(trimmed)})`;
+                });
+                const previousState = ActionResult.fromState(stateManager.getCurrentState());
+                const action = explorer.createAction();
+                const attempts = [];
+                for (const command of commands) {
+                    const success = await action.attempt(command, explanation, true);
+                    attempts.push({
+                        command,
+                        success,
+                        ...(action.lastError && { error: action.lastError.toString() }),
+                    });
+                    if (!success)
+                        continue;
+                    const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
+                    activeNote.commit(TestResult.PASSED);
+                    return successToolResult('hover', { ...toolResult, attempts, code: command }, action);
+                }
+                const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
+                activeNote.commit(TestResult.FAILED);
+                return failedToolResult('hover', 'All hover commands failed', {
+                    ...toolResult,
+                    attempts,
+                    suggestion: 'Use xpathCheck() to locate the row/card/tree node, or visualClick() if the hover target is only visually identifiable.',
+                }, action.lastError);
+            },
+        }),
         pressKey: tool({
             description: dedent `
         Press a keyboard key or key combination. Use this for special keys like Enter, Escape, Tab, Arrow keys, or key combinations with modifiers.
@@ -404,6 +468,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
         Check the page contents based on current page state and screenshot.
         This tool will trigger visual research to check the page contents on request.
         Use it to verify the actions were performed correctly and the page is in the expected state.
+        Input schema has exactly one field: request. Do not pass text, reason, assertion, or other fields.
 
         <example>
         request: "Check current state of the Login form"