explorbot 0.4.3 → 0.4.4

package/dist/boat/prima/src/help.js

@@ -0,0 +1,63 @@
+import dedent from 'dedent';
+export const helpContract = dedent `
+  Prima drives the browser opened by playwright-cli.
+
+    playwright-cli open <url>    starts the session
+    prima <command> ...          drives it
+    playwright-cli close         ends it
+
+  One call runs a whole job:
+
+    prima check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
+    prima do "open the account menu" "choose the settings entry" "switch the theme to dark" "check it took effect"
+    prima pw "({ page }) => page.click('[data-test=submit]')"
+
+  Only research maps a page. Other commands read the accessibility tree; a cached
+  research map joins when present. On large or unclear pages, run prima research first.
+  Without a usable AI model only pw works; otherwise use playwright-cli.
+  DEBUG='explorbot:*' in front of a command logs everything it does.
+`;
+export const checkHelp = dedent `
+  check states the outcome, not the clicks; it finds the path itself. It stays
+  on the current page and never reloads it, so an open dialog survives.
+  --expected  one required outcome, repeatable for several. Without it the
+              scenario text is the outcome. Each returns under
+              ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
+              "not verified" means never checked, not false.
+  Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
+  CONTRADICTION means screenshot and log disagree; judge the html, aria and
+  screenshot under ### Artifacts yourself.
+  ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
+  reported as such rather than as an app failure.
+  Side issues found on the way go under ### Answer, not as step failures.
+`;
+export const doHelp = dedent `
+  ### Steps marks each instruction ok, FAIL or ??. ?? means it ran but the run ended
+  without confirming it - read the steps above. Only FAIL fails the command.
+  Nothing runs past the last instruction. Batch the whole sequence in one call;
+  that is what keeps this tier cheap.
+`;
+export const askHelp = dedent `
+  Answers from a page screenshot, or from its structure with --no-vision.
+`;
+export const verifyHelp = dedent `
+  Reports each expressible assertion as PASSED or FAILED with its playwright form;
+  no overall verdict, read the lines. "none ran" means unexpressible, not false.
+`;
+export const researchHelp = dedent `
+  The map is saved per page state and joins later commands there, so one research run pays for all that follow it.
+`;
+export const statusHelp = dedent `
+  Reads recorded files, so it needs no browser and outlives the session.
+  The hash is matched across all recorded sites. ### Artifacts lists every kept
+  file: aria, html, screenshot and network log when captured, plus per-step captures of a do run.
+`;
+export const reportHelp = dedent `
+  Built from the command log, so it needs no browser and outlives the session.
+  Reports the latest session unless --pw-session names another.
+`;
+export const sessionHelp = dedent `
+  Parallel jobs need one --instance each. --session is ignored when attached,
+  since the attached session keeps its own. --framework is parsed but inactive;
+  reported code is CodeceptJS either way.
+`;

package/dist/boat/prima/src/prima.js

@@ -23,14 +23,13 @@ import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { pluralize } from "../../../src/utils/logger.js";
 import { mdq } from "../../../src/utils/markdown-query.js";
 import { safeFilename } from "../../../src/utils/strings.js";
-import { STATUS_FILE, readArtifacts, writeArtifacts } from "./envelope.js";
+import { STATUS_FILE, STEP_FILES, readArtifacts, writeArtifacts } from "./envelope.js";
 import { isFunctionExpression, takePwValue, toCodeceptWrapper } from "./pw-parser.js";
 import { readDescriptors, selectDescriptor } from "./pw-registry.js";
 import { latestSessionFile, readSession, recordCommand, sessionFile, sessionsDir } from "./session-log.js";
-const TESTER_ONLY_TOOLS = ['learnExperience', 'askUser'];
+const WITHHELD_TOOLS = ['learnExperience', 'askUser', 'research'];
 const ITERATIONS_PER_INSTRUCTION = 2;
 const MAX_INSTRUCTION_ITERATIONS = 24;
-const DEFAULT_RESEARCH_AFTER_VISITS = 3;
 const CONTEXT_HTML_CAP = 6000;
 const MAX_TOOL_ROUNDTRIPS = 5;
 const AI_AGENT_NAME = 'prima';
@@ -68,7 +67,6 @@ export class Prima {
     server = null;
     attached = null;
     session = null;
-    artifacts;
     constructor(options = {}) {
         this.options = options;
         this.bot = new ExplorBot({
@@ -99,6 +97,7 @@ export class Prima {
         const config = await this.loadConfig();
         await this.resolveBrowser(config, discovery);
         await this.bot.start();
+        this.bot.agentResearcher().disable();
         if (!this.options.url)
             return;
         if (this.bot.getCurrentState())
@@ -382,9 +381,11 @@ export class Prima {
         const guard = await this.aiGuard(command);
         if (guard)
             return guard;
+        const researcher = this.bot.agentResearcher();
+        researcher.enable();
         const previousState = this.bot.stateManager().getCurrentState();
         const result = await this.capturedResult(previousState);
-        const uiMap = await this.bot.agentResearcher().research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
+        const uiMap = await researcher.research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
         return this.reportEnvelope(command, result, previousState, { research: dropVolatileColumns(uiMap) });
     }
     async go(target) {
@@ -768,7 +769,7 @@ export class Prima {
         if (!researcher || !navigator)
             return {};
         const tools = createAgentTools({ ...deps, researcher, navigator, withExperience: false });
-        for (const name of TESTER_ONLY_TOOLS)
+        for (const name of WITHHELD_TOOLS)
             delete tools[name];
         return tools;
     }
@@ -823,14 +824,15 @@ export class Prima {
     }
     async pageContext(result) {
         const experience = this.bot.experienceTracker?.()?.renderExperienceTocFor?.(result) || '';
-        const map = this.researchMap(result);
+        const map = getPreviousResearch(result.baseHash);
+        let uiMap = '';
         if (map) {
-            return dedent `
-        <page_ui_map url="${result.url}" title="${result.title}">
+            uiMap = dedent `
+        <page_ui_map>
+        A map of this page recorded by an earlier research run. It names parts the accessibility
+        tree does not, and can be out of date — the tree is what the page holds now.
         ${map}
         </page_ui_map>
-
-        ${experience}
       `;
         }
         return dedent `
@@ -838,20 +840,11 @@ export class Prima {
       ${compactAriaSnapshot(await this.refAriaSnapshot(result), true, (value) => this.offloadValue(value))}
       </page>
 
+      ${uiMap}
+
       ${experience}
     `;
     }
-    researchMap(result) {
-        if (this.bot.stateManager().getVisitCount(result.url) < this.researchAfterVisits())
-            return '';
-        return getPreviousResearch(result.getStateHash());
-    }
-    researchAfterVisits() {
-        const configured = this.bot.getConfig?.()?.ai?.agents?.prima?.researchAfterVisits;
-        if (typeof configured === 'number')
-            return configured;
-        return DEFAULT_RESEARCH_AFTER_VISITS;
-    }
     offloadValue(value) {
         const dir = this.statusDir();
         const name = `value-${createHash('sha1').update(value).digest('hex').slice(0, 8)}.txt`;
@@ -923,16 +916,13 @@ export class Prima {
     }
     async successEnvelope(command, used, result, previousState) {
         const changes = await this.pageChanges(result, previousState, used[0]);
-        const status = await this.saveStatus(result);
         return {
             ok: true,
             command,
             used,
             page: this.pageBlock(result, previousState),
             changes,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
     async failureEnvelope(command, error, previousState) {
@@ -940,29 +930,27 @@ export class Prima {
         const failure = { error: browserErrorMessage(error) };
         if (result.ariaSnapshot)
             failure.compactAria = compactAriaSnapshot(result.ariaSnapshot, true);
-        const status = await this.saveStatus(result);
         return {
             ok: false,
             command,
             page: this.pageBlock(result, previousState),
             failure,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
     async reportEnvelope(command, result, previousState, outcome) {
-        const status = await this.saveStatus(result);
         return {
             ok: true,
             command,
             page: this.pageBlock(result, previousState),
             ...outcome,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
+    async envelopeTail(result) {
+        const { hash, artifacts } = await this.saveStatus(result);
+        return { instance: await this.instanceInfo(), status: hash, artifacts };
+    }
     async capturedResult(previousState, opts = {}) {
         const captured = await this.bot
             .getExplorer()
@@ -1026,9 +1014,9 @@ export class Prima {
     }
     async saveStatus(result) {
         const hash = this.statusHash();
-        await this.writeSnapshot(result);
+        const artifacts = await this.writeSnapshot(result);
         writeFileSync(path.join(this.statusDir(hash), STATUS_FILE), JSON.stringify({ page: this.pageBlock(result, null) }), 'utf-8');
-        return hash;
+        return { hash, artifacts };
     }
     async writeStepFiles(index, label, diff) {
         const state = this.bot.stateManager().getCurrentState();
@@ -1038,17 +1026,17 @@ export class Prima {
         mkdirSync(dir, { recursive: true });
         const stem = path.join(dir, `${index}-${safeFilename(label.slice(0, 60))}`);
         const result = ActionResult.fromState(state);
-        writeFileSync(`${stem}.aria.yaml`, result.ariaSnapshot ?? '', 'utf-8');
-        writeFileSync(`${stem}.html`, await result.combinedHtml(), 'utf-8');
+        writeFileSync(`${stem}.${STEP_FILES.aria}`, result.ariaSnapshot ?? '', 'utf-8');
+        writeFileSync(`${stem}.${STEP_FILES.html}`, await result.combinedHtml(), 'utf-8');
         if (diff)
-            writeFileSync(`${stem}.diff.yaml`, diff, 'utf-8');
+            writeFileSync(`${stem}.${STEP_FILES.diff}`, diff, 'utf-8');
     }
     async writeSnapshot(result) {
-        this.artifacts = writeArtifacts(this.statusDir(), {
+        return writeArtifacts(this.statusDir(), {
             aria: result.ariaSnapshot,
             html: await result.combinedHtml(),
             screenshot: result.screenshot,
-            requests: this.bot.requestStore().getMadeRequests(),
+            requests: this.bot.requestStore().getCapturedRequests(),
         });
     }
     statusHash() {

package/dist/package.json

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

package/dist/src/action-result.d.ts

@@ -26,6 +26,7 @@ interface ActionResultData extends WebPageState {
     }>;
     ariaSnapshot?: string | null;
     ariaSnapshotFile?: string;
+    regionAria?: string | null;
     focusedElement?: FocusedElement | null;
     iframeURL?: string;
     links?: Link[];
@@ -84,6 +85,7 @@ export declare class ActionResult implements ActionResultData {
     links: Link[];
     verifications?: Record<string, boolean>;
     overlay: Region;
+    regionAria: string | null;
     _diffCache: {
         previousId: number | undefined;
         diff: Diff;
@@ -109,6 +111,7 @@ export declare class ActionResult implements ActionResultData {
     }): Promise<string>;
     textHtml(htmlConfig?: HtmlConfig): Promise<string>;
     getInteractiveARIA(): string;
+    getRegionARIA(): string;
     getCompactARIA(): string;
     normalizeHtmlConfig(htmlConfig?: HtmlConfig): HtmlConfig | undefined;
     static fromState(state: WebPageState): ActionResult;

package/dist/src/action-result.js

@@ -40,6 +40,7 @@ export class ActionResult {
     links = [];
     verifications;
     overlay = new Region();
+    regionAria = null;
     _diffCache = null;
     constructor(data) {
         this.id = data.id;
@@ -55,6 +56,7 @@ export class ActionResult {
         this.iframeURL = data.iframeURL;
         this.notes = data.notes ?? [];
         this.verifications = data.verifications;
+        this.regionAria = data.regionAria ?? null;
         // Set readonly properties
         if (data.screenshotFile !== undefined) {
             this.screenshotFile = data.screenshotFile;
@@ -238,6 +240,9 @@ export class ActionResult {
     getInteractiveARIA() {
         return compactAriaSnapshot(this.ariaSnapshot, false);
     }
+    getRegionARIA() {
+        return compactAriaSnapshot(this.regionAria, false);
+    }
     getCompactARIA() {
         return compactAriaSnapshot(this.ariaSnapshot, true);
     }

package/dist/src/action.js

@@ -165,8 +165,19 @@ class Action {
                 focusedElement,
                 iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
             });
-            if (!frame)
+            if (!frame) {
                 await this.detectRegion(result).catch((err) => debugLog('Region detection failed:', err.message));
+                const regionRoot = result.overlay.root;
+                if (result.overlay.isModal && regionRoot) {
+                    result.regionAria = await this.playwrightHelper.page
+                        .locator(regionRoot)
+                        .ariaSnapshot()
+                        .catch((err) => {
+                        debugLog('Region ARIA snapshot failed:', err.message);
+                        return null;
+                    });
+                }
+            }
             this.stateManager.updateState(result, codeBlock);
             return result;
         }

package/dist/src/ai/researcher/deep-analysis.d.ts

@@ -1,5 +1,5 @@
 import { ActionResult, type Diff } from '../../action-result.js';
-import type { ExplorbotConfig } from '../../config.js';
+import { type ExplorbotConfig } from '../../config.js';
 import type Explorer from '../../explorer.js';
 import type { StateManager } from '../../state-manager.js';
 import { WebPageState } from '../../state-manager.js';

package/dist/src/ai/researcher/deep-analysis.js

@@ -1,5 +1,6 @@
 import dedent from 'dedent';
 import { ActionResult } from '../../action-result.js';
+import { agentSettings } from "../../config.js";
 import { executionController } from "../../execution-controller.js";
 import { diffAriaSnapshots } from "../../utils/aria.js";
 import { extractCodeBlocks } from "../../utils/code-extractor.js";
@@ -16,7 +17,7 @@ export function WithDeepAnalysis(Base) {
         async performDeepAnalysis(state, result) {
             tag('info').log('Starting deep analysis of expandable elements');
             await this.navigateTo(state.fullUrl || state.url);
-            const maxClicks = this.config.ai?.agents?.researcher?.maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
+            const maxClicks = agentSettings(this.config, 'researcher').maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
             const expandedSections = [];
             const navigationLinks = [];
             let verifiedCodes = [];
@@ -62,6 +63,8 @@ export function WithDeepAnalysis(Base) {
             this._appendExtendedResearch(result, expandedSections, navigationLinks);
         }
         async researchOverlay(current, previous, pageStateHash) {
+            if (!this.isEnabled())
+                return null;
             const region = current.overlay;
             if (!region.isOpen || !region.name)
                 return null;

package/dist/src/ai/researcher/sections.d.ts

@@ -1,5 +1,5 @@
 import type { ActionResult } from '../../action-result.js';
-import type { ExplorbotConfig } from '../../config.js';
+import { type ExplorbotConfig } from '../../config.js';
 import type Explorer from '../../explorer.js';
 import type { StateManager } from '../../state-manager.js';
 import type { Provider } from '../provider.js';

package/dist/src/ai/researcher/sections.js

@@ -1,4 +1,5 @@
 import dedent from 'dedent';
+import { agentSettings } from "../../config.js";
 import { executionController } from "../../execution-controller.js";
 import { tag } from '../../utils/logger.js';
 import { RulesLoader } from "../../utils/rules-loader.js";
@@ -50,7 +51,7 @@ export function WithSections(Base) {
             return focused.text;
         }
         async _detectFocusCss() {
-            const focusSections = this.config.ai?.agents?.researcher?.focusSections;
+            const focusSections = agentSettings(this.config, 'researcher').focusSections;
             if (!focusSections?.length)
                 return null;
             for (const css of focusSections) {

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/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);
                     }

package/dist/src/ai/tools.js

@@ -634,6 +634,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),

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

@@ -269,7 +269,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 +299,6 @@ interface EnvVar {
     name: string;
     description: string;
     required?: boolean;
+    secret?: boolean;
 }
 export type { ModelRole, EnvVar, ProviderInfo, ConfiguredModel };