explorbot 0.5.2 → 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.2",
+  "version": "0.5.3",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

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');

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-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/pilot.js

@@ -1059,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/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.js

@@ -682,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.
@@ -781,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

@@ -130,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);
+                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({
@@ -1190,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.';

package/dist/src/config.d.ts

@@ -243,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>>;
@@ -261,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;
@@ -275,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;
@@ -302,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;

package/dist/src/config.js

@@ -65,6 +65,7 @@ export class ConfigParser {
     site = null;
     siteStartPath = '/';
     siteConfigPath = null;
+    runBase = null;
     constructor() { }
     static loadEnv(filePath, keepExisting = false) {
         const resolved = resolve(filePath);
@@ -96,6 +97,7 @@ export class ConfigParser {
         if (this.config && !options?.config && !options?.path && this.runtimeTarget === target) {
             return this.config;
         }
+        this.runBase = parseRunBase(options?.baseUrl);
         // Store the initial working directory for reference
         if (!process.env.INITIAL_CWD) {
             process.env.INITIAL_CWD = process.cwd();
@@ -123,12 +125,19 @@ export class ConfigParser {
                 let envUrl = options?.baseUrl;
                 if (!envUrl && target?.startsWith('http'))
                     envUrl = target;
-                const outputRoot = resolveOutputRoot(process.env.EXPLORBOT_URL || envUrl);
+                if (options?.baseUrl) {
+                    const envOrigin = URL.parse(process.env.EXPLORBOT_URL || '')?.origin;
+                    const baseOrigin = URL.parse(options.baseUrl)?.origin;
+                    if (envOrigin && envOrigin !== baseOrigin) {
+                        tag('warning').log(`--base-url ${baseOrigin} selects the site for this run — EXPLORBOT_URL ${envOrigin} is ignored`);
+                    }
+                }
+                const outputRoot = resolveOutputRoot(options?.baseUrl || process.env.EXPLORBOT_URL || envUrl);
                 loadedConfig = await this.buildEnvConfig(envUrl, outputRoot);
                 sourcePath = join(outputRoot, 'explorbot.config.js');
                 log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
             }
-            let config = this.resolveConfig(loadedConfig, options);
+            let config = this.resolveConfig(loadedConfig);
             await resolveConfigModels(config.ai);
             this.site = null;
             this.siteConfigPath = null;
@@ -195,6 +204,22 @@ export class ConfigParser {
     getSiteConfigPath() {
         return this.siteConfigPath;
     }
+    applyBasePath(target) {
+        const base = this.runBase?.path;
+        if (!base)
+            return target;
+        if (!target.startsWith('/'))
+            return target;
+        if (target === base || target.startsWith(`${base}/`) || target.startsWith(`${base}?`))
+            return target;
+        return `${base}${target}`;
+    }
+    getBaseQuery() {
+        return this.runBase?.query || '';
+    }
+    getBasePath() {
+        return this.runBase?.path || '';
+    }
     resolveTargetPath(target) {
         if (!this.site) {
             const configured = this.config?.playwright?.url || this.config?.web?.url;
@@ -203,13 +228,15 @@ export class ConfigParser {
             if (targetOrigin && baseOrigin && targetOrigin !== baseOrigin) {
                 tag('warning').log(`Exploring ${targetOrigin} but base URL is ${baseOrigin}. Relative navigation resolves against the base URL — set web.url to ${targetOrigin} to avoid it.`);
             }
-            return target || '/';
+            return this.applyBasePath(target || '/');
         }
         if (!target)
             return this.siteStartPath;
         const resolved = resolveSiteTarget(target, this.site.url);
         if (resolved.baseUrl !== this.site.url)
             return target;
+        if (target.startsWith('/'))
+            return this.applyBasePath(resolved.path);
         return resolved.path;
     }
     getStatesDir() {
@@ -232,6 +259,7 @@ export class ConfigParser {
             ConfigParser.instance.site = null;
             ConfigParser.instance.siteStartPath = '/';
             ConfigParser.instance.siteConfigPath = null;
+            ConfigParser.instance.runBase = null;
         }
     }
     // For testing purposes only - sets up minimal default config
@@ -393,14 +421,14 @@ export class ConfigParser {
             return JSON.parse(content);
         }
     }
-    resolveConfig(config, options) {
+    resolveConfig(config) {
         if (config.web?.url && !config.playwright?.url) {
             config.playwright = config.playwright || { browser: 'chromium', url: '' };
             config.playwright.url = config.web.url;
         }
-        if (options?.baseUrl) {
+        if (this.runBase) {
             config.playwright = config.playwright || { browser: 'chromium', url: '' };
-            config.playwright.url = options.baseUrl;
+            config.playwright.url = this.runBase.origin;
         }
         resolveLangfuse(config.ai);
         return config;
@@ -609,3 +637,11 @@ export async function createModel(provider, modelId) {
     }
     return (await info.load())(modelId);
 }
+function parseRunBase(baseUrl) {
+    if (!baseUrl)
+        return null;
+    const url = URL.parse(baseUrl);
+    if (!url)
+        throw new Error(`Base URL must be a full URL like https://app.example.com/team/acme, got "${baseUrl}"`);
+    return { origin: url.origin, path: url.pathname.replace(/\/+$/, ''), query: url.search };
+}

package/dist/src/explorbot.js

@@ -449,6 +449,10 @@ export class ExplorBot {
         this.currentPlan = plan;
         if (!plan)
             return;
+        if (plan.url)
+            plan.url = this.configParser.applyBasePath(plan.url);
+        for (const test of plan.tests)
+            test.startUrl = this.configParser.applyBasePath(test.startUrl);
         if (!this.sessionPlans.includes(plan)) {
             this.sessionPlans.push(plan);
         }

package/dist/src/explorer.d.ts

@@ -57,6 +57,8 @@ declare class Explorer {
     convertToCodeceptConfig(config: ExplorbotConfig): any;
     connectOrLaunchBrowser(): Promise<void>;
     openContextPage(): Promise<void>;
+    applyBasePathToHelper(): void;
+    pinBaseQuery(): Promise<void>;
     createBrowserContextOptions(): BrowserContextOptions;
     attachXhrCapture(): void;
     runWithRecovery<T>(label: string, operation: () => Promise<T>): Promise<T>;

package/dist/src/explorer.js

@@ -73,6 +73,7 @@ class Explorer {
         if (!this.playwrightHelper) {
             throw new Error('Playwright helper not available');
         }
+        this.applyBasePathToHelper();
         await this.connectOrLaunchBrowser();
         const hasSession = !this.options?.attachedBrowser && this.options?.session && existsSync(this.options.session);
         await this.openContextPage();
@@ -124,7 +125,7 @@ class Explorer {
     }
     async visit(url, opts = {}) {
         return this.runWithRecovery('visit', async () => {
-            const action = await this.visitOnce(url);
+            const action = await this.visitOnce(ConfigParser.getInstance().applyBasePath(url));
             if (opts.screenshot)
                 return action.capturePageState({ includeScreenshot: true });
             return action.getActionResult() ?? action.capturePageState();
@@ -279,6 +280,7 @@ class Explorer {
         const attached = this.options?.attachedBrowser;
         if (!attached) {
             await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+            await this.pinBaseQuery();
             return;
         }
         const context = attached.contexts()[0] || (await attached.newContext());
@@ -287,6 +289,36 @@ class Explorer {
         this.playwrightHelper.browserContext = context;
         await this.playwrightHelper._setPage(page);
         debugLog(`Adopted attached browser page: ${page.url()}`);
+        await this.pinBaseQuery();
+    }
+    applyBasePathToHelper() {
+        if (!ConfigParser.getInstance().getBasePath())
+            return;
+        const helper = this.playwrightHelper;
+        const original = helper.amOnPage.bind(helper);
+        helper.amOnPage = (url) => original(ConfigParser.getInstance().applyBasePath(url));
+    }
+    async pinBaseQuery() {
+        const query = ConfigParser.getInstance().getBaseQuery();
+        if (!query)
+            return;
+        const pinned = new URLSearchParams(query);
+        const origin = URL.parse(this.config.playwright.url)?.origin;
+        await this.playwrightHelper.browserContext.route('**/*', async (route) => {
+            const request = route.request();
+            if (request.resourceType() !== 'document')
+                return route.continue();
+            const url = URL.parse(request.url());
+            if (!url || url.origin !== origin)
+                return route.continue();
+            const missing = [...pinned].filter(([key]) => !url.searchParams.has(key));
+            if (!missing.length)
+                return route.continue();
+            for (const [key, value] of missing)
+                url.searchParams.set(key, value);
+            return route.continue({ url: url.toString() });
+        });
+        tag('info').log(`Every page load of ${origin} carries ${query}`);
     }
     createBrowserContextOptions() {
         const helperOptions = this.playwrightHelper.options || {};

package/dist/src/global-config.js

@@ -116,7 +116,7 @@ export function resolveSiteTarget(target, defaultBaseUrl) {
         return { baseUrl: url.origin, path: `${url.pathname}${url.search}${url.hash}` };
     }
     if (raw.startsWith('/')) {
-        const base = defaultBaseUrl || process.env.EXPLORBOT_URL;
+        const base = process.env.EXPLORBOT_URL || defaultBaseUrl;
         if (!base) {
             throw new Error(withSites(`Cannot resolve path "${raw}" without a site.`));
         }

package/dist/src/utils/test-files.d.ts

@@ -1,4 +1,9 @@
 export declare function listTestFiles(testsDir: string): string[];
+/**
+ * Generated tests import `codeceptjs/steps`, but in global mode they lie in ~/.explorbot,
+ * far from any node_modules. Link the bot's own codeceptjs next to them so Node resolves it.
+ */
+export declare function ensureCodeceptResolvable(dir: string): void;
 export declare function loadTestSuites(testsDir: string): any[];
 export declare function printTestList(suites: any[]): void;
 export declare function dryRunTestFile(filePath: string): Promise<void>;

package/dist/src/utils/test-files.js

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import chalk from 'chalk';
 import { highlight } from 'cli-highlight';
@@ -8,6 +9,7 @@ import storeListener from 'codeceptjs/lib/listener/store';
 import store from 'codeceptjs/lib/store';
 import figureSet from 'figures';
 import { ConfigParser } from "../config.js";
+const nodeRequire = createRequire(import.meta.url);
 export function listTestFiles(testsDir) {
     if (!existsSync(testsDir))
         return [];
@@ -15,10 +17,34 @@ export function listTestFiles(testsDir) {
         .filter((f) => f.endsWith('.js'))
         .map((f) => path.resolve(testsDir, f));
 }
+/**
+ * Generated tests import `codeceptjs/steps`, but in global mode they lie in ~/.explorbot,
+ * far from any node_modules. Link the bot's own codeceptjs next to them so Node resolves it.
+ */
+export function ensureCodeceptResolvable(dir) {
+    const link = path.join(dir, 'node_modules', 'codeceptjs');
+    if (existsSync(link))
+        return;
+    let target;
+    try {
+        target = path.dirname(nodeRequire.resolve('codeceptjs/package.json'));
+    }
+    catch {
+        return;
+    }
+    try {
+        mkdirSync(path.dirname(link), { recursive: true });
+        symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir');
+    }
+    catch {
+        // Best effort: a project install already resolves codeceptjs without the link.
+    }
+}
 export function loadTestSuites(testsDir) {
     const jsFiles = listTestFiles(testsDir);
     if (jsFiles.length === 0)
         return [];
+    ensureCodeceptResolvable(testsDir);
     codeceptjs.container.createMocha();
     const mocha = codeceptjs.container.mocha();
     mocha.files = jsFiles;
@@ -79,6 +105,7 @@ export async function dryRunTestFile(filePath) {
     const mocha = codeceptjs.container.mocha();
     mocha.reporter(class {
     });
+    ensureCodeceptResolvable(path.dirname(absPath));
     mocha.files = [absPath];
     mocha.loadFiles();
     let currentSuite = '';

package/docs/reference/commands.md

@@ -66,11 +66,23 @@ Every CLI command that drives a browser accepts these options (`start`, `explore
 | `--debug` | Enable debug logging (same as `--verbose`) |
 | `-c, --config <path>` | Path to configuration file |
 | `-p, --path <path>` | Working directory path |
+| `--base-url <url>` | Run against this URL: its path scopes relative paths, its query params ride along with every page load |
 | `-s, --show` | Show browser window |
 | `--headless` | Run browser in headless mode |
 | `--incognito` | Run without recording experiences |
 | `--session [file]` | Save/restore browser session (cookies, localStorage) from file |
 
+### `--base-url`
+
+Points one run at one area of a site, leaving every config file alone. The origin selects the site, so the knowledge and experience already stored for that host still apply. The path prefixes every relative path a plan or a command gives, and the query params are added to each page load.
+
+```bash
+npx explorbot test tests/plans/runs.md '*' \
+  --base-url 'https://app.example.com/teams/acme/?preview=pr-42'
+```
+
+A plan whose tests start at `/runs` runs them at `/teams/acme/runs`, and every page load carries `?preview=pr-42` — enough to keep a preview deployment selected for a whole session. The param travels on the request rather than in the address bar, so Explorbot navigates to clean URLs, though an app that redirects can still echo the param back. Absolute URLs are never prefixed: `https://app.example.com/users/sign_in` still points outside the scoped area, as a login page usually must.
+
 ### `--knowledge`
 
 Passes facts to the run without creating a file in `knowledge/`. Plain text applies everywhere; add frontmatter to scope it to a page or an API endpoint. Repeat the flag for several facts. See [Knowledge](../workflow/knowledge.md#per-session-knowledge).

package/package.json

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

package/src/action.ts

@@ -114,6 +114,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(() => {
@@ -124,6 +125,7 @@ class Action {
             debugLog('Screenshot failed, continuing without it:', err);
             return undefined;
           });
+        await page?.screencast?.showOverlays().catch(() => {});
       }
 
       // Save HTML to file

package/src/ai/historian/codeceptjs.ts

@@ -8,6 +8,7 @@ import { tag } from '../../utils/logger.ts';
 import { relativeToCwd } from '../../utils/next-steps.ts';
 import { CODECEPT_TOOLS, isNonReusableCode, stripComments } from '../../utils/step-analyzer.ts';
 import { safeFilename } from '../../utils/strings.ts';
+import { ensureCodeceptResolvable } from '../../utils/test-files.ts';
 import type { Conversation } from '../conversation.ts';
 import { ASSERTION_TOOLS } from '../tools.ts';
 import type { Constructor } from './mixin.ts';
@@ -99,6 +100,7 @@ export function WithCodeceptJS<T extends Constructor>(Base: T) {
 
       const testsDir = ConfigParser.getInstance().getTestsDir();
       mkdirSync(testsDir, { recursive: true });
+      ensureCodeceptResolvable(testsDir);
 
       const filePath = join(testsDir, safeFilename(plan.title, '.js'));
       writeFileSync(filePath, lines.join('\n'));

package/src/ai/judge-tool.ts

@@ -11,7 +11,11 @@ export function createJudgeTool(deps: ToolDeps, buildState: () => Promise<Record
   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/src/ai/pilot.ts

@@ -1162,6 +1162,9 @@ export class Pilot implements Agent {
         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/src/ai/rerunner.ts

@@ -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.ts';
 import { loop } from '../utils/loop.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
 import { isInternalStep } from '../utils/step-analyzer.ts';
+import { ensureCodeceptResolvable } from '../utils/test-files.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import { toolExecutionLabel } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
@@ -135,6 +136,7 @@ export class Rerunner extends TaskAgent implements Agent {
       codeceptjs.container.createMocha();
       const mocha = codeceptjs.container.mocha();
       mocha.reporter(class {});
+      ensureCodeceptResolvable(dirname(absPath));
       mocha.files = [absPath];
       mocha.loadFiles();
 

package/src/ai/rules.ts

@@ -237,7 +237,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/src/ai/tester.ts

@@ -752,6 +752,16 @@ export class Tester extends TaskAgent implements Agent {
   }
 
   getSystemMessage(): string {
+    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.
@@ -851,6 +861,8 @@ export class Tester extends TaskAgent implements Agent {
 
     ${capabilityGroundingRule}
 
+    ${judgeRule}
+
     ${dataProtectionRules}
 
     ${this.provider.getSystemPromptForAgent('tester', this.stateManager.getCurrentState()?.url) || ''}

package/src/ai/tools.ts

@@ -156,17 +156,22 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
         const suggestion = clickFailureSuggestion(attempts);
+        const data: Record<string, any> = { ...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',
-          {
-            ...toolResult,
-            attempts,
-            suggestion,
-          },
-          ambiguityError || action.lastError
-        );
+        return failedToolResult('click', 'All click commands failed', data, clickError);
       },
     }),
 
@@ -1356,7 +1361,7 @@ export function clickFailureSuggestion(attempts: Array<{ error?: string }>): str
   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'))) {

package/src/config.ts

@@ -327,6 +327,7 @@ export class ConfigParser {
   private site: SiteRecord | null = null;
   private siteStartPath = '/';
   private siteConfigPath: string | null = null;
+  private runBase: RunBase | null = null;
 
   private constructor() {}
 
@@ -368,6 +369,7 @@ export class ConfigParser {
     if (this.config && !options?.config && !options?.path && this.runtimeTarget === target) {
       return this.config;
     }
+    this.runBase = parseRunBase(options?.baseUrl);
 
     // Store the initial working directory for reference
     if (!process.env.INITIAL_CWD) {
@@ -404,14 +406,21 @@ export class ConfigParser {
         let envUrl = options?.baseUrl;
         if (!envUrl && target?.startsWith('http')) envUrl = target;
 
-        const outputRoot = resolveOutputRoot(process.env.EXPLORBOT_URL || envUrl);
+        if (options?.baseUrl) {
+          const envOrigin = URL.parse(process.env.EXPLORBOT_URL || '')?.origin;
+          const baseOrigin = URL.parse(options.baseUrl)?.origin;
+          if (envOrigin && envOrigin !== baseOrigin) {
+            tag('warning').log(`--base-url ${baseOrigin} selects the site for this run — EXPLORBOT_URL ${envOrigin} is ignored`);
+          }
+        }
+        const outputRoot = resolveOutputRoot(options?.baseUrl || process.env.EXPLORBOT_URL || envUrl);
         loadedConfig = await this.buildEnvConfig(envUrl, outputRoot);
         sourcePath = join(outputRoot, 'explorbot.config.js');
 
         log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
       }
 
-      let config = this.resolveConfig(loadedConfig as ExplorbotConfig, options);
+      let config = this.resolveConfig(loadedConfig as ExplorbotConfig);
       await resolveConfigModels(config.ai);
       this.site = null;
       this.siteConfigPath = null;
@@ -484,6 +493,22 @@ export class ConfigParser {
     return this.siteConfigPath;
   }
 
+  public applyBasePath(target: string): string {
+    const base = this.runBase?.path;
+    if (!base) return target;
+    if (!target.startsWith('/')) return target;
+    if (target === base || target.startsWith(`${base}/`) || target.startsWith(`${base}?`)) return target;
+    return `${base}${target}`;
+  }
+
+  public getBaseQuery(): string {
+    return this.runBase?.query || '';
+  }
+
+  public getBasePath(): string {
+    return this.runBase?.path || '';
+  }
+
   public resolveTargetPath(target?: string): string {
     if (!this.site) {
       const configured = this.config?.playwright?.url || this.config?.web?.url;
@@ -492,12 +517,13 @@ export class ConfigParser {
       if (targetOrigin && baseOrigin && targetOrigin !== baseOrigin) {
         tag('warning').log(`Exploring ${targetOrigin} but base URL is ${baseOrigin}. Relative navigation resolves against the base URL — set web.url to ${targetOrigin} to avoid it.`);
       }
-      return target || '/';
+      return this.applyBasePath(target || '/');
     }
     if (!target) return this.siteStartPath;
 
     const resolved = resolveSiteTarget(target, this.site.url);
     if (resolved.baseUrl !== this.site.url) return target;
+    if (target.startsWith('/')) return this.applyBasePath(resolved.path);
     return resolved.path;
   }
 
@@ -524,6 +550,7 @@ export class ConfigParser {
       ConfigParser.instance.site = null;
       ConfigParser.instance.siteStartPath = '/';
       ConfigParser.instance.siteConfigPath = null;
+      ConfigParser.instance.runBase = null;
     }
   }
 
@@ -694,15 +721,15 @@ export class ConfigParser {
     }
   }
 
-  private resolveConfig(config: ExplorbotConfig, options?: { baseUrl?: string }): ExplorbotConfig {
+  private resolveConfig(config: ExplorbotConfig): ExplorbotConfig {
     if (config.web?.url && !config.playwright?.url) {
       config.playwright = config.playwright || { browser: 'chromium', url: '' };
       config.playwright.url = config.web.url;
     }
 
-    if (options?.baseUrl) {
+    if (this.runBase) {
       config.playwright = config.playwright || { browser: 'chromium', url: '' };
-      config.playwright.url = options.baseUrl;
+      config.playwright.url = this.runBase.origin;
     }
 
     resolveLangfuse(config.ai);
@@ -936,8 +963,23 @@ export async function createModel(provider: string, modelId: string): Promise<an
   return (await info.load())(modelId);
 }
 
+function parseRunBase(baseUrl?: string): RunBase | null {
+  if (!baseUrl) return null;
+
+  const url = URL.parse(baseUrl);
+  if (!url) throw new Error(`Base URL must be a full URL like https://app.example.com/team/acme, got "${baseUrl}"`);
+
+  return { origin: url.origin, path: url.pathname.replace(/\/+$/, ''), query: url.search };
+}
+
 type ModelRole = 'model' | 'visionModel' | 'agenticModel';
 
+interface RunBase {
+  origin: string;
+  path: string;
+  query: string;
+}
+
 interface ConfiguredModel {
   name: string;
   provider: string;

package/src/explorbot.ts

@@ -517,6 +517,8 @@ export class ExplorBot {
   setCurrentPlan(plan?: Plan): void {
     this.currentPlan = plan;
     if (!plan) return;
+    if (plan.url) plan.url = this.configParser.applyBasePath(plan.url);
+    for (const test of plan.tests) test.startUrl = this.configParser.applyBasePath(test.startUrl);
     if (!this.sessionPlans.includes(plan)) {
       this.sessionPlans.push(plan);
     }

package/src/explorer.ts

@@ -6,7 +6,7 @@ import stepsListener from 'codeceptjs/lib/listener/steps';
 import storeListener from 'codeceptjs/lib/listener/store';
 import { createTest } from 'codeceptjs/lib/mocha/test';
 import dedent from 'dedent';
-import type { Browser, BrowserContextOptions, Page } from 'playwright';
+import type { Browser, BrowserContextOptions, Page, Route } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
 import type { RequestStore } from './api/request-store.ts';
@@ -103,6 +103,7 @@ class Explorer {
     if (!this.playwrightHelper) {
       throw new Error('Playwright helper not available');
     }
+    this.applyBasePathToHelper();
     await this.connectOrLaunchBrowser();
     const hasSession = !this.options?.attachedBrowser && this.options?.session && existsSync(this.options.session);
     await this.openContextPage();
@@ -163,7 +164,7 @@ class Explorer {
 
   async visit(url: string, opts: CaptureOpts = {}): Promise<ActionResult> {
     return this.runWithRecovery('visit', async () => {
-      const action = await this.visitOnce(url);
+      const action = await this.visitOnce(ConfigParser.getInstance().applyBasePath(url));
       if (opts.screenshot) return action.capturePageState({ includeScreenshot: true });
       return action.getActionResult() ?? action.capturePageState();
     });
@@ -347,6 +348,7 @@ class Explorer {
     const attached = this.options?.attachedBrowser;
     if (!attached) {
       await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+      await this.pinBaseQuery();
       return;
     }
 
@@ -356,6 +358,39 @@ class Explorer {
     this.playwrightHelper.browserContext = context;
     await this.playwrightHelper._setPage(page);
     debugLog(`Adopted attached browser page: ${page.url()}`);
+    await this.pinBaseQuery();
+  }
+
+  private applyBasePathToHelper(): void {
+    if (!ConfigParser.getInstance().getBasePath()) return;
+
+    const helper = this.playwrightHelper;
+    const original = helper.amOnPage.bind(helper);
+    helper.amOnPage = (url: string) => original(ConfigParser.getInstance().applyBasePath(url));
+  }
+
+  private async pinBaseQuery(): Promise<void> {
+    const query = ConfigParser.getInstance().getBaseQuery();
+    if (!query) return;
+
+    const pinned = new URLSearchParams(query);
+    const origin = URL.parse(this.config.playwright.url)?.origin;
+
+    await this.playwrightHelper.browserContext.route('**/*', async (route: Route) => {
+      const request = route.request();
+      if (request.resourceType() !== 'document') return route.continue();
+
+      const url = URL.parse(request.url());
+      if (!url || url.origin !== origin) return route.continue();
+
+      const missing = [...pinned].filter(([key]) => !url.searchParams.has(key));
+      if (!missing.length) return route.continue();
+
+      for (const [key, value] of missing) url.searchParams.set(key, value);
+      return route.continue({ url: url.toString() });
+    });
+
+    tag('info').log(`Every page load of ${origin} carries ${query}`);
   }
 
   private createBrowserContextOptions(): BrowserContextOptions {

package/src/global-config.ts

@@ -131,7 +131,7 @@ export function resolveSiteTarget(target?: string, defaultBaseUrl?: string): Sit
   }
 
   if (raw.startsWith('/')) {
-    const base = defaultBaseUrl || process.env.EXPLORBOT_URL;
+    const base = process.env.EXPLORBOT_URL || defaultBaseUrl;
     if (!base) {
       throw new Error(withSites(`Cannot resolve path "${raw}" without a site.`));
     }

package/src/utils/test-files.ts

@@ -1,4 +1,5 @@
-import { existsSync, readdirSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import chalk from 'chalk';
 import { highlight } from 'cli-highlight';
@@ -9,6 +10,8 @@ import store from 'codeceptjs/lib/store';
 import figureSet from 'figures';
 import { ConfigParser } from '../config.ts';
 
+const nodeRequire = createRequire(import.meta.url);
+
 export function listTestFiles(testsDir: string): string[] {
   if (!existsSync(testsDir)) return [];
 
@@ -17,10 +20,32 @@ export function listTestFiles(testsDir: string): string[] {
     .map((f) => path.resolve(testsDir, f));
 }
 
+/**
+ * Generated tests import `codeceptjs/steps`, but in global mode they lie in ~/.explorbot,
+ * far from any node_modules. Link the bot's own codeceptjs next to them so Node resolves it.
+ */
+export function ensureCodeceptResolvable(dir: string): void {
+  const link = path.join(dir, 'node_modules', 'codeceptjs');
+  if (existsSync(link)) return;
+  let target: string;
+  try {
+    target = path.dirname(nodeRequire.resolve('codeceptjs/package.json'));
+  } catch {
+    return;
+  }
+  try {
+    mkdirSync(path.dirname(link), { recursive: true });
+    symlinkSync(target, link, process.platform === 'win32' ? 'junction' : 'dir');
+  } catch {
+    // Best effort: a project install already resolves codeceptjs without the link.
+  }
+}
+
 export function loadTestSuites(testsDir: string): any[] {
   const jsFiles = listTestFiles(testsDir);
   if (jsFiles.length === 0) return [];
 
+  ensureCodeceptResolvable(testsDir);
   codeceptjs.container.createMocha();
   const mocha = codeceptjs.container.mocha();
   mocha.files = jsFiles;
@@ -93,6 +118,7 @@ export async function dryRunTestFile(filePath: string): Promise<void> {
   codeceptjs.container.createMocha();
   const mocha = codeceptjs.container.mocha();
   mocha.reporter(class {});
+  ensureCodeceptResolvable(path.dirname(absPath));
   mocha.files = [absPath];
   mocha.loadFiles();