explorbot 0.4.2 → 0.4.4

package/dist/boat/prima/src/help.js

@@ -0,0 +1,63 @@
+import dedent from 'dedent';
+export const helpContract = dedent `
+  Prima drives the browser opened by playwright-cli.
+
+    playwright-cli open <url>    starts the session
+    prima <command> ...          drives it
+    playwright-cli close         ends it
+
+  One call runs a whole job:
+
+    prima check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
+    prima do "open the account menu" "choose the settings entry" "switch the theme to dark" "check it took effect"
+    prima pw "({ page }) => page.click('[data-test=submit]')"
+
+  Only research maps a page. Other commands read the accessibility tree; a cached
+  research map joins when present. On large or unclear pages, run prima research first.
+  Without a usable AI model only pw works; otherwise use playwright-cli.
+  DEBUG='explorbot:*' in front of a command logs everything it does.
+`;
+export const checkHelp = dedent `
+  check states the outcome, not the clicks; it finds the path itself. It stays
+  on the current page and never reloads it, so an open dialog survives.
+  --expected  one required outcome, repeatable for several. Without it the
+              scenario text is the outcome. Each returns under
+              ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
+              "not verified" means never checked, not false.
+  Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
+  CONTRADICTION means screenshot and log disagree; judge the html, aria and
+  screenshot under ### Artifacts yourself.
+  ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
+  reported as such rather than as an app failure.
+  Side issues found on the way go under ### Answer, not as step failures.
+`;
+export const doHelp = dedent `
+  ### Steps marks each instruction ok, FAIL or ??. ?? means it ran but the run ended
+  without confirming it - read the steps above. Only FAIL fails the command.
+  Nothing runs past the last instruction. Batch the whole sequence in one call;
+  that is what keeps this tier cheap.
+`;
+export const askHelp = dedent `
+  Answers from a page screenshot, or from its structure with --no-vision.
+`;
+export const verifyHelp = dedent `
+  Reports each expressible assertion as PASSED or FAILED with its playwright form;
+  no overall verdict, read the lines. "none ran" means unexpressible, not false.
+`;
+export const researchHelp = dedent `
+  The map is saved per page state and joins later commands there, so one research run pays for all that follow it.
+`;
+export const statusHelp = dedent `
+  Reads recorded files, so it needs no browser and outlives the session.
+  The hash is matched across all recorded sites. ### Artifacts lists every kept
+  file: aria, html, screenshot and network log when captured, plus per-step captures of a do run.
+`;
+export const reportHelp = dedent `
+  Built from the command log, so it needs no browser and outlives the session.
+  Reports the latest session unless --pw-session names another.
+`;
+export const sessionHelp = dedent `
+  Parallel jobs need one --instance each. --session is ignored when attached,
+  since the attached session keeps its own. --framework is parsed but inactive;
+  reported code is CodeceptJS either way.
+`;

package/dist/boat/prima/src/prima.js

@@ -23,14 +23,13 @@ import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { pluralize } from "../../../src/utils/logger.js";
 import { mdq } from "../../../src/utils/markdown-query.js";
 import { safeFilename } from "../../../src/utils/strings.js";
-import { STATUS_FILE, readArtifacts, writeArtifacts } from "./envelope.js";
+import { STATUS_FILE, STEP_FILES, readArtifacts, writeArtifacts } from "./envelope.js";
 import { isFunctionExpression, takePwValue, toCodeceptWrapper } from "./pw-parser.js";
 import { readDescriptors, selectDescriptor } from "./pw-registry.js";
 import { latestSessionFile, readSession, recordCommand, sessionFile, sessionsDir } from "./session-log.js";
-const TESTER_ONLY_TOOLS = ['learnExperience', 'askUser'];
+const WITHHELD_TOOLS = ['learnExperience', 'askUser', 'research'];
 const ITERATIONS_PER_INSTRUCTION = 2;
 const MAX_INSTRUCTION_ITERATIONS = 24;
-const DEFAULT_RESEARCH_AFTER_VISITS = 3;
 const CONTEXT_HTML_CAP = 6000;
 const MAX_TOOL_ROUNDTRIPS = 5;
 const AI_AGENT_NAME = 'prima';
@@ -68,7 +67,6 @@ export class Prima {
     server = null;
     attached = null;
     session = null;
-    artifacts;
     constructor(options = {}) {
         this.options = options;
         this.bot = new ExplorBot({
@@ -99,6 +97,7 @@ export class Prima {
         const config = await this.loadConfig();
         await this.resolveBrowser(config, discovery);
         await this.bot.start();
+        this.bot.agentResearcher().disable();
         if (!this.options.url)
             return;
         if (this.bot.getCurrentState())
@@ -382,9 +381,11 @@ export class Prima {
         const guard = await this.aiGuard(command);
         if (guard)
             return guard;
+        const researcher = this.bot.agentResearcher();
+        researcher.enable();
         const previousState = this.bot.stateManager().getCurrentState();
         const result = await this.capturedResult(previousState);
-        const uiMap = await this.bot.agentResearcher().research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
+        const uiMap = await researcher.research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
         return this.reportEnvelope(command, result, previousState, { research: dropVolatileColumns(uiMap) });
     }
     async go(target) {
@@ -768,7 +769,7 @@ export class Prima {
         if (!researcher || !navigator)
             return {};
         const tools = createAgentTools({ ...deps, researcher, navigator, withExperience: false });
-        for (const name of TESTER_ONLY_TOOLS)
+        for (const name of WITHHELD_TOOLS)
             delete tools[name];
         return tools;
     }
@@ -823,14 +824,15 @@ export class Prima {
     }
     async pageContext(result) {
         const experience = this.bot.experienceTracker?.()?.renderExperienceTocFor?.(result) || '';
-        const map = this.researchMap(result);
+        const map = getPreviousResearch(result.baseHash);
+        let uiMap = '';
         if (map) {
-            return dedent `
-        <page_ui_map url="${result.url}" title="${result.title}">
+            uiMap = dedent `
+        <page_ui_map>
+        A map of this page recorded by an earlier research run. It names parts the accessibility
+        tree does not, and can be out of date — the tree is what the page holds now.
         ${map}
         </page_ui_map>
-
-        ${experience}
       `;
         }
         return dedent `
@@ -838,20 +840,11 @@ export class Prima {
       ${compactAriaSnapshot(await this.refAriaSnapshot(result), true, (value) => this.offloadValue(value))}
       </page>
 
+      ${uiMap}
+
       ${experience}
     `;
     }
-    researchMap(result) {
-        if (this.bot.stateManager().getVisitCount(result.url) < this.researchAfterVisits())
-            return '';
-        return getPreviousResearch(result.getStateHash());
-    }
-    researchAfterVisits() {
-        const configured = this.bot.getConfig?.()?.ai?.agents?.prima?.researchAfterVisits;
-        if (typeof configured === 'number')
-            return configured;
-        return DEFAULT_RESEARCH_AFTER_VISITS;
-    }
     offloadValue(value) {
         const dir = this.statusDir();
         const name = `value-${createHash('sha1').update(value).digest('hex').slice(0, 8)}.txt`;
@@ -923,16 +916,13 @@ export class Prima {
     }
     async successEnvelope(command, used, result, previousState) {
         const changes = await this.pageChanges(result, previousState, used[0]);
-        const status = await this.saveStatus(result);
         return {
             ok: true,
             command,
             used,
             page: this.pageBlock(result, previousState),
             changes,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
     async failureEnvelope(command, error, previousState) {
@@ -940,29 +930,27 @@ export class Prima {
         const failure = { error: browserErrorMessage(error) };
         if (result.ariaSnapshot)
             failure.compactAria = compactAriaSnapshot(result.ariaSnapshot, true);
-        const status = await this.saveStatus(result);
         return {
             ok: false,
             command,
             page: this.pageBlock(result, previousState),
             failure,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
     async reportEnvelope(command, result, previousState, outcome) {
-        const status = await this.saveStatus(result);
         return {
             ok: true,
             command,
             page: this.pageBlock(result, previousState),
             ...outcome,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
+    async envelopeTail(result) {
+        const { hash, artifacts } = await this.saveStatus(result);
+        return { instance: await this.instanceInfo(), status: hash, artifacts };
+    }
     async capturedResult(previousState, opts = {}) {
         const captured = await this.bot
             .getExplorer()
@@ -1026,9 +1014,9 @@ export class Prima {
     }
     async saveStatus(result) {
         const hash = this.statusHash();
-        await this.writeSnapshot(result);
+        const artifacts = await this.writeSnapshot(result);
         writeFileSync(path.join(this.statusDir(hash), STATUS_FILE), JSON.stringify({ page: this.pageBlock(result, null) }), 'utf-8');
-        return hash;
+        return { hash, artifacts };
     }
     async writeStepFiles(index, label, diff) {
         const state = this.bot.stateManager().getCurrentState();
@@ -1038,17 +1026,17 @@ export class Prima {
         mkdirSync(dir, { recursive: true });
         const stem = path.join(dir, `${index}-${safeFilename(label.slice(0, 60))}`);
         const result = ActionResult.fromState(state);
-        writeFileSync(`${stem}.aria.yaml`, result.ariaSnapshot ?? '', 'utf-8');
-        writeFileSync(`${stem}.html`, await result.combinedHtml(), 'utf-8');
+        writeFileSync(`${stem}.${STEP_FILES.aria}`, result.ariaSnapshot ?? '', 'utf-8');
+        writeFileSync(`${stem}.${STEP_FILES.html}`, await result.combinedHtml(), 'utf-8');
         if (diff)
-            writeFileSync(`${stem}.diff.yaml`, diff, 'utf-8');
+            writeFileSync(`${stem}.${STEP_FILES.diff}`, diff, 'utf-8');
     }
     async writeSnapshot(result) {
-        this.artifacts = writeArtifacts(this.statusDir(), {
+        return writeArtifacts(this.statusDir(), {
             aria: result.ariaSnapshot,
             html: await result.combinedHtml(),
             screenshot: result.screenshot,
-            requests: this.bot.requestStore().getMadeRequests(),
+            requests: this.bot.requestStore().getCapturedRequests(),
         });
     }
     statusHash() {

package/dist/package.json

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

package/dist/src/action-result.d.ts

@@ -26,6 +26,7 @@ interface ActionResultData extends WebPageState {
     }>;
     ariaSnapshot?: string | null;
     ariaSnapshotFile?: string;
+    regionAria?: string | null;
     focusedElement?: FocusedElement | null;
     iframeURL?: string;
     links?: Link[];
@@ -84,6 +85,7 @@ export declare class ActionResult implements ActionResultData {
     links: Link[];
     verifications?: Record<string, boolean>;
     overlay: Region;
+    regionAria: string | null;
     _diffCache: {
         previousId: number | undefined;
         diff: Diff;
@@ -109,6 +111,7 @@ export declare class ActionResult implements ActionResultData {
     }): Promise<string>;
     textHtml(htmlConfig?: HtmlConfig): Promise<string>;
     getInteractiveARIA(): string;
+    getRegionARIA(): string;
     getCompactARIA(): string;
     normalizeHtmlConfig(htmlConfig?: HtmlConfig): HtmlConfig | undefined;
     static fromState(state: WebPageState): ActionResult;

package/dist/src/action-result.js

@@ -40,6 +40,7 @@ export class ActionResult {
     links = [];
     verifications;
     overlay = new Region();
+    regionAria = null;
     _diffCache = null;
     constructor(data) {
         this.id = data.id;
@@ -55,6 +56,7 @@ export class ActionResult {
         this.iframeURL = data.iframeURL;
         this.notes = data.notes ?? [];
         this.verifications = data.verifications;
+        this.regionAria = data.regionAria ?? null;
         // Set readonly properties
         if (data.screenshotFile !== undefined) {
             this.screenshotFile = data.screenshotFile;
@@ -238,6 +240,9 @@ export class ActionResult {
     getInteractiveARIA() {
         return compactAriaSnapshot(this.ariaSnapshot, false);
     }
+    getRegionARIA() {
+        return compactAriaSnapshot(this.regionAria, false);
+    }
     getCompactARIA() {
         return compactAriaSnapshot(this.ariaSnapshot, true);
     }

package/dist/src/action.js

@@ -165,8 +165,19 @@ class Action {
                 focusedElement,
                 iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
             });
-            if (!frame)
+            if (!frame) {
                 await this.detectRegion(result).catch((err) => debugLog('Region detection failed:', err.message));
+                const regionRoot = result.overlay.root;
+                if (result.overlay.isModal && regionRoot) {
+                    result.regionAria = await this.playwrightHelper.page
+                        .locator(regionRoot)
+                        .ariaSnapshot()
+                        .catch((err) => {
+                        debugLog('Region ARIA snapshot failed:', err.message);
+                        return null;
+                    });
+                }
+            }
             this.stateManager.updateState(result, codeBlock);
             return result;
         }

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;
 }