explorbot 0.4.3 → 0.4.5

package/dist/src/ai/tools.js

@@ -11,6 +11,7 @@ import { cleanHtmlSnippet } from "../utils/html.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
+import { ariaRefSelector, describeRef, refIsGone } from "../utils/aria-ref.js";
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
@@ -52,7 +53,6 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
           2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
-          5. I.clickXY(x, y) - coordinates fallback
           After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
         `),
                 explanation: z.string().describe('Why you are clicking this element'),
@@ -63,10 +63,18 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                     activeNote.commit(TestResult.FAILED);
                     return failedToolResult('click', 'No commands provided');
                 }
-                const invalidCommands = rawCommands.map((cmd) => cmd.trim()).filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
+                const trimmedCommands = rawCommands.map((cmd) => cmd.trim());
+                const coordinateCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.clickXY'));
+                if (coordinateCommands.length > 0) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('click', `Coordinate commands are not locators: ${coordinateCommands.join(', ')}. A coordinate click always runs, so it cannot tell you whether the element was there.`, {
+                        suggestion: 'Name the element instead. Use visualClick() when you can see the target but cannot address it, or form() for a deliberate coordinate click such as dismissing a layer.',
+                    });
+                }
+                const invalidCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
                 if (invalidCommands.length > 0) {
                     activeNote.commit(TestResult.FAILED);
-                    return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() or I.clickXY() commands.`, {
+                    return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() commands.`, {
                         suggestion: 'Use form() tool for typing text or multiple actions, or exitIframe() to leave iframe context.',
                     });
                 }
@@ -91,6 +99,15 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                         ambiguityError = action.lastError;
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
+                        if (!hasObservablePageChange(toolResult)) {
+                            activeNote.commit(TestResult.FAILED);
+                            return failedToolResult('click', 'Click executed, but no observable page change was captured.', {
+                                ...toolResult,
+                                attempts,
+                                code: command,
+                                suggestion: 'Treat the element as not clicked. It may be covered by another layer, disabled, or the locator may have matched a non-interactive ancestor. Re-locate via xpathCheck(), which reports whether the element is covered or offscreen, before retrying.',
+                            });
+                        }
                         await commitNote(activeNote, TestResult.PASSED, toolResult, action);
                         return successToolResult('click', { ...toolResult, attempts, code: command }, action);
                     }
@@ -385,10 +402,16 @@ export function createRefTools({ explorer, stateManager }, task) {
             }),
             execute: async ({ ref, element }) => {
                 const activeNote = task.startNote(`Click ${element}`);
+                if (await refIsGone(explorer, ref)) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('clickRef', `Ref ${ref} names no element on the page any more.`, {
+                        suggestion: 'The page has been rebuilt since you were given that ref. Call context() and use the ref it gives, or fall back to click() with a locator.',
+                    });
+                }
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
                 const action = explorer.action();
                 const named = await describeRef(explorer, ref);
-                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
                 if (!(await action.attempt(run, `Click ${element}`))) {
                     activeNote.commit(TestResult.FAILED);
                     return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
@@ -634,6 +657,11 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                         return failedToolResult('research', 'No current page state available. Navigate to a page first.');
                     }
                     const researchResult = await researcher.research(currentState, { screenshot: true, data: true });
+                    if (!researchResult) {
+                        return failedToolResult('research', 'No UI map is available for this page.', {
+                            suggestion: 'Use context() to read the page structure and act on the elements it lists.',
+                        });
+                    }
                     return successToolResult('research', {
                         analysis: researchResult,
                         aria: cap(ActionResult.fromState(currentState).getInteractiveARIA(), ARIA_OUTPUT_CAP),
@@ -1010,17 +1038,6 @@ export async function commitNote(activeNote, result, toolResult, action) {
     }
     activeNote.commit(result);
 }
-async function describeRef(explorer, ref) {
-    return Promise.resolve(explorer?.withPage?.((page) => page.locator(`aria-ref=${ref}`).evaluate((el) => {
-        const tag = el.tagName.toLowerCase();
-        const roles = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
-        const role = el.getAttribute('role') || roles[tag] || tag;
-        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
-        if (!text)
-            return null;
-        return { role, text };
-    }))).catch(() => null);
-}
 async function hasFocusedElement(explorer) {
     return explorer.withPage((page) => page.evaluate(() => !!document.activeElement && document.activeElement !== document.body)).catch(() => true);
 }
@@ -1080,6 +1097,8 @@ function hasObservablePageChange(data) {
         return true;
     if (data.pageDiff.messages?.length)
         return true;
+    if (data.pageDiff.requests?.length)
+        return true;
     return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
 export async function failedToolResult(action, message, data, error) {
@@ -1088,12 +1107,11 @@ export async function failedToolResult(action, message, data, error) {
         result.suggestion = data.suggestion ? `${data.suggestion} ${PAGE_DIFF_SUGGESTION}` : PAGE_DIFF_SUGGESTION;
     }
     const errorTexts = [message, ...(data?.attempts?.map((a) => a.error || '') || [])];
-    const hasMultipleElements = errorTexts.some((t) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN));
-    const multipleElementsSuggestion = hasMultipleElements ? getMultipleElementsSuggestion() : null;
-    if (multipleElementsSuggestion) {
-        result.suggestion = multipleElementsSuggestion;
+    if (errorTexts.some((t) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
+        const matched = await extractWebElements(error);
+        result.suggestion = getMultipleElementsSuggestion(matched);
         result.multipleElementsDetected = true;
-        result.elements = await formatMatchedElements(error);
+        result.elements = formatElementList(matched);
         return result;
     }
     const notFoundSuggestion = getNotFoundSuggestion(message);
@@ -1103,11 +1121,16 @@ export async function failedToolResult(action, message, data, error) {
     }
     return result;
 }
-function getMultipleElementsSuggestion() {
+function getMultipleElementsSuggestion(matched) {
+    const visible = (matched || []).filter((element) => element.visible !== false);
+    let onlyVisible = '';
+    if (matched && visible.length === 1)
+        onlyVisible = `\nOnly element ${matched.indexOf(visible[0]) + 1} is on screen, so that is the one to act on.`;
     return dedent `
     Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
-    Read the numbered elements list and click the one you meant by its number:
+    Read the numbered elements list and act on the one you meant by its number:
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    A match reported as not visible can never be acted on — pick one that is.${onlyVisible}
     If none of them is the element you want, narrow the locator with a container or its full unique text.
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
@@ -1127,7 +1150,7 @@ export function clickFailureSuggestion(attempts) {
         return 'Element exists but another element covers it. Close the overlapping panel or dialog, then retry.';
     }
     if (errors.some((e) => e.includes('is not visible'))) {
-        return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
+        return 'Element is in the DOM but not visible. Reveal it — scroll to it, expand its section, open the panel holding it — or, when the page carries several copies of the same control, target the one that is on screen.';
     }
     if (errors.some((e) => e.includes('SyntaxError'))) {
         return 'The command string never parsed as JavaScript — quotes or brackets do not match. No element was looked up, so this tells you nothing about the page. Re-emit the same intent as valid CodeceptJS.';
@@ -1157,7 +1180,8 @@ async function extractWebElements(error) {
             const xpath = await elements[i].toAbsoluteXPath();
             const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
             const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
-            result.push({ xpath, html, text });
+            const visible = await Promise.resolve(elements[i].isVisible?.()).catch(() => undefined);
+            result.push({ xpath, html, text, visible });
         }
         catch (e) {
             debugLog('Failed to get details for element %d: %s', i, e);
@@ -1165,14 +1189,21 @@ async function extractWebElements(error) {
     }
     return result.length > 0 ? result : null;
 }
-function formatElementList(details) {
-    return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+function formatElementList(matched) {
+    if (!matched)
+        return 'Could not fetch element details. Repeat the action to get better info.';
+    return matched
+        .map((el, i) => {
+        const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
+        if (el.visible !== undefined)
+            lines.push(`Visible: ${el.visible}`);
+        lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
+        return lines.join('\n');
+    })
+        .join('\n\n');
 }
 export async function formatMatchedElements(error) {
-    const details = await extractWebElements(error);
-    if (!details)
-        return 'Could not fetch element details. Repeat the action to get better info.';
-    return formatElementList(details);
+    return formatElementList(await extractWebElements(error));
 }
 function getNotFoundSuggestion(errorMessage) {
     if (!errorMessage.includes('not found')) {

package/dist/src/application-spec.d.ts

@@ -4,10 +4,13 @@ export declare class ApplicationSpec {
     readonly sourcePath: string;
     constructor(sourcePath: string);
     renderFor(state: ActionResult): string;
+    matchedUrls(state: ActionResult): string[];
     get pageCount(): number;
     load(): void;
     resolveSourcePath(sourcePath: string): string;
+    relevantPages(state: ActionResult): ApplicationSpecPage[];
 }
+export declare function resolveSpecBundlePath(sourcePath: string): string | null;
 interface ApplicationSpecPage {
     url: string;
     content: string;

package/dist/src/application-spec.js

@@ -13,7 +13,7 @@ export class ApplicationSpec {
         this.load();
     }
     renderFor(state) {
-        const relevant = this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
+        const relevant = this.relevantPages(state);
         if (relevant.length === 0)
             return '';
         tag('operation').log(`Found application specification for ${state.url}`);
@@ -25,6 +25,9 @@ export class ApplicationSpec {
       </application_spec>
     `;
     }
+    matchedUrls(state) {
+        return this.relevantPages(state).map((page) => page.url);
+    }
     get pageCount() {
         return this.pages.length;
     }
@@ -63,9 +66,22 @@ export class ApplicationSpec {
         }
     }
     resolveSourcePath(sourcePath) {
-        if (path.isAbsolute(sourcePath))
-            return path.resolve(sourcePath);
-        const configParser = ConfigParser.getInstance();
-        return path.resolve(configParser.resolveProjectDir(sourcePath));
+        return resolveSpecSource(sourcePath);
+    }
+    relevantPages(state) {
+        return this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
     }
 }
+export function resolveSpecBundlePath(sourcePath) {
+    const resolved = resolveSpecSource(sourcePath);
+    if (!existsSync(resolved))
+        return null;
+    if (statSync(resolved).isDirectory())
+        return resolved;
+    return path.dirname(resolved);
+}
+function resolveSpecSource(sourcePath) {
+    if (path.isAbsolute(sourcePath))
+        return path.resolve(sourcePath);
+    return path.resolve(ConfigParser.getInstance().resolveProjectDir(sourcePath));
+}

package/dist/src/commands/config-command.js

@@ -39,8 +39,12 @@ export class ConfigCommand extends BaseCommand {
         const env = {};
         for (const variable of EXPLORBOT_ENV_VARS) {
             const value = process.env[variable.name];
-            if (value)
-                env[variable.name] = value;
+            if (!value)
+                continue;
+            let shown = value;
+            if (variable.secret)
+                shown = 'set';
+            env[variable.name] = shown;
         }
         const models = {};
         const providers = {};

package/dist/src/config.d.ts

@@ -105,6 +105,10 @@ interface RerunnerAgentConfig extends AgentConfig {
 interface PlannerAgentConfig extends AgentConfig {
     styles?: string[];
     stylesDir?: string;
+    docsWeight?: number;
+}
+interface ScoutAgentConfig extends AgentConfig {
+    dirs?: string[];
 }
 interface ScreencastConfig {
     size?: {
@@ -129,6 +133,7 @@ interface AgentsConfig {
     quartermaster?: AgentConfig;
     historian?: HistorianAgentConfig;
     fisherman?: AgentConfig;
+    scout?: ScoutAgentConfig;
     chief?: AgentConfig;
     curler?: AgentConfig;
     rerunner?: RerunnerAgentConfig;
@@ -221,7 +226,7 @@ interface ExplorbotConfig {
 type RuleEntry = string | Record<string, string>;
 export declare const EXPLORBOT_CONFIG_PATHS: string[];
 export declare const EXPLORBOT_ENV_VARS: EnvVar[];
-export type { ExplorbotConfig, PlaywrightConfig, AIConfig, HtmlConfig, ActionConfig, AgentConfig, AgentsConfig, HistorianAgentConfig, ResearcherAgentConfig, NavigatorAgentConfig, PlannerAgentConfig, RerunnerAgentConfig, HealRecipe, Hook, HookConfig, HooksConfig, PlaywrightHook, CodeceptJSHook, HookPatternMap, RuleEntry, ReporterConfig, ApiConfig, WebConfig, ApiHookFn, };
+export type { ExplorbotConfig, PlaywrightConfig, AIConfig, HtmlConfig, ActionConfig, AgentConfig, AgentsConfig, HistorianAgentConfig, ResearcherAgentConfig, NavigatorAgentConfig, PlannerAgentConfig, ScoutAgentConfig, RerunnerAgentConfig, HealRecipe, Hook, HookConfig, HooksConfig, PlaywrightHook, CodeceptJSHook, HookPatternMap, RuleEntry, ReporterConfig, ApiConfig, WebConfig, ApiHookFn, };
 export declare class ConfigParser {
     static instance: ConfigParser;
     static recommended: Record<string, Record<string, string>> | null;
@@ -269,7 +274,9 @@ export declare class ConfigParser {
     deepMerge(target: any, source: any): any;
     ensureDirectory(path: string): void;
 }
+export declare function setOutputDir(dir: string): void;
 export declare function outputPath(...segments: string[]): string;
+export declare function agentSettings<K extends keyof AgentsConfig>(config: ExplorbotConfig, agent: K): NonNullable<AgentsConfig[K]>;
 export declare function resolveModel(spec: string, role?: ModelRole): Promise<any>;
 export declare function missingModelRoles(provider: string): ModelRole[];
 export declare class ConfigMissingError extends Error {
@@ -297,5 +304,6 @@ interface EnvVar {
     name: string;
     description: string;
     required?: boolean;
+    secret?: boolean;
 }
 export type { ModelRole, EnvVar, ProviderInfo, ConfiguredModel };

package/dist/src/config.js

@@ -27,6 +27,7 @@ export const PROVIDERS = {
 };
 export const MODEL_ROLES = ['model', 'visionModel', 'agenticModel'];
 let cachedOutputRoot = null;
+let runOutputDir = null;
 const config = {
     playwright: {
         browser: 'chromium',
@@ -49,6 +50,7 @@ export const EXPLORBOT_ENV_VARS = [
     { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
     { name: 'EXPLORBOT_SPEC', description: 'Docbot application spec directory or index.md, used as page knowledge' },
     { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
+    { name: 'EXPLORBOT_API_HEADERS', description: 'Headers sent with every API request, one "Name: value" per line', secret: true },
     { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
     { name: 'EXPLORBOT_MAX_DURATION', description: 'Wall-clock budget in minutes for an explore run; same as --max-duration' },
 ];
@@ -213,6 +215,7 @@ export class ConfigParser {
     // For testing purposes only
     static resetForTesting() {
         cachedOutputRoot = null;
+        runOutputDir = null;
         if (ConfigParser.instance) {
             ConfigParser.instance.config = null;
             ConfigParser.instance.configPath = null;
@@ -441,9 +444,20 @@ export class ConfigParser {
         }
     }
 }
+export function setOutputDir(dir) {
+    runOutputDir = dir;
+}
 export function outputPath(...segments) {
+    if (runOutputDir)
+        return path.join(runOutputDir, ...segments);
     return path.join(ConfigParser.getInstance().getOutputDir(), ...segments);
 }
+export function agentSettings(config, agent) {
+    const ai = (config.ai ??= { model: null });
+    const agents = (ai.agents ??= {});
+    agents[agent] ??= {};
+    return agents[agent];
+}
 export async function resolveModel(spec, role = 'model') {
     const separator = spec.indexOf('/');
     if (separator > 0) {

package/dist/src/explorbot.d.ts

@@ -12,6 +12,7 @@ import { AIProvider } from './ai/provider.js';
 import { Quartermaster } from './ai/quartermaster.js';
 import { Rerunner } from './ai/rerunner.js';
 import { Researcher } from './ai/researcher.js';
+import { Scout } from './ai/scout.js';
 import { SessionAnalyst } from './ai/session-analyst.js';
 import { Tester } from './ai/tester.js';
 import { RequestStore } from './api/request-store.js';
@@ -99,6 +100,8 @@ export declare class ExplorBot {
     agentDriller(): Driller;
     agentSessionAnalyst(): SessionAnalyst;
     agentFisherman(): Fisherman | null;
+    agentScout(): Scout | null;
+    scoutCorpusDirs(): string[];
     getCurrentPlan(): Plan | undefined;
     getSuite(): Suite | null;
     getPlanFeature(): string | undefined;

package/dist/src/explorbot.js

@@ -12,12 +12,15 @@ import { AIProvider } from "./ai/provider.js";
 import { Quartermaster } from "./ai/quartermaster.js";
 import { Rerunner } from "./ai/rerunner.js";
 import { Researcher } from "./ai/researcher.js";
+import { Scout } from "./ai/scout.js";
+import { loadScoutCorpus } from "./ai/scout/tools.js";
 import { SessionAnalyst } from "./ai/session-analyst.js";
 import { Tester } from "./ai/tester.js";
 import { createAgentTools } from "./ai/tools.js";
 import { ApiClient } from "./api/api-client.js";
 import { RequestStore } from "./api/request-store.js";
 import { loadSpec } from "./api/spec-reader.js";
+import { resolveSpecBundlePath } from "./application-spec.js";
 import { ConfigParser } from "./config.js";
 import { ExperienceTracker } from "./experience-tracker.js";
 import Explorer from "./explorer.js";
@@ -184,6 +187,9 @@ export class ExplorBot {
             const fisherman = this.agentFisherman();
             if (fisherman)
                 this.agents.planner.setFisherman(fisherman);
+            const scout = this.agentScout();
+            if (scout)
+                this.agents.planner.setScout(scout);
         }
         return this.agents.planner;
     }
@@ -310,6 +316,33 @@ export class ExplorBot {
         }
         return this.agents.fisherman;
     }
+    agentScout() {
+        const scoutConfig = this.config.ai?.agents?.scout;
+        if (scoutConfig?.enabled !== true)
+            return null;
+        const dirs = this.scoutCorpusDirs();
+        if (dirs.length === 0) {
+            tag('warning').log('Scout enabled but no documentation found — set --spec or ai.agents.scout.dirs');
+            return null;
+        }
+        return (this.agents.scout ||= this.createAgent(({ ai }) => new Scout(ai, loadScoutCorpus(dirs))));
+    }
+    scoutCorpusDirs() {
+        const dirs = [];
+        const specPath = this.options.applicationSpec || this.config.dirs?.spec;
+        if (specPath) {
+            const bundle = resolveSpecBundlePath(specPath);
+            const pagesDir = bundle && path.join(bundle, 'pages');
+            if (pagesDir && existsSync(pagesDir))
+                dirs.push(pagesDir);
+        }
+        for (const dir of this.config.ai?.agents?.scout?.dirs || []) {
+            const resolved = this.configParser.resolveProjectDir(dir);
+            if (existsSync(resolved))
+                dirs.push(resolved);
+        }
+        return [...new Set(dirs)];
+    }
     getCurrentPlan() {
         return this.currentPlan;
     }

package/dist/src/knowledge-tracker.d.ts

@@ -16,6 +16,7 @@ export declare class KnowledgeTracker {
     renderEndpointKnowledge(endpoint: string): string;
     renderRelevantContext(state: ActionResult): string;
     renderApplicationSpec(state: ActionResult): string;
+    applicationSpecUrls(state: ActionResult): string[];
     addKnowledge(urlPattern: string, description: string, opts?: {
         replace?: boolean;
     }): {

package/dist/src/knowledge-tracker.js

@@ -79,6 +79,9 @@ export class KnowledgeTracker {
     renderApplicationSpec(state) {
         return this.applicationSpec?.renderFor(state) || '';
     }
+    applicationSpecUrls(state) {
+        return this.applicationSpec?.matchedUrls(state) || [];
+    }
     addKnowledge(urlPattern, description, opts) {
         const configParser = ConfigParser.getInstance();
         const configPath = configParser.getConfigPath();

package/dist/src/state-manager.js

@@ -60,12 +60,16 @@ export class StateManager {
     updateState(actionResult, codeBlock, trigger = 'manual') {
         const previousState = this.currentState;
         const previousHash = previousState?.hash;
+        const hashChanged = actionResult.hash !== previousHash;
+        if (!hashChanged && previousState?.verifications) {
+            const stillTrue = Object.entries(previousState.verifications).filter(([, passed]) => passed);
+            actionResult.verifications = { ...Object.fromEntries(stillTrue), ...actionResult.verifications };
+        }
         const newState = actionResult;
         this.currentState = newState;
         this.currentState.id = this.nextStateId++;
         if (newState.url)
             this.allVisitedUrls.add(normalizeUrl(newState.url));
-        const hashChanged = actionResult.hash !== previousHash;
         const regionOpened = !hashChanged && this.regionOpened(previousState, newState);
         if (hashChanged || regionOpened) {
             const transition = {

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

@@ -0,0 +1,16 @@
+import { WebElement } from './web-element.js';
+export declare function ariaRefSelector(ref: string): string;
+export declare function isAriaRef(ref: string): boolean;
+export declare function ariaRefSnapshot(page: any): Promise<string>;
+export declare function parseAriaRefs(ariaSnapshot: string): AriaRefEntry[];
+export declare function elementFromAriaRef(page: any, ref: string): Promise<WebElement | null>;
+export declare function refIsGone(explorer: any, ref: string): Promise<boolean>;
+export declare function describeRef(explorer: any, ref: string): Promise<{
+    role: string;
+    text: string;
+} | null>;
+export interface AriaRefEntry {
+    role: string;
+    name: string;
+    ref: string;
+}

package/dist/src/utils/aria-ref.js

@@ -0,0 +1,47 @@
+import { WebElement } from "./web-element.js";
+const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
+const ARIA_REF_PATTERN = /^(f\d+)?e\d+$/i;
+const REF_ROLES = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
+export function ariaRefSelector(ref) {
+    return `aria-ref=${ref}`;
+}
+export function isAriaRef(ref) {
+    return ARIA_REF_PATTERN.test(ref);
+}
+export function ariaRefSnapshot(page) {
+    return page.locator('body').ariaSnapshot({ mode: 'ai' });
+}
+export function parseAriaRefs(ariaSnapshot) {
+    const entries = [];
+    for (const line of ariaSnapshot.split('\n')) {
+        const match = line.match(REF_LINE_PATTERN);
+        if (!match)
+            continue;
+        entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
+    }
+    return entries;
+}
+export async function elementFromAriaRef(page, ref) {
+    if (!isAriaRef(ref))
+        return null;
+    return WebElement.fromPlaywrightLocator(page.locator(ariaRefSelector(ref)));
+}
+export async function refIsGone(explorer, ref) {
+    const count = () => Promise.resolve(explorer?.withPage?.((page) => page.locator(ariaRefSelector(ref)).count())).catch(() => undefined);
+    if ((await count()) !== 0)
+        return false;
+    await Promise.resolve(explorer?.withPage?.(ariaRefSnapshot)).catch(() => null);
+    return (await count()) === 0;
+}
+export async function describeRef(explorer, ref) {
+    return Promise.resolve(explorer?.withPage?.((page) => page.locator(ariaRefSelector(ref)).evaluate((el, roles) => {
+        const tag = el.tagName.toLowerCase();
+        const role = el.getAttribute('role') || roles[tag];
+        if (!role)
+            return null;
+        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
+        if (!text)
+            return null;
+        return { role, text };
+    }, REF_ROLES))).catch(() => null);
+}

package/dist/src/utils/aria.js

@@ -434,9 +434,9 @@ const formatDiffSection = (label, items) => {
     const summary = countBy(items);
     if (summary.size === 0)
         return [`  ${label}: []`];
-    const sorted = Array.from(summary.entries()).sort(([aItem, aCount], [bItem, bCount]) => bCount - aCount || aItem.localeCompare(bItem));
-    const top = sorted.slice(0, TOP_DIFF_ITEMS);
-    const rest = sorted.slice(TOP_DIFF_ITEMS);
+    const ordered = Array.from(summary.entries());
+    const top = ordered.slice(0, TOP_DIFF_ITEMS);
+    const rest = ordered.slice(TOP_DIFF_ITEMS);
     const lines = [`  ${label}:`];
     for (const [item, count] of top) {
         let suffix = '';

package/dist/src/utils/web-annotate.js

@@ -1,24 +1,12 @@
+import { ariaRefSnapshot, parseAriaRefs } from "./aria-ref.js";
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from "./html.js";
 import { createDebug } from './logger.js';
 import { WebElement } from "./web-element.js";
 const debugLog = createDebug('explorbot:web-annotate');
-const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
 const ANNOTATABLE_ROLES = new Set(['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'switch', 'combobox', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'treeitem']);
-function parseAriaRefs(ariaSnapshot) {
-    const entries = [];
-    for (const line of ariaSnapshot.split('\n')) {
-        const match = line.match(REF_LINE_PATTERN);
-        if (!match)
-            continue;
-        if (!ANNOTATABLE_ROLES.has(match[2]))
-            continue;
-        entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
-    }
-    return entries;
-}
 export async function annotatePageElements(page) {
-    const ariaSnapshot = await page.locator('body').ariaSnapshot({ mode: 'ai' });
-    const refEntries = parseAriaRefs(ariaSnapshot);
+    const ariaSnapshot = await ariaRefSnapshot(page);
+    const refEntries = parseAriaRefs(ariaSnapshot).filter((entry) => ANNOTATABLE_ROLES.has(entry.role));
     const byRole = new Map();
     for (const { role, name, ref } of refEntries) {
         let list = byRole.get(role);

package/dist/src/utils/web-element.d.ts

@@ -36,8 +36,6 @@ export declare class WebElement {
     static fromXPathMatch(m: XPathMatch): WebElement;
     static fromPlaywrightLocator(locator: any): Promise<WebElement | null>;
     static fromEidx(page: any, eidx: string): Promise<WebElement | null>;
-    static isAriaRef(ref: string): boolean;
-    static fromAriaRef(page: any, ref: string): Promise<WebElement | null>;
     static fromEidxList(page: any, eidxList: string[]): Promise<WebElement[]>;
     static commonAncestor(page: any, eidxList: string[]): Promise<WebElement | null>;
     static findByXPath(html: string, xpath: string): Promise<{

package/dist/src/utils/web-element.js

@@ -111,14 +111,6 @@ export class WebElement {
     static async fromEidx(page, eidx) {
         return WebElement.fromPlaywrightLocator(page.locator(`[${EXPLORBOT_ATTRS.eidx}="${eidx}"]`));
     }
-    static isAriaRef(ref) {
-        return /^(f\d+)?e\d+$/i.test(ref);
-    }
-    static async fromAriaRef(page, ref) {
-        if (!WebElement.isAriaRef(ref))
-            return null;
-        return WebElement.fromPlaywrightLocator(page.locator(`aria-ref=${ref}`));
-    }
     static async fromEidxList(page, eidxList) {
         const validEidxList = eidxList.filter((eidx) => /^e\d+$/i.test(eidx));
         if (validEidxList.length === 0)

package/docs/api-testing/basics.md

@@ -30,7 +30,7 @@ export default {
 
 - **`baseEndpoint`** (required) — the base URL prepended to every request. Test steps use relative paths like `/users`; Curler adds the base for you.
 - **`spec`** (required) — one or more OpenAPI specs, given as HTTP(S) URLs or local file paths, in YAML or JSON. Chief uses the spec to plan; Curler uses it to look up schemas. Both agents refuse to run without one.
-- **`headers`** — sent with every request. This is where API keys and auth tokens go.
+- **`headers`** — sent with every request. This is where API keys and auth tokens go. `-H "Name: value"` on the command line and `EXPLORBOT_API_HEADERS` add to them without a config file.
 
 See the [full configuration reference](../reference/configuration.md) for every option and [providers](../basics/providers.md) for choosing an AI model.
 
@@ -60,16 +60,24 @@ A matching `teardown` hook runs after all tests finish — use it to clean up da
 
 Chief and Curler need three things: where the API is, what its spec says, and how to authenticate. Pass all three on the command line and no config file is needed:
 
+```bash
+npx explorbot api explore https://api.example.com/v1 \
+  --spec ./openapi.yaml \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+`api explore` takes the base endpoint as its argument, so one line covers the whole run: it plans in every style, executes each plan, and reports the totals. The other commands take a path within the API and read the base from `--endpoint`:
+
 ```bash
 npx explorbot api plan /users \
   --endpoint https://api.example.com/v1 \
   --spec ./openapi.yaml \
-  --knowledge 'Send X-Api-Key: ${env.API_KEY} on every request'
+  -H "Authorization: Bearer $TOKEN"
 ```
 
-`--endpoint` and `--spec` each have an environment twin — `EXPLORBOT_URL` and `EXPLORBOT_API_SPEC` — and the flag wins when both are set. `--knowledge` adds to the facts `EXPLORBOT_KNOWLEDGE` and `EXPLORBOT_KNOWLEDGE_FILE` bring in rather than replacing them. Configure your models once with `npx explorbot init --global` and every run stores its plans and requests per host under `~/.explorbot/sites/<host>/`, so a later `api test` against the same API picks up where the last one left off. Knowledge given on the command line lasts for the run; `api know` is what writes it down.
+Each flag has an environment twin — `EXPLORBOT_URL`, `EXPLORBOT_API_SPEC` and `EXPLORBOT_API_HEADERS` — and the flag wins when both are set. `-H` is repeatable and takes one `Name: value` per use; the variable takes one per line. Headers land on every request, the startup health check included, and merge over any `headers` a config file sets. `--knowledge` adds to the facts `EXPLORBOT_KNOWLEDGE` and `EXPLORBOT_KNOWLEDGE_FILE` bring in rather than replacing them. Configure your models once with `npx explorbot init --global` and every run stores its plans and requests per host under `~/.explorbot/sites/<host>/`, so a later `api test` against the same API picks up where the last one left off. Knowledge given on the command line lasts for the run; `api know` is what writes it down.
 
-`--endpoint` keeps its path prefix: given `https://api.example.com/v1`, steps stay relative (`/users`) and Curler sends them to `https://api.example.com/v1/users`. `api test`, which takes a plan file rather than an endpoint, reads it from the flag or the variable.
+The base endpoint keeps its path prefix: given `https://api.example.com/v1`, steps stay relative (`/users`) and Curler sends them to `https://api.example.com/v1/users`. `api test`, which takes a plan file rather than an endpoint, reads the base from the flag or the variable.
 
 ### A dedicated API project