explorbot 0.5.2 → 0.5.4

package/dist/src/ai/navigator.js

@@ -119,10 +119,10 @@ class Navigator {
         const currentUrl = this.getComparableCurrentUrl(stateManager, expectedUrl);
         return matchesNavigationUrl(expectedUrl, currentUrl);
     }
-    async visit(url) {
-        return this.visitOnce(url);
+    async visit(url, opts = {}) {
+        return this.visitOnce(url, opts.recover !== false);
     }
-    async visitOnce(url) {
+    async visitOnce(url, recover) {
         try {
             const action = this.explorer.action();
             await action.execute(`I.amOnPage('${url}')`);
@@ -131,7 +131,10 @@ class Navigator {
                 throw new Error(`Navigation to "${url}" opened an empty page. The target must be a valid URL path starting with "/".`);
             }
             await this.hooksRunner.runBeforeHook('navigator', url);
-            if (!this.isOnExpectedPage(url, action.stateManager)) {
+            if (!recover && action.lastError)
+                throw new Error(`Navigation to ${url} failed: ${action.lastError.message}`);
+            const arrived = this.isOnExpectedPage(url, action.stateManager);
+            if (recover && !arrived) {
                 const actualPath = action.stateManager.getCurrentState()?.url || '';
                 const actionResult = action.actionResult || ActionResult.fromState(action.stateManager.getCurrentState());
                 const originalMessage = `Navigate to: ${url}. Current page: ${actualPath}`;
@@ -154,6 +157,7 @@ class Navigator {
             }
             await this.explorer.capture({ screenshot: true });
             await this.hooksRunner.runAfterHook('navigator', url);
+            return arrived || recover;
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);
@@ -252,7 +256,7 @@ class Navigator {
                     return;
                 }
                 tag('operation').log('Feeding failures back to AI for a new batch...');
-                conversation.addUserText(await this.buildRetryFeedback(batchFailures, !htmlContextAdded, actionResult));
+                conversation.addUserText(await this.buildRetryFeedback(batchFailures, !htmlContextAdded, action.actionResult ?? actionResult));
                 htmlContextAdded = true;
                 codeBlocks = [];
                 batchFailures.length = 0;
@@ -347,10 +351,6 @@ class Navigator {
 
       <page>
         ${actionResult.toAiContext()}
-
-        <page_html>
-        ${await actionResult.combinedHtml()}
-        </page_html>
       </page>
 
       <task>
@@ -360,6 +360,8 @@ class Navigator {
         Propose different solutions to achieve the result.
         Solution should be valid CodeceptJS code.
         Use only data from the <page> context to plan the solution.
+        The page is given as an ARIA snapshot only: use ARIA and text locators from it.
+        Full HTML is provided if these solutions fail.
         Try various ways to achieve the result
       </task>
 
@@ -722,7 +724,10 @@ class Navigator {
                 await action.exitIframe();
                 const verified = await action.attempt(codeBlock, message);
                 const proof = action.assertionSteps.map(renderAssertion).filter(Boolean);
-                results.push({ code: codeBlock, passed: verified, proof });
+                const result = { code: codeBlock, passed: verified, proof };
+                if (!verified && action.lastError)
+                    result.error = action.lastError.message;
+                results.push(result);
                 if (verified) {
                     tag('success').log('Verification passed');
                     successfulCodes.push(codeBlock);

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

@@ -3,7 +3,7 @@ import type { RequestStore } from '../api/request-store.js';
 import type Explorer from '../explorer.js';
 import type { PlaywrightRecorder } from '../playwright-recorder.js';
 import type { StateManager } from '../state-manager.js';
-import { type Test } from '../test-plan.js';
+import { SettledExpectation, type SettledStatus, type Test } from '../test-plan.js';
 import type { Agent, AgentDeps } from './agent.js';
 import type { Conversation } from './conversation.js';
 import type { Fisherman } from './fisherman.js';
@@ -44,6 +44,7 @@ export declare class Pilot implements Agent {
     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[]>;
+    resolveContradictions(outcomes: SettledExpectation[], finalState?: ActionResult): Promise<SettledExpectation[]>;
     settleByJudge(task: Test, expectations: string[]): Promise<Map<string, SettledStatus>>;
     formatExpectations(task: Test): string;
     sendToPilot(userText: string, functionId: string, opts: {
@@ -104,9 +105,3 @@ export declare class Pilot implements Agent {
     formatActions(toolCalls: any[]): string;
     getSystemPrompt(task: Test, initialState: ActionResult): string;
 }
-export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
-export interface SettledExpectation {
-    text: string;
-    status: SettledStatus;
-    evidence?: string;
-}

package/dist/src/ai/pilot.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { ConfigParser } from "../config.js";
 import { Stats } from "../stats.js";
-import { TestResult, TestStatus } from "../test-plan.js";
+import { SettledExpectation, TestResult, TestStatus } from "../test-plan.js";
 import { collectInteractiveNodes } from "../utils/aria.js";
 import { ErrorPageError } from "../utils/error-page.js";
 import { createDebug, tag } from "../utils/logger.js";
@@ -26,6 +26,11 @@ const OUTCOME_STATUS = {
     'The run shows this outcome happened.': 'passed',
     'The run shows this outcome did not happen.': 'failed',
 };
+const CONTRADICTION_RESOLUTION = {
+    'The page structure agrees with the screenshot, and the outcome happened.': { status: 'passed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+    'The page structure agrees with the screenshot, and the outcome did not happen.': { status: 'failed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+    'The page structure agrees with the run log: the page holds it, but the screenshot does not show it.': { status: 'contradiction', resolution: 'the page structure agrees with the run log: the page holds it but does not display it, a likely rendering bug' },
+};
 export class Pilot {
     emoji = '🧭';
     provider;
@@ -544,7 +549,7 @@ export class Pilot {
             settledByJudge = await this.settleByJudge(task, undecided);
         undecided = undecided.filter((text) => !settledByJudge.has(text));
         if (!undecided.length)
-            return task.expected.map((text) => ({ text, status: settledByJudge.get(text) || decided(text) }));
+            return task.expected.map((text) => new SettledExpectation(text, settledByJudge.get(text) || decided(text)));
         const schema = z.object({
             outcomes: z.array(z.object({
                 expectation: z.string().describe('The expected outcome, repeated exactly as it was given'),
@@ -607,17 +612,39 @@ export class Pilot {
         if (!response)
             response = await settle(userContent, this.provider.getAgenticModel('pilot'));
         const judged = new Map((response?.object?.outcomes || []).map((outcome) => [outcome.expectation, outcome]));
-        return task.expected.map((text) => {
+        const settled = task.expected.map((text) => {
             const byJudge = settledByJudge.get(text);
             if (byJudge)
-                return { text, status: byJudge };
+                return new SettledExpectation(text, byJudge);
             if (!undecided.includes(text))
-                return { text, status: decided(text) };
+                return new SettledExpectation(text, decided(text));
             const outcome = judged.get(text);
             if (!outcome)
-                return { text, status: 'unverified' };
-            return { text, status: outcome.status || 'unverified', evidence: outcome.evidence };
+                return new SettledExpectation(text, 'unverified');
+            return new SettledExpectation(text, outcome.status || 'unverified', outcome.evidence);
         });
+        return this.resolveContradictions(settled, finalState);
+    }
+    async resolveContradictions(outcomes, finalState) {
+        const judge = this.judge;
+        if (!judge || !finalState)
+            return outcomes;
+        if (!outcomes.some((outcome) => outcome.contradicted))
+            return outcomes;
+        const page = finalState.getCompactARIA().slice(0, JUDGE_PAGE_CAP);
+        return Promise.all(outcomes.map(async (outcome) => {
+            if (!outcome.contradicted)
+                return outcome;
+            const decision = await judge.decide(`The screenshot and the run log disagree about the expected outcome: ${outcome.text}. Which side does the page structure support?`, [...Object.keys(CONTRADICTION_RESOLUTION), UNDECIDED], {
+                expectation: outcome.text,
+                disagreement: outcome.evidence || '',
+                page,
+            });
+            const resolved = CONTRADICTION_RESOLUTION[decision.value ?? ''];
+            if (!resolved)
+                return outcome;
+            return outcome.resolve(resolved.status, resolved.resolution);
+        }));
     }
     async settleByJudge(task, expectations) {
         const settled = new Map();
@@ -1059,6 +1086,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/researcher.js

@@ -77,7 +77,7 @@ export class Researcher extends ResearcherBase {
     `;
     }
     async research(state, opts = {}) {
-        const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
+        const { screenshot = false, force = false, deep = false, data = false, fix = true, light = false } = opts;
         const maxRetries = this.settings.retries ?? 2;
         let retriesLeft = opts._retriesLeft ?? maxRetries;
         this.actionResult = ActionResult.fromState(state);
@@ -103,6 +103,8 @@ export class Researcher extends ResearcherBase {
         return Observability.run(sessionName, { tags: ['researcher'], sessionId: stateHash }, async () => {
             const displayUrl = state.fullUrl || state.url;
             tag('info').log(`Researching ${displayUrl} to understand the context...`);
+            if (light)
+                tag('info').log('Light research: single pass, locator verification skipped');
             setActivity(`${this.emoji} Researching...`, 'action');
             await this.ensureNavigated(displayUrl, screenshot && this.provider.hasVision());
             await this.hooksRunner.runBeforeHook('researcher', state.url);
@@ -135,7 +137,7 @@ export class Researcher extends ResearcherBase {
                 }
             }
             const isOnCurrentState = this.actionResult.getStateHash() === this.stateManager.getCurrentState()?.hash;
-            this.hasScreenshotToAnalyze = screenshot && this.provider.hasVision() && isOnCurrentState;
+            this.hasScreenshotToAnalyze = !light && screenshot && this.provider.hasVision() && isOnCurrentState;
             const conversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
             const prompt = await this.buildResearchPrompt();
             conversation.addUserText(prompt);
@@ -164,12 +166,12 @@ export class Researcher extends ResearcherBase {
             // Stage 2: Test containers + locators
             result.parseLocators();
             debugLog(`Extracted ${result.locators.length} locators from research`);
-            if (!interrupted() && result.locators.length === 0 && retriesLeft > 0) {
+            if (!light && !interrupted() && result.locators.length === 0 && retriesLeft > 0) {
                 tag('warning').log(`No locators parsed, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
                 await new Promise((r) => setTimeout(r, 1000));
                 return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 });
             }
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 const brokenContainers = await this.resolveContainers(result);
                 const containerCount = result.containers.length;
                 if (containerCount > 0 && brokenContainers.length === containerCount && retriesLeft > 0) {
@@ -187,7 +189,7 @@ export class Researcher extends ResearcherBase {
                 await this.testLocators(toTest);
             }
             // Stage 3: Fix broken sections via AI conversation continuation
-            if (!interrupted() && fix && result.locators.some((l) => l.valid === false)) {
+            if (!light && !interrupted() && fix && result.locators.some((l) => l.valid === false)) {
                 await this.fixBrokenSections(result, activeConversation);
             }
             // Focused section: unified Playwright probe (HTML+CSS+visibility).
@@ -227,11 +229,11 @@ export class Researcher extends ResearcherBase {
                 }
             }
             // Stage 5: Backfill broken elements
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 await this.backfillCoordinates(result);
                 await this.backfillBrokenLocators(result);
             }
-            if (!interrupted()) {
+            if (!light && !interrupted()) {
                 await this.detectPagination(result);
             }
             // Focused section: final fallback (vision-only — without a screenshot we don't infer focus)
@@ -258,7 +260,7 @@ export class Researcher extends ResearcherBase {
             }
             result.cleanup();
             let researchFile = null;
-            if (stateHash) {
+            if (stateHash && !light) {
                 researchFile = saveResearch(researchState, result.text, combinedHtml);
             }
             const summaryText = mdq(result.text).query('section2(/^summary/i)').query('paragraph[0]').text().trim();

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

@@ -91,7 +91,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }, task) {
                 const attempts = [];
                 let ambiguityError = null;
                 for (let i = 0; i < commands.length; i++) {
-                    const command = transformContainsCommand(commands[i]);
+                    let command = transformContainsCommand(commands[i]);
                     let success = await action.attempt(command, explanation);
                     const attempt = { command, success };
                     if (action.lastError)
@@ -104,9 +104,14 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }, task) {
                             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)
+                                command = action.executedSteps.map((step) => step.command).join('\n') || command;
                         }
                     }
                     if (success) {
+                        attempt.command = command;
+                        attempt.success = true;
+                        attempt.error = undefined;
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
                         if (!hasObservablePageChange(toolResult)) {
                             activeNote.commit(TestResult.FAILED);
@@ -130,11 +135,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 +1206,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

@@ -125,7 +125,7 @@ export class ExplorBot {
         await this.visit(this.options.from || '/');
     }
     async visit(url) {
-        return this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
+        await this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
     }
     async openTab() {
         await this.explorer.openTab();
@@ -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/test-plan.d.ts

@@ -33,6 +33,17 @@ export declare class ActiveNote {
     getMessage(): string;
     getStartTime(): number;
 }
+export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
+export declare class SettledExpectation {
+    readonly text: string;
+    readonly status: SettledStatus;
+    readonly evidence?: string;
+    readonly resolution?: string;
+    constructor(text: string, status: SettledStatus, evidence?: string, resolution?: string);
+    get failed(): boolean;
+    get contradicted(): boolean;
+    resolve(status: SettledStatus, resolution: string): SettledExpectation;
+}
 export interface StepData {
     text: string;
     duration?: number;