explorbot 0.2.3 → 0.2.4

package/dist/src/config.js

@@ -9,12 +9,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path, { basename, dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
 import dedent from 'dedent';
 import matter from 'gray-matter';
 import { findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from './global-config.js';
 import { getCliName } from './utils/cli-name.js';
-import { log } from './utils/logger.js';
+import { log, tag } from './utils/logger.js';
 export const PROVIDERS = {
     openai: { envKey: 'OPENAI_API_KEY', load: async () => (await import('@ai-sdk/openai')).createOpenAI() },
     anthropic: { envKey: 'ANTHROPIC_API_KEY', load: async () => (await import('@ai-sdk/anthropic')).createAnthropic() },
@@ -178,8 +179,15 @@ export class ConfigParser {
         return this.site;
     }
     resolveTargetPath(target) {
-        if (!this.site)
+        if (!this.site) {
+            const configured = this.config?.playwright?.url || this.config?.web?.url;
+            const targetOrigin = target ? URL.parse(target)?.origin : null;
+            const baseOrigin = configured ? URL.parse(configured)?.origin : null;
+            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 || '/';
+        }
         if (!target)
             return this.siteStartPath;
         const resolved = resolveSiteTarget(target, this.site.url);
@@ -321,9 +329,10 @@ export class ConfigParser {
     }
     async loadConfigModule(configPath) {
         const ext = configPath.split('.').pop();
+        const moduleUrl = pathToFileURL(resolve(configPath)).href;
         if (ext === 'ts') {
             try {
-                const module = await import(__rewriteRelativeImportExtension(configPath));
+                const module = await import(__rewriteRelativeImportExtension(moduleUrl));
                 return module;
             }
             catch (error) {
@@ -332,7 +341,7 @@ export class ConfigParser {
             }
         }
         else if (ext === 'js' || ext === 'mjs') {
-            const module = await import(__rewriteRelativeImportExtension(configPath));
+            const module = await import(__rewriteRelativeImportExtension(moduleUrl));
             return module;
         }
         else {

package/dist/src/execution-controller.d.ts

@@ -10,6 +10,8 @@ export declare class ExecutionController extends EventEmitter {
     constructor();
     static getInstance(): ExecutionController;
     setInputCallback(callback: InputCallback): void;
+    hasInputCallback(): boolean;
+    clearInputCallback(): void;
     startExecution(): void;
     getAbortSignal(): AbortSignal | undefined;
     interrupt(): void;

package/dist/src/execution-controller.js

@@ -20,6 +20,12 @@ export class ExecutionController extends EventEmitter {
     setInputCallback(callback) {
         this.inputCallback = callback;
     }
+    hasInputCallback() {
+        return !!this.inputCallback;
+    }
+    clearInputCallback() {
+        this.inputCallback = null;
+    }
     startExecution() {
         this.interrupted = false;
         this.abortController = new AbortController();

package/dist/src/explorbot.d.ts

@@ -15,7 +15,7 @@ import { Researcher } from './ai/researcher.js';
 import { SessionAnalyst } from './ai/session-analyst.js';
 import { Tester } from './ai/tester.js';
 import { RequestStore } from './api/request-store.js';
-import type { ExplorbotConfig } from './config.js';
+import type { ExplorbotConfig, ReporterConfig } from './config.js';
 import { ConfigParser } from './config.js';
 import { ExperienceTracker } from './experience-tracker.js';
 import Explorer from './explorer.js';
@@ -37,6 +37,7 @@ export interface ExplorBotOptions {
     session?: string | boolean;
     instance?: string;
     optionalAi?: boolean;
+    reporter?: ReporterConfig;
     attachedBrowser?: Browser;
     applicationSpec?: string;
 }

package/dist/src/explorbot.js

@@ -101,6 +101,8 @@ export class ExplorBot {
         this.config = await this.configParser.loadConfig(this.options);
         if (this.options.session === true)
             this.options.session = path.join(this.configParser.getOutputDir(), 'session.json');
+        if (typeof this.options.session === 'string')
+            this.options.session = path.resolve(this.options.path || '.', this.options.session);
         if (this.options.optionalAi)
             return this.bootstrapOptionalProvider();
         this.provider = new AIProvider(this.config.ai);
@@ -138,7 +140,7 @@ export class ExplorBot {
         return (this._stateManager ||= new StateManager(this.experienceTracker(), this.knowledgeTracker()));
     }
     reporter() {
-        return (this._reporter ||= new Reporter(this.config.reporter, this.stateManager()));
+        return (this._reporter ||= new Reporter(this.options.reporter || this.config.reporter, this.stateManager()));
     }
     requestStore() {
         return (this._requestStore ||= new RequestStore(this.configParser.getOutputDir()));

package/dist/src/explorer.js

@@ -10,7 +10,6 @@ import { ActionResult } from "./action-result.js";
 import Action from './action.js';
 import { XhrCapture } from "./api/xhr-capture.js";
 import { ConfigParser } from './config.js';
-import { TestResult } from "./test-plan.js";
 import { BrowserRecoveryError, browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from "./utils/browser-errors.js";
 import { createDebug, log, tag } from './utils/logger.js';
 import { sleep, waitForPageReadiness } from "./utils/page-readiness.js";
@@ -624,12 +623,12 @@ class Explorer {
         if (this.observedTestPages.has(page))
             return;
         this.testPageErrorHandler ||= (err) => {
-            this._activeTest?.addNote(`Console error: ${err.message}`, TestResult.FAILED);
+            this._activeTest?.addObservation(`Console error: ${err.message}`);
         };
         this.testConsoleHandler ||= (msg) => {
             if (msg.type() !== 'error')
                 return;
-            this._activeTest?.addNote(`Console error: ${msg.text()}`, TestResult.FAILED);
+            this._activeTest?.addObservation(`Console error: ${msg.text()}`);
         };
         this.testDialogHandler ||= (dialog) => {
             const dialogType = dialog.type();

package/dist/src/playwright-recorder.js

@@ -292,8 +292,38 @@ function formatSelectOption(options) {
         return quote(values[0]);
     return `[${values.map((v) => quote(v)).join(', ')}]`;
 }
+function assertionLocator(target) {
+    if (typeof target === 'string')
+        return `page.locator(${JSON.stringify(target)})`;
+    if (!target || typeof target !== 'object')
+        return null;
+    const role = target.role || target.aria;
+    const name = target.text ?? target.name ?? target.label;
+    if (role && name)
+        return `page.getByRole(${JSON.stringify(String(role))}, { name: ${JSON.stringify(String(name))} })`;
+    if (role)
+        return `page.getByRole(${JSON.stringify(String(role))})`;
+    if (name)
+        return `page.getByText(${JSON.stringify(String(name))})`;
+    if (target.css)
+        return `page.locator(${JSON.stringify(String(target.css))})`;
+    if (target.xpath)
+        return `page.locator(${JSON.stringify(`xpath=${target.xpath}`)})`;
+    return null;
+}
 export function renderAssertion(assertion) {
     const args = assertion.args;
+    const target = assertionLocator(args[0]);
+    if (target) {
+        if (assertion.name === 'seeElement')
+            return `await expect(${target}).toBeVisible();`;
+        if (assertion.name === 'dontSeeElement')
+            return `await expect(${target}).toBeHidden();`;
+        if (assertion.name === 'seeInField' && args[1] !== undefined)
+            return `await expect(${target}).toHaveValue(${JSON.stringify(String(args[1]))});`;
+        if (assertion.name === 'dontSeeInField' && args[1] !== undefined)
+            return `await expect(${target}).not.toHaveValue(${JSON.stringify(String(args[1]))});`;
+    }
     if (assertion.name === 'see' && typeof args[0] === 'string') {
         return `await expect(page).toContainText(${JSON.stringify(args[0])});`;
     }

package/dist/src/remote.d.ts

@@ -0,0 +1,54 @@
+import type { Command } from 'commander';
+import { type ActivityEntry } from './activity.js';
+import { type LogDestination, type TaggedLogEntry } from './utils/logger.js';
+/**
+ * Streams a run to a remote UI over one WebSocket, dialling out so a child
+ * process and a CI bot are the same case.
+ *
+ * It **is** a LogDestination — that is the whole integration on the logger's
+ * side — and it answers asks by installing itself as the execution
+ * controller's input callback. Nothing else in explorbot knows it exists.
+ */
+export declare class Remote implements LogDestination {
+    url: string | null;
+    socket: WebSocket | null;
+    queue: Frame[];
+    reconnectDelay: number;
+    reconnectTimer: ReturnType<typeof setTimeout> | null;
+    asks: Map<string, (value: string | null) => void>;
+    askCounter: number;
+    lastActivity: string | null;
+    registerOption(program: Command): void;
+    attach(url: string, command: string): void;
+    isAttached(): boolean;
+    send(type: string, data?: Record<string, unknown>): void;
+    ask(prompt: string): Promise<string | null>;
+    close(exitCode: number): Promise<void>;
+    isEnabled(): boolean;
+    /**
+     * The entry as the logger already built it, so the `LogType` reaches the UI
+     * as the frame's level and each kind is styled there instead of being scraped
+     * back out of flattened text.
+     */
+    write(entry: TaggedLogEntry): void;
+    connect(): void;
+    reconnect(): void;
+    flush(): Promise<void>;
+    drain(): void;
+    push(frame: Frame): void;
+    receive(raw: string): void;
+    /** A new listener is primed with the current activity, which at attach time is
+     *  nothing — so skip repeats, the priming null included. */
+    reportActivity(activity: ActivityEntry | null): void;
+    errorOf(args: any[] | undefined): string | undefined;
+    commandPath(command: Command): string;
+}
+export declare const remote: Remote;
+/** Whatever the run wants to say. Not a schema — the UI renders what it knows
+ *  and ignores the rest, so either side can start sending more at any time. */
+type Frame = {
+    type: string;
+    ts: number;
+    [key: string]: unknown;
+};
+export {};

package/dist/src/remote.js

@@ -0,0 +1,229 @@
+import stripAnsi from 'strip-ansi';
+import { addActivityListener } from "./activity.js";
+import { executionController } from "./execution-controller.js";
+import { addDestination } from "./utils/logger.js";
+const QUEUE_CAP = 1000;
+const CONTENT_CAP = 8000;
+const RECONNECT_BASE_MS = 500;
+const RECONNECT_MAX_MS = 10_000;
+const ASK_TIMEOUT_MS = 15 * 60_000;
+const FLUSH_TIMEOUT_MS = 3000;
+/**
+ * Streams a run to a remote UI over one WebSocket, dialling out so a child
+ * process and a CI bot are the same case.
+ *
+ * It **is** a LogDestination — that is the whole integration on the logger's
+ * side — and it answers asks by installing itself as the execution
+ * controller's input callback. Nothing else in explorbot knows it exists.
+ */
+export class Remote {
+    url = null;
+    socket = null;
+    queue = [];
+    reconnectDelay = RECONNECT_BASE_MS;
+    reconnectTimer = null;
+    asks = new Map();
+    askCounter = 0;
+    lastActivity = null;
+    registerOption(program) {
+        program.option('--ws <url>', 'Stream this run to a remote UI over WebSocket');
+        program.hook('preAction', (_thisCommand, actionCommand) => {
+            const url = actionCommand.optsWithGlobals().ws || process.env.EXPLORBOT_WS_URL;
+            if (!url)
+                return;
+            this.attach(String(url), this.commandPath(actionCommand));
+        });
+    }
+    attach(url, command) {
+        if (this.url)
+            return;
+        this.url = url;
+        this.connect();
+        this.send('hello', { command, cwd: process.cwd(), pid: process.pid });
+        addDestination(this);
+        executionController.setInputCallback((prompt) => this.ask(prompt));
+        addActivityListener((activity) => this.reportActivity(activity));
+    }
+    isAttached() {
+        return !!this.url;
+    }
+    send(type, data = {}) {
+        if (!this.url)
+            return;
+        const frame = { type, ts: Date.now(), ...data };
+        if (this.socket?.readyState === WebSocket.OPEN) {
+            this.push(frame);
+            return;
+        }
+        this.queue.push(frame);
+        if (this.queue.length > QUEUE_CAP)
+            this.queue.splice(0, this.queue.length - QUEUE_CAP);
+    }
+    ask(prompt) {
+        if (!this.url)
+            return Promise.resolve(null);
+        this.askCounter++;
+        const askId = `ask-${this.askCounter}`;
+        this.send('ask', { askId, prompt });
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.asks.delete(askId);
+                resolve(null);
+            }, ASK_TIMEOUT_MS);
+            this.asks.set(askId, (value) => {
+                clearTimeout(timer);
+                resolve(value);
+            });
+        });
+    }
+    async close(exitCode) {
+        if (!this.url)
+            return;
+        this.send('result', { ok: exitCode === 0, exitCode });
+        await this.flush();
+        this.url = null;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        // Whoever asks next has nobody to ask — leaving the callback installed would
+        // route them into a closed socket and park them until the ask times out.
+        executionController.clearInputCallback();
+        for (const resolve of this.asks.values())
+            resolve(null);
+        this.asks.clear();
+        this.queue = [];
+        this.socket?.close();
+        this.socket = null;
+    }
+    isEnabled() {
+        return this.isAttached();
+    }
+    /**
+     * The entry as the logger already built it, so the `LogType` reaches the UI
+     * as the frame's level and each kind is styled there instead of being scraped
+     * back out of flattened text.
+     */
+    write(entry) {
+        if (entry.type === 'html')
+            return;
+        let content = stripAnsi(entry.content ?? '');
+        if (content.length > CONTENT_CAP)
+            content = `${content.slice(0, CONTENT_CAP)}… (${content.length} chars)`;
+        this.send('log', {
+            level: entry.type,
+            content,
+            namespace: entry.namespace,
+            error: this.errorOf(entry.originalArgs),
+        });
+    }
+    connect() {
+        if (!this.url)
+            return;
+        let opening;
+        try {
+            opening = new WebSocket(this.url);
+        }
+        catch {
+            this.reconnect();
+            return;
+        }
+        this.socket = opening;
+        opening.addEventListener('open', () => {
+            this.reconnectDelay = RECONNECT_BASE_MS;
+            this.drain();
+        });
+        opening.addEventListener('message', (event) => this.receive(String(event.data)));
+        opening.addEventListener('close', () => {
+            if (this.socket !== opening)
+                return;
+            this.socket = null;
+            this.reconnect();
+        });
+        // A failed connection always closes too, which is where the retry is scheduled.
+        opening.addEventListener('error', () => { });
+    }
+    reconnect() {
+        if (!this.url || this.reconnectTimer)
+            return;
+        const delay = this.reconnectDelay;
+        this.reconnectDelay = Math.min(this.reconnectDelay * 2, RECONNECT_MAX_MS);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+        this.reconnectTimer.unref?.();
+    }
+    async flush() {
+        const deadline = Date.now() + FLUSH_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            if (this.socket?.readyState === WebSocket.OPEN) {
+                this.drain();
+                if (!this.queue.length && !this.socket.bufferedAmount)
+                    return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+    drain() {
+        if (this.socket?.readyState !== WebSocket.OPEN)
+            return;
+        const pending = this.queue;
+        this.queue = [];
+        for (const frame of pending)
+            this.push(frame);
+    }
+    push(frame) {
+        try {
+            this.socket?.send(JSON.stringify(frame));
+        }
+        catch {
+            this.queue.push(frame);
+        }
+    }
+    receive(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (frame.type === 'interrupt') {
+            executionController.interrupt();
+            return;
+        }
+        const resolve = this.asks.get(String(frame.askId));
+        if (!resolve)
+            return;
+        this.asks.delete(String(frame.askId));
+        resolve(frame.value ?? null);
+    }
+    /** A new listener is primed with the current activity, which at attach time is
+     *  nothing — so skip repeats, the priming null included. */
+    reportActivity(activity) {
+        const message = activity?.message ?? null;
+        if (message === this.lastActivity)
+            return;
+        this.lastActivity = message;
+        this.send('activity', { message, kind: activity?.type });
+    }
+    errorOf(args) {
+        const failure = args?.[1] ?? args?.[0]?.error;
+        if (!failure)
+            return undefined;
+        if (typeof failure === 'string')
+            return failure;
+        if (typeof failure.message === 'string')
+            return failure.message;
+        return undefined;
+    }
+    commandPath(command) {
+        const parts = [];
+        let node = command;
+        while (node) {
+            parts.unshift(node.name());
+            node = node.parent;
+        }
+        return parts.slice(1).join(' ') || parts.join(' ');
+    }
+}
+export const remote = new Remote();

package/dist/src/reporter.d.ts

@@ -26,6 +26,7 @@ export declare class Reporter {
     combineStepsAndNotes(test: Test, lastScreenshotFile?: string): Step[];
     buildVerificationStep(test: Test, lastScreenshotFile?: string): Step | undefined;
     reportTest(test: Test, meta?: ReporterMeta): Promise<void>;
+    reportTestData(status: string | null, testData: Record<string, unknown>): Promise<void>;
     finishRun(): Promise<void>;
     isEnabled(): boolean;
     setRunDescription(text: string): Promise<void>;

package/dist/src/reporter.js

@@ -242,13 +242,19 @@ export class Reporter {
                 time: durationMs != null ? Math.round(durationMs) : 0,
             };
             debugLog(testData);
-            await this.client.addTestRun(status, testData);
+            await this.reportTestData(status, testData);
             debugLog(`Test reported: ${test.scenario} - ${status}`);
         }
         catch (error) {
             debugLog('Failed to report test:', error);
         }
     }
+    async reportTestData(status, testData) {
+        await this.startRun();
+        if (!this.isRunStarted)
+            return;
+        await this.client.addTestRun(status, testData);
+    }
     async finishRun() {
         if (!this.isRunStarted) {
             return;

package/dist/src/state-manager.d.ts

@@ -1,4 +1,4 @@
-import { ActionResult } from './action-result.js';
+import { type FocusedElement, ActionResult } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
 export interface Link {
@@ -37,6 +37,7 @@ export interface WebPageState {
     h4?: string;
     ariaSnapshot?: string | null;
     ariaSnapshotFile?: string;
+    focusedElement?: FocusedElement | null;
     links?: Link[];
     verifications?: Record<string, boolean>;
 }

package/dist/src/stats.d.ts

@@ -13,6 +13,7 @@ export declare class Stats {
     static plans: number;
     static mode?: ExplorbotMode;
     static focus?: string;
+    static visionDisabled: boolean;
     static models: Record<string, TokenUsage>;
     static recordTokens(_agent: string, model: string, usage: TokenUsage): void;
     static getElapsedTime(): string;

package/dist/src/stats.js

@@ -7,6 +7,7 @@ export class Stats {
     static plans = 0;
     static mode;
     static focus;
+    static visionDisabled = false;
     static models = {};
     static recordTokens(_agent, model, usage) {
         if (!Stats.models[model]) {

package/dist/src/test-plan.d.ts

@@ -18,6 +18,7 @@ export interface Note {
     endTime: number;
     screenshot?: string;
     log?: string;
+    observation?: boolean;
 }
 export declare class ActiveNote {
     task: Task;
@@ -56,6 +57,7 @@ export declare class Task {
     getPrintableNotes(): string[];
     notesToString(): string;
     addNote(message: string, status?: TestResultType, screenshot?: string, log?: string): void;
+    addObservation(message: string): void;
     addUrlNote(state: UrlNoteState, prevState?: {
         title?: string;
         h1?: string;

package/dist/src/test-plan.js

@@ -91,6 +91,13 @@ export class Task {
         const timestamp = `${now}_${this.timestampCounter++}`;
         this.notes[timestamp] = { message, status, startTime: now, endTime: now, screenshot, log };
     }
+    addObservation(message) {
+        const isDuplicate = Object.values(this.notes).some((note) => note.message === message);
+        if (isDuplicate)
+            return;
+        const now = performance.now();
+        this.notes[`${now}_${this.timestampCounter++}`] = { message, status: TestResult.FAILED, startTime: now, endTime: now, observation: true };
+    }
     addUrlNote(state, prevState) {
         const fullUrl = state.fullUrl || state.url;
         if (!fullUrl)

package/dist/src/utils/aria.d.ts

@@ -3,17 +3,11 @@ export interface FocusAreaResult {
     type: 'dialog' | 'modal' | null;
     name: string | null;
 }
-export declare const compactAriaSnapshot: (snapshot: string | null, keepNamed?: boolean) => string;
+export type ValueOffload = (value: string) => string | undefined;
+export declare const compactAriaSnapshot: (snapshot: string | null, keepNamed?: boolean, offload?: ValueOffload) => string;
 export declare const diffAriaSnapshots: (previous: string | null, current: string | null) => AriaDiff;
 export declare const detectFocusArea: (snapshot: string | null) => FocusAreaResult;
 export declare const collectInteractiveNodes: (snapshot: string | null) => Array<Record<string, unknown>>;
-export interface FocusedElementInfo {
-    role: string;
-    name: string;
-    value?: string;
-    attributes?: string[];
-}
-export declare function extractFocusedElement(ariaSnapshot: string | null): FocusedElementInfo | null;
 export declare function parseAriaLocator(ariaStr: string): {
     role: string;
     text: string;