explorbot 0.4.1 → 0.4.3

package/dist/src/ai/provider.js

@@ -10,6 +10,7 @@ import { configuredModels, modelName as getModelName } from '../config.js';
 import { executionController } from "../execution-controller.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
+import { getCliName } from '../utils/cli-name.js';
 import { createDebug, tag } from '../utils/logger.js';
 import { withRetry } from '../utils/retry.js';
 import { RulesLoader } from "../utils/rules-loader.js";
@@ -43,14 +44,7 @@ export async function flushTelemetry() {
 }
 const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
 function extractCachedTokens(usage) {
-    if (!usage)
-        return 0;
-    const direct = usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens;
-    if (typeof direct === 'number')
-        return direct;
-    const raw = usage.raw;
-    const fromRaw = raw?.prompt_tokens_details?.cached_tokens ?? raw?.promptTokensDetails?.cachedTokens;
-    return typeof fromRaw === 'number' ? fromRaw : 0;
+    return usage?.inputTokenDetails?.cacheReadTokens ?? 0;
 }
 function abortAfterIdle(ms, cancel, controller) {
     return new Promise((_, reject) => {
@@ -99,7 +93,7 @@ export class Provider {
     modelCallWaiters = [];
     constructor(config) {
         if (!config?.model) {
-            throw new AiError('AI model is not configured. Set ai.model in your config file.');
+            throw new AiError(`AI model is not configured. Set ai.model in your config file, or pick one with ${getCliName()} recommended-models`);
         }
         this.config = config;
         this.initLangfuse();
@@ -226,8 +220,8 @@ export class Provider {
         if (!usage)
             return;
         Stats.recordTokens(agentName, modelName, {
-            input: usage.inputTokens ?? usage.promptTokens ?? 0,
-            output: usage.outputTokens ?? usage.completionTokens ?? 0,
+            input: usage.inputTokens ?? 0,
+            output: usage.outputTokens ?? 0,
             total: usage.totalTokens ?? 0,
             cached: extractCachedTokens(usage),
         });
@@ -387,7 +381,7 @@ export class Provider {
         let invalidRequestFeedbackAdded = false;
         const executedStepMessages = [];
         try {
-            const response = await this.withModelRequestSlot(() => withRetry(async () => {
+            let response = await this.withModelRequestSlot(() => withRetry(async () => {
                 const stepMessages = [];
                 const onStepEnd = (step) => {
                     stepMessages.push(...(step.response?.messages || []));
@@ -413,7 +407,7 @@ export class Provider {
                 return result;
             }, this.getRetryOptions(options)));
             clearActivity();
-            withExecutedSteps(response, executedStepMessages);
+            response = withExecutedSteps(response, executedStepMessages);
             // Log tool usage summary
             if (response.toolCalls && response.toolCalls.length > 0) {
                 responseLog(response.toolCalls);
@@ -585,7 +579,7 @@ export class Provider {
     }
     async processImage(prompt, image) {
         if (!this.config.visionModel) {
-            throw new Error('Vision model not configured. Please set ai.visionModel in your config.');
+            throw new Error(`Vision model not configured. Set ai.visionModel in your config; ${getCliName()} recommended-models lists the providers that serve one`);
         }
         setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');
         const messages = [

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

@@ -8,6 +8,7 @@ export declare function visuallyAnnotateContainers(page: Page, containers: Array
     css: string;
     label: string;
 }>): Promise<number>;
+export declare function removeVisualAnnotations(page: Page): Promise<void>;
 export declare function WithCoordinates<T extends Constructor>(Base: T): {
     new (...args: any[]): {
         explorer: Explorer;
@@ -20,6 +21,7 @@ export declare function WithCoordinates<T extends Constructor>(Base: T): {
                 label: string;
             }>;
         }): Promise<number>;
+        removeVisualAnnotations(): Promise<void>;
         _analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult>;
         mergeVisualData(result: ResearchResult, visualData: Map<string, {
             coordinates: string | null;

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

@@ -62,6 +62,15 @@ export async function visuallyAnnotateContainers(page, containers) {
         return count;
     }, containers);
 }
+export async function removeVisualAnnotations(page) {
+    try {
+        await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+            for (const element of elements)
+                element.remove();
+        });
+    }
+    catch { }
+}
 export function WithCoordinates(Base) {
     return class extends Base {
         analyzeScreenshotForVisualProps() {
@@ -70,6 +79,9 @@ export function WithCoordinates(Base) {
         async visuallyAnnotateElements(opts) {
             return this.explorer.withPage((page) => visuallyAnnotateContainers(page, opts?.containers || []));
         }
+        async removeVisualAnnotations() {
+            await this.explorer.withPage((page) => removeVisualAnnotations(page));
+        }
         async _analyzeScreenshotForVisualProps() {
             const elements = new Map();
             const emptyResult = { elements, pagePurpose: null, primaryActions: null, focusedSection: null };
@@ -81,7 +93,7 @@ export function WithCoordinates(Base) {
             tag('step').log('Analyzing annotated screenshot for visual properties');
             const prompt = dedent `
         This screenshot has two types of annotations:
-        - **Section containers**: dashed bordered boxes (no labels on them). A legend at the bottom-left maps dashed line colors to section names. Ignore containers for this task.
+        - **Section containers**: dashed bordered boxes (no labels on them). A legend at the bottom-right maps dashed line colors to section names. Ignore containers for this task.
         - **Interactive elements**: solid bordered boxes with eidx numbers in the top-right corner above the box. Adjacent elements use different colors.
 
         For each interactive element (solid border, eidx number), report:

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

@@ -62,29 +62,29 @@ export function WithDeepAnalysis(Base) {
             this._appendExtendedResearch(result, expandedSections, navigationLinks);
         }
         async researchOverlay(current, previous, pageStateHash) {
-            const focusArea = current.overlay;
-            if (!focusArea.present || !focusArea.name)
+            const region = current.overlay;
+            if (!region.isOpen || !region.name)
                 return null;
             const cached = getCachedResearch(pageStateHash);
             if (!cached)
                 return null;
-            const escaped = focusArea.name.replace(/"/g, '\\"');
+            const escaped = region.name.replace(/"/g, '\\"');
             if (mdq(cached).query(`section3(~"${escaped}")`).count() > 0) {
-                debugLog(`Overlay "${focusArea.name}" already in cached research, skipping`);
+                debugLog(`Overlay "${region.name}" already in cached research, skipping`);
                 return null;
             }
             const diff = await current.diff(previous);
             if (!diff.ariaChanged && diff.htmlParts.length === 0) {
-                debugLog(`No diff between current and previous state for overlay "${focusArea.name}"`);
+                debugLog(`No diff between current and previous state for overlay "${region.name}"`);
                 return null;
             }
             const alreadyExpanded = this._summarizeExpanded(parseResearchSections(cached)
                 .filter((s) => s.elements.length > 0)
                 .map((s) => s.rawMarkdown));
-            tag('substep').log(`Researching overlay: ${focusArea.name}`);
-            const sectionMarkdown = await this._analyzeExpandedAction('', focusArea.name, diff, alreadyExpanded);
+            tag('substep').log(`Researching overlay: ${region.name}`);
+            const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded);
             if (!sectionMarkdown) {
-                debugLog(`Overlay "${focusArea.name}" produced no meaningful expansion`);
+                debugLog(`Overlay "${region.name}" produced no meaningful expansion`);
                 return null;
             }
             const extQuery = mdq(cached).query('section1(~"Extended Research")');
@@ -97,7 +97,7 @@ export function WithDeepAnalysis(Base) {
                 updated = `${cached.trimEnd()}\n\n# Extended Research\n\n${sectionMarkdown}\n`;
             }
             saveResearch({ hash: pageStateHash }, updated);
-            tag('substep').log(`Overlay research appended: ${focusArea.name}`);
+            tag('substep').log(`Overlay research appended: ${region.name}`);
             return sectionMarkdown;
         }
         _loadPreviousExtendedSections(hash) {

package/dist/src/ai/researcher/fingerprint-worker.js

@@ -3,17 +3,7 @@ import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from "../../utils/html-diff.js";
 import { isSamePageFamily } from "../../utils/url-matcher.js";
-function diceSimilarity(a, b) {
-    let intersection = 0;
-    for (const item of a) {
-        if (b.has(item))
-            intersection++;
-    }
-    const total = a.size + b.size;
-    if (total === 0)
-        return 100;
-    return Math.round(((2 * intersection) / total) * 100);
-}
+import { diceSimilarity } from "../../utils/similarity.js";
 parentPort.on('message', (data) => {
     const { html, statesDir, maxAgeMs, threshold, url } = data;
     if (!existsSync(statesDir)) {

package/dist/src/ai/researcher.js

@@ -193,7 +193,7 @@ export class Researcher extends ResearcherBase {
                 const containers = validContainers.filter((c) => !freshBroken.includes(c.css));
                 await this.visuallyAnnotateElements({ containers });
                 this.actionResult = await this.explorer.capture({ screenshot: true });
-                const visualResult = await this.analyzeScreenshotForVisualProps();
+                const visualResult = await this.analyzeScreenshotForVisualProps().finally(() => this.removeVisualAnnotations());
                 if (visualResult.elements.size > 0) {
                     await this.mergeVisualData(result, visualResult.elements);
                     result.parseLocators();

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
@@ -318,6 +320,14 @@ export const actionRule = dedent `
   If locator doesn't work, try CSS or XPath locators.
   If nothing works, use I.clickXY(x, y) as last resort.
 
+  When a click result reports several matches, pick one from its numbered list by position rather than guessing a new locator.
+  Reuse the same locator with step.opts({ elementIndex: N }) as the LAST argument. N is the "Element N" number.
+
+  <example>
+    I.click('Remove', step.opts({ elementIndex: 2 }));
+    I.click({ role: 'link', text: 'Details' }, '.panel', step.opts({ elementIndex: 1 }));
+  </example>
+
   For checkboxes, prefer I.checkOption/I.uncheckOption over I.click.
 
 

package/dist/src/ai/tester.js

@@ -486,14 +486,14 @@ export class Tester extends TaskAgent {
         const currentStateHash = currentState.hash;
         const isNewUrl = this.previousUrl !== currentUrl;
         const isNewState = !isNewUrl && this.previousStateHash !== null && this.previousStateHash !== currentStateHash;
-        if (this.previousRegionPresent !== null && this.previousRegionPresent !== currentState.overlay.present) {
+        if (this.previousRegionPresent !== null && this.previousRegionPresent !== currentState.overlay.isOpen) {
             this.regionTransitioned = true;
         }
-        this.previousRegionPresent = currentState.overlay.present;
+        this.previousRegionPresent = currentState.overlay.isOpen;
         this.previousUrl = currentUrl;
         this.previousStateHash = currentStateHash;
         let context = '';
-        const focusArea = currentState.overlay;
+        const region = currentState.overlay;
         const focusedElement = currentState.focusedElement;
         if (focusedElement) {
             const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
@@ -511,30 +511,30 @@ export class Tester extends TaskAgent {
         </no_focus>
       `;
         }
-        if (focusArea.detected) {
-            const areaName = focusArea.name ? ` "${focusArea.name}"` : '';
+        if (region.isModal) {
+            const areaName = region.name ? ` "${region.name}"` : '';
             let rootHint = '';
-            if (focusArea.root)
-                rootHint = `\nIts content lives inside \`${focusArea.root}\` — scope locators to it.`;
+            if (region.root)
+                rootHint = `\nIts content lives inside \`${region.root}\` — scope locators to it.`;
             context += dedent `
-        <focus_scope>
-        A ${focusArea.type}${areaName} is currently open above the page.${rootHint}
-        Scope all interactions to elements inside this ${focusArea.type}.
-        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the ${focusArea.type}.
-        Use <page_aria> to confirm the element you target is actually inside the ${focusArea.type}.
-        </focus_scope>
+        <overlay>
+        An overlay${areaName} is currently open above the page.${rootHint}
+        Scope all interactions to elements inside this overlay.
+        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the overlay.
+        Use <page_aria> to confirm the element you target is actually inside the overlay.
+        </overlay>
       `;
         }
-        if (!focusArea.detected && focusArea.present && isNewState) {
+        if (!region.isModal && region.isOpen && isNewState) {
             let rootHint = '';
-            if (focusArea.root)
-                rootHint = `\nIt lives inside \`${focusArea.root}\`.`;
+            if (region.root)
+                rootHint = `\nIt lives inside \`${region.root}\`.`;
             context += dedent `
-        <area_of_interest>
-        A large new area "${focusArea.name || 'unnamed area'}" appeared on this page without navigation.${rootHint}
+        <region>
+        A large new region "${region.name || 'unnamed region'}" appeared on this page without navigation.${rootHint}
         The scenario most likely continues inside this area — prefer its elements for your next actions.
         The rest of the page (navigation, menus, filters) is still interactive and remains available.
-        </area_of_interest>
+        </region>
       `;
         }
         if (currentState.isInsideIframe) {
@@ -594,7 +594,7 @@ export class Tester extends TaskAgent {
       `;
             return context;
         }
-        if (focusArea.present && focusArea.name && this.pageStateHash && this.pageActionResult) {
+        if (region.isOpen && region.name && this.pageStateHash && this.pageActionResult) {
             const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash).catch(this.skipResearch);
             if (overlaySection) {
                 context += dedent `

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

@@ -12,7 +12,7 @@ interface AgentToolDeps extends ToolDeps {
     withExperience?: boolean;
 }
 export declare const ASSERTION_TOOLS: readonly ["verify"];
-export declare function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps, task: Task): {
+export declare function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task: Task): {
     click: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
         commands: any;
         explanation: any;

package/dist/src/ai/tools.js

@@ -16,7 +16,7 @@ import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 const debugLog = createDebug('explorbot:tools');
 export const ASSERTION_TOOLS = ['verify'];
-export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
+export function createCodeceptJSTools({ explorer, stateManager }, task) {
     return {
         click: tool({
             description: dedent `
@@ -29,6 +29,12 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
           Container narrows search area. Use when page has multiple matching elements.
           Example: Page has 3 "Delete" buttons in different rows:
           I.click("Delete", ".row-1") - clicks Delete inside element with class row-1
+        I.click(locator, step.opts({ elementIndex: N })) - click the Nth element the locator matches
+          Use after a result reported several matches. N is the "Element N" number from that list.
+          step.opts() always goes LAST, after the container when there is one.
+          Example: the result listed 3 "Delete" buttons and you want the second:
+          I.click("Delete", step.opts({ elementIndex: 2 }))
+          I.click("Delete", ".table", step.opts({ elementIndex: 2 })) - same, narrowed to a container
 
         IMPORTANT: This tool ONLY accepts click commands. For typing text, use form() tool.
         CRITICAL: All commands MUST target the SAME element using different locators.
@@ -47,6 +53,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
           5. I.clickXY(x, y) - coordinates fallback
+          After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
         `),
                 explanation: z.string().describe('Why you are clicking this element'),
             }),
@@ -72,6 +79,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
                 const action = explorer.action();
                 const attempts = [];
+                let ambiguityError = null;
                 for (let i = 0; i < commands.length; i++) {
                     const command = transformContainsCommand(commands[i]);
                     const success = await action.attempt(command, explanation);
@@ -79,34 +87,14 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     if (action.lastError)
                         attempt.error = errorText(action.lastError);
                     attempts.push(attempt);
+                    if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound')
+                        ambiguityError = action.lastError;
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
                         await commitNote(activeNote, TestResult.PASSED, toolResult, action);
                         return successToolResult('click', { ...toolResult, attempts, code: command }, action);
                     }
                 }
-                let disambiguated = null;
-                if (attempts.some((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
-                    disambiguated = await disambiguateElements(action.lastError, explanation, ai);
-                }
-                if (disambiguated) {
-                    debugLog('Disambiguation picked element %d', disambiguated.position);
-                    const failedCommand = attempts.find((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))?.command;
-                    const retryCommands = [];
-                    if (failedCommand) {
-                        retryCommands.push(failedCommand.replace(/\)$/, `, step.opts({ elementIndex: ${disambiguated.position} }))`));
-                    }
-                    retryCommands.push(`I.click('${disambiguated.xpath.replace(/'/g, "\\'")}')`);
-                    for (const retryCmd of retryCommands) {
-                        if (!(await action.attempt(retryCmd, explanation))) {
-                            attempts.push({ command: retryCmd, success: false, error: errorText(action.lastError) });
-                            continue;
-                        }
-                        const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, retryCmd);
-                        await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-                        return successToolResult('click', { ...toolResult, attempts, code: retryCmd, disambiguated: true }, action);
-                    }
-                }
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
                 await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                 const suggestion = clickFailureSuggestion(attempts);
@@ -114,7 +102,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     ...toolResult,
                     attempts,
                     suggestion,
-                }, action.lastError);
+                }, ambiguityError || action.lastError);
             },
         }),
         hover: tool({
@@ -344,13 +332,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     if (action.lastError) {
                         const message = errorText(action.lastError);
                         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
-                        let formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
-                        if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
-                            const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
-                            if (disambiguated) {
-                                formSuggestion = `Multiple elements matched. Add step.opts({ elementIndex: ${disambiguated.position} }) to the failing command. Fallback locator: ${disambiguated.xpath}`;
-                            }
-                        }
+                        const formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
                         return failedToolResult('form', `Form execution FAILED! ${message}\n${formatExecutedSteps(action.executedSteps, codeLines.length)}`, {
                             ...toolResult,
                             code: codeBlock,
@@ -1123,13 +1105,11 @@ export async function failedToolResult(action, message, data, error) {
 }
 function getMultipleElementsSuggestion() {
     return dedent `
-    Multiple elements matched your locator. To fix this:
-    1. Use container context: I.click({ "role": "button", "text": "Submit" }, '.form-container')
-    2. Use more specific CSS: target the actual element (input, button, a) not wrapper divs
-    3. Add distinguishing attributes: input[type="submit"], button[type="submit"], [value="..."]
-    4. If buttons have similar text like "Create" and "Create Demo", use the FULL unique text
-    5. Use xpathCheck() to inspect matched elements and pick the correct one
-    6. Use visualClick() to click the right element by visual appearance
+    Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
+    Read the numbered elements list and click the one you meant by its number:
+    reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    If none of them is the element you want, narrow the locator with a container or its full unique text.
+    If the list is missing, call xpathCheck() to see what the locator matches.
   `;
 }
 export function withdrawVisionTools(tools) {
@@ -1194,42 +1174,6 @@ export async function formatMatchedElements(error) {
         return 'Could not fetch element details. Repeat the action to get better info.';
     return formatElementList(details);
 }
-async function disambiguateElements(error, explanation, provider) {
-    const elementDetails = await extractWebElements(error);
-    if (!elementDetails)
-        return null;
-    const elementList = formatElementList(elementDetails);
-    const schema = z.object({
-        position: z.number().nullable().describe('1-based position of the correct element, or null if none match'),
-    });
-    try {
-        const result = await provider.generateObject([
-            {
-                role: 'user',
-                content: dedent `
-            A click action failed because multiple elements matched the locator.
-            The intended action was: ${explanation}
-
-            Here are the matched elements:
-
-            ${elementList}
-
-            Which element (1-${elementDetails.length}) best matches the intended action?
-            Return the position number, or null if none of them match.
-          `,
-            },
-        ], schema, provider.getModelForAgent(), { agentName: 'disambiguator', timeout: 15000 });
-        const position = result?.object?.position;
-        if (position && position >= 1 && position <= elementDetails.length) {
-            return { position, xpath: elementDetails[position - 1].xpath };
-        }
-        return null;
-    }
-    catch (e) {
-        debugLog('Element disambiguation AI call failed: %s', e);
-        return null;
-    }
-}
 function getNotFoundSuggestion(errorMessage) {
     if (!errorMessage.includes('not found')) {
         return null;

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,25 +6,26 @@ 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;
     addMadeRequest(result: RequestResult): void;
-    addRequest(result: RequestResult): void;
     getCapturedRequests(): RequestResult[];
     getMadeRequests(): RequestResult[];
-    getRequests(): RequestResult[];
     getLastRequest(): RequestResult | undefined;
-    getRequestsByEndpoint(pathPrefix: string): RequestResult[];
-    getRequestsByMethod(method: string): RequestResult[];
-    getRequestsByStatus(status: number): RequestResult[];
-    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';