explorbot 0.1.32-beta.1 → 0.2.0

package/src/ai/tools.ts

@@ -1,11 +1,11 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import { ActionResult, type ToolResultMetadata } from '../action-result.ts';
+import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
 import { type Task, TestResult } from '../test-plan.js';
-import { extractFocusedElement } from '../utils/aria.ts';
+import { LARGE_ARIA_CHANGE_THRESHOLD, extractFocusedElement } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
@@ -40,6 +40,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: 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`
@@ -85,21 +86,15 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
 
         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);
+          const success = await action.attempt(command, explanation);
 
-          attempts.push({
-            command,
-            success,
-            ...(action.lastError && { error: action.lastError.toString() }),
-          });
+          const attempt: { command: string; success: boolean; error?: string } = { 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);
           }
         }
@@ -119,24 +114,18 @@ export function createCodeceptJSTools(explorer: Explorer, task: 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 || '';
@@ -208,12 +197,10 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
         const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
 
         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: string; success: boolean; error?: string } = { command, success };
+          if (action.lastError) attempt.error = action.lastError.toString();
+          attempts.push(attempt);
 
           if (!success) continue;
 
@@ -282,10 +269,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
             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',
                 {
@@ -299,10 +283,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
             }
 
             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,
@@ -339,10 +320,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
           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',
               {
@@ -355,10 +333,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
           }
 
           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,
@@ -367,7 +342,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: 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}`);
         }
       },
@@ -443,10 +418,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
 
           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)) {
@@ -468,10 +440,15 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
             );
           }
 
-          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',
             {
@@ -486,7 +463,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: 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}`);
         }
       },
@@ -494,13 +471,9 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
   };
 }
 
-export function createSpecialContextTools(explorer: Explorer, context: 'iframe') {
+export function createIframeTools(explorer: Explorer) {
   const stateManager = explorer.getStateManager();
 
-  if (context !== 'iframe') {
-    return {};
-  }
-
   return {
     exitIframe: tool({
       description: dedent`
@@ -534,7 +507,7 @@ export function createSpecialContextTools(explorer: Explorer, context: 'iframe')
           });
         } 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}`);
         }
       },
@@ -542,20 +515,43 @@ export function createSpecialContextTools(explorer: Explorer, context: 'iframe')
   };
 }
 
+export function createLearnExperienceTool({ getExperienceTracker, getState }: { getExperienceTracker: () => ExperienceTracker; getState: () => ActionResult | null }) {
+  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,
-  experienceTracker,
-  getState,
   supervisor,
+  withExperience,
 }: {
   explorer: Explorer;
   researcher: Researcher;
   navigator: Navigator;
-  experienceTracker?: ExperienceTracker;
-  getState?: () => ActionResult | null;
   supervisor?: boolean;
+  withExperience?: boolean;
 }): any {
   let visionDisabled = false;
 
@@ -600,7 +596,7 @@ export function createAgentTools({
           });
         } 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}`, {
@@ -649,7 +645,7 @@ export function createAgentTools({
             reminder: 'Context provided. Do not call context() again until you perform actions or suspect page changed.',
           });
         } catch (error) {
-          const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
+          const errorMessage = errorText(error);
           return failedToolResult('context', `Context tool failed: ${errorMessage}`);
         }
       },
@@ -700,7 +696,7 @@ export function createAgentTools({
           });
         } 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,
           });
@@ -756,7 +752,7 @@ export function createAgentTools({
           });
         } 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,
           });
@@ -801,7 +797,7 @@ export function createAgentTools({
           });
         } 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,
           });
@@ -881,7 +877,7 @@ export function createAgentTools({
           });
         } 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}`, {
@@ -921,22 +917,24 @@ export function createAgentTools({
           });
         }
 
+        let previousState: ActionResult | null = 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: Record<string, any> = { 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);
       },
     }),
 
@@ -954,7 +952,7 @@ export function createAgentTools({
             return true;
           })
           .map((s, i) => ({ index: i, url: s.url, title: s.title, h1: s.h1 }));
-        return { success: true, states };
+        return successToolResult('getVisitedStates', { states });
       },
     }),
 
@@ -1004,43 +1002,42 @@ export function createAgentTools({
         }
 
         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;
       },
     });
   }
@@ -1131,11 +1128,16 @@ function transformContainsCommand(command: string): string {
   return command;
 }
 
-function countAriaChanges(ariaChanges: string): number {
-  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: unknown): string {
+  if (error instanceof Error) return error.toString();
+  return 'Unknown error occurred';
+}
+
+async function commitNote(activeNote: any, result: TestResult, toolResult: any, action: any): Promise<void> {
+  if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
+    activeNote.screenshot = await action.saveScreenshot();
+  }
+  activeNote.commit(result);
 }
 
 function successToolResult(action: string, data?: Record<string, any>, source?: { playwrightGroupId?: string | null; assertionSteps?: any[] }) {
@@ -1151,7 +1153,7 @@ function successToolResult(action: string, data?: Record<string, any>, 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) {
       suggestion = 'Action ran without error but produced no observable change (URL, ARIA and HTML all unchanged). The locator likely matched a non-interactive ancestor or an element outside the intended control. Re-locate via xpathCheck() or verify with see() before treating this as success.';
@@ -1163,6 +1165,17 @@ function successToolResult(action: string, data?: Record<string, any>, source?:
   return result;
 }
 
+export function isMajorPageChange(pageDiff: PageDiff): boolean {
+  return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
+}
+
+function hasObservablePageChange(data?: Record<string, any>): boolean {
+  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: string, message: string, data?: Record<string, any>, error?: Error | null) {
   const result: Record<string, any> = { success: false, action, message, ...data };
   if (data?.pageDiff) {
@@ -1273,7 +1286,7 @@ async function disambiguateElements(error: Error | null | undefined, explanation
 }
 
 function getNotFoundSuggestion(errorMessage: string): string | null {
-  if (!errorMessage.includes('was not found') && !errorMessage.includes('not found by text|CSS|XPath')) {
+  if (!errorMessage.includes('not found')) {
     return null;
   }
 

package/src/commands/compact-command.ts

@@ -1,12 +1,11 @@
 import { basename } from 'node:path';
 import chalk from 'chalk';
-import type { ExperienceFile } from '../ai/experience-compactor.js';
+import { COMPACT_MAX_LENGTH } from '../ai/experience-compactor.js';
+import type { ExperienceFile } from '../experience-tracker.js';
 import type { ExperienceTracker } from '../experience-tracker.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand, type Suggestion } 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';
@@ -22,7 +21,7 @@ export class CompactCommand extends BaseCommand {
     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) {
@@ -62,7 +61,7 @@ export class CompactCommand extends BaseCommand {
   private buildDryRunSuggestions(compactor: ReturnType<typeof this.explorBot.agentExperienceCompactor>, files: ExperienceFile[], target?: string): Suggestion[] {
     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 [];
     const argsPart = target ? ` ${target}` : '';
@@ -73,7 +72,7 @@ export class CompactCommand extends BaseCommand {
   private async runFullSweep(compactor: ReturnType<typeof this.explorBot.agentExperienceCompactor>, merge: boolean): Promise<{ merged: number; compacted: number }> {
     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 };
     }
 
@@ -119,7 +118,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) wouldAiReview++;
@@ -148,7 +147,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/src/commands/context-command.ts

@@ -44,7 +44,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: ContextMode = 'compact';
     if (opts.full) {

package/src/commands/context-knowledge-command.ts

@@ -17,7 +17,7 @@ export class ContextKnowledgeCommand extends BaseCommand {
     }
 
     const actionResult = ActionResult.fromState(state);
-    const knowledgeTracker = this.explorBot.getKnowledgeTracker();
+    const knowledgeTracker = this.explorBot.knowledgeTracker();
     const knowledge = knowledgeTracker.getRelevantKnowledge(actionResult);
 
     if (knowledge.length === 0) {

package/src/commands/experience-command.ts

@@ -20,7 +20,7 @@ export class ExperienceCommand extends BaseCommand {
     }
     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);

package/src/commands/knows-command.ts

@@ -23,7 +23,7 @@ export class KnowsCommand extends BaseCommand {
 
   async execute(args: string, limit = 0): Promise<void> {
     const url = args.trim();
-    const tracker = this.explorBot.getKnowledgeTracker();
+    const tracker = this.explorBot.knowledgeTracker();
 
     if (!url) {
       const allKnowledge = tracker.listAllKnowledge();

package/src/commands/learn-command.ts

@@ -13,12 +13,14 @@ export class LearnCommand extends BaseCommand {
 
     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/src/components/AddKnowledge.tsx

@@ -1,15 +1,16 @@
 import { Box, Text, useInput } from 'ink';
 import React, { useEffect, useState } from 'react';
-import { KnowledgeTracker } from '../knowledge-tracker.js';
+import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import InputReadline from './InputReadline.js';
 
 interface AddKnowledgeProps {
   initialUrl?: string;
+  knowledgeTracker: KnowledgeTracker;
   onComplete?: () => void;
   onCancel?: () => void;
 }
 
-const AddKnowledge: React.FC<AddKnowledgeProps> = ({ initialUrl = '', onComplete, onCancel }) => {
+const AddKnowledge: React.FC<AddKnowledgeProps> = ({ initialUrl = '', knowledgeTracker, onComplete, onCancel }) => {
   const [urlPattern, setUrlPattern] = useState(initialUrl);
   const [description, setDescription] = useState('');
   const [activeField, setActiveField] = useState<'url' | 'description'>(initialUrl ? 'description' : 'url');
@@ -20,18 +21,16 @@ const AddKnowledge: React.FC<AddKnowledgeProps> = ({ initialUrl = '', 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);
       } catch (error) {
@@ -41,7 +40,7 @@ const AddKnowledge: React.FC<AddKnowledgeProps> = ({ initialUrl = '', onComplete
     } else {
       setExistingKnowledge([]);
     }
-  }, [urlPattern]);
+  }, [urlPattern, knowledgeTracker]);
 
   const handleSave = () => {
     if (!urlPattern.trim() || !description.trim()) {
@@ -49,7 +48,6 @@ const AddKnowledge: React.FC<AddKnowledgeProps> = ({ initialUrl = '', onComplete
     }
 
     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}`);