explorbot 0.4.2 → 0.4.3

package/bin/explorbot-cli.ts

@@ -8,6 +8,7 @@ import figureSet from 'figures';
 import { render } from 'ink';
 import React from 'react';
 import { flushTelemetry } from '../src/ai/provider.js';
+import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
@@ -43,7 +44,9 @@ process.on('unhandledRejection', (reason) => {
   tag('error').log(`Unhandled rejection: ${reason instanceof Error ? `${reason.message}\n${reason.stack}` : String(reason)}`);
 });
 
-if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
+const printsJson = process.argv.includes('--json') || process.argv.includes('help-json');
+
+if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima') && !printsJson) {
   console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 
@@ -952,6 +955,8 @@ ${rows}
 `;
 };
 
+program.addHelpText('after', `\nFor agents and tools:\n  ${cli} help-json [command...]  the same definitions as JSON — commands, arguments, options, defaults\n`);
 program.addHelpText('after', envHelp);
+HelpJsonCommand.register(program);
 
 program.parse();

package/dist/bin/explorbot-cli.js

@@ -8,6 +8,7 @@ import figureSet from 'figures';
 import { render } from 'ink';
 import React from 'react';
 import { flushTelemetry } from '../src/ai/provider.js';
+import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
@@ -37,7 +38,8 @@ process.on('uncaughtException', async (error) => {
 process.on('unhandledRejection', (reason) => {
     tag('error').log(`Unhandled rejection: ${reason instanceof Error ? `${reason.message}\n${reason.stack}` : String(reason)}`);
 });
-if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
+const printsJson = process.argv.includes('--json') || process.argv.includes('help-json');
+if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima') && !printsJson) {
     console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 function buildExplorBotOptions(from, options) {
@@ -867,5 +869,7 @@ ${rows}
       ${cli} explore /login --max-tests 3
 `;
 };
+program.addHelpText('after', `\nFor agents and tools:\n  ${cli} help-json [command...]  the same definitions as JSON — commands, arguments, options, defaults\n`);
 program.addHelpText('after', envHelp);
+HelpJsonCommand.register(program);
 program.parse();

package/dist/package.json

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

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

@@ -7,5 +7,6 @@ export declare class RequestHaul {
     requests(): RequestResult[];
     failed(): RequestResult[];
     successfulWrites(): RequestResult[];
+    successfulReads(): RequestResult[];
     byId(): Map<string, RequestResult>;
 }

package/dist/src/ai/fisherman/request-haul.js

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

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,17 +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 { isDynamicSegment } from "../utils/url-matcher.js";
+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 getResult = () => result ?? synthesizeResult(haul, 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(haul, true);
+        const synthesized = synthesizeResult(haul, true, readOnly);
         if (text && synthesized.success)
             synthesized.summary = text;
         result = synthesized;
@@ -24,12 +29,14 @@ export function createFishermanTools(apiClient, requestStore, haul, 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 = {
@@ -80,7 +87,7 @@ export function createFishermanTools(apiClient, requestStore, haul, 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'),
@@ -111,11 +118,14 @@ export function createFishermanTools(apiClient, requestStore, haul, 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({
@@ -160,8 +170,55 @@ export function createFishermanTools(apiClient, requestStore, haul, 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 };
 }
+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) {
@@ -186,15 +243,23 @@ export function verifyFinish(haul, input) {
         verified.push(...writes.map(toCreatedItem));
     return { result: { success: true, summary: input.summary, created: verified, failed: input.failed || [] } };
 }
-function synthesizeResult(haul, declaredDone) {
+function synthesizeResult(haul, declaredDone, readOnly) {
     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 = { 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,8 +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;
@@ -23,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;
+    buildLookupSystemPrompt(endpointList: string, toolNames: string[], scopeUrl?: string): string;
     isStuckOnEndpoint(haul: RequestHaul): boolean;
     buildTaskPrompt(instructions: string): string;
 }

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/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/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';