explorbot 0.4.3 → 0.4.5

package/dist/src/ai/researcher.js

@@ -1,7 +1,7 @@
 import dedent from 'dedent';
 import { ActionResult } from '../action-result.js';
 import { setActivity } from "../activity.js";
-import { outputPath } from "../config.js";
+import { agentSettings, outputPath } from "../config.js";
 import { executionController } from "../execution-controller.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
@@ -13,7 +13,7 @@ import { mdq } from "../utils/markdown-query.js";
 import { RulesLoader } from "../utils/rules-loader.js";
 import { annotatePageElements } from "../utils/web-annotate.js";
 import { ContextLengthError } from './provider.js';
-import { findSimilarResearch, getCachedResearch, reportResearch, saveResearch } from "./researcher/cache.js";
+import { findSimilarResearch, getCachedResearch, getPreviousResearch, reportResearch, saveResearch } from "./researcher/cache.js";
 import { WithCoordinates } from "./researcher/coordinates.js";
 import { WithDeepAnalysis } from "./researcher/deep-analysis.js";
 import { detectFocusedSection, hasFocusedSection, markSectionAsFocused, pickDefaultFocusedSection } from "./researcher/focus.js";
@@ -42,12 +42,19 @@ export class Researcher extends ResearcherBase {
     constructor(deps) {
         super(deps);
         this.experienceTracker = deps.stateManager.getExperienceTracker();
-        const ai = deps.config.ai;
-        if (ai) {
-            ai.agents ??= {};
-            ai.agents.researcher ??= {};
-            ai.agents.researcher.reasoning ??= 'low';
-        }
+        this.settings.reasoning ??= 'low';
+    }
+    get settings() {
+        return agentSettings(this.config, 'researcher');
+    }
+    isEnabled() {
+        return this.settings.enabled !== false;
+    }
+    enable() {
+        this.settings.enabled = true;
+    }
+    disable() {
+        this.settings.enabled = false;
     }
     getNavigator() {
         throw new Error('not implemented');
@@ -70,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 maxRetries = this.config.ai?.agents?.researcher?.retries ?? 2;
+        const maxRetries = this.settings.retries ?? 2;
         let retriesLeft = opts._retriesLeft ?? maxRetries;
         this.actionResult = ActionResult.fromState(state);
         const stateHash = this.actionResult.baseHash;
@@ -83,6 +90,13 @@ export class Researcher extends ResearcherBase {
                 return cached;
             }
         }
+        if (!this.isEnabled()) {
+            debugLog('Researcher is disabled, answering with the recorded map');
+            const recorded = getPreviousResearch(stateHash);
+            if (recorded)
+                reportResearch(stateHash, recorded);
+            return recorded;
+        }
         Stats.researches++;
         const sessionName = `researcher: ${state.url}`;
         return Observability.run(sessionName, { tags: ['researcher'], sessionId: stateHash }, async () => {
@@ -286,7 +300,7 @@ export class Researcher extends ResearcherBase {
         this.actionResult = await this.explorer.visit(url, { screenshot: screenshot ?? false });
     }
     async waitUntilSettled(screenshot) {
-        const errorPageTimeout = this.config.ai?.agents?.researcher?.errorPageTimeout ?? 10;
+        const errorPageTimeout = this.settings.errorPageTimeout ?? 10;
         if (errorPageTimeout <= 0)
             return false;
         const includeScreenshot = screenshot && this.provider.hasVision();
@@ -316,7 +330,7 @@ export class Researcher extends ResearcherBase {
         return false;
     }
     getConfiguredSections() {
-        const configSections = this.config.ai?.agents?.researcher?.sections;
+        const configSections = this.settings.sections;
         if (!configSections?.length)
             return POSSIBLE_SECTIONS;
         const filtered = {};

package/dist/src/ai/rules.js

@@ -6,8 +6,9 @@ const locatorPriorityRule = dedent `
 
   1. ARIA locators (first choice) - target browser's accessibility tree, most reliable
      Use JSON format: { "role": "button", "text": "Login" }
-     Copy role and text VERBATIM from the ARIA snapshot or UI map — never guess the pair.
-     If the element is absent from the snapshot, do not invent one; use text or CSS instead.
+     Copy role and text VERBATIM from the ARIA snapshot, UI map, or the page diff that
+     reported the element — never guess the pair; a guessed role can silently match a
+     different element with the same text. If named nowhere, use text or CSS instead.
 
   2. Text locators (second choice) - exact visible text, use only when unique on the page
      Example: 'Login', 'Submit', 'Username'
@@ -225,10 +226,10 @@ export const unexpectedPopupRule = dedent `
   If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
 
   Dismiss strategy (try in order):
-  1. I.clickXY(0, 0) — click outside the popup to close it
-  2. I.pressKey('Escape') — press Escape to dismiss
-  3. I.click('Cancel') — click Cancel button if present
-  4. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  1. I.pressKey('Escape') — press Escape to dismiss
+  2. I.click('Cancel') — click Cancel button if present
+  3. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  4. I.clickXY(0, 0) via form() tool and check if page diff changed
   </unexpected_popup_rule>
 `;
 export const sectionContextRule = dedent `
@@ -318,7 +319,7 @@ export const actionRule = dedent `
   Prefer text/ARIA locators with context over complex CSS/XPath selectors.
   For inline create/edit flows, after filling a field verify it contains the value, then confirm using the nearest explicit button/link, an adjacent icon-only confirm control in the same row/form, or Enter if the field remains focused.
   If locator doesn't work, try CSS or XPath locators.
-  If nothing works, use I.clickXY(x, y) as last resort.
+  If nothing works, use visualClick() — it locates the target in a screenshot before clicking it.
 
   When a click result reports several matches, pick one from its numbered list by position rather than guessing a new locator.
   Reuse the same locator with step.opts({ elementIndex: N }) as the LAST argument. N is the "Element N" number.

package/dist/src/ai/scout/tools.d.ts

@@ -0,0 +1,17 @@
+export declare function loadScoutCorpus(dirs: string[]): ScoutCorpus;
+export declare function excludeCorpusUrls(corpus: ScoutCorpus, urls: string[]): ScoutCorpus;
+export declare function createScoutTools(corpus: ScoutCorpus): Promise<{
+    tools: Record<string, any>;
+    scanner: "rg" | "grep";
+    getResult: () => string;
+    finishFromText: (text?: string) => void;
+}>;
+export interface ScoutCorpus {
+    dirs: string[];
+    files: ScoutCorpusFile[];
+    excludedPaths: string[];
+}
+export interface ScoutCorpusFile {
+    path: string;
+    url?: string;
+}

package/dist/src/ai/scout/tools.js

@@ -0,0 +1,130 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tool } from 'ai';
+import { createBashTool } from 'bash-tool';
+import dedent from 'dedent';
+import { z } from 'zod';
+import { ConfigParser } from "../../config.js";
+import { tag } from "../../utils/logger.js";
+import { loadMarkdownFiles } from "../../utils/markdown-files.js";
+import { readCaptainFile } from "../captain/file-tools.js";
+const MAX_FILES = 500;
+const MAX_FINDINGS = 6000;
+let cachedScanner = null;
+export function loadScoutCorpus(dirs) {
+    const files = [];
+    for (const dir of dirs) {
+        if (files.length >= MAX_FILES) {
+            tag('warning').log(`Scout corpus capped at ${MAX_FILES} files — remaining directories skipped`);
+            break;
+        }
+        for (const file of loadMarkdownFiles(dir, { recursive: true })) {
+            if (files.length >= MAX_FILES)
+                break;
+            const entry = { path: file.filePath };
+            if (typeof file.data.url === 'string')
+                entry.url = file.data.url;
+            files.push(entry);
+        }
+    }
+    return { dirs, files, excludedPaths: [] };
+}
+export function excludeCorpusUrls(corpus, urls) {
+    if (urls.length === 0)
+        return corpus;
+    const excludedUrls = new Set(urls);
+    const files = [];
+    const excludedPaths = [...corpus.excludedPaths];
+    for (const file of corpus.files) {
+        if (file.url && excludedUrls.has(file.url)) {
+            excludedPaths.push(file.path);
+            continue;
+        }
+        files.push(file);
+    }
+    return { dirs: corpus.dirs, files, excludedPaths };
+}
+export async function createScoutTools(corpus) {
+    const scanner = await detectScanner();
+    const projectRoot = ConfigParser.getInstance().getProjectRoot();
+    let result = '';
+    let searchedOrRead = false;
+    const getResult = () => result;
+    const finishFromText = (text) => {
+        if (text && searchedOrRead)
+            result = text.slice(0, MAX_FINDINGS);
+    };
+    const files = {};
+    const readableFiles = new Set();
+    for (const file of corpus.files) {
+        files[toPosix(file.path)] = readFileSync(file.path, 'utf8');
+        readableFiles.add(resolve(file.path));
+    }
+    const toolkit = await createBashTool({
+        destination: '/',
+        files,
+        maxOutputLength: 20000,
+    });
+    const bashExecute = toolkit.bash.execute;
+    const bash = {
+        ...toolkit.bash,
+        execute: async (input) => {
+            tag('step').log(`Scout: bash ${input.command}`);
+            searchedOrRead = true;
+            return bashExecute?.(input);
+        },
+    };
+    const tools = {
+        bash,
+        readFile: tool({
+            description: dedent `
+        Read one documentation file from the corpus.
+        Pass the exact path returned by a search result.
+      `,
+            inputSchema: z.object({
+                path: z.string().describe('File path from a search result'),
+                startLine: z.number().optional().describe('First line to read, 1-based. Negative values count from the end of the file'),
+                endLine: z.number().optional().describe('Last line to read, 1-based and inclusive. Negative values count from the end of the file'),
+                maxChars: z.number().optional().describe('Maximum characters to return, default 12000'),
+            }),
+            execute: async (input) => {
+                tag('step').log(`Scout: read ${input.path}`);
+                const output = readCaptainFile(projectRoot, input, corpus.dirs);
+                if (!output.success)
+                    return output;
+                const resolvedPath = resolve(projectRoot || process.cwd(), output.path);
+                if (!readableFiles.has(resolvedPath)) {
+                    return { success: false, message: 'File is outside the Scout corpus' };
+                }
+                searchedOrRead = true;
+                return output;
+            },
+        }),
+    };
+    return { tools, scanner, getResult, finishFromText };
+}
+async function detectScanner() {
+    if (cachedScanner)
+        return cachedScanner;
+    if (await binaryRuns('rg')) {
+        cachedScanner = 'rg';
+        return cachedScanner;
+    }
+    if (await binaryRuns('grep')) {
+        cachedScanner = 'grep';
+        return cachedScanner;
+    }
+    throw new Error('Scout requires ripgrep or grep on PATH — neither was found');
+}
+async function binaryRuns(binary) {
+    try {
+        const proc = Bun.spawn([binary, '--version'], { stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+        return (await proc.exited) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function toPosix(path) {
+    return path.split('\\').join('/');
+}

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

@@ -0,0 +1,21 @@
+import type { Agent } from './agent.js';
+import type { Provider } from './provider.js';
+import { type ScoutCorpus } from './scout/tools.js';
+export declare class Scout implements Agent {
+    provider: Provider;
+    corpus: ScoutCorpus;
+    emoji: string;
+    cache: Map<string, string>;
+    constructor(provider: Provider, corpus: ScoutCorpus);
+    isAvailable(): boolean;
+    collectDocs(query: ScoutQuery): Promise<string>;
+    runSession(corpus: ScoutCorpus, query: ScoutQuery): Promise<string | null>;
+    buildSystemPrompt(toolNames: string[], corpus: ScoutCorpus, query: ScoutQuery, scanner: 'rg' | 'grep'): string;
+    buildTaskPrompt(query: ScoutQuery): string;
+}
+export interface ScoutQuery {
+    url?: string;
+    title?: string;
+    feature?: string;
+    excludeUrls: string[];
+}

package/dist/src/ai/scout.js

@@ -0,0 +1,150 @@
+import dedent from 'dedent';
+import { tag } from "../utils/logger.js";
+import { loop } from "../utils/loop.js";
+import { createScoutTools, excludeCorpusUrls } from "./scout/tools.js";
+const MAX_ITERATIONS = 3;
+const MAX_TOOL_ROUNDTRIPS = 5;
+const CACHE_LIMIT = 40;
+const URL_LISTING_LIMIT = 40;
+export class Scout {
+    provider;
+    corpus;
+    emoji = '🔎';
+    cache = new Map();
+    constructor(provider, corpus) {
+        this.provider = provider;
+        this.corpus = corpus;
+    }
+    isAvailable() {
+        return this.corpus.files.length > 0;
+    }
+    async collectDocs(query) {
+        if (!this.isAvailable())
+            return '';
+        const cacheKey = `${query.url || ''}|${query.feature || ''}|${query.excludeUrls.join(',')}`;
+        const cached = this.cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const corpus = excludeCorpusUrls(this.corpus, query.excludeUrls);
+        if (corpus.files.length === 0)
+            return '';
+        const result = await this.runSession(corpus, query);
+        if (result === null)
+            return '';
+        if (this.cache.size > CACHE_LIMIT)
+            this.cache.clear();
+        this.cache.set(cacheKey, result);
+        return result;
+    }
+    async runSession(corpus, query) {
+        const { tools, scanner, getResult, finishFromText } = await createScoutTools(corpus);
+        const conversation = this.provider.startConversation(this.buildSystemPrompt(Object.keys(tools), corpus, query, scanner), 'scout', this.provider.getAgenticModel('scout'));
+        conversation.addUserText(this.buildTaskPrompt(query));
+        tag('info').log(`Scout: collecting documentation for ${query.feature || query.url || 'the current page'}`);
+        let failed = false;
+        await loop(async ({ stop, iteration }) => {
+            const invokeResult = await this.provider.invokeConversation(conversation, tools, {
+                maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
+                agentName: 'scout',
+            });
+            if (!invokeResult?.toolExecutions?.length) {
+                finishFromText(invokeResult?.response?.text);
+                stop();
+                return;
+            }
+            if (iteration >= MAX_ITERATIONS) {
+                const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
+                finishFromText(final?.response?.text);
+                stop();
+            }
+        }, {
+            maxAttempts: MAX_ITERATIONS,
+            observability: { name: `scout: ${query.feature || query.url || 'docs'}`, agent: 'scout' },
+            catch: async ({ error, stop }) => {
+                failed = true;
+                tag('warning').log(`Scout error: ${error.message}`);
+                stop();
+            },
+        });
+        if (failed)
+            return null;
+        const digest = getResult();
+        if (digest) {
+            const preview = digest.slice(0, 600);
+            const ellipsis = digest.length > 600 ? '…' : '';
+            tag('info').log(`Scout digest:\n${preview}${ellipsis}`);
+        }
+        return digest;
+    }
+    buildSystemPrompt(toolNames, corpus, query, scanner) {
+        const urls = corpus.files.map((file) => file.url).filter(Boolean);
+        const urlless = corpus.files.filter((file) => !file.url);
+        let pagesListing = '';
+        if (urls.length > 0) {
+            const listing = urls
+                .slice(0, URL_LISTING_LIMIT)
+                .map((url) => `- ${url}`)
+                .join('\n');
+            pagesListing = `Documented pages:\n${listing}`;
+            const remaining = urls.length - URL_LISTING_LIMIT;
+            if (remaining > 0)
+                pagesListing += `\n…and ${remaining} more — find them with ${scanner}`;
+        }
+        if (urlless.length > 0) {
+            const listing = urlless
+                .slice(0, URL_LISTING_LIMIT)
+                .map((file) => `- ${toPosix(file.path)}`)
+                .join('\n');
+            pagesListing += `\nFiles with no page URL (hand-written docs):\n${listing}`;
+        }
+        const prompt = dedent `
+      You are Scout — a documentation retrieval agent. You find collected documentation relevant to a testing focus and report it for test planning.
+
+      You never see the application itself. The documentation corpus is your only source of truth.
+
+      CORPUS:
+      ${corpus.files.length} markdown files under:
+      - ${corpus.dirs.map(toPosix).join('\n- ')}
+      ${pagesListing}
+
+      These pages are already provided to the planner in full — do not re-report them:
+      ${query.excludeUrls.map((url) => `- ${url}`).join('\n') || '- none'}
+
+      AVAILABLE TOOLS:
+      ${toolNames.join(', ')}.
+      Use tool names exactly as listed. Do not invent aliases or combined names.
+      Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
+
+      SCANNER:
+      ${scanner} is the search command. Scan the working directory through bash() — explore freely, pipelines, globs and repeated searches are fine. Read files with readFile().
+
+      WORKFLOW:
+      1. Scan with ${scanner} using plain prose words from the focus — feature names, page purposes, capabilities
+      2. Read the files whose hits look most relevant
+      3. Report the digest as your final message — no tool call is needed to finish
+
+      RULES:
+      - Report only what the documentation states. Never fill gaps with assumptions about the application
+      - Keep verified capabilities and unverified possibilities distinguishable, the way the documentation marks them
+      - Name the page URL each item belongs to, so scenarios anchor to real routes
+      - Explore briefly: a few scans and reads are enough, then report
+      - A short accurate digest beats a long loose one; reporting that nothing relevant exists is a valid answer
+    `;
+        const customPrompt = this.provider.getSystemPromptForAgent('scout');
+        if (customPrompt)
+            return `${prompt}\n\n${customPrompt}`;
+        return prompt;
+    }
+    buildTaskPrompt(query) {
+        return dedent `
+      Page URL: ${query.url || 'Unknown'}
+      Page title: ${query.title || 'Unknown'}
+      Focus: ${query.feature || 'the page as a whole'}
+
+      Report the documented capabilities, states and transitions a test planner could turn into scenarios.
+    `;
+    }
+}
+function toPosix(path) {
+    return path.split('\\').join('/');
+}

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

@@ -22,6 +22,7 @@ export declare class Tester extends TaskAgent implements Agent {
     MAX_ITERATIONS: number;
     MAX_EXTENSIONS: number;
     ASSERTION_TOOLS: string[];
+    pendingReview: string;
     researcher: Researcher;
     navigator: Navigator;
     agentTools: any;

package/dist/src/ai/tester.js

@@ -40,6 +40,7 @@ export class Tester extends TaskAgent {
     MAX_ITERATIONS = 30;
     MAX_EXTENSIONS = 2;
     ASSERTION_TOOLS = ['verify'];
+    pendingReview = '';
     researcher;
     navigator;
     agentTools;
@@ -97,6 +98,7 @@ export class Tester extends TaskAgent {
         this.seenUiMapUrls.clear();
         this.lastAnalyzedStateHash = null;
         this.stalledIterations = 0;
+        this.pendingReview = '';
         this.previousRegionPresent = null;
         this.regionTransitioned = false;
         this.stateManager.clearHistory();
@@ -293,7 +295,7 @@ export class Tester extends TaskAgent {
                 const result = await this.provider.invokeConversation(conversation, tools, {
                     maxToolRoundtrips: 3,
                     toolChoice: 'required',
-                    stopWhen: () => task.hasFinished,
+                    stopWhen: () => task.hasFinished || !!this.pendingReview,
                 });
                 if (!result)
                     throw new Error('Failed to get response from provider');
@@ -339,6 +341,15 @@ export class Tester extends TaskAgent {
             `);
                     }
                 }
+                if (this.pendingReview && this.pilot) {
+                    const reviewed = this.pendingReview;
+                    this.pendingReview = '';
+                    const reviewState = this.getCurrentState();
+                    if (reviewed === 'finish')
+                        await this.pilot.reviewFinish(task, reviewState, conversation, this.navigator);
+                    if (reviewed === 'stop')
+                        await this.pilot.reviewStop(task, reviewState, conversation);
+                }
                 if (task.hasFinished) {
                     stop();
                     return;
@@ -513,17 +524,20 @@ export class Tester extends TaskAgent {
         }
         if (region.isModal) {
             const areaName = region.name ? ` "${region.name}"` : '';
-            let rootHint = '';
-            if (region.root)
-                rootHint = `\nIts content lives inside \`${region.root}\` — scope locators to it.`;
+            let scoping = 'Use <page_aria> to confirm the element you target is actually inside the overlay.';
+            if (region.root) {
+                scoping = `Its root is \`${region.root}\` — build every locator as ARIA scoped to that root, e.g. I.click({ role: 'button', text: 'Continue' }, '${region.root}')`;
+            }
             context += dedent `
         <overlay>
-        An overlay${areaName} is currently open above the page.${rootHint}
-        Scope all interactions to elements inside this overlay.
-        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the overlay.
-        Use <page_aria> to confirm the element you target is actually inside the overlay.
-        </overlay>
+        You are inside an overlay${areaName} opened above the page.
+        ${scoping}
+        Elements outside the overlay are behind it and not actionable while it is open — they may share names or roles with the ones inside, so never target them by bare text.
       `;
+            const regionAria = currentState.getRegionARIA();
+            if (regionAria)
+                context += `\nIt holds exactly these elements:\n<overlay_aria>\n${regionAria}\n</overlay_aria>`;
+            context += '\n</overlay>\n';
         }
         if (!region.isModal && region.isOpen && isNewState) {
             let rootHint = '';
@@ -920,18 +934,8 @@ export class Tester extends TaskAgent {
                 }),
                 execute: async ({ reason }) => {
                     task.addNote(`Stop requested: ${reason}`);
-                    if (this.pilot) {
-                        const currentState = this.getCurrentState();
-                        await this.pilot.reviewStop(task, currentState, conversation);
-                        if (!task.hasFinished) {
-                            return {
-                                success: false,
-                                action: 'stop',
-                                message: 'Stop rejected; Continue execution',
-                            };
-                        }
-                    }
-                    else {
+                    this.pendingReview = 'stop';
+                    if (!this.pilot) {
                         task.addNote(reason, TestResult.FAILED);
                         task.finish(TestResult.FAILED);
                     }
@@ -966,18 +970,8 @@ export class Tester extends TaskAgent {
                         return { success: true, action: 'finish', message: 'already finished' };
                     }
                     task.addNote(`Finish requested: ${verify}`);
-                    if (this.pilot) {
-                        const currentState = this.getCurrentState();
-                        await this.pilot.reviewFinish(task, currentState, conversation, this.navigator);
-                        if (!task.hasFinished) {
-                            return {
-                                success: false,
-                                action: 'finish',
-                                message: 'Finishing rejected; Continue execution',
-                            };
-                        }
-                    }
-                    else {
+                    this.pendingReview = 'finish';
+                    if (!this.pilot) {
                         task.addNote('Test finished successfully', TestResult.PASSED);
                         task.finish(TestResult.PASSED);
                     }