explorbot 0.4.2 → 0.4.4

package/docs/workflow/agentic-usage.md

@@ -58,6 +58,7 @@ No `init`, no config file, no project directory, no model IDs to look up. These
 | `EXPLORBOT_KNOWLEDGE_FILE` | no | Path to a knowledge markdown file |
 | `EXPLORBOT_SPEC` | no | Docbot application spec directory or index.md, used as page knowledge |
 | `EXPLORBOT_API_SPEC` | no | OpenAPI spec path for the API boat |
+| `EXPLORBOT_API_HEADERS` | no | Headers sent with every API request, one "Name: value" per line |
 | `EXPLORBOT_NO_BANNER` | no | Suppress the startup banner, for machine-readable output |
 | `EXPLORBOT_MAX_DURATION` | no | Wall-clock budget in minutes for an explore run; same as --max-duration |
 <!-- END env -->
@@ -66,6 +67,18 @@ No `init`, no config file, no project directory, no model IDs to look up. These
 
 This table is generated from the registry in `src/config.ts`, which also feeds `explorbot --help` — so `npx explorbot --help` lists the same variables on any command, and an agent can discover them without reading these docs.
 
+### Discovering commands
+
+An agent that has to build a command line does not have to scrape help text. `help-json` prints the whole command tree — every command with its description, aliases, arguments, options and defaults, plus the version and the variables above:
+
+```bash
+npx explorbot help-json | jq -r '.commands[] | "\(.name): \(.description)"'
+npx explorbot help-json explore | jq '.options'      # one command
+npx explorbot help-json api config                   # nested boat commands
+```
+
+It prints nothing but JSON, so the output pipes straight into `jq`. `npx explorbot config --json` does the same for the resolved configuration.
+
 ### Naming models
 
 Set `EXPLORBOT_AI_PROVIDER` to a provider name and Explorbot uses that provider's recommended model for every role — the same IDs listed in [Providers](../basics/providers.md), maintained in [`models.json`](../../models.json):
@@ -219,11 +232,12 @@ The same variables drive API testing and doc collection.
 ```bash
 EXPLORBOT_URL=https://api.example.com \
 EXPLORBOT_API_SPEC=./openapi.yaml \
+EXPLORBOT_API_HEADERS="Authorization: Bearer $TOKEN" \
 EXPLORBOT_AI_PROVIDER=openrouter \
   npx explorbot api explore /users
 ```
 
-The API boat also takes those two as flags, so one line carries the whole run: `npx explorbot api explore /users --endpoint https://api.example.com --spec ./openapi.yaml`.
+The API boat also takes those three as flags, so one line carries the whole run: `npx explorbot api explore https://api.example.com --spec ./openapi.yaml -H "Authorization: Bearer $TOKEN"`. Given a full URL, `api explore` reads it as the base endpoint; a path like `/users` needs the base in `--endpoint` or `EXPLORBOT_URL`.
 
 ```bash
 EXPLORBOT_AI_PROVIDER=openrouter \

package/package.json

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

package/src/action-result.ts

@@ -33,6 +33,7 @@ interface ActionResultData extends WebPageState {
   iframeSnapshots?: Array<{ src: string; html: string; id?: string }>;
   ariaSnapshot?: string | null;
   ariaSnapshotFile?: string;
+  regionAria?: string | null;
   focusedElement?: FocusedElement | null;
   iframeURL?: string;
   links?: Link[];
@@ -90,6 +91,7 @@ export class ActionResult implements ActionResultData {
   public links: Link[] = [];
   public verifications?: Record<string, boolean>;
   public overlay: Region = new Region();
+  public regionAria: string | null = null;
   private _diffCache: { previousId: number | undefined; diff: Diff } | null = null;
 
   constructor(data: ActionResultData) {
@@ -106,6 +108,7 @@ export class ActionResult implements ActionResultData {
     this.iframeURL = data.iframeURL;
     this.notes = data.notes ?? [];
     this.verifications = data.verifications;
+    this.regionAria = data.regionAria ?? null;
 
     // Set readonly properties
     if (data.screenshotFile !== undefined) {
@@ -304,6 +307,10 @@ export class ActionResult implements ActionResultData {
     return compactAriaSnapshot(this.ariaSnapshot, false);
   }
 
+  getRegionARIA(): string {
+    return compactAriaSnapshot(this.regionAria, false);
+  }
+
   getCompactARIA(): string {
     return compactAriaSnapshot(this.ariaSnapshot, true);
   }

package/src/action.ts

@@ -14,8 +14,8 @@ import { browserErrorMessage, isFatalBrowserError, isNavigationTransitionError }
 import { captureHtmlForSnapshot, htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
 import { Overlay, OverlayPage } from './utils/overlay.js';
-import type { Region } from './utils/region.js';
 import { sleep, waitForPageReadiness } from './utils/page-readiness.ts';
+import type { Region } from './utils/region.js';
 import { safeFilename } from './utils/strings.ts';
 import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from './utils/web-sandbox.ts';
 
@@ -182,7 +182,19 @@ class Action {
         focusedElement,
         iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
       });
-      if (!frame) await this.detectRegion(result).catch((err: Error) => debugLog('Region detection failed:', err.message));
+      if (!frame) {
+        await this.detectRegion(result).catch((err: Error) => 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: Error) => {
+              debugLog('Region ARIA snapshot failed:', err.message);
+              return null;
+            });
+        }
+      }
       this.stateManager.updateState(result, codeBlock);
       return result;
     } catch (err) {

package/src/ai/fisherman/request-haul.ts

@@ -20,6 +20,10 @@ export class RequestHaul {
     return this.requests().filter((r) => r.isWrite && !r.error && r.status >= 200 && r.status < 400);
   }
 
+  successfulReads(): RequestResult[] {
+    return this.requests().filter((r) => !r.isWrite && !r.error && r.status >= 200 && r.status < 400);
+  }
+
   byId(): Map<string, RequestResult> {
     const map = new Map<string, RequestResult>();
     for (const request of this.successfulWrites()) {

package/src/ai/{fisherman-tools.ts → fisherman/tools.ts}

@@ -1,28 +1,36 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import type { ApiClient } from '../api/api-client.ts';
-import type { RequestResult } from '../api/request-result.ts';
-import type { RequestStore } from '../api/request-store.ts';
-import { extractEndpointDefinition } from '../api/spec-reader.ts';
-import { tag } from '../utils/logger.ts';
-import { isDynamicSegment } from '../utils/url-matcher.ts';
-import type { RequestHaul } from './fisherman/request-haul.ts';
-
-export function createFishermanTools(apiClient: ApiClient, requestStore: RequestStore, haul: RequestHaul, opts: { spec?: any; baseEndpoint?: string }) {
+import type { ApiClient } from '../../api/api-client.ts';
+import type { RequestResult } from '../../api/request-result.ts';
+import type { RequestStore } from '../../api/request-store.ts';
+import { extractEndpointDefinition } from '../../api/spec-reader.ts';
+import type { Test } from '../../test-plan.ts';
+import { tag } from '../../utils/logger.ts';
+import { isDynamicSegment } from '../../utils/url-matcher.ts';
+import type { Fisherman } from '../fisherman.ts';
+import type { RequestHaul } from './request-haul.ts';
+
+const BODY_PREVIEW_LIMIT = 2000;
+
+export function createFishermanTools(apiClient: ApiClient, requestStore: RequestStore, haul: RequestHaul, opts: { spec?: any; baseEndpoint?: string; readOnly?: boolean }) {
+  const readOnly = opts.readOnly === true;
   let finished = false;
   let result: FishermanResult | null = null;
 
-  const getResult = () => result ?? synthesizeResult(haul, false);
+  let allowedMethods: string[] = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+  if (readOnly) allowedMethods = ['GET'];
+
+  const getResult = () => result ?? synthesizeResult(haul, false, readOnly);
   const isFinished = () => finished;
   const finishFromText = (text?: string) => {
     finished = true;
-    const synthesized = synthesizeResult(haul, true);
+    const synthesized = synthesizeResult(haul, true, readOnly);
     if (text && synthesized.success) synthesized.summary = text;
     result = synthesized;
   };
 
-  const tools = {
+  const tools: Record<string, any> = {
     getEndpointSpec: tool({
       description: dedent`
         Get the request specification for an endpoint.
@@ -30,13 +38,14 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
         Call this before making a request to an endpoint you haven't used before.
       `,
       inputSchema: z.object({
-        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
+        method: z.enum(allowedMethods as [string, ...string[]]).describe('HTTP method'),
         path: z.string().describe('Endpoint path, e.g. /suites'),
       }),
       execute: async ({ method, path }) => {
         tag('step').log(`Fisherman: spec lookup ${method} ${path}`);
 
-        const captured = requestStore.findCapturedRequest(method, path);
+        let captured = requestStore.findCapturedRequest(method, path);
+        if (captured && !captured.requestBody && opts.spec && captured.status < 400) captured = undefined;
         if (captured) {
           if (captured.status >= 400) {
             const rejectedCapture = {
@@ -88,7 +97,7 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
         Returns status, plus IDs and names auto-extracted from the response under 'extracted'.
       `,
       inputSchema: z.object({
-        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).describe('HTTP method'),
+        method: z.enum(allowedMethods as [string, ...string[]]).describe('HTTP method'),
         path: z.string().describe('API path (e.g., /suites, /suites/1)'),
         body: z.any().optional().describe('Request body (JSON object)'),
         queryParams: z.record(z.string(), z.string()).optional().describe('Query parameters'),
@@ -125,11 +134,13 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
 
         const extracted = extractKeyFields(reqResult.responseBody);
         tag('success').log(`Fisherman: ${input.method} ${input.path} > ${statusLine}`);
-        return {
+        const output: Record<string, any> = {
           success: true,
           status: reqResult.status,
           extracted,
         };
+        if (readOnly) output.bodyPreview = reqResult.rawResponseBody.substring(0, BODY_PREVIEW_LIMIT);
+        return output;
       },
     }),
 
@@ -181,9 +192,63 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
     }),
   };
 
+  if (readOnly) {
+    tools.finish = tool({
+      description: 'Report the answer to the question. Call when the requests have shown what exists.',
+      inputSchema: z.object({
+        answer: z.string().describe('What the data shows, quoting the concrete names, titles and ids that were returned'),
+      }),
+      execute: async ({ answer }) => {
+        if (haul.successfulReads().length === 0) {
+          tag('warning').log('Fisherman: finish rejected — no successful request in this run');
+          return { finished: false, error: 'No successful request was made in this run, so nothing was read. Keep working, or call stop if the question cannot be answered.' };
+        }
+
+        tag('success').log(`Fisherman answered: ${answer}`);
+        finished = true;
+        result = { success: true, summary: answer, created: [], failed: [] };
+        return { finished: true };
+      },
+    });
+  }
+
   return { tools, getResult, isFinished, finishFromText };
 }
 
+export function createAskApiTool(fisherman: Fisherman | null, task: Test) {
+  return {
+    askApi: tool({
+      description: dedent`
+        Ask what data already exists, changing nothing.
+        Ask a question about existing records: which ones are there, what they are called, whether a particular one exists.
+        Use it before precondition() to see whether suitable data is already available, and whenever a step needs the exact name or id of a record that is already there.
+        It never creates, edits or deletes anything — precondition() does that.
+      `,
+      inputSchema: z.object({
+        question: z.string().describe('What to find out about data that already exists'),
+      }),
+      execute: async ({ question }) => {
+        tag('info').log(`Ask API: ${question}`);
+
+        if (!fisherman?.isAvailable()) {
+          return { answered: false, reason: 'No API access is configured, so existing data cannot be queried. Judge from the page instead.' };
+        }
+
+        const result = await fisherman.lookupData(question, task.startUrl, task.sessionName);
+
+        if (!result.success) {
+          tag('warning').log(`Ask API unanswered: ${result.summary}`);
+          return { answered: false, reason: result.summary || 'The API could not answer this question' };
+        }
+
+        task.addNote(`Asked API: ${question} — ${result.summary}`);
+        tag('success').log(`Ask API: ${result.summary}`);
+        return { answered: true, answer: result.summary };
+      },
+    }),
+  };
+}
+
 export function verifyFinish(haul: RequestHaul, input: { summary: string; created: FishermanResult['created']; failed?: FishermanResult['failed'] }): { result: FishermanResult | null; error?: string } {
   const writes = haul.successfulWrites();
   if (writes.length === 0) {
@@ -211,14 +276,22 @@ export function verifyFinish(haul: RequestHaul, input: { summary: string; create
   return { result: { success: true, summary: input.summary, created: verified, failed: input.failed || [] } };
 }
 
-function synthesizeResult(haul: RequestHaul, declaredDone: boolean): FishermanResult {
+function synthesizeResult(haul: RequestHaul, declaredDone: boolean, readOnly: boolean): FishermanResult {
   const made = haul.requests();
-  const writes = haul.successfulWrites();
   const failures = haul.failed();
-  let summary = `Stopped before finishing: ${made.length} requests, ${writes.length} successful writes, ${failures.length} failed`;
+  let succeeded = haul.successfulWrites();
+  let successLabel = 'successful writes';
+  if (readOnly) {
+    succeeded = haul.successfulReads();
+    successLabel = 'successful reads';
+  }
+  let summary = `Stopped before finishing: ${made.length} requests, ${succeeded.length} ${successLabel}, ${failures.length} failed`;
   const lastFailure = failures[failures.length - 1];
   if (lastFailure) summary += `; last failure: ${lastFailure.toSummary()}`;
-  return { success: declaredDone && writes.length > 0, summary, created: writes.map(toCreatedItem), failed: [] };
+
+  const result: FishermanResult = { success: declaredDone && succeeded.length > 0, summary, created: [], failed: [] };
+  if (!readOnly) result.created = succeeded.map(toCreatedItem);
+  return result;
 }
 
 function toCreatedItem(write: RequestResult): FishermanResult['created'][number] {

package/src/ai/fisherman.ts

@@ -1,14 +1,15 @@
 import dedent from 'dedent';
 import type { ApiClient } from '../api/api-client.ts';
-import { type RequestStore, isFailedRequest } from '../api/request-store.ts';
+import { type EndpointFamily, type RequestStore, isFailedRequest } from '../api/request-store.ts';
 import { listAllEndpoints } from '../api/spec-reader.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 
 const debugLog = createDebug('explorbot:fisherman');
 import { loop } from '../utils/loop.ts';
 import type { Agent } from './agent.ts';
-import { type FishermanResult, createFishermanTools } from './fisherman-tools.ts';
+import type { Conversation } from './conversation.ts';
 import { RequestHaul } from './fisherman/request-haul.ts';
+import { type FishermanResult, createFishermanTools } from './fisherman/tools.ts';
 import type { Provider } from './provider.ts';
 import { dataProtectionRules } from './rules.ts';
 
@@ -73,7 +74,6 @@ export class Fisherman implements Agent {
 
     if (!endpointList) {
       tag('warning').log('Fisherman: no endpoints available');
-      this.mode = 'disabled';
       return { success: false, summary: 'No API endpoints available', created: [], failed: [] };
     }
 
@@ -89,6 +89,59 @@ export class Fisherman implements Agent {
     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: string, scopeUrl?: string, sessionName?: string): Promise<FishermanResult> {
+    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;
+  }
+
+  private async runSession(conversation: Conversation, tools: Record<string, any>, opts: { haul: RequestHaul; isFinished: () => boolean; finishFromText: (text?: string) => void; label: string }): Promise<void> {
     await loop(
       async ({ stop, iteration }) => {
         debugLog(`iteration ${iteration}`);
@@ -98,19 +151,19 @@ export class Fisherman implements Agent {
         });
         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;
@@ -124,7 +177,7 @@ export class Fisherman implements Agent {
       {
         maxAttempts: MAX_ITERATIONS,
         observability: {
-          name: `fisherman: ${instructions.slice(0, 50)}`,
+          name: opts.label,
           agent: 'fisherman',
           sessionId: this.sessionName,
         },
@@ -135,10 +188,6 @@ export class Fisherman implements Agent {
         },
       }
     );
-
-    const result = getResult();
-    tag('info').log(`Fisherman result: ${result.summary}`);
-    return result;
   }
 
   private async detectMode(scopeUrl?: string): Promise<void> {
@@ -178,18 +227,19 @@ export class Fisherman implements Agent {
     }
   }
 
-  private buildEndpointList(scopeUrl?: string): string {
+  private buildEndpointList(scopeUrl?: string, family: EndpointFamily = 'write'): string {
     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);
   }
 
   private buildSystemPrompt(endpointList: string, toolNames: string[], scopeUrl?: string): string {
@@ -229,6 +279,38 @@ export class Fisherman implements Agent {
     `;
   }
 
+  private buildLookupSystemPrompt(endpointList: string, toolNames: string[], scopeUrl?: string): string {
+    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
+    `;
+  }
+
   private isStuckOnEndpoint(haul: RequestHaul): boolean {
     const made = haul.requests();
     if (made.length < REPEATED_FAILURE_LIMIT) return false;
@@ -250,3 +332,10 @@ export class Fisherman implements Agent {
     `;
   }
 }
+
+function keepReadLines(endpointList: string): string {
+  return endpointList
+    .split('\n')
+    .filter((line) => line.startsWith('GET '))
+    .join('\n');
+}

package/src/ai/pilot.ts

@@ -18,6 +18,7 @@ import { truncateJson } from '../utils/strings.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import type { Conversation } from './conversation.ts';
 import type { Fisherman } from './fisherman.ts';
+import { createAskApiTool } from './fisherman/tools.ts';
 import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import type { Researcher } from './researcher.ts';
@@ -452,7 +453,8 @@ export class Pilot implements Agent {
 
         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
@@ -688,7 +690,7 @@ export class Pilot implements Agent {
     }
     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,
@@ -734,7 +736,12 @@ export class Pilot implements Agent {
     return planning;
   }
 
-  private buildPreconditionTool(task: Test) {
+  private fishermanStatus(): string {
+    if (this.fisherman?.isAvailable()) return 'available';
+    return 'none';
+  }
+
+  private buildFishermanTools(task: Test) {
     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({
@@ -745,7 +752,7 @@ export class Pilot implements Agent {
         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');
@@ -776,6 +783,7 @@ export class Pilot implements Agent {
           return { noted: true, prepared: true, created: result.created };
         },
       }),
+      ...createAskApiTool(this.fisherman, task),
     };
   }
 
@@ -1152,7 +1160,7 @@ export class Pilot implements Agent {
       - 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.
 
@@ -1168,8 +1176,13 @@ export class Pilot implements Agent {
 
       ${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/src/ai/researcher/deep-analysis.ts

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 import { ActionResult, type Diff } from '../../action-result.js';
-import type { ExplorbotConfig } from '../../config.ts';
+import { type ExplorbotConfig, agentSettings } from '../../config.ts';
 import { executionController } from '../../execution-controller.ts';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
@@ -31,7 +31,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       tag('info').log('Starting deep analysis of expandable elements');
       await (this as any).navigateTo(state.fullUrl || state.url);
 
-      const maxClicks = (this.config.ai?.agents?.researcher as any)?.maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
+      const maxClicks = agentSettings(this.config, 'researcher').maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
 
       const expandedSections: string[] = [];
       const navigationLinks: Array<{ code: string; url: string }> = [];
@@ -88,6 +88,8 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     }
 
     async researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null> {
+      if (!(this as any).isEnabled()) return null;
+
       const region = current.overlay;
       if (!region.isOpen || !region.name) return null;
 

package/src/ai/researcher/sections.ts

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../../action-result.js';
-import type { ExplorbotConfig } from '../../config.ts';
+import { type ExplorbotConfig, agentSettings } from '../../config.ts';
 import { executionController } from '../../execution-controller.ts';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
@@ -66,7 +66,7 @@ export function WithSections<T extends Constructor>(Base: T) {
     }
 
     private async _detectFocusCss(): Promise<string | null> {
-      const focusSections = (this.config.ai?.agents?.researcher as any)?.focusSections as string[] | undefined;
+      const focusSections = agentSettings(this.config, 'researcher').focusSections;
       if (!focusSections?.length) return null;
 
       for (const css of focusSections) {