explorbot 0.3.2 → 0.3.5

package/bin/explorbot-cli.ts

@@ -7,16 +7,16 @@ import { Command } from 'commander';
 import figureSet from 'figures';
 import { render } from 'ink';
 import React from 'react';
+import { flushTelemetry } from '../src/ai/provider.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { flushTelemetry } from '../src/ai/provider.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot, type ExplorBotOptions } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
 import { Stats } from '../src/stats.js';
 import { Plan } from '../src/test-plan.js';
 import { getCliName } from '../src/utils/cli-name.ts';
-import { isVerboseMode, log, setPreserveConsoleLogs, setQuietMode } from '../src/utils/logger.js';
+import { isVerboseMode, log, setPreserveConsoleLogs, setQuietMode, tag } from '../src/utils/logger.js';
 import { jsonToTable } from '../src/utils/markdown-parser.js';
 import { parseMarkdownToTerminal } from '../src/utils/markdown-terminal.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../src/utils/next-steps.ts';
@@ -30,6 +30,16 @@ const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version as stri
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
 remote.registerOption(program);
 
+process.on('uncaughtException', async (error) => {
+  tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);
+  await flushTelemetry();
+  process.exit(1);
+});
+
+process.on('unhandledRejection', (reason) => {
+  tag('error').log(`Unhandled rejection: ${reason instanceof Error ? `${reason.message}\n${reason.stack}` : String(reason)}`);
+});
+
 if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
   console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
@@ -546,6 +556,7 @@ program
   .command('learn [url] [description]')
   .description('Add knowledge for URLs')
   .option('-p, --path <path>', 'Working directory path')
+  .option('--replace', 'Replace existing knowledge for this URL instead of appending')
   .action(async (url, description, options) => {
     try {
       await ConfigParser.getInstance().loadConfig({
@@ -556,7 +567,7 @@ program
       const tracker = new KnowledgeTracker();
 
       if (url && description) {
-        const result = tracker.addKnowledge(url, description);
+        const result = tracker.addKnowledge(url, description, { replace: options.replace });
         const action = result.isNewFile ? 'Created' : 'Updated';
         console.log(`Knowledge ${action} in: ${result.filename}`);
         return;

package/dist/bin/explorbot-cli.js

@@ -7,16 +7,16 @@ import { Command } from 'commander';
 import figureSet from 'figures';
 import { render } from 'ink';
 import React from 'react';
+import { flushTelemetry } from '../src/ai/provider.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { flushTelemetry } from '../src/ai/provider.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
 import { Stats } from '../src/stats.js';
 import { Plan } from '../src/test-plan.js';
 import { getCliName } from "../src/utils/cli-name.js";
-import { isVerboseMode, log, setPreserveConsoleLogs, setQuietMode } from '../src/utils/logger.js';
+import { isVerboseMode, log, setPreserveConsoleLogs, setQuietMode, tag } from '../src/utils/logger.js';
 import { jsonToTable } from '../src/utils/markdown-parser.js';
 import { parseMarkdownToTerminal } from '../src/utils/markdown-terminal.js';
 import { printNextSteps, relativeToCwd } from "../src/utils/next-steps.js";
@@ -26,6 +26,14 @@ const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../p
 const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
 remote.registerOption(program);
+process.on('uncaughtException', async (error) => {
+    tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);
+    await flushTelemetry();
+    process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+    tag('error').log(`Unhandled rejection: ${reason instanceof Error ? `${reason.message}\n${reason.stack}` : String(reason)}`);
+});
 if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
     console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
@@ -493,6 +501,7 @@ program
     .command('learn [url] [description]')
     .description('Add knowledge for URLs')
     .option('-p, --path <path>', 'Working directory path')
+    .option('--replace', 'Replace existing knowledge for this URL instead of appending')
     .action(async (url, description, options) => {
     try {
         await ConfigParser.getInstance().loadConfig({
@@ -501,7 +510,7 @@ program
         const { KnowledgeTracker } = await import('../src/knowledge-tracker.js');
         const tracker = new KnowledgeTracker();
         if (url && description) {
-            const result = tracker.addKnowledge(url, description);
+            const result = tracker.addKnowledge(url, description, { replace: options.replace });
             const action = result.isNewFile ? 'Created' : 'Updated';
             console.log(`Knowledge ${action} in: ${result.filename}`);
             return;

package/dist/models.json

@@ -18,6 +18,8 @@
     "agenticModel": "gpt-5.6-luna"
   },
   "anthropic": {
+    "model": "claude-haiku-4-5-20251001",
+    "visionModel": "claude-haiku-4-5-20251001",
     "agenticModel": "claude-haiku-4-5-20251001"
   },
   "mistral": {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.3.2",
+  "version": "0.3.5",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/dist/src/action-result.d.ts

@@ -135,6 +135,7 @@ export declare class Diff {
     isSameUrl(): boolean;
     urlHasChanged(): boolean;
     get htmlParts(): HtmlDiffPart[];
+    cleanedHtmlParts(): Promise<HtmlDiffPart[]>;
     get ariaChanged(): string | null;
     get ariaChangeCount(): number;
     get htmlDiff(): HtmlDiffResult | null;

package/dist/src/action-result.js

@@ -444,17 +444,9 @@ export class ActionResult {
             pageDiff.ariaChangeCount = diff.ariaChangeCount;
         }
         if (diff.htmlParts.length > 0) {
-            const htmlConfig = this.normalizeHtmlConfig();
-            const processedParts = [];
-            for (const part of diff.htmlParts) {
-                const filteredHtml = htmlCombinedSnapshot(part.subtree, htmlConfig?.combined);
-                const minified = await minifyHtml(filteredHtml);
-                if (minified) {
-                    processedParts.push({ ...part, subtree: minified });
-                }
-            }
-            if (processedParts.length > 0) {
-                pageDiff.htmlParts = collapseHtmlParts(processedParts);
+            const collapsed = collapseHtmlParts(await diff.cleanedHtmlParts());
+            if (collapsed.length > 0) {
+                pageDiff.htmlParts = collapsed;
             }
         }
         if (pageDiff.ariaChanges && this.iframeSnapshots.length > 0) {
@@ -490,7 +482,9 @@ function collapseHtmlParts(parts) {
     const total = parts.reduce((sum, p) => sum + p.subtree.length, 0);
     const fullPageReRender = total > HTML_PARTS_TOTAL_BUDGET || parts.length > HTML_PARTS_COUNT_LIMIT;
     if (fullPageReRender) {
-        return parts.map((part) => ({
+        return parts
+            .filter((part) => part.added.length > 0 || part.removed.length > 0)
+            .map((part) => ({
             ...part,
             subtree: `<html><head></head><body>...collapsed (${part.subtree.length} chars, ${part.added.length} added, ${part.removed.length} removed)...</body></html>`,
         }));
@@ -543,6 +537,17 @@ export class Diff {
             return [];
         return this._htmlDiffResult.parts;
     }
+    async cleanedHtmlParts() {
+        const htmlConfig = ConfigParser.getInstance().getConfig().html;
+        const cleaned = [];
+        for (const part of this.htmlParts) {
+            const minified = await minifyHtml(htmlCombinedSnapshot(part.subtree, htmlConfig?.combined));
+            if (!minified)
+                continue;
+            cleaned.push({ ...part, subtree: minified });
+        }
+        return cleaned;
+    }
     get ariaChanged() {
         return this._ariaDiffResult;
     }

package/dist/src/action.d.ts

@@ -15,6 +15,7 @@ declare class Action {
         name: string;
         args: any[];
     }>;
+    executedSteps: ExecutedStep[];
     lastValue: unknown;
     recorder?: PlaywrightRecorder;
     recovery: RecoveryRunner;
@@ -58,3 +59,12 @@ export type RecoveryRunner = <T>(fn: () => Promise<T>) => Promise<T>;
 export interface ExecuteOptions {
     verbatim?: boolean;
 }
+export declare const attachStepLogger: (target: ExecutedStep[], assertionsTarget?: Array<{
+    name: string;
+    args: any[];
+}>) => (() => void);
+export interface ExecutedStep {
+    command: string;
+    success: boolean;
+    error?: string;
+}

package/dist/src/action.js

@@ -31,6 +31,7 @@ class Action {
     playwrightHelper;
     playwrightGroupId = null;
     assertionSteps = [];
+    executedSteps = [];
     lastValue;
     recorder;
     recovery;
@@ -304,7 +305,7 @@ class Action {
         let codeString = code.replace(/^\(I\) => /, '').trim();
         const executedSteps = [];
         const assertionSteps = [];
-        const stepListener = attachStepLogger(executedSteps, assertionSteps);
+        const detachSteps = attachStepLogger(executedSteps, assertionSteps);
         const groupId = this.recorder ? await this.recorder.beginAction(codeString) : null;
         this.playwrightGroupId = groupId;
         const detachResponses = this.captureResponses();
@@ -330,10 +331,12 @@ class Action {
                 await recorder.add(() => sleep(this.config.action?.delay || 500));
                 await recorder.promise();
                 this.lastValue = await returned;
+                if (!recorder.isRunning())
+                    throw new Error('CodeceptJS recorder is stopped, commands were skipped and never reached the browser');
             }
             this.restorePageTimeout();
             if (executedSteps.length > 0) {
-                codeString = executedSteps.join('\n');
+                codeString = executedSteps.map((step) => step.command).join('\n');
             }
             const pageState = await this.captureOnce({ codeBlock: codeString });
             this.actionResult = pageState;
@@ -350,11 +353,12 @@ class Action {
             throw err;
         }
         finally {
+            this.executedSteps = executedSteps;
             this.restorePageTimeout();
             detachResponses();
             if (groupId)
                 await this.recorder.endAction();
-            detachStepLogger(stepListener);
+            detachSteps();
             if (stepSpan) {
                 stepSpan.end();
             }
@@ -443,13 +447,16 @@ async function captureTitle(page, actor) {
     return '';
 }
 const ASSERTION_STEP_NAMES = new Set(['see', 'dontSee', 'seeElement', 'dontSeeElement', 'seeInField', 'dontSeeInField', 'seeInCurrentUrl', 'dontSeeInCurrentUrl']);
-const attachStepLogger = (target, assertionsTarget) => {
+export const attachStepLogger = (target, assertionsTarget) => {
     const listener = (step, error) => {
         if (!step?.toCode)
             return;
         if (step.name?.startsWith('grab'))
             return;
-        target.push(step.toCode());
+        const executed = { command: step.toCode(), success: !error };
+        if (error)
+            executed.error = errorToString(error);
+        target.push(executed);
         if (assertionsTarget && ASSERTION_STEP_NAMES.has(step.name)) {
             assertionsTarget.push({ name: step.name, args: step.args || [] });
         }
@@ -461,11 +468,10 @@ const attachStepLogger = (target, assertionsTarget) => {
     };
     codeceptjs.event.dispatcher.on(codeceptjs.event.step.passed, listener);
     codeceptjs.event.dispatcher.on(codeceptjs.event.step.failed, listener);
-    return listener;
-};
-const detachStepLogger = (listener) => {
-    codeceptjs.event.dispatcher.off(codeceptjs.event.step.passed, listener);
-    codeceptjs.event.dispatcher.off(codeceptjs.event.step.failed, listener);
+    return () => {
+        codeceptjs.event.dispatcher.off(codeceptjs.event.step.passed, listener);
+        codeceptjs.event.dispatcher.off(codeceptjs.event.step.failed, listener);
+    };
 };
 const readFocusedElement = () => {
     const el = document.activeElement;

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

@@ -4,8 +4,9 @@ export interface ToolExecution {
     input: any;
     output: any;
     wasSuccessful: boolean;
+    reasoning?: string;
 }
-export declare function toToolExecution(toolName: string, input: any, rawOutput: any): ToolExecution;
+export declare function toToolExecution(toolName: string, input: any, rawOutput: any, reasoning?: string): ToolExecution;
 export declare function toolExecutionLabel(input: Record<string, any> | undefined): string;
 export declare const NARRATION_TOOL = "commentary";
 export declare class Conversation {

package/dist/src/ai/conversation.js

@@ -1,8 +1,8 @@
-export function toToolExecution(toolName, input, rawOutput) {
+export function toToolExecution(toolName, input, rawOutput, reasoning) {
     let output = rawOutput;
     if (rawOutput?.type === 'json' && rawOutput?.value)
         output = rawOutput.value;
-    return { toolName, input, output, wasSuccessful: output?.success !== false };
+    return { toolName, input, output, wasSuccessful: output?.success !== false, reasoning };
 }
 export function toolExecutionLabel(input) {
     return input?.explanation || input?.assertion || input?.reason || input?.request || '';
@@ -189,10 +189,14 @@ export class Conversation {
                 continue;
             if (!Array.isArray(message.content))
                 continue;
+            const reasoning = message.content
+                .filter((part) => part.type === 'reasoning' && part.text?.trim())
+                .map((part) => part.text.trim())
+                .join('\n');
             for (const part of message.content) {
                 if (part.type !== 'tool-call')
                     continue;
-                toolCalls.set(part.toolCallId, part.input);
+                toolCalls.set(part.toolCallId, { input: part.input, reasoning });
             }
         }
         const executions = [];
@@ -206,7 +210,8 @@ export class Conversation {
                     continue;
                 if (part.toolName === NARRATION_TOOL)
                     continue;
-                executions.push(toToolExecution(part.toolName, toolCalls.get(part.toolCallId) || {}, part.output));
+                const call = toolCalls.get(part.toolCallId);
+                executions.push(toToolExecution(part.toolName, call?.input || {}, part.output, call?.reasoning));
             }
         }
         return executions;

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

@@ -1,5 +1,6 @@
 import { ActionResult } from '../action-result.js';
 import type Action from '../action.js';
+import type { ExecutedStep } from '../action.js';
 import type { ExplorbotConfig } from '../config.js';
 import type { ExperienceTracker } from '../experience-tracker.js';
 import Explorer from '../explorer.js';
@@ -16,6 +17,7 @@ declare class Navigator implements Agent {
     hooksRunner: HooksRunner;
     MAX_ATTEMPTS: number;
     lastFailureReason: string | null;
+    executedSteps: ExecutedStep[];
     systemPrompt: string;
     freeSailSystemPrompt: string;
     explorer: Explorer;
@@ -55,6 +57,7 @@ declare class Navigator implements Agent {
         freshState: ActionResult;
         urlMatches: boolean;
     }>;
+    targetUrlReached(action: Action, expectedUrl: string, state: ActionResult): boolean;
     ariaDiff(freshState: ActionResult, previous: ActionResult): Promise<string | null>;
     saveFlow(message: string, expectedUrl: string | undefined, actionResult: ActionResult, progressBlocks: string[]): void;
     rescueDelayedRedirect(action: Action, expectedUrl: string): Promise<boolean>;

package/dist/src/ai/navigator.js

@@ -2,8 +2,8 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.js';
-import { normalizeUrl } from '../state-manager.js';
 import { renderAssertion } from "../playwright-recorder.js";
+import { normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { getCliName } from "../utils/cli-name.js";
 import { extractCodeBlocks } from '../utils/code-extractor.js';
@@ -26,6 +26,7 @@ class Navigator {
     hooksRunner;
     MAX_ATTEMPTS = Number.parseInt(process.env.MAX_ATTEMPTS || '5');
     lastFailureReason = null;
+    executedSteps = [];
     systemPrompt = dedent `
   <role>
     You are senior test automation engineer with master QA skills.
@@ -194,10 +195,15 @@ class Navigator {
         if (!this.provider)
             throw new Error('AI-assisted recovery is unavailable: no AI model is configured.');
         this.lastFailureReason = null;
+        this.executedSteps = [];
         tag('info').log('AI Navigator resolving state at', actionResult.url);
         debugLog('Resolution message:', message);
         const action = opts?.action ?? this.explorer.action();
         const expectedUrl = opts?.expectedUrl;
+        if (expectedUrl && this.targetUrlReached(action, expectedUrl, actionResult)) {
+            tag('success').log(`Already at ${expectedUrl} — navigation resolved`);
+            return true;
+        }
         const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
         const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
         conversation.addUserText(await this.buildResolutionPrompt(message, actionResult, opts?.experience));
@@ -278,14 +284,20 @@ class Navigator {
                 const freshHash = check.freshState.getStateHash();
                 resolved = check.urlMatches && freshHash !== actionResult.getStateHash();
                 if (!resolved && attempt.ok) {
-                    lastFailure = `URL did not change (still ${check.freshState.url})`;
+                    if (check.urlMatches) {
+                        lastFailure = `Reached ${check.freshState.url} but the page state did not change`;
+                        tag('warning').log(`Page state did not change at ${check.freshState.url}`);
+                    }
+                    else {
+                        lastFailure = `Reached ${check.freshState.url}, expected ${expectedUrl}`;
+                        tag('warning').log(`URL verification failed: expected ${expectedUrl}, got ${check.freshState.url}`);
+                    }
                     batchFailures.push({
                         code: codeBlock,
                         error: lastFailure,
                         ariaChanges: await this.ariaDiff(check.freshState, prevActionResult),
                         urlAfter: check.freshState.url,
                     });
-                    tag('warning').log(`URL verification failed: expected ${expectedUrl}, got ${check.freshState.url}`);
                 }
                 if (freshHash !== prevHash && (attempt.ok || check.urlMatches)) {
                     progressBlocks.push(codeBlock);
@@ -411,6 +423,7 @@ class Navigator {
         await action.exitIframe();
         debugLog(`Attempting resolution: ${codeBlock}`);
         const ok = await action.attempt(codeBlock, message);
+        this.executedSteps.push(...action.executedSteps);
         const page = action.playwrightHelper?.page;
         if (page) {
             try {
@@ -437,9 +450,12 @@ class Navigator {
             }
         }
         const freshState = await this.explorer.capture();
-        const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && matchesNavigationUrl(expectedUrl, this.comparableUrl(freshState, expectedUrl));
+        const urlMatches = this.targetUrlReached(action, expectedUrl, freshState);
         return { freshState, urlMatches };
     }
+    targetUrlReached(action, expectedUrl, state) {
+        return this.isSameExpectedOrigin(expectedUrl, action.stateManager) && matchesNavigationUrl(expectedUrl, this.comparableUrl(state, expectedUrl));
+    }
     async ariaDiff(freshState, previous) {
         if (freshState.getStateHash() === previous.getStateHash())
             return null;

package/dist/src/ai/pilot.js

@@ -16,6 +16,7 @@ import { withdrawVisionTools } from "./tools.js";
 const CHECK_TOOLS = ['verify', 'see', 'research'];
 const EVIDENCE_TOOLS = ['verify', 'see'];
 const META_TOOLS = ['record', 'reset', 'stop', 'finish'];
+const PILOT_REASONING_LIMIT = 500;
 const PILOT_MESSAGE_LIMIT = 2;
 const PILOT_MESSAGE_MAX_LENGTH = 160;
 export class Pilot {
@@ -941,6 +942,12 @@ export class Pilot {
                 line += `\n   result: ${resultMessage}`;
             if (errorDetail && errorDetail !== resultMessage)
                 line += `\n   error: ${errorDetail}`;
+            if (!t.wasSuccessful && t.reasoning) {
+                let rationale = t.reasoning;
+                if (rationale.length > PILOT_REASONING_LIMIT)
+                    rationale = `...${rationale.slice(-PILOT_REASONING_LIMIT)}`;
+                line += `\n   tester reasoned: ${rationale.replace(/\n+/g, ' ')}`;
+            }
             const attempts = t.output?.attempts;
             if (attempts && attempts.length > 1 && t.wasSuccessful) {
                 const failedBefore = attempts.filter((a) => !a.success);
@@ -998,6 +1005,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

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,18 @@ 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;
         try {
             const response = await this.withModelRequestSlot(() => withRetry(async () => {
-                const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000));
+                const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages: attemptMessages, ...config, abortSignal: signal }), config.timeout || 30000).catch((error) => {
+                    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') {
@@ -620,6 +630,22 @@ function repairToolCall(options) {
         return repairChannelMarker(options);
     return repairHarmonyChannel(options);
 }
+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

@@ -5,10 +5,12 @@ import { diffAriaSnapshots } from "../../utils/aria.js";
 import { extractCodeBlocks } from "../../utils/code-extractor.js";
 import { tag } from '../../utils/logger.js';
 import { mdq } from "../../utils/markdown-query.js";
+import { truncate } from "../../utils/strings.js";
 import { getCachedResearch, getPreviousResearch, saveResearch } from "./cache.js";
 import { debugLog } from "./mixin.js";
 import { parseResearchSections } from "./parser.js";
 const DEFAULT_MAX_EXPANDABLE_CLICKS = 10;
+const MAX_HTML_DIFF_CHARS = 20_000;
 export function WithDeepAnalysis(Base) {
     return class extends Base {
         async performDeepAnalysis(state, result) {
@@ -430,6 +432,8 @@ export function WithDeepAnalysis(Base) {
 
         `;
             }
+            const cleanedParts = await diff.cleanedHtmlParts();
+            const htmlChanges = truncate(cleanedParts.map((p) => `[Container: ${p.container}]\n${p.subtree}`).join('\n\n'), MAX_HTML_DIFF_CHARS);
             const prompt = dedent `
         ${intro}
         Analyze the changes and produce a UI map section.
@@ -438,7 +442,7 @@ export function WithDeepAnalysis(Base) {
         ${diff.ariaChanged || 'none'}
 
         HTML changes:
-        ${diff.htmlParts.map((p) => `[Container: ${p.container}]\n${p.subtree}`).join('\n\n') || 'none'}
+        ${htmlChanges || 'none'}
         ${alreadyHint}
 
         Respond with a SINGLE section in this format:

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

@@ -93,7 +93,6 @@ export function WithSections(Base) {
         - Do not copy global toolbar, navigation, list, or detail elements into this section unless they are descendants of this section container.
         - Every element with eidx inside this section's container MUST appear in the table.
         - Every row needs CSS; ARIA may be "-" for icon-only buttons.
-        - ARIA locator JSON uses keys "role" and "text" (NOT "name").
         - Elements marked data-explorbot-hit="covered" or "offscreen" are not directly actionable; describe the covering or focused UI first.
         - In split-pane pages, entity detail panels are active detail context; include close/back/pin controls in the detail panel section when present.
         </rules>

package/dist/src/ai/researcher.js

@@ -345,7 +345,6 @@ export class Researcher extends ResearcherBase {
       - If an element has data-explorbot-hit="covered" or "offscreen", do not present it as directly actionable. Prefer the overlay, drawer, dialog, or focused section covering it, and mention what must be dismissed or revealed first.
       - Every element with an eidx attribute MUST appear in exactly one matching UI map section — describe icon-only buttons by their visual role.
       - Every UI map row needs a CSS selector; ARIA may be "-" for icon-only buttons, CSS must never be "-".
-      - ARIA locator JSON uses keys "role" and "text" (NOT "name").
       - Mark elements with likely hover interactions (title, aria-describedby, menu items with submenus) as "(hover)".
       </rules>
 

package/dist/src/ai/rules.js

@@ -67,7 +67,6 @@ const locatorStrategyRule = dedent `
 
   <bad_aria_locator_example>
   { "role": "button", "text": "" }  // INVALID - empty text is useless, use "-" instead
-  { "role": "button", "name": "Save" }  // WRONG key - use "text", not "name"
   </bad_aria_locator_example>
 
   NEVER include \`eidx\` attribute in any locator (ARIA, CSS, XPath). It is an internal annotation.

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

@@ -33,6 +33,7 @@ export declare class Tester extends TaskAgent implements Agent {
     lastAnalyzedStateHash: string | null;
     stalledIterations: number;
     readonly MAX_STALLED_ITERATIONS = 3;
+    skipResearch: (err: Error) => string;
     constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any);
     getNavigator(): Navigator;
     setPilot(pilot: Pilot): void;

package/dist/src/ai/tester.js

@@ -51,6 +51,12 @@ export class Tester extends TaskAgent {
     lastAnalyzedStateHash = null;
     stalledIterations = 0;
     MAX_STALLED_ITERATIONS = 3;
+    skipResearch = (err) => {
+        if (err.name === 'AbortError')
+            throw err;
+        tag('warning').log(`Research skipped: ${err.message}`);
+        return '';
+    };
     constructor(deps, researcher, navigator, agentTools) {
         super(deps);
         this.requestStore = deps.requestStore;
@@ -512,14 +518,7 @@ export class Tester extends TaskAgent {
             const alreadySeenUiMap = this.seenUiMapUrls.has(currentUrl);
             let research = '';
             if (!alreadySeenUiMap) {
-                try {
-                    research = await this.researcher.research(currentState);
-                }
-                catch (err) {
-                    if (!(err instanceof ErrorPageError))
-                        throw err;
-                    tag('warning').log(`Research skipped: ${err.message}`);
-                }
+                research = await this.researcher.research(currentState).catch(this.skipResearch);
             }
             this.pageStateHash = currentStateHash;
             this.pageActionResult = currentState;
@@ -559,7 +558,7 @@ export class Tester extends TaskAgent {
             return context;
         }
         if (focusArea.detected && focusArea.name && this.pageStateHash && this.pageActionResult) {
-            const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash);
+            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

@@ -1,3 +1,4 @@
+import type { ExecutedStep } from '../action.js';
 import { ActionResult, type PageDiff } from '../action-result.js';
 import { type ExperienceTracker } from '../experience-tracker.js';
 import { type Task } from '../test-plan.js';
@@ -62,6 +63,7 @@ export declare function successToolResult(action: string, data?: Record<string,
 }): Record<string, any>;
 export declare function isMajorPageChange(pageDiff: PageDiff): boolean;
 export declare function hasFailedRequest(pageDiff: PageDiff): boolean;
+export declare function formatExecutedSteps(steps: ExecutedStep[], requestedCount?: number): string;
 export declare function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null): Promise<Record<string, any>>;
 export declare function withdrawVisionTools(tools: Record<string, any>): void;
 export declare function clickFailureSuggestion(attempts: Array<{