explorbot 0.4.1 → 0.4.3

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

@@ -0,0 +1,50 @@
+import type { ApiClient } from '../../api/api-client.js';
+import type { RequestStore } from '../../api/request-store.js';
+import type { Test } from '../../test-plan.js';
+import type { Fisherman } from '../fisherman.js';
+import type { RequestHaul } from './request-haul.js';
+export declare function createFishermanTools(apiClient: ApiClient, requestStore: RequestStore, haul: RequestHaul, opts: {
+    spec?: any;
+    baseEndpoint?: string;
+    readOnly?: boolean;
+}): {
+    tools: Record<string, any>;
+    getResult: () => FishermanResult;
+    isFinished: () => boolean;
+    finishFromText: (text?: string) => void;
+};
+export declare function createAskApiTool(fisherman: Fisherman | null, 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>>;
+};
+export declare function verifyFinish(haul: RequestHaul, input: {
+    summary: string;
+    created: FishermanResult['created'];
+    failed?: FishermanResult['failed'];
+}): {
+    result: FishermanResult | null;
+    error?: string;
+};
+export interface FishermanResult {
+    success: boolean;
+    summary: string;
+    created: Array<{
+        type: string;
+        id?: string | number;
+        title?: string;
+        request?: string;
+    }>;
+    failed: Array<{
+        type: string;
+        reason: string;
+    }>;
+}

package/dist/src/ai/{fisherman-tools.js → fisherman/tools.js}

@@ -1,21 +1,22 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import { extractEndpointDefinition } from "../api/spec-reader.js";
-import { tag } from "../utils/logger.js";
-import { RequestMap } from "../utils/request-map.js";
-import { isDynamicSegment } from "../utils/url-matcher.js";
-export function createFishermanTools(apiClient, requestStore, opts) {
+import { extractEndpointDefinition } from "../../api/spec-reader.js";
+import { tag } from "../../utils/logger.js";
+import { isDynamicSegment } from "../../utils/url-matcher.js";
+const BODY_PREVIEW_LIMIT = 2000;
+export function createFishermanTools(apiClient, requestStore, haul, opts) {
+    const readOnly = opts.readOnly === true;
     let finished = false;
     let result = null;
-    const ledgerStart = requestStore.getMadeRequests().length;
-    const runRequests = () => requestStore.getMadeRequests().slice(ledgerStart);
-    const successfulWrites = () => runRequests().filter((r) => r.isWrite && !r.error && r.status >= 200 && r.status < 400);
-    const getResult = () => result ?? synthesizeResult(runRequests(), successfulWrites(), false);
+    let allowedMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+    if (readOnly)
+        allowedMethods = ['GET'];
+    const getResult = () => result ?? synthesizeResult(haul, false, readOnly);
     const isFinished = () => finished;
     const finishFromText = (text) => {
         finished = true;
-        const synthesized = synthesizeResult(runRequests(), successfulWrites(), true);
+        const synthesized = synthesizeResult(haul, true, readOnly);
         if (text && synthesized.success)
             synthesized.summary = text;
         result = synthesized;
@@ -28,12 +29,14 @@ export function createFishermanTools(apiClient, requestStore, opts) {
         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).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 = {
@@ -84,7 +87,7 @@ export function createFishermanTools(apiClient, requestStore, opts) {
         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).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'),
@@ -115,11 +118,14 @@ export function createFishermanTools(apiClient, requestStore, opts) {
                 }
                 const extracted = extractKeyFields(reqResult.responseBody);
                 tag('success').log(`Fisherman: ${input.method} ${input.path} > ${statusLine}`);
-                return {
+                const output = {
                     success: true,
                     status: reqResult.status,
                     extracted,
                 };
+                if (readOnly)
+                    output.bodyPreview = reqResult.rawResponseBody.substring(0, BODY_PREVIEW_LIMIT);
+                return output;
             },
         }),
         finish: tool({
@@ -142,30 +148,12 @@ export function createFishermanTools(apiClient, requestStore, opts) {
                     .describe('List of items that could not be created'),
             }),
             execute: async ({ summary, created, failed }) => {
-                const writes = successfulWrites();
-                if (writes.length === 0) {
-                    tag('warning').log('Fisherman: finish rejected — no successful write request in this run');
-                    return { finished: false, error: 'No successful write request was made in this run, so nothing was created. Keep working, or call stop if the data cannot be prepared.' };
-                }
-                const createdRequests = new RequestMap(writes);
-                const verified = [];
-                for (const item of created) {
-                    if (item.id === undefined) {
-                        verified.push(item);
-                        continue;
-                    }
-                    const request = createdRequests.get(item.id);
-                    if (!request) {
-                        tag('warning').log(`Fisherman: dropped unverified created item ${item.type} (id: ${item.id})`);
-                        continue;
-                    }
-                    verified.push({ ...item, request: request.toEndpoint() });
-                }
-                if (verified.length === 0)
-                    verified.push(...writes.map(toCreatedItem));
+                const { result: verified, error } = verifyFinish(haul, { summary, created, failed });
+                if (!verified)
+                    return { finished: false, error };
                 tag('success').log(`Fisherman done: ${summary}`);
                 finished = true;
-                result = { success: true, summary, created: verified, failed: failed || [] };
+                result = verified;
                 return { finished: true };
             },
         }),
@@ -182,15 +170,96 @@ export function createFishermanTools(apiClient, requestStore, opts) {
             },
         }),
     };
+    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 };
 }
-function synthesizeResult(made, writes, declaredDone) {
-    const failures = made.filter((r) => r.status >= 400 || r.error);
-    let summary = `Stopped before finishing: ${made.length} requests, ${writes.length} successful writes, ${failures.length} failed`;
+export function createAskApiTool(fisherman, task) {
+    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, input) {
+    const writes = haul.successfulWrites();
+    if (writes.length === 0) {
+        tag('warning').log('Fisherman: finish rejected — no successful write request in this run');
+        return { result: null, error: 'No successful write request was made in this run, so nothing was created. Keep working, or call stop if the data cannot be prepared.' };
+    }
+    const createdRequests = haul.byId();
+    const verified = [];
+    for (const item of input.created) {
+        if (item.id === undefined) {
+            verified.push(item);
+            continue;
+        }
+        const request = createdRequests.get(String(item.id));
+        if (!request) {
+            tag('warning').log(`Fisherman: dropped unverified created item ${item.type} (id: ${item.id})`);
+            continue;
+        }
+        verified.push({ ...item, request: request.toEndpoint() });
+    }
+    if (verified.length === 0)
+        verified.push(...writes.map(toCreatedItem));
+    return { result: { success: true, summary: input.summary, created: verified, failed: input.failed || [] } };
+}
+function synthesizeResult(haul, declaredDone, readOnly) {
+    const made = haul.requests();
+    const failures = haul.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 = { success: declaredDone && succeeded.length > 0, summary, created: [], failed: [] };
+    if (!readOnly)
+        result.created = succeeded.map(toCreatedItem);
+    return result;
 }
 function toCreatedItem(write) {
     const { id, title } = write.extractIdAndTitle();

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

@@ -1,7 +1,9 @@
 import type { ApiClient } from '../api/api-client.js';
-import type { RequestStore } from '../api/request-store.js';
+import { type EndpointFamily, type RequestStore } from '../api/request-store.js';
 import type { Agent } from './agent.js';
-import { type FishermanResult } from './fisherman-tools.js';
+import type { Conversation } from './conversation.js';
+import { RequestHaul } from './fisherman/request-haul.js';
+import { type FishermanResult } from './fisherman/tools.js';
 import type { Provider } from './provider.js';
 export declare class Fisherman implements Agent {
     emoji: string;
@@ -22,10 +24,18 @@ export declare class Fisherman implements Agent {
     ensureReady(scopeUrl?: string): Promise<void>;
     getEndpointList(scopeUrl?: string): string;
     prepareData(instructions: string, scopeUrl?: string, sessionName?: string): Promise<FishermanResult>;
+    lookupData(question: string, scopeUrl?: string, sessionName?: string): Promise<FishermanResult>;
+    runSession(conversation: Conversation, tools: Record<string, any>, opts: {
+        haul: RequestHaul;
+        isFinished: () => boolean;
+        finishFromText: (text?: string) => void;
+        label: string;
+    }): Promise<void>;
     detectMode(scopeUrl?: string): Promise<void>;
     refreshAuth(): Promise<void>;
-    buildEndpointList(scopeUrl?: string): string;
+    buildEndpointList(scopeUrl?: string, family?: EndpointFamily): string;
     buildSystemPrompt(endpointList: string, toolNames: string[], scopeUrl?: string): string;
-    isStuckOnEndpoint(ledgerStart: number): boolean;
+    buildLookupSystemPrompt(endpointList: string, toolNames: string[], scopeUrl?: string): string;
+    isStuckOnEndpoint(haul: RequestHaul): boolean;
     buildTaskPrompt(instructions: string): string;
 }

package/dist/src/ai/fisherman.js

@@ -1,9 +1,11 @@
 import dedent from 'dedent';
+import { isFailedRequest } from "../api/request-store.js";
 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;
@@ -56,18 +58,58 @@ 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();
         debugLog(`auth headers: ${Object.keys(this.apiClient.getHeaders()).join(', ')}`);
-        const { tools, getResult, isFinished, finishFromText } = createFishermanTools(this.apiClient, this.requestStore, {
+        const haul = new RequestHaul(this.requestStore);
+        const { tools, getResult, isFinished, finishFromText } = createFishermanTools(this.apiClient, this.requestStore, haul, {
             spec: this.spec,
             baseEndpoint: this.baseEndpoint,
         });
-        const ledgerStart = this.requestStore.getMadeRequests().length;
         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, {
@@ -75,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(ledgerStart)) {
+            if (this.isStuckOnEndpoint(opts.haul)) {
                 tag('warning').log('Fisherman: repeated failures on the same endpoint — stopping');
                 stop();
                 return;
@@ -97,7 +139,7 @@ export class Fisherman {
         }, {
             maxAttempts: MAX_ITERATIONS,
             observability: {
-                name: `fisherman: ${instructions.slice(0, 50)}`,
+                name: opts.label,
                 agent: 'fisherman',
                 sessionId: this.sessionName,
             },
@@ -107,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) {
@@ -141,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 = '';
@@ -190,13 +231,44 @@ export class Fisherman {
       ${dataProtectionRules}
     `;
     }
-    isStuckOnEndpoint(ledgerStart) {
-        const made = this.requestStore.getMadeRequests().slice(ledgerStart);
+    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)
             return false;
         const recent = made.slice(-REPEATED_FAILURE_LIMIT);
         const first = recent[0];
-        return recent.every((r) => (r.status >= 400 || r.error) && r.method === first.method && r.path === first.path);
+        return recent.every((r) => isFailedRequest(r) && r.method === first.method && r.path === first.path);
     }
     buildTaskPrompt(instructions) {
         return dedent `
@@ -211,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";
@@ -19,6 +20,7 @@ const META_TOOLS = ['record', 'reset', 'stop', 'finish'];
 const PILOT_REASONING_LIMIT = 500;
 const PILOT_MESSAGE_LIMIT = 2;
 const PILOT_MESSAGE_MAX_LENGTH = 160;
+const PILOT_REQUEST_LIMIT = 5;
 export class Pilot {
     emoji = '🧭';
     provider;
@@ -397,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
@@ -602,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',
@@ -654,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({
@@ -665,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)
@@ -697,6 +705,7 @@ export class Pilot {
                     return { noted: true, prepared: true, created: result.created };
                 },
             }),
+            ...createAskApiTool(this.fisherman, task),
         };
     }
     async checkDataAvailability(task, requestedData, fishermanReason) {
@@ -741,21 +750,21 @@ export class Pilot {
         lines.push(`h2: ${state.h2 || ''}`);
         lines.push(`h3: ${state.h3 || ''}`);
         lines.push(`h4: ${state.h4 || ''}`);
-        const focusArea = state.overlay;
-        if (focusArea.detected) {
-            let line = `modal: ${focusArea.name || focusArea.type}`;
-            if (focusArea.root)
-                line += ` (root: ${focusArea.root})`;
+        const region = state.overlay;
+        if (region.isModal) {
+            let line = `overlay: ${region.name || region.type}`;
+            if (region.root)
+                line += ` (root: ${region.root})`;
             lines.push(line);
         }
-        else if (focusArea.present) {
-            let line = `region: ${focusArea.name || 'unnamed'} (inline`;
-            if (focusArea.root)
-                line += `, root: ${focusArea.root}`;
+        else if (region.isOpen) {
+            let line = `region: ${region.name || 'unnamed'} (inline`;
+            if (region.root)
+                line += `, root: ${region.root}`;
             lines.push(`${line})`);
         }
         else {
-            lines.push('modal: none');
+            lines.push('overlay: none');
         }
         const tabs = this.stateManager.otherTabs;
         if (tabs.length > 0) {
@@ -971,9 +980,13 @@ export class Pilot {
                 line += `\n   ${ariaDiff}`;
             if (t.output?.pageDiff?.urlChanged)
                 line += `\n   moved: ${t.output.pageDiff.previousUrl} → ${t.output.pageDiff.currentUrl}`;
-            const failedRequests = (t.output?.pageDiff?.requests ?? []).filter((r) => r.status >= 400);
-            if (failedRequests.length > 0) {
-                line += `\n   requests: ${failedRequests.map((r) => `${r.method} ${r.path} → ${r.status}`).join(', ')}`;
+            const pageRequests = t.output?.pageDiff?.requests ?? [];
+            const requests = pageRequests
+                .filter((r) => r.status >= 400)
+                .concat(pageRequests.filter((r) => r.status < 400))
+                .slice(0, PILOT_REQUEST_LIMIT);
+            if (requests.length > 0) {
+                line += `\n   requests: ${requests.map((r) => `${r.method} ${r.path} → ${r.status}`).join(', ')}`;
             }
             const messages = (t.output?.pageDiff?.messages ?? []).slice(0, PILOT_MESSAGE_LIMIT);
             if (messages.length > 0) {
@@ -1034,15 +1047,15 @@ export class Pilot {
 
       Diagnostic patterns (use <state>, executed/element/skipped fields, ariaDiff):
       - Click failed + button in "disabled buttons" → required field missing. Instruct fill first.
-      - "modal: none" but Tester targets a modal → modal closed; re-trigger.
+      - "overlay: none" but Tester targets an overlay → overlay closed; re-trigger.
       - "region:" in <state> → a large area appeared in place without navigation (subview, wizard step, panel). Direct Tester to act inside it; the rest of the page is still usable.
       - Action SUCCESS but ariaDiff empty → may have worked without visible DOM change; check result message.
-      - MultipleElementsFound → xpathCheck() to identify the right one, then precise locator or visualClick().
+      - MultipleElementsFound → nothing was clicked. Tell Tester to reuse the same locator with step.opts({ elementIndex: N }) from the numbered elements list.
       - Wrong page (settings vs feature) → getVisitedStates() then back() or reset(). Don't try breadcrumbs (SPA back-nav is unreliable).
       - 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 → missing data; call precondition() to create it.
+      - 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.
 
@@ -1058,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).