explorbot 0.5.1 → 0.5.3

package/bin/explorbot-cli.ts

@@ -56,6 +56,7 @@ interface CLIOptions {
   debug?: boolean;
   config?: string;
   path?: string;
+  baseUrl?: string;
   show?: boolean;
   headless?: boolean;
   incognito?: boolean;
@@ -66,6 +67,7 @@ interface CLIOptions {
 function buildExplorBotOptions(from: string | undefined, options: CLIOptions): ExplorBotOptions {
   return {
     from,
+    baseUrl: options.baseUrl,
     verbose: options.verbose || options.debug,
     config: options.config,
     path: options.path,
@@ -83,6 +85,7 @@ function addCommonOptions(cmd: Command): Command {
     .option('--debug', 'Enable debug logging (same as --verbose)')
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
+    .option('--base-url <url>', 'Run against this URL: its path scopes relative paths (plans, commands, saved tests on rerun), its query params ride along with every page load')
     .option('-s, --show', 'Show browser window')
     .option('--headless', 'Run browser in headless mode')
     .option('--incognito', 'Run without recording experiences')

package/dist/bin/explorbot-cli.js

@@ -46,6 +46,7 @@ if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima') && !prin
 function buildExplorBotOptions(from, options) {
     return {
         from,
+        baseUrl: options.baseUrl,
         verbose: options.verbose || options.debug,
         config: options.config,
         path: options.path,
@@ -62,6 +63,7 @@ function addCommonOptions(cmd) {
         .option('--debug', 'Enable debug logging (same as --verbose)')
         .option('-c, --config <path>', 'Path to configuration file')
         .option('-p, --path <path>', 'Working directory path')
+        .option('--base-url <url>', 'Run against this URL: its path scopes relative paths (plans, commands, saved tests on rerun), its query params ride along with every page load')
         .option('-s, --show', 'Show browser window')
         .option('--headless', 'Run browser in headless mode')
         .option('--incognito', 'Run without recording experiences')

package/dist/package.json

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

package/dist/src/action.d.ts

@@ -48,6 +48,7 @@ declare class Action {
     captureBrowserLogs(): Promise<any[]>;
     executeOnce(code: string, verbatim?: boolean): Promise<Action>;
     attempt(codeBlock: string, originalMessage?: string): Promise<boolean>;
+    attemptExactElementIndex(codeBlock: string, elementIndex: number, originalMessage?: string): Promise<boolean>;
     exitIframe(): Promise<void>;
     getActor(): CodeceptJS.I;
     getActionResult(): ActionResult | null;

package/dist/src/action.js

@@ -105,6 +105,7 @@ class Action {
             if (includeScreenshot) {
                 const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
                 const screenshotPath = join(statesDir, filename);
+                await page?.screencast?.hideOverlays().catch(() => { });
                 screenshotFile = await page
                     ?.screenshot({ path: screenshotPath, fullPage: true })
                     .then(() => {
@@ -115,6 +116,7 @@ class Action {
                     debugLog('Screenshot failed, continuing without it:', err);
                     return undefined;
                 });
+                await page?.screencast?.showOverlays().catch(() => { });
             }
             // Save HTML to file
             const htmlFile = safeFilename(`${stateHash}_${timestamp}`, '.html');
@@ -461,6 +463,13 @@ class Action {
             return false;
         }
     }
+    async attemptExactElementIndex(codeBlock, elementIndex, originalMessage) {
+        const applyElementIndex = (step) => {
+            step.opts = { ...step.opts, elementIndex };
+        };
+        codeceptjs.event.dispatcher.once(codeceptjs.event.step.started, applyElementIndex);
+        return this.attempt(codeBlock, originalMessage).finally(() => codeceptjs.event.dispatcher.off(codeceptjs.event.step.started, applyElementIndex));
+    }
     async exitIframe() {
         if (!this.playwrightHelper.frame)
             return;

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

@@ -6,6 +6,7 @@ import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
 import { CODECEPT_TOOLS, isNonReusableCode, stripComments } from "../../utils/step-analyzer.js";
 import { safeFilename } from "../../utils/strings.js";
+import { ensureCodeceptResolvable } from "../../utils/test-files.js";
 import { ASSERTION_TOOLS } from "../tools.js";
 import { escapeString, getExecutionLabel } from "./utils.js";
 export function WithCodeceptJS(Base) {
@@ -79,6 +80,7 @@ export function WithCodeceptJS(Base) {
             }
             const testsDir = ConfigParser.getInstance().getTestsDir();
             mkdirSync(testsDir, { recursive: true });
+            ensureCodeceptResolvable(testsDir);
             const filePath = join(testsDir, safeFilename(plan.title, '.js'));
             writeFileSync(filePath, lines.join('\n'));
             this.savedFiles.add(filePath);

package/dist/src/ai/judge-provider.js

@@ -1,3 +1,5 @@
+import { Observability } from "../observability.js";
+import { redactSecrets } from "../utils/secrets.js";
 const REQUEST_TIMEOUT_MS = 15000;
 export class JudgeProvider {
     model;
@@ -19,6 +21,9 @@ export class JudgeProvider {
         if (options)
             q = { type: 'choice', instructions: question, criteria: Object.fromEntries(options.map((option, index) => [String(index), option])) };
         const body = JSON.stringify({ model: this.model, state, questions: { q } });
+        const span = Observability.getSpan();
+        span?.setAttribute('langfuse.observation.input', redactSecrets(body));
+        span?.setAttribute('ai.telemetry.metadata.judgeEndpoint', this.url);
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
         try {

package/dist/src/ai/judge-tool.js

@@ -9,7 +9,11 @@ export function createJudgeTool(deps, buildState) {
     return {
         judge: tool({
             description: dedent `
-        Settle one judgement about the current page instead of guessing. Phrase it literally and concretely.
+        Fast yes/no or pick-one decision about the current page, answered from <page_aria> and your recent steps.
+        No screenshot, no HTML, produces no test code.
+        Use for in-flow judgements you would otherwise guess: did the last action already take effect, which of several similar elements the scenario means, is this the expected page or dialog.
+        Not for final assertions (use verify/finish) and not for anything page_aria does not show, such as styling or visual state (use see).
+        Phrase the question literally and concretely.
       `,
             inputSchema: z.object({
                 question: z.string().describe('The statement to confirm, or the question the options answer'),

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

@@ -15,13 +15,15 @@ export declare class Judge {
         tool: boolean;
         direct: boolean;
     };
+    threshold: number;
     constructor(provider: JudgeProvider, enabled: {
         tool: boolean;
         direct: boolean;
-    });
+    }, threshold?: number);
     static fromConfig(config: AIConfig['decisionModel']): Judge | null;
     get toolEnabled(): boolean;
     decide(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;
+    pick(question: string, options: string[], state: unknown): Promise<number | null>;
     consult(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;
     request(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;
     recordFailure(error: unknown): null;

package/dist/src/ai/judge.js

@@ -5,6 +5,7 @@ import { JudgeProvider } from "./judge-provider.js";
 const debugLog = createDebug('explorbot:judge');
 const APPROVAL_THRESHOLD = 0.7;
 export const UNDECIDED = 'undecided';
+const UNDECIDED_HINT = `Choose "${UNDECIDED}" if you are not sure or no option fits.`;
 export const JUDGE_PAGE_CAP = 12000;
 export class Decision {
     value;
@@ -23,14 +24,19 @@ export class Decision {
 export class Judge {
     provider;
     enabled;
-    constructor(provider, enabled) {
+    threshold;
+    constructor(provider, enabled, threshold = APPROVAL_THRESHOLD) {
         this.provider = provider;
         this.enabled = enabled;
+        this.threshold = threshold;
     }
     static fromConfig(config) {
         if (!config)
             return null;
-        return new Judge(new JudgeProvider(config.provider, config.model), { tool: config.tool !== false, direct: config.direct !== false });
+        const threshold = config.threshold ?? APPROVAL_THRESHOLD;
+        if (!(threshold > 0 && threshold < 1))
+            throw new Error(`decisionModel.threshold must be between 0 and 1, got ${config.threshold}`);
+        return new Judge(new JudgeProvider(config.provider, config.model), { tool: config.tool !== false, direct: config.direct !== false }, threshold);
     }
     get toolEnabled() {
         return this.enabled.tool;
@@ -40,13 +46,23 @@ export class Judge {
             return new Decision(null, 0);
         return this.consult(question, options, state);
     }
+    async pick(question, options, state) {
+        if (new Set(options).size < options.length)
+            return null;
+        const decision = await this.decide(question, [...options, UNDECIDED], state);
+        if (!decision.value)
+            return null;
+        return options.indexOf(decision.value) + 1;
+    }
     async consult(question, options, state) {
         if (Array.isArray(options) && options.length < 2)
             return new Decision(null, 0);
         return Observability.run('judge.decide', { tags: ['judge'] }, async () => {
             setActivity('⚖️ Asking judge...', 'ai');
             const decision = await this.request(question, options, state).finally(() => clearActivity());
-            Observability.getSpan()?.setAttribute('ai.telemetry.metadata.judgeDecision', JSON.stringify({ question, value: decision.value, confidence: decision.confidence }));
+            const span = Observability.getSpan();
+            span?.setAttribute('ai.telemetry.metadata.judgeQuestion', question);
+            span?.setAttribute('ai.telemetry.metadata.judgeDecision', JSON.stringify({ question, value: decision.value, confidence: decision.confidence, threshold: this.threshold, model: this.provider.model }));
             return decision;
         });
     }
@@ -54,10 +70,14 @@ export class Judge {
         let list;
         if (Array.isArray(options))
             list = options;
-        const answer = await this.provider.decide(state, question, list).catch((error) => this.recordFailure(error));
+        let instructions = question;
+        if (list?.includes(UNDECIDED))
+            instructions = `${question} ${UNDECIDED_HINT}`;
+        const answer = await this.provider.decide(state, instructions, list).catch((error) => this.recordFailure(error));
         if (!answer)
             return new Decision(null, 0);
-        if (answer.probability <= APPROVAL_THRESHOLD)
+        Observability.getSpan()?.setAttribute('langfuse.observation.output', JSON.stringify(answer));
+        if (answer.probability <= this.threshold)
             return new Decision(null, answer.probability);
         if (answer.value === UNDECIDED)
             return new Decision(null, answer.probability);
@@ -65,7 +85,10 @@ export class Judge {
     }
     recordFailure(error) {
         debugLog('judge declined: %s', error);
-        Observability.getSpan()?.setAttribute('ai.telemetry.metadata.judgeError', String(error));
+        const span = Observability.getSpan();
+        span?.setAttribute('ai.telemetry.metadata.judgeError', String(error));
+        span?.setAttribute('langfuse.observation.level', 'ERROR');
+        span?.setAttribute('langfuse.observation.status_message', String(error));
         return null;
     }
 }

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

@@ -41,6 +41,7 @@ export declare class Pilot implements Agent {
     buildVerdictSystemPrompt(task: Test): string;
     planTest(task: Test, currentState: ActionResult): Promise<string>;
     reviewNewPage(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
+    periodicAnalyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     analyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     settleExpectations(task: Test, finalState?: ActionResult): Promise<SettledExpectation[]>;
     settleByJudge(task: Test, expectations: string[]): Promise<Map<string, SettledStatus>>;

package/dist/src/ai/pilot.js

@@ -11,7 +11,7 @@ import { createDebug, tag } from "../utils/logger.js";
 const debugLog = createDebug('explorbot:pilot');
 import { truncateJson } from "../utils/strings.js";
 import { createAskApiTool } from "./fisherman/tools.js";
-import { UNDECIDED } from "./judge.js";
+import { JUDGE_PAGE_CAP, UNDECIDED } from "./judge.js";
 import { capabilityGroundingRule, dataProtectionRules } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 import { withdrawVisionTools } from "./tools.js";
@@ -477,6 +477,22 @@ export class Pilot {
         Tester holds no recipe for this page until you load one — open the <experience> entries whose titles fit a step you are about to instruct.
       `, 'pilot.reviewNewPage', { tools: true, maxToolRoundtrips: 2, task });
     }
+    async periodicAnalyzeProgress(task, currentState, testerConversation) {
+        const toolCalls = testerConversation.getToolExecutions().slice(-this.stepsToReview);
+        const healthy = await this.judge?.decide('The recent actions advance the scenario toward its remaining expected outcomes.', null, {
+            scenario: task.scenario,
+            plannedSteps: task.plannedSteps,
+            expectations: this.formatExpectations(task),
+            runLog: task.notesToString() || 'No steps recorded.',
+            visitedUrls: task.getVisitedUrls({ localOnly: true }),
+            state: this.buildStateContext(currentState),
+            page: currentState.getCompactARIA().slice(0, JUDGE_PAGE_CAP),
+            recentActions: this.formatActions(toolCalls),
+        });
+        if (healthy?.approved)
+            return '';
+        return this.analyzeProgress(task, currentState, testerConversation);
+    }
     async analyzeProgress(task, currentState, testerConversation) {
         tag('substep').log('Pilot analyzing progress...');
         if (!this.conversation) {
@@ -487,9 +503,6 @@ export class Pilot {
         const toolCalls = testerConversation.getToolExecutions().slice(-this.stepsToReview);
         const actionsContext = this.formatActions(toolCalls);
         const stateContext = this.buildStateContext(currentState);
-        const healthy = await this.judge?.decide('The run is moving toward the goal and can continue without a supervisor reviewing it now.', null, { scenario: task.scenario, state: stateContext, recentActions: actionsContext });
-        if (healthy?.approved)
-            return '';
         const hasFailures = toolCalls.length === 0 || toolCalls.some((t) => !t.wasSuccessful);
         const text = await this.sendToPilot(dedent `
         START URL: ${task.startUrl}
@@ -1046,6 +1059,9 @@ export class Pilot {
             const consoleError = t.output?.pageDiff?.consoleErrors?.[0];
             if (consoleError)
                 line += `\n   console: ${consoleError.slice(0, PILOT_MESSAGE_MAX_LENGTH)}`;
+            const disabledReason = t.output?.disabledReason?.[0];
+            if (disabledReason)
+                line += `\n   shown on hover of disabled target: ${disabledReason.slice(0, PILOT_MESSAGE_MAX_LENGTH)}`;
             return line;
         })
             .join('\n\n');

package/dist/src/ai/provider.js

@@ -1,9 +1,9 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { OpenTelemetry } from '@ai-sdk/otel';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
-import { AsyncLocalStorage } from 'node:async_hooks';
-import dedent from 'dedent';
 import { APICallError, NoObjectGeneratedError, asSchema, extractJsonMiddleware, generateObject, generateText, isStepCount, parsePartialJson, registerTelemetry, tool, wrapLanguageModel } from 'ai';
+import dedent from 'dedent';
 import { z } from 'zod';
 import { clearActivity, setActivity } from "../activity.js";
 import { configuredModels, modelName as getModelName } from '../config.js';
@@ -51,15 +51,16 @@ const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum
 function extractCachedTokens(usage) {
     return usage?.inputTokenDetails?.cacheReadTokens ?? 0;
 }
-function abortAfterIdle(ms, cancel, controller, busy) {
+function abortAfterIdle(ms, state, controller, busy) {
     return new Promise((_, reject) => {
         const tick = () => {
-            if (cancel.cancelled)
+            if (state.cancelled)
                 return;
             if (executionController.isAwaitingInput() || busy.tools > 0) {
                 setTimeout(tick, ms);
                 return;
             }
+            state.timedOut = true;
             controller.abort();
             reject(new Error('AI request timeout'));
         };
@@ -232,14 +233,20 @@ export class Provider {
         });
     }
     async raceWithIdleTimeout(fn, timeoutMs, busy = { tools: 0 }) {
-        const cancel = { cancelled: false };
+        const state = { cancelled: false, timedOut: false };
         const controller = new AbortController();
         const combinedSignal = combinedAbortSignal(controller);
         try {
-            return await Promise.race([fn(combinedSignal), abortAfterIdle(timeoutMs, cancel, controller, busy)]);
+            return await Promise.race([fn(combinedSignal), abortAfterIdle(timeoutMs, state, controller, busy)]);
+        }
+        catch (error) {
+            if (state.timedOut && !executionController.getAbortSignal()?.aborted) {
+                throw new Error('AI request timeout', { cause: error });
+            }
+            throw error;
         }
         finally {
-            cancel.cancelled = true;
+            state.cancelled = true;
         }
     }
     async recoverFromContextLength(error, messages, options, retry) {

package/dist/src/ai/rerunner.js

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { relative, resolve } from 'node:path';
+import { dirname, relative, resolve } from 'node:path';
 import { tool } from 'ai';
 import { createBashTool } from 'bash-tool';
 import chalk from 'chalk';
@@ -19,6 +19,7 @@ import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
 import { RulesLoader } from "../utils/rules-loader.js";
 import { isInternalStep } from "../utils/step-analyzer.js";
+import { ensureCodeceptResolvable } from "../utils/test-files.js";
 import { toolExecutionLabel } from "./conversation.js";
 import { actionRule, locatorRule, sectionContextRule } from "./rules.js";
 import { TaskAgent } from "./task-agent.js";
@@ -122,6 +123,7 @@ export class Rerunner extends TaskAgent {
             const mocha = codeceptjs.container.mocha();
             mocha.reporter(class {
             });
+            ensureCodeceptResolvable(dirname(absPath));
             mocha.files = [absPath];
             mocha.loadFiles();
             let testIndex = 0;

package/dist/src/ai/rules.js

@@ -224,7 +224,7 @@ export const unexpectedPopupRule = dedent `
   If a modal/popup appeared that you didn't expect, dismiss it first before continuing with original task.
   If elements become hidden or unclickable (timeout errors on visible elements), a dialog or overlay may have appeared on top.
   If a click error mentions "intercepts pointer events", another element is covering the target — dismiss it first.
-  If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
+  If buttons are disabled unexpectedly, trust any explanation the app gives (tooltip, hint text) over your own guess; otherwise check for a blocking popup or empty required fields.
 
   Dismiss strategy (try in order):
   1. I.pressKey('Escape') — press Escape to dismiss

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

@@ -51,6 +51,7 @@ export declare class Tester extends TaskAgent implements Agent {
         success: boolean;
     }>;
     shouldAnalyzeProgress(iteration: number, currentState: ActionResult): boolean;
+    get isStruggling(): boolean;
     shouldStopForStalledExecution(task: Test, previousState: ActionResult, toolExecutions: any[]): boolean;
     prepareInstructionsForNextStep(task: Test): Promise<string>;
     reinjectContextIfNeeded(iteration: number, currentState: ActionResult): Promise<string>;

package/dist/src/ai/tester.js

@@ -285,7 +285,13 @@ export class Tester extends TaskAgent {
                             nextStep += `\n\n${guidance}`;
                     }
                     else if (this.shouldAnalyzeProgress(iteration, currentState) && this.pilot) {
-                        const guidance = await this.pilot.analyzeProgress(task, currentState, conversation);
+                        let guidance;
+                        if (this.isStruggling) {
+                            guidance = await this.pilot.analyzeProgress(task, currentState, conversation);
+                        }
+                        else {
+                            guidance = await this.pilot.periodicAnalyzeProgress(task, currentState, conversation);
+                        }
                         if (guidance)
                             nextStep += `\n\n${guidance}`;
                         this.consecutiveFailures = 0;
@@ -432,9 +438,7 @@ export class Tester extends TaskAgent {
             this.regionTransitioned = false;
             return true;
         }
-        if (this.consecutiveFailures >= 3)
-            return true;
-        if (this.consecutiveEmptyResults >= 2)
+        if (this.isStruggling)
             return true;
         if (iteration % this.progressCheckInterval !== 0)
             return false;
@@ -442,6 +446,9 @@ export class Tester extends TaskAgent {
             return false;
         return true;
     }
+    get isStruggling() {
+        return this.consecutiveFailures >= 3 || this.consecutiveEmptyResults >= 2;
+    }
     shouldStopForStalledExecution(task, previousState, toolExecutions) {
         if (task.hasFinished)
             return false;
@@ -675,6 +682,15 @@ export class Tester extends TaskAgent {
         return meta;
     }
     getSystemMessage() {
+        let judgeRule = '';
+        if (this.agentTools?.judge) {
+            judgeRule = dedent `
+        <judge_rule>
+        For a quick judgement about the current page (did the last action already take effect, which element the scenario means), ask judge() before see().
+        Keep see() for what only a screenshot shows.
+        </judge_rule>
+      `;
+        }
         return dedent `
     <role>
     You are a senior test automation engineer with expertise in CodeceptJS and exploratory testing.
@@ -774,6 +790,8 @@ export class Tester extends TaskAgent {
 
     ${capabilityGroundingRule}
 
+    ${judgeRule}
+
     ${dataProtectionRules}
 
     ${this.provider.getSystemPromptForAgent('tester', this.stateManager.getCurrentState()?.url) || ''}

package/dist/src/ai/tools.js

@@ -14,7 +14,7 @@ import { pause } from '../utils/loop.js';
 import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { WebElement } from "../utils/web-element.js";
 import { createJudgeTool } from "./judge-tool.js";
-import { JUDGE_PAGE_CAP, UNDECIDED } from "./judge.js";
+import { JUDGE_PAGE_CAP } from "./judge.js";
 import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 const debugLog = createDebug('explorbot:tools');
@@ -92,13 +92,20 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }, task) {
                 let ambiguityError = null;
                 for (let i = 0; i < commands.length; i++) {
                     const command = transformContainsCommand(commands[i]);
-                    const success = await action.attempt(command, explanation);
+                    let success = await action.attempt(command, explanation);
                     const attempt = { command, success };
                     if (action.lastError)
                         attempt.error = errorText(action.lastError);
                     attempts.push(attempt);
-                    if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound')
+                    if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound') {
                         ambiguityError = action.lastError;
+                        if (judge) {
+                            const labels = (await extractWebElements(ambiguityError))?.map((el) => el.label) || [];
+                            const index = await judge.pick(PICK_ELEMENT_QUESTION, labels, { intent: explanation, task: task.description });
+                            if (index)
+                                success = await action.attemptExactElementIndex(command, index, explanation);
+                        }
+                    }
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
                         if (!hasObservablePageChange(toolResult)) {
@@ -123,11 +130,22 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }, task) {
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
                 await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                 const suggestion = clickFailureSuggestion(attempts);
-                return failedToolResult('click', 'All click commands failed', {
-                    ...toolResult,
-                    attempts,
-                    suggestion,
-                }, ambiguityError || action.lastError, judge, explanation);
+                const data = { ...toolResult, attempts, suggestion };
+                const clickError = ambiguityError || action.lastError;
+                for (const disabled of attempts.filter((a) => a.error?.includes('not enabled'))) {
+                    const hoverCommand = disabled.command.replace('I.click(', 'I.moveCursorTo(');
+                    const beforeHover = ActionResult.fromState(stateManager.getCurrentState());
+                    if (!(await action.attempt(hoverCommand, 'Hover the disabled element to reveal why it is disabled')))
+                        continue;
+                    const hoverResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(beforeHover, hoverCommand);
+                    const shown = hoverResult.pageDiff?.messages;
+                    if (!shown?.length)
+                        break;
+                    data.disabledReason = shown;
+                    data.suggestion = `Element is DISABLED. Hovering it showed: "${shown.join(' | ')}". That is why — act on it or report it, do not guess another cause.`;
+                    break;
+                }
+                return failedToolResult('click', 'All click commands failed', data, clickError);
             },
         }),
         hover: tool({
@@ -1148,11 +1166,11 @@ export async function failedToolResult(action, message, data, error, judge, inte
         result.suggestion = getMultipleElementsSuggestion();
         result.multipleElementsDetected = true;
         result.elements = formatElementList(matched);
-        const labels = (matched || []).map((element) => `${element.text || 'no text'} — ${element.html}`);
-        const pick = await judge?.decide('Which listed element does the intent name?', [...labels, UNDECIDED], { intent });
-        if (!pick?.value)
+        if (!judge || !matched)
+            return result;
+        const index = await judge.pick(PICK_ELEMENT_QUESTION, matched.map((el) => el.label), { intent });
+        if (!index)
             return result;
-        const index = labels.indexOf(pick.value) + 1;
         result.suggestion = `Element ${index} is the one meant. Repeat the action with step.opts({ elementIndex: ${index} }) as the last argument.`;
         return result;
     }
@@ -1170,6 +1188,7 @@ function getMultipleElementsSuggestion() {
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
     A match reported as not visible can never be acted on — pick one that is.
     If none of them is the element you want, narrow the locator with a container or its full unique text.
+    If the matches cannot be told apart, click the one you mean by appearance with visualClick().
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
 }
@@ -1182,7 +1201,7 @@ export function withdrawVisionTools(tools) {
 export function clickFailureSuggestion(attempts) {
     const errors = attempts.map((a) => a.error || '');
     if (errors.some((e) => e.includes('not enabled'))) {
-        return 'Element exists but is DISABLED — clicking it again cannot work. A precondition is unmet: a required field is empty, nothing is selected, or a dialog is blocking. Satisfy it, then retry.';
+        return 'Element exists but is DISABLED — clicking it again cannot work. Find the precondition the page shows as unmet, then retry.';
     }
     if (errors.some((e) => e.includes('intercepts pointer events'))) {
         return 'Element exists but another element covers it. Close the overlapping panel or dialog, then retry.';
@@ -1206,6 +1225,7 @@ const MAX_DISAMBIGUATE_ELEMENTS = 10;
 const MAX_DISAMBIGUATE_TEXT = 80;
 const MAX_DISAMBIGUATE_HTML = 300;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
+const PICK_ELEMENT_QUESTION = 'Which listed element does the intent name?';
 async function extractWebElements(error) {
     if (!error || error.name !== 'MultipleElementsFound')
         return null;
@@ -1219,7 +1239,7 @@ async function extractWebElements(error) {
             const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
             const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
             const visible = await Promise.resolve(elements[i].isVisible?.()).catch(() => undefined);
-            result.push({ xpath, html, text, visible });
+            result.push({ xpath, html, text, visible, label: `${text || 'no text'} — ${html}` });
         }
         catch (e) {
             debugLog('Failed to get details for element %d: %s', i, e);

package/dist/src/config.d.ts

@@ -162,6 +162,7 @@ interface AIConfig {
         model: string;
         tool?: boolean;
         direct?: boolean;
+        threshold?: number;
     };
     retryAttempts?: number;
     retryDelay?: number;
@@ -242,6 +243,7 @@ export declare class ConfigParser {
     site: SiteRecord | null;
     siteStartPath: string;
     siteConfigPath: string | null;
+    runBase: RunBase | null;
     constructor();
     static loadEnv(filePath: string, keepExisting?: boolean): void;
     static recommendedModels(): Record<string, Record<string, string>>;
@@ -260,6 +262,9 @@ export declare class ConfigParser {
     isGlobalMode(): boolean;
     getSite(): SiteRecord | null;
     getSiteConfigPath(): string | null;
+    applyBasePath(target: string): string;
+    getBaseQuery(): string;
+    getBasePath(): string;
     resolveTargetPath(target?: string): string;
     getStatesDir(): string;
     getPlansDir(): string;
@@ -274,9 +279,7 @@ export declare class ConfigParser {
     buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig>;
     findConfigFile(): string | null;
     loadConfigModule(configPath: string): Promise<any>;
-    resolveConfig(config: ExplorbotConfig, options?: {
-        baseUrl?: string;
-    }): ExplorbotConfig;
+    resolveConfig(config: ExplorbotConfig): ExplorbotConfig;
     validateConfig(config: ExplorbotConfig): void;
     getNestedValue(obj: any, path: string): any;
     mergeWithDefaults(config: Partial<ExplorbotConfig>): ExplorbotConfig;
@@ -301,6 +304,11 @@ export declare function resolveStateRoot(baseUrl: string, ephemeral?: boolean):
 export declare function materializeKnowledge(outputRoot: string): void;
 export declare function createModel(provider: string, modelId: string): Promise<any>;
 type ModelRole = 'model' | 'visionModel' | 'agenticModel';
+interface RunBase {
+    origin: string;
+    path: string;
+    query: string;
+}
 interface ConfiguredModel {
     name: string;
     provider: string;