explorbot 0.4.2 → 0.4.4

package/dist/src/ai/fisherman.js

@@ -4,8 +4,8 @@ import { listAllEndpoints } from "../api/spec-reader.js";
 import { createDebug, tag } from "../utils/logger.js";
 const debugLog = createDebug('explorbot:fisherman');
 import { loop } from "../utils/loop.js";
-import { createFishermanTools } from "./fisherman-tools.js";
 import { RequestHaul } from "./fisherman/request-haul.js";
+import { createFishermanTools } from "./fisherman/tools.js";
 import { dataProtectionRules } from "./rules.js";
 const MAX_ITERATIONS = 15;
 const MAX_TOOL_ROUNDTRIPS = 5;
@@ -58,7 +58,6 @@ export class Fisherman {
         debugLog(`endpoints:\n${endpointList || '(none)'}`);
         if (!endpointList) {
             tag('warning').log('Fisherman: no endpoints available');
-            this.mode = 'disabled';
             return { success: false, summary: 'No API endpoints available', created: [], failed: [] };
         }
         await this.refreshAuth();
@@ -70,6 +69,47 @@ export class Fisherman {
         });
         const conversation = this.provider.startConversation(this.buildSystemPrompt(endpointList, Object.keys(tools), scopeUrl), 'fisherman');
         conversation.addUserText(this.buildTaskPrompt(instructions));
+        await this.runSession(conversation, tools, { haul, isFinished, finishFromText, label: `fisherman: ${instructions.slice(0, 50)}` });
+        const result = getResult();
+        tag('info').log(`Fisherman result: ${result.summary}`);
+        return result;
+    }
+    async lookupData(question, scopeUrl, sessionName) {
+        this.sessionName = sessionName;
+        tag('info').log(`Fisherman [read]: ${question}`);
+        await this.ensureReady(scopeUrl);
+        if (this.mode === 'disabled') {
+            debugLog('disabled — no data for scope');
+            return { success: false, summary: 'No API data available for this scope', created: [], failed: [] };
+        }
+        const endpointList = this.buildEndpointList(scopeUrl, 'read');
+        debugLog(`read endpoints:\n${endpointList || '(none)'}`);
+        if (!endpointList) {
+            tag('warning').log('Fisherman: no read endpoints available');
+            return { success: false, summary: 'No read endpoints are known for this scope', created: [], failed: [] };
+        }
+        await this.refreshAuth();
+        const haul = new RequestHaul(this.requestStore);
+        const { tools, getResult, isFinished, finishFromText } = createFishermanTools(this.apiClient, this.requestStore, haul, {
+            spec: this.spec,
+            baseEndpoint: this.baseEndpoint,
+            readOnly: true,
+        });
+        const conversation = this.provider.startConversation(this.buildLookupSystemPrompt(endpointList, Object.keys(tools), scopeUrl), 'fisherman');
+        conversation.addUserText(dedent `
+      Answer this question about data that already exists:
+
+      ${question}
+
+      Make the requests needed to answer it, then call finish with the answer.
+      If the available endpoints cannot answer it, call stop with the reason.
+    `);
+        await this.runSession(conversation, tools, { haul, isFinished, finishFromText, label: `fisherman lookup: ${question.slice(0, 50)}` });
+        const result = getResult();
+        tag('info').log(`Fisherman answer: ${result.summary}`);
+        return result;
+    }
+    async runSession(conversation, tools, opts) {
         await loop(async ({ stop, iteration }) => {
             debugLog(`iteration ${iteration}`);
             const invokeResult = await this.provider.invokeConversation(conversation, tools, {
@@ -77,17 +117,17 @@ export class Fisherman {
                 agentName: 'fisherman',
             });
             debugLog(`iteration ${iteration} done, text: ${invokeResult?.response?.text?.slice(0, 200) || '(none)'}`);
-            if (isFinished()) {
+            if (opts.isFinished()) {
                 stop();
                 return;
             }
             if (!invokeResult?.toolExecutions?.length) {
                 debugLog('no tool call in this turn — treating as finish');
-                finishFromText(invokeResult?.response?.text);
+                opts.finishFromText(invokeResult?.response?.text);
                 stop();
                 return;
             }
-            if (this.isStuckOnEndpoint(haul)) {
+            if (this.isStuckOnEndpoint(opts.haul)) {
                 tag('warning').log('Fisherman: repeated failures on the same endpoint — stopping');
                 stop();
                 return;
@@ -99,7 +139,7 @@ export class Fisherman {
         }, {
             maxAttempts: MAX_ITERATIONS,
             observability: {
-                name: `fisherman: ${instructions.slice(0, 50)}`,
+                name: opts.label,
                 agent: 'fisherman',
                 sessionId: this.sessionName,
             },
@@ -109,9 +149,6 @@ export class Fisherman {
                 stop();
             },
         });
-        const result = getResult();
-        tag('info').log(`Fisherman result: ${result.summary}`);
-        return result;
     }
     async detectMode(scopeUrl) {
         if (this.hasApiConfig) {
@@ -143,18 +180,20 @@ export class Fisherman {
             this.apiClient.setHeaders(this.configHeaders);
         }
     }
-    buildEndpointList(scopeUrl) {
+    buildEndpointList(scopeUrl, family = 'write') {
         this.scopeDegraded = false;
         if (this.mode === 'achieve' && this.spec) {
-            const specEndpoints = listAllEndpoints(this.spec, this.baseEndpoint);
+            let specEndpoints = listAllEndpoints(this.spec, this.baseEndpoint);
+            if (family === 'read')
+                specEndpoints = keepReadLines(specEndpoints);
             if (specEndpoints)
                 return specEndpoints;
         }
-        const scoped = this.requestStore.toEndpointList(scopeUrl || '/');
+        const scoped = this.requestStore.toEndpointList(scopeUrl || '/', family);
         if (scoped)
             return scoped;
         this.scopeDegraded = true;
-        return this.requestStore.toEndpointList();
+        return this.requestStore.toEndpointList(undefined, family);
     }
     buildSystemPrompt(endpointList, toolNames, scopeUrl) {
         let scopeBlock = '';
@@ -192,6 +231,37 @@ export class Fisherman {
       ${dataProtectionRules}
     `;
     }
+    buildLookupSystemPrompt(endpointList, toolNames, scopeUrl) {
+        let scopeBlock = '';
+        if (scopeUrl) {
+            scopeBlock = `\n\nSCOPE: You are answering about ${scopeUrl}.`;
+            if (this.scopeDegraded)
+                scopeBlock += '\nThe endpoint list could not be narrowed to this scope and may include endpoints belonging to other scopes. Prefer the endpoint whose path belongs to this scope.';
+        }
+        return dedent `
+      You are Fisherman — reading the API to report what data already exists. You change nothing.
+
+      AVAILABLE ENDPOINTS:
+      ${endpointList}
+      ${scopeBlock}
+
+      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.
+
+      WORKFLOW:
+      1. Pick the endpoint that lists the kind of item the question is about
+      2. Request it, and when the answer needs a parent resource, request the parent first and use its id
+      3. Call finish with the answer, quoting the concrete names, titles and ids the responses returned
+
+      RULES:
+      - Report only what a response actually returned. Never describe data you did not read
+      - Report an empty collection as empty. An absent item must not be reported as present
+      - Answer the question that was asked and stop. Do not survey unrelated endpoints
+      - Use the response category and error text to correct a failed request. Retry a temporary or server failure once
+    `;
+    }
     isStuckOnEndpoint(haul) {
         const made = haul.requests();
         if (made.length < REPEATED_FAILURE_LIMIT)
@@ -213,3 +283,9 @@ export class Fisherman {
     `;
     }
 }
+function keepReadLines(endpointList) {
+    return endpointList
+        .split('\n')
+        .filter((line) => line.startsWith('GET '))
+        .join('\n');
+}

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

@@ -49,7 +49,19 @@ export declare class Pilot implements Agent {
     }): Promise<string>;
     getExperienceToc(): string;
     pickPlanningTools(): Record<string, unknown>;
-    buildPreconditionTool(task: Test): {
+    fishermanStatus(): string;
+    buildFishermanTools(task: Test): {
+        askApi: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
+            question: any;
+        }, {
+            answered: boolean;
+            reason: string;
+            answer?: undefined;
+        } | {
+            answered: boolean;
+            answer: string;
+            reason?: undefined;
+        }, import("@ai-sdk/provider-utils").Context>>;
         precondition: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
             description: any;
         }, {

package/dist/src/ai/pilot.js

@@ -10,6 +10,7 @@ import { ErrorPageError } from "../utils/error-page.js";
 import { createDebug, tag } from "../utils/logger.js";
 const debugLog = createDebug('explorbot:pilot');
 import { truncateJson } from "../utils/strings.js";
+import { createAskApiTool } from "./fisherman/tools.js";
 import { capabilityGroundingRule, dataProtectionRules } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 import { withdrawVisionTools } from "./tools.js";
@@ -398,7 +399,8 @@ export class Pilot {
 
         Plan the test execution for this scenario.
 
-        FIRST: Decide if precondition() is needed.
+        FIRST: Decide if precondition() is needed. When the page does not settle whether suitable data
+        already exists, call askApi() to find out before creating any.
 
         Call precondition() WHEN:
         - The scenario edits/deletes/modifies an item, and you want a DISPOSABLE item to act on safely
@@ -603,7 +605,7 @@ export class Pilot {
                 finalUserText = `${tocBlock}\n\n${userText}`;
         }
         this.conversation.addUserText(finalUserText);
-        const tools = { ...this.pickPlanningTools(), ...this.buildPreconditionTool(opts.task) };
+        const tools = { ...this.pickPlanningTools(), ...this.buildFishermanTools(opts.task) };
         const result = await this.provider.invokeConversation(this.conversation, tools, {
             maxToolRoundtrips: opts.maxToolRoundtrips ?? 0,
             toolChoice: opts.tools ? 'auto' : 'none',
@@ -655,7 +657,12 @@ export class Pilot {
         withdrawVisionTools(planning);
         return planning;
     }
-    buildPreconditionTool(task) {
+    fishermanStatus() {
+        if (this.fisherman?.isAvailable())
+            return 'available';
+        return 'none';
+    }
+    buildFishermanTools(task) {
         const unavailable = 'Data was not created and cannot be created automatically. Do not call precondition again for this test — continue with what the page already shows.';
         return {
             precondition: tool({
@@ -666,7 +673,7 @@ export class Pilot {
                 execute: async ({ description }) => {
                     task.addNote(`Precondition: ${description}`);
                     tag('info').log(`Precondition: ${description}`);
-                    debugLog(`precondition: ${description}, fisherman: ${this.fisherman?.isAvailable() ? 'available' : 'none'}`);
+                    debugLog(`precondition: ${description}, fisherman: ${this.fishermanStatus()}`);
                     if (!this.fisherman || !this.fisherman.isAvailable()) {
                         const skipReason = await this.checkDataAvailability(task, description, 'Fisherman not available');
                         if (skipReason)
@@ -698,6 +705,7 @@ export class Pilot {
                     return { noted: true, prepared: true, created: result.created };
                 },
             }),
+            ...createAskApiTool(this.fisherman, task),
         };
     }
     async checkDataAvailability(task, requestedData, fishermanReason) {
@@ -1047,7 +1055,7 @@ export class Pilot {
       - Click SUCCESS but executed locator ≠ explanation intent, or "skipped" attempts present → wrong element clicked.
       - form(I.type()) SUCCESS but "element" shows a button/link → keys went to wrong element; click the input first.
       - ariaDiff shows 5+ added/removed → page entered new mode (editor/modal); call context() before guessing selectors.
-      - Empty dropdown/list when items expected → wait explicitly, then check the state changed: ariaDiff and any GET that loaded data. If still nothing loaded, confirm the empty state with verify().
+      - Empty dropdown/list when items expected → wait explicitly, then check the state changed: ariaDiff and any GET that loaded data. If still nothing loaded, confirm the empty state with verify(), or askApi() for whether the data exists at all.
       - Search-and-select needs SEQUENCE: focus trigger → type to filter → click option. Tell Tester to split into separate tool calls.
       - Multi-action explanation in one tool call → instruct Tester to split.
 
@@ -1063,8 +1071,13 @@ export class Pilot {
 
       ${capabilityGroundingRule}
 
-      YOUR Pilot-only tool: precondition(description) — create FRESH disposable test data via API. Never
-      request users. Use when:
+      YOUR Pilot-only tools, both over the API:
+
+      askApi(question) — ask what data already exists. It changes nothing. Use it to check whether
+      suitable data is already there before creating any, and to get the exact name or id of an existing
+      record a step must act on.
+
+      precondition(description) — create FRESH disposable test data. Never request users. Use when:
 
       - Scenario edits/deletes/modifies an item → create a disposable target ("1 post").
       - Scenario needs auxiliary data (labels, categories, statuses for filtering).

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/rules.js

@@ -163,6 +163,8 @@ export const dataProtectionRules = dedent `
   Do not use Fisherman or API data preparation to bypass a no-mutation, read-only, search,
   filter, tab, or list-inspection constraint. Use visible existing data when it is available.
   If no suitable data exists, report the missing precondition instead of creating data.
+  Reading through the API to establish what already exists is not a mutation and stays allowed
+  under a read-only constraint.
 
   Destructive actions are allowed only against data created by the current scenario
   or prepared for that scenario by Fisherman/API preconditions. Existing application data must

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/api/request-result.js

@@ -96,7 +96,9 @@ export class RequestResult {
             yaml += body;
         }
         writeFileSync(this.requestFile, yaml, 'utf8');
-        writeFileSync(this.responseFile, this._rawResponseBody || '', 'utf8');
+        if (!this._rawResponseBody)
+            return;
+        writeFileSync(this.responseFile, this._rawResponseBody, 'utf8');
     }
     static load(requestFile) {
         const content = readFileSync(requestFile, 'utf8');

package/dist/src/api/request-store.d.ts

@@ -6,8 +6,10 @@ export declare class RequestStore {
     onFailedListeners: Array<(r: RequestResult) => void>;
     outputDir: string;
     sessionStartedAt: Date;
+    readEndpointKeys: Set<string>;
     constructor(outputDir: string);
     addCapturedRequest(result: RequestResult): void;
+    addReadRequest(result: RequestResult): void;
     addFailedRequest(result: RequestResult): void;
     getFailedRequests(): RequestResult[];
     onFailedRequest(cb: (r: RequestResult) => void): () => void;
@@ -15,12 +17,15 @@ export declare class RequestStore {
     getCapturedRequests(): RequestResult[];
     getMadeRequests(): RequestResult[];
     getLastRequest(): RequestResult | undefined;
-    toEndpointList(scopePath?: string): string;
+    toEndpointList(scopePath?: string, methods?: EndpointFamily): string;
     extractAuthHeaders(): Record<string, string>;
     findCapturedRequest(method: string, searchPath: string): RequestResult | undefined;
     toLog(): string;
     loadFromDisk(): void;
     getWriteRequestsForScope(scopePath: string): RequestResult[];
+    getReadRequestsForScope(scopePath: string): RequestResult[];
     clear(): void;
+    getRequestsForScope(scopePath: string, methods: EndpointFamily): RequestResult[];
 }
 export declare function isFailedRequest(request: RequestResult): boolean;
+export type EndpointFamily = 'read' | 'write';