explorbot 0.1.32-beta.1 → 0.2.1

package/dist/src/ai/researcher.js

@@ -7,11 +7,11 @@ import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
 import { diffAriaSnapshots } from "../utils/aria.js";
 import { ErrorPageError, detectPageCondition } from "../utils/error-page.js";
-import { HooksRunner } from "../utils/hooks-runner.js";
 import { isBodyEmpty } from "../utils/html.js";
-import { createDebug, pluralize, tag } from '../utils/logger.js';
+import { createDebug, tag } from '../utils/logger.js';
 import { mdq } from "../utils/markdown-query.js";
 import { RulesLoader } from "../utils/rules-loader.js";
+import { annotatePageElements } from "../utils/web-annotate.js";
 import { ContextLengthError } from './provider.js';
 import { findSimilarResearch, getCachedResearch, saveResearch } from "./researcher/cache.js";
 import { WithCoordinates } from "./researcher/coordinates.js";
@@ -39,15 +39,10 @@ export class Researcher extends ResearcherBase {
     emoji = '🔍';
     experienceTracker;
     hasScreenshotToAnalyze = false;
-    hooksRunner;
-    constructor(explorer, provider) {
-        super();
-        this.explorer = explorer;
-        this.provider = provider;
-        this.stateManager = explorer.getStateManager();
-        this.experienceTracker = this.stateManager.getExperienceTracker();
-        this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
-        const ai = explorer.getConfig().ai;
+    constructor(deps) {
+        super(deps);
+        this.experienceTracker = deps.stateManager.getExperienceTracker();
+        const ai = deps.config.ai;
         if (ai) {
             ai.agents ??= {};
             ai.agents.researcher ??= {};
@@ -57,15 +52,6 @@ export class Researcher extends ResearcherBase {
     getNavigator() {
         throw new Error('not implemented');
     }
-    getExperienceTracker() {
-        return this.experienceTracker;
-    }
-    getKnowledgeTracker() {
-        return this.explorer.getKnowledgeTracker();
-    }
-    getProvider() {
-        return this.provider;
-    }
     static getCachedResearch(state) {
         return getCachedResearch(state.hash || '');
     }
@@ -82,7 +68,7 @@ export class Researcher extends ResearcherBase {
     }
     async research(state, opts = {}) {
         const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
-        const maxRetries = this.explorer.getConfig().ai?.agents?.researcher?.retries ?? 2;
+        const maxRetries = this.config.ai?.agents?.researcher?.retries ?? 2;
         let retriesLeft = opts._retriesLeft ?? maxRetries;
         this.actionResult = ActionResult.fromState(state);
         const stateHash = state.hash || this.actionResult.getStateHash();
@@ -101,9 +87,9 @@ export class Researcher extends ResearcherBase {
             setActivity(`${this.emoji} Researching...`, 'action');
             await this.ensureNavigated(displayUrl, screenshot && this.provider.hasVision());
             await this.hooksRunner.runBeforeHook('researcher', state.url);
-            const annotatedElements = await this.explorer.annotateElements();
+            const { elements: annotatedElements } = await this.explorer.withPage(annotatePageElements);
             debugLog(`Annotated ${annotatedElements.length} interactive elements with eidx`);
-            this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot && this.provider.hasVision() });
+            this.actionResult = await this.explorer.capture({ screenshot: screenshot && this.provider.hasVision() });
             const condition = detectPageCondition(this.actionResult);
             if (condition === 'error') {
                 tag('warning').log(`Detected error page at ${state.url}`);
@@ -165,11 +151,10 @@ export class Researcher extends ResearcherBase {
                 return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 });
             }
             if (!interrupted()) {
-                const containerLocs = result.containerLocators;
-                await this.testLocators(containerLocs);
-                const brokenContainers = containerLocs.filter((l) => l.valid === false);
-                if (containerLocs.length > 0 && brokenContainers.length === containerLocs.length && retriesLeft > 0) {
-                    tag('warning').log(`All ${containerLocs.length} containers broken, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
+                const brokenContainers = await this.resolveContainers(result);
+                const containerCount = result.containers.length;
+                if (containerCount > 0 && brokenContainers.length === containerCount && retriesLeft > 0) {
+                    tag('warning').log(`All ${containerCount} containers broken, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
                     await new Promise((r) => setTimeout(r, 2000));
                     return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 });
                 }
@@ -181,13 +166,6 @@ export class Researcher extends ResearcherBase {
                 }
                 const toTest = result.locators.filter((l) => l.valid === null);
                 await this.testLocators(toTest);
-                const brokenCount = result.locators.filter((l) => l.valid === false).length;
-                const brokenRatio = result.locators.length > 0 ? brokenCount / result.locators.length : 0;
-                if (brokenRatio > 0.8 && retriesLeft > 0) {
-                    tag('warning').log(`${Math.round(brokenRatio * 100)}% locators broken, waiting 3s and retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
-                    await new Promise((r) => setTimeout(r, 3000));
-                    return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 });
-                }
             }
             // Stage 3: Fix broken sections via AI conversation continuation
             if (!interrupted() && fix && result.locators.some((l) => l.valid === false)) {
@@ -197,7 +175,7 @@ export class Researcher extends ResearcherBase {
             // Must run BEFORE visuallyAnnotateContainers — annotation overlays inject z-index 99998+ which would pollute the scoring.
             if (!interrupted() && this.hasScreenshotToAnalyze) {
                 const sections = parseResearchSections(result.text);
-                const focused = await this.explorer.runWithBrowserRecovery('detectFocusedSection', () => detectFocusedSection(this.explorer.playwrightHelper.page, sections));
+                const focused = await this.explorer.withPage((page) => detectFocusedSection(page, sections));
                 if (focused)
                     markSectionAsFocused(result, focused);
             }
@@ -206,11 +184,11 @@ export class Researcher extends ResearcherBase {
                 const validContainers = extractValidContainers(result.text);
                 result.parseLocators();
                 const freshContainerLocs = result.containerLocators;
-                await this.testLocators(freshContainerLocs);
+                await this.testLocators(freshContainerLocs, { scope: true });
                 const freshBroken = freshContainerLocs.filter((l) => l.valid === false).map((l) => l.locator);
                 const containers = validContainers.filter((c) => !freshBroken.includes(c.css));
                 await this.visuallyAnnotateElements({ containers });
-                this.actionResult = await this.explorer.capturePageWithScreenshot();
+                this.actionResult = await this.explorer.capture({ screenshot: true });
                 const visualResult = await this.analyzeScreenshotForVisualProps();
                 if (visualResult.elements.size > 0) {
                     await this.mergeVisualData(result, visualResult.elements);
@@ -261,12 +239,10 @@ export class Researcher extends ResearcherBase {
             if (stateHash) {
                 researchFile = saveResearch(stateHash, result.text, combinedHtml);
             }
-            const summaryMatch = result.text.match(/## Summary\s*\n+([\s\S]*?)(?=\n##|$)/i);
-            if (summaryMatch) {
-                const summaryLine = summaryMatch[1].trim().split('\n')[0].trim().slice(0, 200);
-                if (summaryLine)
-                    this.experienceTracker.updateSummary(this.actionResult, summaryLine);
-            }
+            const summaryText = mdq(result.text).query('section2(/^summary/)').query('paragraph[0]').text().trim();
+            const summaryLine = summaryText.split('\n')[0]?.trim().slice(0, 200);
+            if (summaryLine)
+                this.experienceTracker.updateSummary(this.actionResult, summaryLine);
             tag('multiline').log(formatResearchSummary(result.text, { visionUsed: this.hasScreenshotToAnalyze }));
             tag('success').log('Research complete');
             if (researchFile)
@@ -282,8 +258,7 @@ export class Researcher extends ResearcherBase {
     async ensureNavigated(url, screenshot) {
         if (!this.actionResult) {
             debugLog('No action result, navigating to URL');
-            await this.explorer.visit(url);
-            this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot });
+            this.actionResult = await this.explorer.visit(url, { screenshot });
             return;
         }
         const isOnCurrentState = this.actionResult.getStateHash() === this.stateManager.getCurrentState()?.hash;
@@ -291,34 +266,32 @@ export class Researcher extends ResearcherBase {
         const isEmpty = isBodyEmpty(stateHtml);
         if (!isEmpty && isOnCurrentState) {
             if ((!this.actionResult.screenshot && screenshot) || !this.actionResult.ariaSnapshot) {
-                this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot });
+                this.actionResult = await this.explorer.capture({ screenshot });
             }
             return;
         }
         if (isEmpty && isOnCurrentState) {
             debugLog('HTML body empty on current URL, waiting for content');
             tag('step').log('Page body is empty, waiting for content...');
-            await this.explorer.visit(url);
-            this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot ?? false });
+            this.actionResult = await this.explorer.visit(url, { screenshot: screenshot ?? false });
             await this.waitUntilSettled(screenshot ?? false);
             return;
         }
         debugLog('Not on current state, navigating to URL');
         tag('step').log('Navigating to URL...');
-        await this.explorer.visit(url);
-        this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot ?? false });
+        this.actionResult = await this.explorer.visit(url, { screenshot: screenshot ?? false });
     }
     async waitUntilSettled(screenshot) {
-        const errorPageTimeout = this.explorer.getConfig().ai?.agents?.researcher?.errorPageTimeout ?? 10;
+        const errorPageTimeout = this.config.ai?.agents?.researcher?.errorPageTimeout ?? 10;
         if (errorPageTimeout <= 0)
             return false;
         const includeScreenshot = screenshot && this.provider.hasVision();
         try {
-            await this.explorer.runWithBrowserRecovery('waitUntilSettled', () => this.explorer.playwrightHelper.page?.waitForLoadState('networkidle', { timeout: errorPageTimeout * 1000 }));
+            await this.explorer.withPage((page) => page.waitForLoadState('networkidle', { timeout: errorPageTimeout * 1000 }));
         }
         catch { }
-        await this.explorer.annotateElements();
-        this.actionResult = await this.explorer.capturePageState({ includeScreenshot });
+        await this.explorer.withPage(annotatePageElements);
+        this.actionResult = await this.explorer.capture({ screenshot: includeScreenshot });
         let condition = detectPageCondition(this.actionResult);
         if (condition === 'error') {
             throw new ErrorPageError(this.actionResult.url, this.actionResult.title, this.actionResult.httpStatus);
@@ -327,8 +300,8 @@ export class Researcher extends ResearcherBase {
             return true;
         for (let i = 0; i < 3; i++) {
             await new Promise((r) => setTimeout(r, 1000));
-            await this.explorer.annotateElements();
-            this.actionResult = await this.explorer.capturePageState({ includeScreenshot });
+            await this.explorer.withPage(annotatePageElements);
+            this.actionResult = await this.explorer.capture({ screenshot: includeScreenshot });
             condition = detectPageCondition(this.actionResult);
             if (condition === 'error') {
                 throw new ErrorPageError(this.actionResult.url, this.actionResult.title, this.actionResult.httpStatus);
@@ -339,7 +312,7 @@ export class Researcher extends ResearcherBase {
         return false;
     }
     getConfiguredSections() {
-        const configSections = this.explorer.getConfig().ai?.agents?.researcher?.sections;
+        const configSections = this.config.ai?.agents?.researcher?.sections;
         if (!configSections?.length)
             return POSSIBLE_SECTIONS;
         const filtered = {};
@@ -365,7 +338,10 @@ export class Researcher extends ResearcherBase {
       - Research all menus and navigational areas.
       - Ignore decorative sidebars, footer-only links, and external links.
       - Detect layout patterns: list/detail split, 2-pane, or 3-pane layouts.
-      - Every element with an eidx attribute MUST appear in the UI map — describe icon-only buttons by their visual role.
+      - In split-pane layouts, keep global toolbar, list pane, and detail pane as separate sections. Do not copy toolbar/list elements into the detail section unless they are physically inside that detail container.
+      - If the URL or page state opens an entity detail panel, describe that panel as the active detail context and include its close/back/pin controls when present.
+      - If an element has data-explorbot-hit="covered" or "offscreen", do not present it as directly actionable. Prefer the overlay, drawer, dialog, or focused section covering it, and mention what must be dismissed or revealed first.
+      - Every element with an eidx attribute MUST appear in exactly one matching UI map section — describe icon-only buttons by their visual role.
       - Every UI map row needs a CSS selector; ARIA may be "-" for icon-only buttons, CSS must never be "-".
       - ARIA locator JSON uses keys "role" and "text" (NOT "name").
       - Mark elements with likely hover interactions (title, aria-describedby, menu items with submenus) as "(hover)".
@@ -382,6 +358,7 @@ export class Researcher extends ResearcherBase {
             .join('\n')}
 
       - Sections can overlap; prefer more detailed sections over broader ones.
+      - Section tables must list only elements physically inside the declared container. If a control belongs to a global toolbar, list it only in the toolbar section.
       - Never name a section "Focus" or "Focused" — use what it contains (Detail, Modal, Form, Content, List).
       - Omit sections that are not present or not relevant.
       - Each section needs a container CSS locator; UI map CSS locators are relative to it.
@@ -402,21 +379,7 @@ export class Researcher extends ResearcherBase {
         if (!this.actionResult)
             throw new Error('actionResult is not set');
         const html = await this.actionResult.combinedHtml();
-        const knowledgeFiles = this.stateManager.getRelevantKnowledge();
-        let knowledge = '';
-        if (knowledgeFiles.length > 0) {
-            const knowledgeContent = knowledgeFiles
-                .map((k) => k.content)
-                .filter((k) => !!k)
-                .join('\n\n');
-            tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')} for: ${this.actionResult.url}`);
-            knowledge = `
-        <hint>
-        Here is relevant knowledge for this page:
-
-        ${knowledgeContent}
-        </hint>`;
-        }
+        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(this.actionResult);
         const ariaSnapshot = this.actionResult.getCompactARIA();
         return dedent `
       Analyze this web page and provide a comprehensive research report in markdown format.
@@ -471,35 +434,6 @@ export class Researcher extends ResearcherBase {
 
     `;
     }
-    async textContent(state) {
-        const actionResult = ActionResult.fromState(state);
-        const html = await actionResult.combinedHtml();
-        const prompt = dedent `
-      Transform into markdown.
-      Identify headers, footers, asides, special application parts and main contant.
-      Content should be in markdown format. If it is content: tables must be tables, lists must be lists.
-      Navigation elements should be represented as standalone blocks after the content.
-      Do not summarize content, just transform it into markdown.
-      It is important to list all the content text
-      If it is link it must be linked
-      You can summarize footers/navigation/aside elements.
-      But main conteint should be kept as text and formatted as markdown based on its current markup.
-      Links to external web sites should be avoided in output.
-
-      Break down into sections:
-
-      ## Content Area
-
-      ## Navigation Area
-
-      <page_html>
-      ${html}
-      </page_html>
-    `;
-        const model = this.provider.getModelForAgent('researcher');
-        const r = await this.provider.chat([{ role: 'user', content: prompt }], model, { agentName: 'researcher', telemetryFunctionId: 'researcher.textContent' });
-        return r.text;
-    }
     getScreenshotFromState(state) {
         const actionResult = ActionResult.fromState(state);
         const image = actionResult.screenshot;
@@ -692,9 +626,9 @@ export class Researcher extends ResearcherBase {
     }
     async cancelInUi() {
         const beforeAria = this.stateManager.getCurrentState()?.ariaSnapshot || null;
-        await this.explorer.executeAction('I.clickXY(0, 0)');
-        if (diffAriaSnapshots(beforeAria, this.stateManager.getCurrentState()?.ariaSnapshot || null))
+        await this.explorer.action().execute('I.clickXY(0, 0)');
+        if (diffAriaSnapshots(beforeAria, this.stateManager.getCurrentState()?.ariaSnapshot || null).text)
             return;
-        await this.explorer.executeAction(`I.pressKey('Escape')`);
+        await this.explorer.action().execute(`I.pressKey('Escape')`);
     }
 }

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

@@ -1,5 +1,6 @@
 export declare const recommendedCodeceptCommands: readonly ["I.click", "I.type", "I.fillField", "I.see", "I.seeElement"];
 export declare const locatorRule: string;
+export declare const drillLocatorRule: string;
 export declare const fileUploadRule: string;
 export declare const formRequirementsRule: string;
 export declare const protectionRule: string;

package/dist/src/ai/rules.js

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 export const recommendedCodeceptCommands = ['I.click', 'I.type', 'I.fillField', 'I.see', 'I.seeElement'];
-export const locatorRule = dedent `
+const locatorPriorityRule = dedent `
   <locator_priority>
   Use the following priority when selecting locators:
 
@@ -17,10 +17,11 @@ export const locatorRule = dedent `
      Example: '#login-btn', '[data-testid="submit"]', 'form#login input[name="email"]'
 
   4. XPath (last resort) - for complex hierarchy or when CSS can't express the path
-     Always start with //, never use positional indices like [1], [2]
+     Always start with //. Avoid positional indices like [1], [2] except as a last-resort disambiguator
      Example: '//form[@id="login"]//input[@name="email"]'
   </locator_priority>
-
+`;
+const contextSimplificationRule = dedent `
   <context_simplification>
   When container is available from UI map sections:
   - Text + container is simplest and PREFERRED: I.click('Save', '.modal')
@@ -28,7 +29,8 @@ export const locatorRule = dedent `
   - ALWAYS use context parameter unless locator is XPath or unique ID
   - No need for complex ARIA when container narrows scope sufficiently
   </context_simplification>
-
+`;
+const locatorStrategyRule = dedent `
   <disambiguation>
   When multiple elements could match the request, select based on intent:
   1. Match the context of recent actions - if filling a form, use elements in that same form
@@ -46,8 +48,9 @@ export const locatorRule = dedent `
   - Use aria-label value if present: { "role": "button", "text": "Close" } (from aria-label="Close")
   - Use title attribute if present: { "role": "button", "text": "Settings" } (from title="Settings")
   - If no accessible name exists, mark ARIA as "-" and use CSS/XPath:
-    * CSS: use partial href a[href*="settings"] or SVG icon class a:has(svg.md-icon-cog)
-    * XPath: use contains(@href,"settings") or SVG class //a[.//svg[contains(@class,"md-icon-cog")]]
+    * CSS: use partial href a[href*="settings"] or SVG icon class a:has(svg.icon-settings)
+    * XPath: use contains(@href,"settings") or SVG class //a[.//svg[contains(@class,"icon-settings")]]
+  - In inline create/edit rows, confirmation can be an icon-only control near the edited field instead of a text Save button. Anchor the locator to the same row/form as the field and target the adjacent confirm icon/control.
   - NEVER use empty text: { "role": "button", "text": "" } is INVALID and useless
 
   <good_aria_locator_example>
@@ -78,9 +81,9 @@ export const locatorRule = dedent `
   - Vue: data-v-* attributes
   Avoid locators that seem to have generated ids or class names (long random numbers, uuids, hashes, etc)
   Prefer text or ARIA locators over href-based ones. But for icon-only links with no accessible name, use:
-  - Partial href match: a[href*="settings"], a[href*="requirements"] (use path segments, not full URLs)
-  - SVG icon class: a:has(svg.md-icon-cog), button:has(svg.md-icon-plus) (target the SVG class inside the link/button)
-  Avoid full absolute href like a[href="/projects/imr_manual12/settings"] — use generic path segments instead
+  - Partial href match: a[href*="settings"], a[href*="reports"] (use path segments, not full URLs)
+  - SVG icon class: a:has(svg.icon-settings), button:has(svg.icon-add) (target the SVG class inside the link/button)
+  Avoid full absolute href like a[href="/items/12345/settings"] — use generic path segments instead
   Avoid CSS framework utility classes as containers (Tailwind: flex, grid, space-x-*, justify-*, items-*, w-*, h-*, p-*, m-*, etc; Bootstrap: col-*, row, d-flex, etc)
   Prefer semantic class names, roles, data attributes, or element hierarchy for containers
 
@@ -92,7 +95,7 @@ export const locatorRule = dedent `
 
   <xpath_rules>
   XPath locators must start with //.
-  XPath should use positional indices [1], [2], [3] and contains(., "text") for disambiguation.
+  XPath may use positional indices [1], [2] and contains(., "text") as a last-resort disambiguator when attribute/text strategies are exhausted.
   XPath should rely less on class names — prefer element hierarchy, position, and text content.
   XPath and CSS MUST provide different strategies for finding the same element.
   </xpath_rules>
@@ -104,21 +107,23 @@ export const locatorRule = dedent `
     '#content-top #user_name'
     '#content-top form input[name="name"]'
     'a.nav-item[href*="settings"]' // icon-only link matched by partial href
-    'a.nav-item:has(svg.md-icon-cog)' // icon-only link matched by SVG icon class
+    'a.nav-item:has(svg.icon-settings)' // icon-only link matched by SVG icon class
     '//nav//a[contains(@href,"settings")]' // XPath for icon-only nav link
   </good locator example>
 
   <bad locator example>
-    'a.filter-tab:nth-of-type(1)' // WRONG: positional in CSS, use :has-text("Manual") instead
-    '//a[contains(@class,"filter-tab") and contains(@class,"active")]' // WRONG: XPath repeats CSS approach, use positional //a[contains(@class,"filter-tab")][1]
+    'a.filter-tab:nth-of-type(1)' // WRONG: positional in CSS, use :has-text("Active") instead
+    '//a[contains(@class,"filter-tab") and contains(@class,"active")]' // WRONG: XPath repeats CSS approach, provide a different strategy e.g. //a[contains(@class,"filter-tab")][1]
     '//table//tbody/tr[1]//button[contains(@onclick,'fn()')]' // onclick is not semantic attribute
     '//html/body/vue-button-123' // vue-framework specific locator
-    'link "New Template"'  // WRONG: malformed string, use {"role":"link","text":"New Template"}
-    'a[href="/projects/imr_manual12/settings"]' // WRONG: full absolute href, use a[href*="settings"] instead
+    'link "New Item"'  // WRONG: malformed string, use {"role":"link","text":"New Item"}
+    'a[href="/items/12345/settings"]' // WRONG: full absolute href, use a[href*="settings"] instead
   </bad locator example>
 
   HTML locators must be valid JS strings
 `;
+export const locatorRule = [locatorPriorityRule, contextSimplificationRule, locatorStrategyRule].join('\n\n');
+export const drillLocatorRule = [locatorPriorityRule, locatorStrategyRule].join('\n\n');
 export const fileUploadRule = dedent `
   <file_upload>
   Explorbot CAN upload files using I.attachFile() via form() tool.
@@ -294,6 +299,7 @@ export const actionRule = dedent `
   Use context parameter (second argument) to narrow click area when:
   - The same text/button appears multiple times on page
   - You need to click inside a specific form, modal, or section
+  - You need an icon-only confirm/save control next to a field in an inline create/edit row
   Context should be a CSS selector pointing to a unique container.
 
   <example>
@@ -306,6 +312,7 @@ export const actionRule = dedent `
   </example>
 
   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.
 

package/dist/src/ai/session-analyst.js

@@ -42,6 +42,9 @@ export class SessionAnalyst {
       ## Severity (defects only)
       [High] blocks a core flow · [Medium] degrades a flow but workaround exists · [Low] cosmetic / edge case
 
+      ## Naming tests
+      Reference every test by its full label wrapped in backticks: \`\`\`ET-<number> <test title>\`\`\` — the \`ref\` and \`scenario\` from its \`<test>\` block. Backticks only, never bold. Never write a bare \`#2\`.
+
       ## Format
 
       # Session Analysis
@@ -53,22 +56,22 @@ export class SessionAnalyst {
       - Features: <capabilities>
 
       ## What works
-      - **<feature>** — #2, #7, #8
+      - **<feature>** — \`ET-2 <title>\`, \`ET-7 <title>\`
 
       ## Defects
 
       ### [Medium] <plain-English bug title>
-      Affects: #3, #5
+      Affects: \`ET-3 <title>\`, \`ET-5 <title>\`
       Reproduce:
         1. <concrete UI step>
         2. <next>
       Evidence: <one short observation>
 
       ## UX issues
-      - **<feature>** — <what's confusing> (#7)
+      - **<feature>** — <what's confusing> (\`ET-7 <title>\`)
 
       ## Execution Issues
-      - **#2 <scenario>** — <≤10 words, what was unreliable>
+      - \`ET-2 <title>\` — <≤10 words, what was unreliable>
 
       ## Brevity rules
 
@@ -127,7 +130,7 @@ export class SessionAnalyst {
         `
             : 'verification_status: none';
         return dedent `
-      <test ref="#${ref}">
+      <test ref="ET-${ref}">
       url: ${test.startUrl || '/'}
       scenario: ${test.scenario}
       result: ${test.result || 'unknown'}

package/dist/src/ai/task-agent.d.ts

@@ -1,27 +1,40 @@
 import type { ActionResult } from '../action-result.js';
-import { type ExperienceTracker } from '../experience-tracker.js';
+import type { ExplorbotConfig } from '../config.js';
+import type { ExperienceTracker } from '../experience-tracker.js';
+import type Explorer from '../explorer.js';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
+import type { StateManager } from '../state-manager.js';
+import { HooksRunner } from '../utils/hooks-runner.js';
+import type { AgentDeps, ToolDeps } from './agent.js';
 import { Historian } from './historian.js';
 import type { Navigator } from './navigator.js';
 import type { Provider } from './provider.js';
 import { Quartermaster } from './quartermaster.js';
 export declare function isInteractive(): boolean;
 export declare abstract class TaskAgent {
+    explorer: Explorer;
+    provider: Provider;
+    config: ExplorbotConfig;
+    stateManager: StateManager;
+    knowledgeTracker: KnowledgeTracker;
+    hooksRunner: HooksRunner;
     consecutiveFailures: number;
     consecutiveEmptyResults: number;
     recentToolCalls: any[];
     readonly ACTION_TOOLS: string[];
     _historian: Historian | null;
     _quartermaster: Quartermaster | null;
+    constructor(deps?: AgentDeps);
+    setHistorian(historian: Historian): void;
+    setQuartermaster(quartermaster: Quartermaster): void;
     abstract getNavigator(): Navigator;
-    abstract getExperienceTracker(): ExperienceTracker;
-    abstract getKnowledgeTracker(): KnowledgeTracker;
-    abstract getProvider(): Provider;
+    get toolDeps(): ToolDeps;
+    getExperienceTracker(): ExperienceTracker;
+    getKnowledgeTracker(): KnowledgeTracker;
+    getProvider(): Provider;
     getKnowledge(actionResult: ActionResult): string;
     getExperience(actionResult: ActionResult): string;
-    setHistorian(historian: Historian): void;
     getHistorian(): Historian;
-    setQuartermaster(quartermaster: Quartermaster): void;
     getQuartermaster(): Quartermaster;
     trackToolExecutions(toolExecutions: any[]): void;
     resetFailureCount(): void;

package/dist/src/ai/task-agent.js

@@ -1,7 +1,4 @@
-import dedent from 'dedent';
-import { renderExperienceToc } from '../experience-tracker.js';
-import { createDebug, pluralize, tag } from '../utils/logger.js';
-const debugLog = createDebug('explorbot:task-agent');
+import { HooksRunner } from "../utils/hooks-runner.js";
 export function isInteractive() {
     return process.env.INK_RUNNING === 'true';
 }
@@ -11,50 +8,57 @@ function createNullProxy() {
     });
 }
 export class TaskAgent {
+    explorer;
+    provider;
+    config;
+    stateManager;
+    knowledgeTracker;
+    hooksRunner;
     consecutiveFailures = 0;
     consecutiveEmptyResults = 0;
     recentToolCalls = [];
     ACTION_TOOLS = [];
     _historian = null;
     _quartermaster = null;
-    getKnowledge(actionResult) {
-        const knowledgeFiles = this.getKnowledgeTracker().getRelevantKnowledge(actionResult);
-        if (knowledgeFiles.length === 0)
-            return '';
-        const knowledgeContent = knowledgeFiles
-            .map((k) => k.content)
-            .filter((k) => !!k)
-            .join('\n\n');
-        tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')}`);
-        return dedent `
-      <knowledge>
-      Here is relevant knowledge for this page:
-
-      ${knowledgeContent}
-      </knowledge>
-    `;
-    }
-    getExperience(actionResult) {
-        const tracker = this.getExperienceTracker();
-        const toc = tracker.getExperienceTableOfContents(actionResult);
-        if (toc.length === 0)
-            return '';
-        const totalSections = toc.reduce((sum, entry) => sum + entry.sections.length, 0);
-        debugLog(`injecting experience TOC (${toc.length} files, ${totalSections} sections)`);
-        tag('operation').log(`Found ${toc.length} experience ${pluralize(toc.length, 'file')} (${totalSections} sections)`);
-        return renderExperienceToc(toc);
+    constructor(deps) {
+        if (!deps)
+            return;
+        this.explorer = deps.explorer;
+        this.provider = deps.ai;
+        this.config = deps.config;
+        this.stateManager = deps.stateManager;
+        this.knowledgeTracker = deps.knowledgeTracker;
+        this.hooksRunner = new HooksRunner(deps.explorer, deps.config);
     }
     setHistorian(historian) {
         this._historian = historian;
     }
+    setQuartermaster(quartermaster) {
+        this._quartermaster = quartermaster;
+    }
+    get toolDeps() {
+        return { explorer: this.explorer, stateManager: this.stateManager, ai: this.provider };
+    }
+    getExperienceTracker() {
+        return this.stateManager.getExperienceTracker();
+    }
+    getKnowledgeTracker() {
+        return this.knowledgeTracker;
+    }
+    getProvider() {
+        return this.provider;
+    }
+    getKnowledge(actionResult) {
+        return this.getKnowledgeTracker().renderRelevantKnowledge(actionResult);
+    }
+    getExperience(actionResult) {
+        return this.getExperienceTracker().renderExperienceTocFor(actionResult);
+    }
     getHistorian() {
         if (this._historian)
             return this._historian;
         return createNullProxy();
     }
-    setQuartermaster(quartermaster) {
-        this._quartermaster = quartermaster;
-    }
     getQuartermaster() {
         if (this._quartermaster)
             return this._quartermaster;