explorbot 0.4.4 → 0.4.5

package/boat/prima/src/prima.ts

@@ -20,6 +20,7 @@ import { Reporter } from '../../../src/reporter.ts';
 import type { WebPageState } from '../../../src/state-manager.ts';
 import { Stats } from '../../../src/stats.ts';
 import { Task, Test, TestResult } from '../../../src/test-plan.ts';
+import { ariaRefSnapshot } from '../../../src/utils/aria-ref.ts';
 import { compactAriaSnapshot } from '../../../src/utils/aria.ts';
 import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
 import { pluralize } from '../../../src/utils/logger.ts';
@@ -324,11 +325,15 @@ export class Prima {
       return null;
     });
 
-    if (settleError) trace.push({ label: 'settling which instructions were satisfied', ok: false, proof: browserErrorMessage(settleError) });
-
+    const stillOpen = ledger.filter((entry) => entry.status === 'open').length;
     for (const execution of invoked?.toolExecutions || []) {
       this.applyLedgerReport(execution, ledger, trace);
     }
+
+    let unsettled = '';
+    if (settleError) unsettled = browserErrorMessage(settleError);
+    if (invoked && ledger.filter((entry) => entry.status === 'open').length === stillOpen) unsettled = 'the model was asked to report every remaining instruction and reported none';
+    if (unsettled) trace.push({ label: 'settling which instructions were satisfied', ok: false, proof: unsettled });
   }
 
   private ledgerProgress(ledger: LedgerEntry[]): string {
@@ -916,7 +921,7 @@ export class Prima {
   }
 
   private async refAriaSnapshot(result: ActionResult): Promise<string | null> {
-    const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.((page: any) => page.locator('body').ariaSnapshot({ mode: 'ai' }))).catch(() => null);
+    const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.(ariaRefSnapshot)).catch(() => null);
     return snapshot || result.ariaSnapshot;
   }
 

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

@@ -18,6 +18,7 @@ import { findSiteWith, listSites } from "../../../src/global-config.js";
 import { Reporter } from "../../../src/reporter.js";
 import { Stats } from "../../../src/stats.js";
 import { Task, Test, TestResult } from "../../../src/test-plan.js";
+import { ariaRefSnapshot } from "../../../src/utils/aria-ref.js";
 import { compactAriaSnapshot } from "../../../src/utils/aria.js";
 import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { pluralize } from "../../../src/utils/logger.js";
@@ -295,11 +296,17 @@ export class Prima {
             settleError = error;
             return null;
         });
-        if (settleError)
-            trace.push({ label: 'settling which instructions were satisfied', ok: false, proof: browserErrorMessage(settleError) });
+        const stillOpen = ledger.filter((entry) => entry.status === 'open').length;
         for (const execution of invoked?.toolExecutions || []) {
             this.applyLedgerReport(execution, ledger, trace);
         }
+        let unsettled = '';
+        if (settleError)
+            unsettled = browserErrorMessage(settleError);
+        if (invoked && ledger.filter((entry) => entry.status === 'open').length === stillOpen)
+            unsettled = 'the model was asked to report every remaining instruction and reported none';
+        if (unsettled)
+            trace.push({ label: 'settling which instructions were satisfied', ok: false, proof: unsettled });
     }
     ledgerProgress(ledger) {
         return ledger
@@ -858,7 +865,7 @@ export class Prima {
         return path.join(path.basename(dir), name);
     }
     async refAriaSnapshot(result) {
-        const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.((page) => page.locator('body').ariaSnapshot({ mode: 'ai' }))).catch(() => null);
+        const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.(ariaRefSnapshot)).catch(() => null);
         return snapshot || result.ariaSnapshot;
     }
     executedCodes(code) {

package/dist/package.json

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

package/dist/src/ai/fisherman/tools.js

@@ -3,8 +3,10 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { extractEndpointDefinition } from "../../api/spec-reader.js";
 import { tag } from "../../utils/logger.js";
+import { truncate } from "../../utils/strings.js";
 import { isDynamicSegment } from "../../utils/url-matcher.js";
 const BODY_PREVIEW_LIMIT = 2000;
+const READS_IN_ANSWER = 3;
 export function createFishermanTools(apiClient, requestStore, haul, opts) {
     const readOnly = opts.readOnly === true;
     let finished = false;
@@ -213,7 +215,7 @@ export function createAskApiTool(fisherman, task) {
                     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}`);
+                tag('success').log(`Ask API: ${truncate(result.summary, 200)}`);
                 return { answered: true, answer: result.summary };
             },
         }),
@@ -252,6 +254,10 @@ function synthesizeResult(haul, declaredDone, readOnly) {
         succeeded = haul.successfulReads();
         successLabel = 'successful reads';
     }
+    if (readOnly && succeeded.length > 0) {
+        const bodies = succeeded.slice(-READS_IN_ANSWER).map((read) => `${read.toEndpoint()} → ${read.rawResponseBody.substring(0, BODY_PREVIEW_LIMIT)}`);
+        return { success: true, summary: bodies.join('\n\n'), created: [], failed: [] };
+    }
     let summary = `Stopped before finishing: ${made.length} requests, ${succeeded.length} ${successLabel}, ${failures.length} failed`;
     const lastFailure = failures[failures.length - 1];
     if (lastFailure)

package/dist/src/ai/fisherman.js

@@ -2,6 +2,7 @@ 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";
+import { truncate } from "../utils/strings.js";
 const debugLog = createDebug('explorbot:fisherman');
 import { loop } from "../utils/loop.js";
 import { RequestHaul } from "./fisherman/request-haul.js";
@@ -106,7 +107,7 @@ export class Fisherman {
     `);
         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}`);
+        tag('info').log(`Fisherman answer: ${truncate(result.summary, 200)}`);
         return result;
     }
     async runSession(conversation, tools, opts) {

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

@@ -97,7 +97,6 @@ export declare class Pilot implements Agent {
     hasSuccessfulCheckEvidence(currentState: ActionResult, testerConversation: Conversation): boolean;
     formatSuccessfulAssertions(currentState: ActionResult, testerConversation: Conversation): string;
     formatActions(toolCalls: any[]): string;
-    buildDeletionScope(task: Test): string;
     getSystemPrompt(task: Test, initialState: ActionResult): string;
 }
 export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';

package/dist/src/ai/pilot.js

@@ -316,28 +316,28 @@ export class Pilot {
         return dedent `
       SCENARIO: ${task.scenario}
 
-      ${this.buildDeletionScope(task)}
-
       EXPECTED RESULTS (milestones):
       ${task.expected.map((e) => `- ${e}`).join('\n')}
     `;
     }
     buildResetSystemPrompt(task) {
         return dedent `
-      You are Pilot — decide whether a reset is legitimate. Reset is DESTRUCTIVE: it abandons this
-      iteration's work, but server-side side effects (records created, forms submitted) persist.
-      Unnecessary resets create duplicate data and infinite loops.
+      You are Pilot — decide whether a reset is legitimate. Reset only re-navigates to the start URL:
+      it writes nothing, though it abandons this iteration's work and server-side side effects persist.
+      The hazard is the tester REDOING a completed flow afterwards — duplicate data and infinite loops.
 
       ${this.buildSharedEvidenceRules()}
 
       DECISION:
-      - "allow": current page cannot host the scenario, irrecoverable error, or no path back.
-      - "continue": prior action already succeeded (URL changed, record visible, confirmation shown) — verify/finish instead. Or scenario goal may already be met; instruct tester to verify the actual outcome rather than redo. Provide guidance.
+      - "allow": current page cannot host the scenario, irrecoverable error, no path back, or an
+        expectation requires the outcome to survive a reload or a return to the start page and no
+        reset has been taken yet this run — there the reset IS the check, not a redo.
+      - "continue": the outcome the scenario needs is already observable on the CURRENT page — verify/finish instead. Provide guidance.
       - "fail": resetCount >= 2 and underlying situation hasn't changed; same flow tried twice with same failure mode.
       - "skipped": feature doesn't exist on this app or prerequisites can't be met.
 
       PRIORITY:
-      1) Successful side effects in session_log → almost never allow reset.
+      1) Successful side effects in session_log → allow reset only to re-observe them, never to repeat them.
       2) resetCount — each prior reset raises the bar.
       3) Tester's stated reason — weigh against evidence, don't trust blindly.
 
@@ -999,22 +999,6 @@ export class Pilot {
         })
             .join('\n\n');
     }
-    buildDeletionScope(task) {
-        const deletableItems = task.plan
-            ? task.plan
-                .listTests()
-                .filter((t) => t.isSuccessful && t.sessionName)
-                .map((t) => t.sessionName)
-            : [];
-        const scenarioLower = task.scenario.toLowerCase();
-        if (deletableItems.length > 0) {
-            return `For deletion scenarios, items can only be deleted if their title contains: ${deletableItems.join(', ')}`;
-        }
-        if (scenarioLower.includes('delete') || scenarioLower.includes('remove')) {
-            return 'No items available for deletion — test should create an item first';
-        }
-        return '';
-    }
     getSystemPrompt(task, initialState) {
         const interactive = isInteractive();
         const stepsText = task.plannedSteps.length > 0 ? task.plannedSteps.map((s, i) => `${i + 1}. ${s}`).join('\n') : 'No planned steps';

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

@@ -9,6 +9,7 @@ import { Conversation } from './conversation.js';
 import type { Fisherman } from './fisherman.js';
 import type { Provider } from './provider.js';
 import { type Researcher } from './researcher.js';
+import type { Scout } from './scout.js';
 declare const PlannerBase: {
     new (...args: any[]): {
         currentPlan: Plan | null;
@@ -59,9 +60,12 @@ export declare class Planner extends PlannerBase implements Agent {
     lastSuite: Suite | null;
     researcher: Researcher;
     fisherman: Fisherman | null;
+    scout: Scout | null;
     constructor(deps: AgentDeps, researcher: Researcher);
     setFisherman(fisherman: Fisherman): void;
+    setScout(scout: Scout): void;
     get sectionOrder(): string[];
+    get docsWeight(): number;
     getDefaultStartUrl(state: {
         url: string;
         fullUrl?: string;

package/dist/src/ai/planner.js

@@ -50,6 +50,7 @@ export class Planner extends PlannerBase {
     lastSuite = null;
     researcher;
     fisherman = null;
+    scout = null;
     constructor(deps, researcher) {
         super();
         this.explorer = deps.explorer;
@@ -62,9 +63,16 @@ export class Planner extends PlannerBase {
     setFisherman(fisherman) {
         this.fisherman = fisherman;
     }
+    setScout(scout) {
+        this.scout = scout;
+    }
     get sectionOrder() {
         return ConfigParser.getInstance().getConfig().ai?.agents?.researcher?.sections || Object.keys(POSSIBLE_SECTIONS);
     }
+    get docsWeight() {
+        const value = ConfigParser.getInstance().getConfig().ai?.agents?.planner?.docsWeight ?? 70;
+        return Math.max(0, Math.min(100, value));
+    }
     getDefaultStartUrl(state) {
         return state.fullUrl || state.url;
     }
@@ -291,6 +299,7 @@ export class Planner extends PlannerBase {
         const conversation = new Conversation([], model);
         conversation.autoTrimTag('page_research', 20000);
         conversation.autoTrimTag('tested_scenarios', 10000);
+        conversation.autoTrimTag('docs_context', 8000);
         conversation.addUserText(this.getSystemMessage(feature));
         const planningPrompt = dedent `
       <task>
@@ -345,6 +354,10 @@ export class Planner extends PlannerBase {
         const research = await this.researcher.research(currentState || state, {
             deep: true,
         });
+        let docsPromise = null;
+        if (this.scout && this.docsWeight > 0) {
+            docsPromise = this.scout.collectDocs({ url: state.url, title: state.title, feature, excludeUrls: this.knowledgeTracker.applicationSpecUrls(state) });
+        }
         let plannerResearch = mdq(research).query('code').replace('');
         plannerResearch = mdq(plannerResearch)
             .query('table')
@@ -376,6 +389,21 @@ export class Planner extends PlannerBase {
         if (applicationContext) {
             conversation.addUserText(applicationContext);
         }
+        if (docsPromise) {
+            const docs = await docsPromise;
+            if (docs) {
+                conversation.addUserText(dedent `
+          <docs_context>
+          Documentation retrieved from the collected corpus by the Scout agent.
+          Ground scenarios in these documented capabilities where they apply; treat them as supporting context, not a script.
+
+          Aim for roughly ${this.docsWeight}% of the scenarios to exercise behavior documented above; the remainder may explore beyond the documentation.
+
+          ${docs}
+          </docs_context>
+        `);
+            }
+        }
         conversation.addUserText(dedent `
       ${this.buildApproach(style)}
 

package/dist/src/ai/provider.js

@@ -366,7 +366,9 @@ export class Provider {
         const modelName = getModelName(model);
         setActivity(`🤖 Asking ${modelName} with dynamic tools`, 'ai');
         promptLog(`Using model: ${modelName}`);
-        const toolsWithCommentary = tools?.commentary ? tools : { ...tools, commentary: createHarmonyChannelFallbackTool() };
+        let toolsWithCommentary = tools;
+        if (!tools?.commentary && options.toolChoice !== 'required')
+            toolsWithCommentary = { ...tools, commentary: createHarmonyChannelFallbackTool() };
         const toolNames = Object.keys(toolsWithCommentary || {});
         tag('debug').log(`Tools enabled: [${toolNames.join(', ')}]`);
         promptLog('Available tools:', toolNames);

package/dist/src/ai/rules.js

@@ -6,8 +6,9 @@ const locatorPriorityRule = dedent `
 
   1. ARIA locators (first choice) - target browser's accessibility tree, most reliable
      Use JSON format: { "role": "button", "text": "Login" }
-     Copy role and text VERBATIM from the ARIA snapshot or UI map — never guess the pair.
-     If the element is absent from the snapshot, do not invent one; use text or CSS instead.
+     Copy role and text VERBATIM from the ARIA snapshot, UI map, or the page diff that
+     reported the element — never guess the pair; a guessed role can silently match a
+     different element with the same text. If named nowhere, use text or CSS instead.
 
   2. Text locators (second choice) - exact visible text, use only when unique on the page
      Example: 'Login', 'Submit', 'Username'
@@ -225,10 +226,10 @@ export const unexpectedPopupRule = dedent `
   If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
 
   Dismiss strategy (try in order):
-  1. I.clickXY(0, 0) — click outside the popup to close it
-  2. I.pressKey('Escape') — press Escape to dismiss
-  3. I.click('Cancel') — click Cancel button if present
-  4. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  1. I.pressKey('Escape') — press Escape to dismiss
+  2. I.click('Cancel') — click Cancel button if present
+  3. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  4. I.clickXY(0, 0) via form() tool and check if page diff changed
   </unexpected_popup_rule>
 `;
 export const sectionContextRule = dedent `
@@ -318,7 +319,7 @@ export const actionRule = dedent `
   Prefer text/ARIA locators with context over complex CSS/XPath selectors.
   For inline create/edit flows, after filling a field verify it contains the value, then confirm using the nearest explicit button/link, an adjacent icon-only confirm control in the same row/form, or Enter if the field remains focused.
   If locator doesn't work, try CSS or XPath locators.
-  If nothing works, use I.clickXY(x, y) as last resort.
+  If nothing works, use visualClick() — it locates the target in a screenshot before clicking it.
 
   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.

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

@@ -0,0 +1,17 @@
+export declare function loadScoutCorpus(dirs: string[]): ScoutCorpus;
+export declare function excludeCorpusUrls(corpus: ScoutCorpus, urls: string[]): ScoutCorpus;
+export declare function createScoutTools(corpus: ScoutCorpus): Promise<{
+    tools: Record<string, any>;
+    scanner: "rg" | "grep";
+    getResult: () => string;
+    finishFromText: (text?: string) => void;
+}>;
+export interface ScoutCorpus {
+    dirs: string[];
+    files: ScoutCorpusFile[];
+    excludedPaths: string[];
+}
+export interface ScoutCorpusFile {
+    path: string;
+    url?: string;
+}

package/dist/src/ai/scout/tools.js

@@ -0,0 +1,130 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tool } from 'ai';
+import { createBashTool } from 'bash-tool';
+import dedent from 'dedent';
+import { z } from 'zod';
+import { ConfigParser } from "../../config.js";
+import { tag } from "../../utils/logger.js";
+import { loadMarkdownFiles } from "../../utils/markdown-files.js";
+import { readCaptainFile } from "../captain/file-tools.js";
+const MAX_FILES = 500;
+const MAX_FINDINGS = 6000;
+let cachedScanner = null;
+export function loadScoutCorpus(dirs) {
+    const files = [];
+    for (const dir of dirs) {
+        if (files.length >= MAX_FILES) {
+            tag('warning').log(`Scout corpus capped at ${MAX_FILES} files — remaining directories skipped`);
+            break;
+        }
+        for (const file of loadMarkdownFiles(dir, { recursive: true })) {
+            if (files.length >= MAX_FILES)
+                break;
+            const entry = { path: file.filePath };
+            if (typeof file.data.url === 'string')
+                entry.url = file.data.url;
+            files.push(entry);
+        }
+    }
+    return { dirs, files, excludedPaths: [] };
+}
+export function excludeCorpusUrls(corpus, urls) {
+    if (urls.length === 0)
+        return corpus;
+    const excludedUrls = new Set(urls);
+    const files = [];
+    const excludedPaths = [...corpus.excludedPaths];
+    for (const file of corpus.files) {
+        if (file.url && excludedUrls.has(file.url)) {
+            excludedPaths.push(file.path);
+            continue;
+        }
+        files.push(file);
+    }
+    return { dirs: corpus.dirs, files, excludedPaths };
+}
+export async function createScoutTools(corpus) {
+    const scanner = await detectScanner();
+    const projectRoot = ConfigParser.getInstance().getProjectRoot();
+    let result = '';
+    let searchedOrRead = false;
+    const getResult = () => result;
+    const finishFromText = (text) => {
+        if (text && searchedOrRead)
+            result = text.slice(0, MAX_FINDINGS);
+    };
+    const files = {};
+    const readableFiles = new Set();
+    for (const file of corpus.files) {
+        files[toPosix(file.path)] = readFileSync(file.path, 'utf8');
+        readableFiles.add(resolve(file.path));
+    }
+    const toolkit = await createBashTool({
+        destination: '/',
+        files,
+        maxOutputLength: 20000,
+    });
+    const bashExecute = toolkit.bash.execute;
+    const bash = {
+        ...toolkit.bash,
+        execute: async (input) => {
+            tag('step').log(`Scout: bash ${input.command}`);
+            searchedOrRead = true;
+            return bashExecute?.(input);
+        },
+    };
+    const tools = {
+        bash,
+        readFile: tool({
+            description: dedent `
+        Read one documentation file from the corpus.
+        Pass the exact path returned by a search result.
+      `,
+            inputSchema: z.object({
+                path: z.string().describe('File path from a search result'),
+                startLine: z.number().optional().describe('First line to read, 1-based. Negative values count from the end of the file'),
+                endLine: z.number().optional().describe('Last line to read, 1-based and inclusive. Negative values count from the end of the file'),
+                maxChars: z.number().optional().describe('Maximum characters to return, default 12000'),
+            }),
+            execute: async (input) => {
+                tag('step').log(`Scout: read ${input.path}`);
+                const output = readCaptainFile(projectRoot, input, corpus.dirs);
+                if (!output.success)
+                    return output;
+                const resolvedPath = resolve(projectRoot || process.cwd(), output.path);
+                if (!readableFiles.has(resolvedPath)) {
+                    return { success: false, message: 'File is outside the Scout corpus' };
+                }
+                searchedOrRead = true;
+                return output;
+            },
+        }),
+    };
+    return { tools, scanner, getResult, finishFromText };
+}
+async function detectScanner() {
+    if (cachedScanner)
+        return cachedScanner;
+    if (await binaryRuns('rg')) {
+        cachedScanner = 'rg';
+        return cachedScanner;
+    }
+    if (await binaryRuns('grep')) {
+        cachedScanner = 'grep';
+        return cachedScanner;
+    }
+    throw new Error('Scout requires ripgrep or grep on PATH — neither was found');
+}
+async function binaryRuns(binary) {
+    try {
+        const proc = Bun.spawn([binary, '--version'], { stdout: 'ignore', stderr: 'ignore', stdin: 'ignore' });
+        return (await proc.exited) === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function toPosix(path) {
+    return path.split('\\').join('/');
+}

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

@@ -0,0 +1,21 @@
+import type { Agent } from './agent.js';
+import type { Provider } from './provider.js';
+import { type ScoutCorpus } from './scout/tools.js';
+export declare class Scout implements Agent {
+    provider: Provider;
+    corpus: ScoutCorpus;
+    emoji: string;
+    cache: Map<string, string>;
+    constructor(provider: Provider, corpus: ScoutCorpus);
+    isAvailable(): boolean;
+    collectDocs(query: ScoutQuery): Promise<string>;
+    runSession(corpus: ScoutCorpus, query: ScoutQuery): Promise<string | null>;
+    buildSystemPrompt(toolNames: string[], corpus: ScoutCorpus, query: ScoutQuery, scanner: 'rg' | 'grep'): string;
+    buildTaskPrompt(query: ScoutQuery): string;
+}
+export interface ScoutQuery {
+    url?: string;
+    title?: string;
+    feature?: string;
+    excludeUrls: string[];
+}

package/dist/src/ai/scout.js

@@ -0,0 +1,150 @@
+import dedent from 'dedent';
+import { tag } from "../utils/logger.js";
+import { loop } from "../utils/loop.js";
+import { createScoutTools, excludeCorpusUrls } from "./scout/tools.js";
+const MAX_ITERATIONS = 3;
+const MAX_TOOL_ROUNDTRIPS = 5;
+const CACHE_LIMIT = 40;
+const URL_LISTING_LIMIT = 40;
+export class Scout {
+    provider;
+    corpus;
+    emoji = '🔎';
+    cache = new Map();
+    constructor(provider, corpus) {
+        this.provider = provider;
+        this.corpus = corpus;
+    }
+    isAvailable() {
+        return this.corpus.files.length > 0;
+    }
+    async collectDocs(query) {
+        if (!this.isAvailable())
+            return '';
+        const cacheKey = `${query.url || ''}|${query.feature || ''}|${query.excludeUrls.join(',')}`;
+        const cached = this.cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const corpus = excludeCorpusUrls(this.corpus, query.excludeUrls);
+        if (corpus.files.length === 0)
+            return '';
+        const result = await this.runSession(corpus, query);
+        if (result === null)
+            return '';
+        if (this.cache.size > CACHE_LIMIT)
+            this.cache.clear();
+        this.cache.set(cacheKey, result);
+        return result;
+    }
+    async runSession(corpus, query) {
+        const { tools, scanner, getResult, finishFromText } = await createScoutTools(corpus);
+        const conversation = this.provider.startConversation(this.buildSystemPrompt(Object.keys(tools), corpus, query, scanner), 'scout', this.provider.getAgenticModel('scout'));
+        conversation.addUserText(this.buildTaskPrompt(query));
+        tag('info').log(`Scout: collecting documentation for ${query.feature || query.url || 'the current page'}`);
+        let failed = false;
+        await loop(async ({ stop, iteration }) => {
+            const invokeResult = await this.provider.invokeConversation(conversation, tools, {
+                maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
+                agentName: 'scout',
+            });
+            if (!invokeResult?.toolExecutions?.length) {
+                finishFromText(invokeResult?.response?.text);
+                stop();
+                return;
+            }
+            if (iteration >= MAX_ITERATIONS) {
+                const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
+                finishFromText(final?.response?.text);
+                stop();
+            }
+        }, {
+            maxAttempts: MAX_ITERATIONS,
+            observability: { name: `scout: ${query.feature || query.url || 'docs'}`, agent: 'scout' },
+            catch: async ({ error, stop }) => {
+                failed = true;
+                tag('warning').log(`Scout error: ${error.message}`);
+                stop();
+            },
+        });
+        if (failed)
+            return null;
+        const digest = getResult();
+        if (digest) {
+            const preview = digest.slice(0, 600);
+            const ellipsis = digest.length > 600 ? '…' : '';
+            tag('info').log(`Scout digest:\n${preview}${ellipsis}`);
+        }
+        return digest;
+    }
+    buildSystemPrompt(toolNames, corpus, query, scanner) {
+        const urls = corpus.files.map((file) => file.url).filter(Boolean);
+        const urlless = corpus.files.filter((file) => !file.url);
+        let pagesListing = '';
+        if (urls.length > 0) {
+            const listing = urls
+                .slice(0, URL_LISTING_LIMIT)
+                .map((url) => `- ${url}`)
+                .join('\n');
+            pagesListing = `Documented pages:\n${listing}`;
+            const remaining = urls.length - URL_LISTING_LIMIT;
+            if (remaining > 0)
+                pagesListing += `\n…and ${remaining} more — find them with ${scanner}`;
+        }
+        if (urlless.length > 0) {
+            const listing = urlless
+                .slice(0, URL_LISTING_LIMIT)
+                .map((file) => `- ${toPosix(file.path)}`)
+                .join('\n');
+            pagesListing += `\nFiles with no page URL (hand-written docs):\n${listing}`;
+        }
+        const prompt = dedent `
+      You are Scout — a documentation retrieval agent. You find collected documentation relevant to a testing focus and report it for test planning.
+
+      You never see the application itself. The documentation corpus is your only source of truth.
+
+      CORPUS:
+      ${corpus.files.length} markdown files under:
+      - ${corpus.dirs.map(toPosix).join('\n- ')}
+      ${pagesListing}
+
+      These pages are already provided to the planner in full — do not re-report them:
+      ${query.excludeUrls.map((url) => `- ${url}`).join('\n') || '- none'}
+
+      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.
+
+      SCANNER:
+      ${scanner} is the search command. Scan the working directory through bash() — explore freely, pipelines, globs and repeated searches are fine. Read files with readFile().
+
+      WORKFLOW:
+      1. Scan with ${scanner} using plain prose words from the focus — feature names, page purposes, capabilities
+      2. Read the files whose hits look most relevant
+      3. Report the digest as your final message — no tool call is needed to finish
+
+      RULES:
+      - Report only what the documentation states. Never fill gaps with assumptions about the application
+      - Keep verified capabilities and unverified possibilities distinguishable, the way the documentation marks them
+      - Name the page URL each item belongs to, so scenarios anchor to real routes
+      - Explore briefly: a few scans and reads are enough, then report
+      - A short accurate digest beats a long loose one; reporting that nothing relevant exists is a valid answer
+    `;
+        const customPrompt = this.provider.getSystemPromptForAgent('scout');
+        if (customPrompt)
+            return `${prompt}\n\n${customPrompt}`;
+        return prompt;
+    }
+    buildTaskPrompt(query) {
+        return dedent `
+      Page URL: ${query.url || 'Unknown'}
+      Page title: ${query.title || 'Unknown'}
+      Focus: ${query.feature || 'the page as a whole'}
+
+      Report the documented capabilities, states and transitions a test planner could turn into scenarios.
+    `;
+    }
+}
+function toPosix(path) {
+    return path.split('\\').join('/');
+}