explorbot 0.1.32-beta.1 → 0.2.0

package/dist/src/ai/tools.js

@@ -3,7 +3,7 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { TestResult } from '../test-plan.js';
-import { extractFocusedElement } from "../utils/aria.js";
+import { LARGE_ARIA_CHANGE_THRESHOLD, extractFocusedElement } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
@@ -31,6 +31,7 @@ export function createCodeceptJSTools(explorer, task) {
         CRITICAL: All commands MUST target the SAME element using different locators.
         This is a FALLBACK list, NOT a sequence of different clicks.
         If you need to click multiple different elements, make SEPARATE click() calls.
+        Inline create/edit UIs may use icon-only confirm controls near the edited field instead of text buttons. Target the nearest actionable icon/control in the same row or form.
       `,
             inputSchema: z.object({
                 commands: z.array(z.string()).describe(dedent `
@@ -71,19 +72,14 @@ export function createCodeceptJSTools(explorer, task) {
                 const attempts = [];
                 for (let i = 0; i < commands.length; i++) {
                     const command = transformContainsCommand(commands[i]);
-                    const isLast = i === commands.length - 1;
-                    const success = await action.attempt(command, explanation, isLast);
-                    attempts.push({
-                        command,
-                        success,
-                        ...(action.lastError && { error: action.lastError.toString() }),
-                    });
+                    const success = await action.attempt(command, explanation);
+                    const attempt = { command, success };
+                    if (action.lastError)
+                        attempt.error = action.lastError.toString();
+                    attempts.push(attempt);
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
-                        if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                            activeNote.screenshot = await action.saveScreenshot();
-                        }
-                        activeNote.commit(TestResult.PASSED);
+                        await commitNote(activeNote, TestResult.PASSED, toolResult, action);
                         return successToolResult('click', { ...toolResult, attempts, code: command }, action);
                     }
                 }
@@ -100,23 +96,17 @@ export function createCodeceptJSTools(explorer, task) {
                     }
                     retryCommands.push(`I.click('${disambiguated.xpath.replace(/'/g, "\\'")}')`);
                     for (const retryCmd of retryCommands) {
-                        if (!(await action.attempt(retryCmd, explanation, true))) {
+                        if (!(await action.attempt(retryCmd, explanation))) {
                             attempts.push({ command: retryCmd, success: false, error: action.lastError?.toString() });
                             continue;
                         }
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, retryCmd);
-                        if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                            activeNote.screenshot = await action.saveScreenshot();
-                        }
-                        activeNote.commit(TestResult.PASSED);
+                        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]);
-                if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                    activeNote.screenshot = await action.saveScreenshot();
-                }
-                activeNote.commit(TestResult.FAILED);
+                await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                 let suggestion = "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
                 const lastError = attempts[attempts.length - 1]?.error || '';
                 if (lastError.includes('was not found') || lastError.includes('not found by text')) {
@@ -176,12 +166,11 @@ export function createCodeceptJSTools(explorer, task) {
                 const action = explorer.createAction();
                 const attempts = [];
                 for (const command of commands) {
-                    const success = await action.attempt(command, explanation, true);
-                    attempts.push({
-                        command,
-                        success,
-                        ...(action.lastError && { error: action.lastError.toString() }),
-                    });
+                    const success = await action.attempt(command, explanation);
+                    const attempt = { command, success };
+                    if (action.lastError)
+                        attempt.error = action.lastError.toString();
+                    attempts.push(attempt);
                     if (!success)
                         continue;
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
@@ -239,10 +228,7 @@ export function createCodeceptJSTools(explorer, task) {
                         await action.attempt(typeCommand, explanation);
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, key);
                         if (!action.lastError) {
-                            if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                                activeNote.screenshot = await action.saveScreenshot();
-                            }
-                            activeNote.commit(TestResult.PASSED);
+                            await commitNote(activeNote, TestResult.PASSED, toolResult, action);
                             return successToolResult('pressKey', {
                                 ...toolResult,
                                 message: `Automatically used type() for "${key}" (not a standard key press)`,
@@ -251,10 +237,7 @@ export function createCodeceptJSTools(explorer, task) {
                             }, action);
                         }
                         const errorMsg = `pressKey fallback to type() failed: ${action.lastError?.toString()}`;
-                        if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                            activeNote.screenshot = await action.saveScreenshot();
-                        }
-                        activeNote.commit(TestResult.FAILED);
+                        await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                         return failedToolResult('pressKey', errorMsg, {
                             ...toolResult,
                             code: typeCommand,
@@ -286,10 +269,7 @@ export function createCodeceptJSTools(explorer, task) {
                     await action.attempt(pressKeyCommand, explanation);
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, key);
                     if (!action.lastError) {
-                        if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                            activeNote.screenshot = await action.saveScreenshot();
-                        }
-                        activeNote.commit(TestResult.PASSED);
+                        await commitNote(activeNote, TestResult.PASSED, toolResult, action);
                         return successToolResult('pressKey', {
                             ...toolResult,
                             message: `Pressed key: ${key}${modifier ? ` with modifier(s): ${Array.isArray(modifier) ? modifier.join('+') : modifier}` : ''}`,
@@ -297,10 +277,7 @@ export function createCodeceptJSTools(explorer, task) {
                         }, action);
                     }
                     const errorMsg = `pressKey() failed: ${action.lastError?.toString()}`;
-                    if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                        activeNote.screenshot = await action.saveScreenshot();
-                    }
-                    activeNote.commit(TestResult.FAILED);
+                    await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                     return failedToolResult('pressKey', errorMsg, {
                         ...toolResult,
                         code: pressKeyCommand,
@@ -310,7 +287,7 @@ export function createCodeceptJSTools(explorer, task) {
                 catch (error) {
                     throwIfFatalBrowserError(error);
                     activeNote.commit(TestResult.FAILED);
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     return failedToolResult('pressKey', `PressKey tool failed: ${errorMessage}`);
                 }
             },
@@ -379,10 +356,7 @@ export function createCodeceptJSTools(explorer, task) {
                     const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, formLocator);
                     if (action.lastError) {
                         const message = action.lastError ? String(action.lastError) : 'Unknown error';
-                        if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                            activeNote.screenshot = await action.saveScreenshot();
-                        }
-                        activeNote.commit(TestResult.FAILED);
+                        await commitNote(activeNote, TestResult.FAILED, toolResult, action);
                         let formSuggestion = 'Look into error message and identify which commands passed and which failed. Continue execution using step-by-step approach using click() and form() tools.';
                         if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
                             const disambiguated = await disambiguateElements(action.lastError, explanation, explorer.getAIProvider());
@@ -396,10 +370,15 @@ export function createCodeceptJSTools(explorer, task) {
                             suggestion: formSuggestion,
                         }, action.lastError);
                     }
-                    if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
-                        activeNote.screenshot = await action.saveScreenshot();
+                    if (!hasObservablePageChange(toolResult)) {
+                        activeNote.commit(TestResult.FAILED);
+                        return failedToolResult('form', 'Form command executed, but no observable page or form-state change was captured.', {
+                            ...toolResult,
+                            code: codeBlock,
+                            suggestion: 'Treat the field/form action as not completed. Re-locate the editable control, check whether another UI layer is active, then retry and verify the field value before submitting.',
+                        });
                     }
-                    activeNote.commit(TestResult.PASSED);
+                    await commitNote(activeNote, TestResult.PASSED, toolResult, action);
                     return successToolResult('form', {
                         ...toolResult,
                         message: `Form completed successfully with ${lines.length} commands.`,
@@ -411,18 +390,15 @@ export function createCodeceptJSTools(explorer, task) {
                 catch (error) {
                     throwIfFatalBrowserError(error);
                     activeNote.commit(TestResult.FAILED);
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     return failedToolResult('form', `Form tool failed: ${errorMessage}`);
                 }
             },
         }),
     };
 }
-export function createSpecialContextTools(explorer, context) {
+export function createIframeTools(explorer) {
     const stateManager = explorer.getStateManager();
-    if (context !== 'iframe') {
-        return {};
-    }
     return {
         exitIframe: tool({
             description: dedent `
@@ -453,14 +429,38 @@ export function createSpecialContextTools(explorer, context) {
                 }
                 catch (error) {
                     throwIfFatalBrowserError(error);
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     return failedToolResult('exitIframe', `Failed to exit iframe: ${errorMessage}`);
                 }
             },
         }),
     };
 }
-export function createAgentTools({ explorer, researcher, navigator, experienceTracker, getState, supervisor, }) {
+export function createLearnExperienceTool({ getExperienceTracker, getState }) {
+    return tool({
+        description: dedent `
+      Read the full body of a specific experience section listed in <experience>.
+      The TOC shows entries like "A.1 ## FLOW: ..." or "A.2 ## ACTION: ...". Pass the fileTag and sectionIndex.
+      Only call when a TOC entry looks directly relevant to the current step.
+    `,
+        inputSchema: z.object({
+            fileTag: z.string().describe('File tag from the TOC, e.g. "A", "B", "AA"'),
+            sectionIndex: z.number().int().positive().describe('1-based section index within that file'),
+        }),
+        execute: async ({ fileTag, sectionIndex }) => {
+            const state = getState();
+            if (!state) {
+                return { error: 'No current page state available.' };
+            }
+            const section = getExperienceTracker().getExperienceSection(fileTag, sectionIndex, state);
+            if (!section) {
+                return { error: 'Section not found. Experience may have been updated; re-read the latest TOC.' };
+            }
+            return section;
+        },
+    });
+}
+export function createAgentTools({ explorer, researcher, navigator, supervisor, withExperience, }) {
     let visionDisabled = false;
     const tools = {
         see: tool({
@@ -499,7 +499,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 catch (error) {
                     throwIfFatalBrowserError(error);
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     visionDisabled = true;
                     tag('warning').log('⚠️ Vision model is not available. Visual checks are disabled for this session.');
                     return failedToolResult('see', `See tool failed: ${errorMessage}`, {
@@ -545,7 +545,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                     });
                 }
                 catch (error) {
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     return failedToolResult('context', `Context tool failed: ${errorMessage}`);
                 }
             },
@@ -588,7 +588,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 catch (error) {
                     throwIfFatalBrowserError(error);
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     return failedToolResult('verify', `Verify tool failed: ${errorMessage}`, {
                         error: errorMessage,
                     });
@@ -641,7 +641,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 catch (error) {
                     throwIfFatalBrowserError(error);
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     return failedToolResult('research', `Research tool failed: ${errorMessage}`, {
                         error: errorMessage,
                     });
@@ -681,7 +681,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 catch (error) {
                     throwIfFatalBrowserError(error);
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     return failedToolResult('interact', `Interact tool failed: ${errorMessage}`, {
                         error: errorMessage,
                     });
@@ -749,7 +749,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
                 catch (error) {
                     throwIfFatalBrowserError(error);
-                    const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+                    const errorMessage = errorText(error);
                     visionDisabled = true;
                     tag('warning').log('⚠️ Vision model is not available. Visual clicks are disabled for this session.');
                     return failedToolResult('visualClick', `visualClick tool failed: ${errorMessage}`, {
@@ -785,20 +785,23 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                         suggestion: 'Use reset() to navigate to the starting page.',
                     });
                 }
+                let previousState = null;
+                if (currentState)
+                    previousState = ActionResult.fromState(currentState);
                 const action = explorer.createAction();
                 const success = await action.attempt(`I.amOnPage(${JSON.stringify(targetUrl)})`, `${reason} (BACK to ${targetUrl})`);
                 if (success) {
-                    const previousState = ActionResult.fromState(stateManager.getCurrentState());
-                    const toolResult = await previousState.toToolResult(previousState, `I.amOnPage("${targetUrl}")`);
+                    const newState = ActionResult.fromState(stateManager.getCurrentState());
+                    const toolResult = await newState.toToolResult(previousState, `I.amOnPage("${targetUrl}")`);
                     return successToolResult('back', {
                         ...toolResult,
                         message: `Navigated back to ${targetUrl}`,
                     });
                 }
-                return failedToolResult('back', `Failed to navigate back to ${targetUrl}`, {
-                    suggestion: 'Try reset() to return to the starting page.',
-                    ...(action.lastError && { error: action.lastError.toString() }),
-                });
+                const failData = { suggestion: 'Try reset() to return to the starting page.' };
+                if (action.lastError)
+                    failData.error = action.lastError.toString();
+                return failedToolResult('back', `Failed to navigate back to ${targetUrl}`, failData);
             },
         }),
         getVisitedStates: tool({
@@ -816,7 +819,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                     return true;
                 })
                     .map((s, i) => ({ index: i, url: s.url, title: s.title, h1: s.h1 }));
-                return { success: true, states };
+                return successToolResult('getVisitedStates', { states });
             },
         }),
         xpathCheck: tool({
@@ -859,39 +862,37 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                     });
                 }
                 const action = explorer.createAction();
-                const visible = await action.attempt(`I.seeElement(${JSON.stringify(xpath)})`, 'xpathCheck visibility', false);
+                const visible = await action.attempt(`I.seeElement(${JSON.stringify(xpath)})`, 'xpathCheck visibility');
+                const liveElement = await WebElement.fromPlaywrightLocator(explorer.playwrightHelper.page.locator(`xpath=${xpath}`));
                 const matchesSummary = result.elements.map((el, i) => `${i + 1}. <${el.tag} ${el.keyAttrs}> text="${el.text}" html: ${el.outerHTML}`).join('\n');
                 const visibilityNote = visible ? 'Element IS visible in browser — Tester can use this XPath as locator.' : 'Element exists in DOM but is NOT visible. May need scrolling, a click to reveal, or is hidden.';
+                const hit = liveElement?.ourAttr('hit') || null;
+                const coveredBy = liveElement?.ourAttr('coveredBy') || null;
+                let resolvedVisibilityNote = visibilityNote;
+                if (hit === 'covered') {
+                    resolvedVisibilityNote = `Element exists in DOM and is visible, but is covered by ${coveredBy || 'another UI layer'}. Dismiss or move the covering UI before interacting with it.`;
+                }
+                if (hit === 'offscreen') {
+                    resolvedVisibilityNote = 'Element exists in DOM but its interaction point is outside the viewport. Scroll or reveal it before interacting.';
+                }
                 return successToolResult('xpathCheck', {
                     totalFound: result.totalFound,
                     matches: matchesSummary,
-                    visibilityNote,
+                    visibilityNote: resolvedVisibilityNote,
+                    hit,
+                    coveredBy,
                     xpath,
                 });
             },
         }),
     };
-    if (experienceTracker && getState) {
-        tools.learnExperience = tool({
-            description: dedent `
-        Read the full body of a specific experience section listed in <experience>.
-        The TOC shows entries like "A.1 ## FLOW: ..." or "A.2 ## ACTION: ...". Pass the fileTag and sectionIndex.
-        Only call when a TOC entry looks directly relevant to the current step.
-      `,
-            inputSchema: z.object({
-                fileTag: z.string().describe('File tag from the TOC, e.g. "A", "B", "AA"'),
-                sectionIndex: z.number().int().positive().describe('1-based section index within that file'),
-            }),
-            execute: async ({ fileTag, sectionIndex }) => {
-                const state = getState();
-                if (!state) {
-                    return { error: 'No current page state available.' };
-                }
-                const section = experienceTracker.getExperienceSection(fileTag, sectionIndex, state);
-                if (!section) {
-                    return { error: 'Section not found. Experience may have been updated; re-read the latest TOC.' };
-                }
-                return section;
+    if (withExperience !== false) {
+        tools.learnExperience = createLearnExperienceTool({
+            getExperienceTracker: () => explorer.getStateManager().getExperienceTracker(),
+            getState: () => {
+                const stateManager = explorer.getStateManager();
+                const currentState = stateManager.getCurrentState();
+                return currentState ? ActionResult.fromState(currentState) : null;
             },
         });
     }
@@ -970,11 +971,16 @@ function transformContainsCommand(command) {
     }
     return command;
 }
-function countAriaChanges(ariaChanges) {
-    const addedCount = (ariaChanges.match(/\n {4}- /g) || []).length;
-    const removedMatch = ariaChanges.match(/removed: (\d+) interactive/);
-    const removedCount = removedMatch ? Number.parseInt(removedMatch[1]) : 0;
-    return addedCount + removedCount;
+function errorText(error) {
+    if (error instanceof Error)
+        return error.toString();
+    return 'Unknown error occurred';
+}
+async function commitNote(activeNote, result, toolResult, action) {
+    if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
+        activeNote.screenshot = await action.saveScreenshot();
+    }
+    activeNote.commit(result);
 }
 function successToolResult(action, data, source) {
     const result = { success: true, action, ...data };
@@ -989,7 +995,7 @@ function successToolResult(action, data, source) {
         const ariaChanges = data.pageDiff.ariaChanges || '';
         const urlChanged = data.pageDiff.urlChanged === true;
         const hasHtmlParts = Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
-        if (countAriaChanges(ariaChanges) >= 50) {
+        if (isMajorPageChange(data.pageDiff)) {
             suggestion = `MAJOR PAGE CHANGE. Page entered a different mode. Check htmlParts and iframes in pageDiff before next action. ${suggestion}`;
         }
         else if (!urlChanged && !ariaChanges && !hasHtmlParts) {
@@ -1002,6 +1008,18 @@ function successToolResult(action, data, source) {
     }
     return result;
 }
+export function isMajorPageChange(pageDiff) {
+    return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
+}
+function hasObservablePageChange(data) {
+    if (!data?.pageDiff)
+        return false;
+    if (data.pageDiff.urlChanged === true)
+        return true;
+    if (data.pageDiff.ariaChanges)
+        return true;
+    return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
+}
 async function failedToolResult(action, message, data, error) {
     const result = { success: false, action, message, ...data };
     if (data?.pageDiff) {
@@ -1098,7 +1116,7 @@ async function disambiguateElements(error, explanation, provider) {
     }
 }
 function getNotFoundSuggestion(errorMessage) {
-    if (!errorMessage.includes('was not found') && !errorMessage.includes('not found by text|CSS|XPath')) {
+    if (!errorMessage.includes('not found')) {
         return null;
     }
     return dedent `

package/dist/src/commands/compact-command.d.ts

@@ -1,4 +1,4 @@
-import type { ExperienceFile } from '../ai/experience-compactor.js';
+import type { ExperienceFile } from '../experience-tracker.js';
 import type { ExperienceTracker } from '../experience-tracker.js';
 import { BaseCommand, type Suggestion } from './base-command.js';
 export declare class CompactCommand extends BaseCommand {

package/dist/src/commands/compact-command.js

@@ -1,8 +1,8 @@
 import { basename } from 'node:path';
 import chalk from 'chalk';
+import { COMPACT_MAX_LENGTH } from '../ai/experience-compactor.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
-const COMPACT_THRESHOLD = 5000;
 export class CompactCommand extends BaseCommand {
     name = 'compact';
     description = 'Compact stored experience files; optionally filtered by filename or URL substring';
@@ -16,7 +16,7 @@ export class CompactCommand extends BaseCommand {
         const target = remaining[0];
         const dryRun = !!opts.dryRun;
         const merge = opts.merge !== false;
-        const tracker = this.explorBot.getExperienceTracker();
+        const tracker = this.explorBot.experienceTracker();
         const files = this.resolveTarget(tracker, target);
         if (files === null) {
             tag('info').log('No experience files found.');
@@ -51,7 +51,7 @@ export class CompactCommand extends BaseCommand {
     buildDryRunSuggestions(compactor, files, target) {
         const wouldTouch = files.filter((f) => {
             const stripped = compactor.stripNonUsefulEntries(f.content);
-            return stripped !== f.content || stripped.length >= COMPACT_THRESHOLD || compactor.isRecent(f);
+            return stripped !== f.content || stripped.length >= COMPACT_MAX_LENGTH || compactor.isRecent(f);
         });
         if (wouldTouch.length === 0)
             return [];
@@ -62,7 +62,7 @@ export class CompactCommand extends BaseCommand {
     async runFullSweep(compactor, merge) {
         if (!merge) {
             tag('info').log('Compacting all experience files (merge skipped)…');
-            const compacted = await compactor.compactFiles(this.explorBot.getExperienceTracker().getAllExperience());
+            const compacted = await compactor.compactFiles(this.explorBot.experienceTracker().getAllExperience());
             return { merged: 0, compacted };
         }
         tag('info').log('Merging experience files with similar URLs, then compacting all…');
@@ -101,7 +101,7 @@ export class CompactCommand extends BaseCommand {
             const charsRemoved = chars - strippedChars;
             const willStrip = stripped !== file.content;
             const willReview = compactor.isRecent(file);
-            const willAi = strippedChars >= COMPACT_THRESHOLD;
+            const willAi = strippedChars >= COMPACT_MAX_LENGTH;
             if (willStrip)
                 wouldStrip++;
             if (willReview)
@@ -131,7 +131,7 @@ export class CompactCommand extends BaseCommand {
         lines.push(`  ${chalk.dim('Files matched:')}      ${chalk.bold(String(files.length))}`);
         lines.push(`  ${chalk.dim('Would strip:')}        ${chalk.bold(String(wouldStrip))} ${chalk.dim('(remove legacy / FAILED / Visual click, rename to FLOW/ACTION)')}`);
         lines.push(`  ${chalk.dim('Would ai-review:')}    ${chalk.bold(String(wouldAiReview))} ${chalk.dim('(recent files ≤30d — quality/reusability check)')}`);
-        lines.push(`  ${chalk.dim('Would ai-compact:')}   ${chalk.bold(String(wouldAiCompact))} ${chalk.dim(`(over ${COMPACT_THRESHOLD} chars after strip)`)}`);
+        lines.push(`  ${chalk.dim('Would ai-compact:')}   ${chalk.bold(String(wouldAiCompact))} ${chalk.dim(`(over ${COMPACT_MAX_LENGTH} chars after strip)`)}`);
         lines.push(`  ${chalk.dim('Total chars:')}        ${chalk.bold(String(totalChars))}`);
         tag('info').log(lines.join('\n'));
     }

package/dist/src/commands/context-command.js

@@ -36,7 +36,7 @@ export class ContextCommand extends BaseCommand {
         }
         const actionResult = await explorer.createAction().capturePageState({ includeScreenshot: isVisual });
         const experienceTracker = explorer.getStateManager().getExperienceTracker();
-        const knowledgeTracker = this.explorBot.getKnowledgeTracker();
+        const knowledgeTracker = this.explorBot.knowledgeTracker();
         let mode = 'compact';
         if (opts.full) {
             mode = 'full';

package/dist/src/commands/context-knowledge-command.js

@@ -13,7 +13,7 @@ export class ContextKnowledgeCommand extends BaseCommand {
             throw new Error('No active page');
         }
         const actionResult = ActionResult.fromState(state);
-        const knowledgeTracker = this.explorBot.getKnowledgeTracker();
+        const knowledgeTracker = this.explorBot.knowledgeTracker();
         const knowledge = knowledgeTracker.getRelevantKnowledge(actionResult);
         if (knowledge.length === 0) {
             tag('info').log(`No knowledge found for: ${actionResult.url}`);

package/dist/src/commands/experience-command.js

@@ -16,7 +16,7 @@ export class ExperienceCommand extends BaseCommand {
             return;
         }
         const recency = opts.recent ? 'recent' : opts.old ? 'old' : undefined;
-        const tracker = this.explorBot.getExperienceTracker();
+        const tracker = this.explorBot.experienceTracker();
         const [first, second] = remaining;
         const combinedRef = first?.match(/^([A-Z]+)[.\-]?(\d+)$/i);
         if (combinedRef) {

package/dist/src/commands/knows-command.js

@@ -17,7 +17,7 @@ export class KnowsCommand extends BaseCommand {
     description = 'List all knowledge URLs or show matching knowledge for a URL';
     async execute(args, limit = 0) {
         const url = args.trim();
-        const tracker = this.explorBot.getKnowledgeTracker();
+        const tracker = this.explorBot.knowledgeTracker();
         if (!url) {
             const allKnowledge = tracker.listAllKnowledge();
             if (allKnowledge.length === 0) {

package/dist/src/commands/learn-command.js

@@ -10,10 +10,12 @@ export class LearnCommand extends BaseCommand {
         const note = args.trim();
         if (!note) {
             const AddKnowledge = (await import('../components/AddKnowledge.js')).default;
-            const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+            const explorer = this.explorBot.getExplorer();
+            const state = explorer.getStateManager().getCurrentState();
             const initialUrl = state?.url || '';
             const { unmount } = render(React.createElement(AddKnowledge, {
                 initialUrl,
+                knowledgeTracker: explorer.getKnowledgeTracker(),
                 onComplete: () => unmount(),
                 onCancel: () => unmount(),
             }), {

package/dist/src/components/AddKnowledge.d.ts

@@ -1,6 +1,8 @@
 import React from 'react';
+import type { KnowledgeTracker } from '../knowledge-tracker.js';
 interface AddKnowledgeProps {
     initialUrl?: string;
+    knowledgeTracker: KnowledgeTracker;
     onComplete?: () => void;
     onCancel?: () => void;
 }

package/dist/src/components/AddKnowledge.js

@@ -1,8 +1,7 @@
 import { Box, Text, useInput } from 'ink';
 import React, { useEffect, useState } from 'react';
-import { KnowledgeTracker } from '../knowledge-tracker.js';
 import InputReadline from './InputReadline.js';
-const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
+const AddKnowledge = ({ initialUrl = '', knowledgeTracker, onComplete, onCancel }) => {
     const [urlPattern, setUrlPattern] = useState(initialUrl);
     const [description, setDescription] = useState('');
     const [activeField, setActiveField] = useState(initialUrl ? 'description' : 'url');
@@ -11,18 +10,16 @@ const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
     const isStandalone = !onComplete;
     useEffect(() => {
         try {
-            const knowledgeTracker = new KnowledgeTracker();
             const urls = knowledgeTracker.getExistingUrls();
             setSuggestedUrls(urls);
         }
         catch (error) {
             console.error('Failed to load suggestions:', error);
         }
-    }, []);
+    }, [knowledgeTracker]);
     useEffect(() => {
         if (urlPattern.trim()) {
             try {
-                const knowledgeTracker = new KnowledgeTracker();
                 const knowledge = knowledgeTracker.getKnowledgeForUrl(urlPattern);
                 setExistingKnowledge(knowledge);
             }
@@ -34,13 +31,12 @@ const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
         else {
             setExistingKnowledge([]);
         }
-    }, [urlPattern]);
+    }, [urlPattern, knowledgeTracker]);
     const handleSave = () => {
         if (!urlPattern.trim() || !description.trim()) {
             return;
         }
         try {
-            const knowledgeTracker = new KnowledgeTracker();
             const result = knowledgeTracker.addKnowledge(urlPattern.trim(), description.trim());
             const action = result.isNewFile ? 'Created' : 'Updated';
             console.log(`\nKnowledge ${action} in: ${result.filename}`);

package/dist/src/components/App.js

@@ -111,7 +111,7 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
                 return;
             setChecklistData({
                 config: explorBot.getConfig(),
-                knowledgeTracker: explorBot.getKnowledgeTracker(),
+                knowledgeTracker: explorBot.knowledgeTracker(),
             });
             setShowWelcome(true);
             setShowInput(true);
@@ -283,7 +283,7 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
         React.createElement(Box, { height: 3, flexDirection: "row", justifyContent: "space-between", alignItems: "center", paddingX: 1 },
             React.createElement(ActivityPane, { isInputVisible: showInput }),
             showSessionTimer && React.createElement(SessionTimer, { startedAt: sessionStartedAtRef.current })),
-        showWelcome && React.createElement(WelcomeCommands, { hasKnowledge: explorBot.getKnowledgeTracker().listAllKnowledge().length > 0 }),
+        showWelcome && React.createElement(WelcomeCommands, { hasKnowledge: explorBot.knowledgeTracker().listAllKnowledge().length > 0 }),
         showInput && React.createElement(Box, { height: 1 }),
         interruptPrompt && showInput && (React.createElement(Box, { paddingX: 1 },
             React.createElement(Text, { color: "yellow" }, interruptPrompt))),