npm - explorbot - Versions diffs - 0.2.4 → 0.3.0 - Mend

explorbot 0.2.4 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (113) hide show

package/bin/explorbot-cli.ts +19 -7
package/boat/api-tester/src/cli.ts +17 -0
package/boat/doc-collector/src/cli.ts +14 -1
package/boat/prima/README.md +96 -0
package/boat/prima/package.json +14 -10
package/boat/prima/src/cli.ts +29 -12
package/boat/prima/src/envelope.ts +35 -13
package/boat/prima/src/prima.ts +78 -45
package/dist/bin/explorbot-cli.js +19 -7
package/dist/boat/api-tester/src/cli.js +17 -0
package/dist/boat/doc-collector/src/cli.js +14 -1
package/dist/boat/prima/src/cli.js +26 -7
package/dist/boat/prima/src/envelope.js +32 -8
package/dist/boat/prima/src/prima.js +75 -43
package/dist/models.json +4 -4
package/dist/package.json +6 -2
package/dist/src/action-result.d.ts +13 -0
package/dist/src/action-result.js +46 -15
package/dist/src/action.d.ts +5 -2
package/dist/src/action.js +53 -18
package/dist/src/ai/captain/web-mode.js +1 -2
package/dist/src/ai/captain.d.ts +20 -0
package/dist/src/ai/captain.js +10 -1
package/dist/src/ai/driller.js +6 -2
package/dist/src/ai/fisherman-tools.d.ts +40 -1
package/dist/src/ai/fisherman-tools.js +39 -0
package/dist/src/ai/fisherman.js +2 -1
package/dist/src/ai/navigator.d.ts +28 -0
package/dist/src/ai/navigator.js +223 -175
package/dist/src/ai/pilot.d.ts +7 -4
package/dist/src/ai/pilot.js +89 -30
package/dist/src/ai/planner/subpages.js +2 -16
package/dist/src/ai/planner.js +1 -1
package/dist/src/ai/provider.d.ts +2 -2
package/dist/src/ai/provider.js +28 -22
package/dist/src/ai/researcher/cache.d.ts +10 -3
package/dist/src/ai/researcher/cache.js +23 -10
package/dist/src/ai/researcher/deep-analysis.js +1 -1
package/dist/src/ai/researcher/fingerprint-worker.js +21 -4
package/dist/src/ai/researcher.js +6 -4
package/dist/src/ai/rules.js +1 -5
package/dist/src/ai/session-analyst.js +2 -0
package/dist/src/ai/tester.d.ts +6 -3
package/dist/src/ai/tester.js +30 -35
package/dist/src/ai/tools.d.ts +8 -5
package/dist/src/ai/tools.js +83 -57
package/dist/src/commands/config-command.d.ts +51 -0
package/dist/src/commands/config-command.js +117 -0
package/dist/src/commands/index.js +2 -0
package/dist/src/commands/init-command.js +13 -20
package/dist/src/config.d.ts +8 -1
package/dist/src/config.js +43 -1
package/dist/src/experience-tracker.d.ts +2 -0
package/dist/src/experience-tracker.js +12 -0
package/dist/src/explorbot.js +5 -2
package/dist/src/playwright-recorder.js +6 -12
package/dist/src/remote.d.ts +3 -2
package/dist/src/remote.js +8 -2
package/dist/src/state-manager.d.ts +1 -1
package/dist/src/state-manager.js +3 -1
package/dist/src/test-plan.d.ts +9 -0
package/dist/src/test-plan.js +30 -0
package/dist/src/utils/html-diff.d.ts +5 -0
package/dist/src/utils/html-diff.js +65 -6
package/dist/src/utils/logger.d.ts +1 -1
package/dist/src/utils/logger.js +8 -0
package/dist/src/utils/strings.d.ts +2 -0
package/dist/src/utils/strings.js +32 -0
package/dist/src/utils/url-matcher.d.ts +1 -0
package/dist/src/utils/url-matcher.js +31 -2
package/docs/basics/getting-started.md +33 -10
package/docs/basics/providers.md +6 -4
package/docs/contributing/npm-package.md +73 -4
package/docs/index.json +2 -1
package/docs/reference/commands.md +3 -0
package/docs/reference/websocket.md +50 -0
package/docs/superpowers/specs/2026-08-18-prima-false-verdicts.md +159 -0
package/models.json +4 -4
package/package.json +6 -2
package/src/action-result.ts +61 -16
package/src/action.ts +56 -18
package/src/ai/captain/web-mode.ts +1 -2
package/src/ai/captain.ts +9 -1
package/src/ai/driller.ts +6 -2
package/src/ai/fisherman-tools.ts +35 -0
package/src/ai/fisherman.ts +2 -1
package/src/ai/navigator.ts +238 -179
package/src/ai/pilot.ts +104 -36
package/src/ai/planner/subpages.ts +2 -13
package/src/ai/planner.ts +1 -1
package/src/ai/provider.ts +29 -21
package/src/ai/researcher/cache.ts +29 -11
package/src/ai/researcher/deep-analysis.ts +1 -1
package/src/ai/researcher/fingerprint-worker.ts +23 -5
package/src/ai/researcher.ts +6 -4
package/src/ai/rules.ts +1 -5
package/src/ai/session-analyst.ts +2 -0
package/src/ai/tester.ts +33 -34
package/src/ai/tools.ts +88 -61
package/src/commands/config-command.ts +146 -0
package/src/commands/index.ts +2 -0
package/src/commands/init-command.ts +14 -20
package/src/config.ts +47 -2
package/src/experience-tracker.ts +13 -0
package/src/explorbot.ts +4 -2
package/src/playwright-recorder.ts +6 -11
package/src/remote.ts +8 -2
package/src/state-manager.ts +5 -2
package/src/test-plan.ts +38 -0
package/src/utils/html-diff.ts +72 -7
package/src/utils/logger.ts +9 -1
package/src/utils/strings.ts +36 -0
package/src/utils/url-matcher.ts +27 -2

package/src/ai/researcher.ts CHANGED Viewed

@@ -19,7 +19,7 @@ import { annotatePageElements } from '../utils/web-annotate.ts';
 import type { Agent, AgentDeps } from './agent.js';
 import type { Navigator } from './navigator.ts';
 import { ContextLengthError, type Provider } from './provider.js';
-import { findSimilarResearch, getCachedResearch, saveResearch } from './researcher/cache.ts';
+import { findSimilarResearch, getCachedResearch, reportResearch, saveResearch } from './researcher/cache.ts';
 import { type CoordinateMethods, WithCoordinates } from './researcher/coordinates.ts';
 import { type DeepAnalysisMethods, WithDeepAnalysis } from './researcher/deep-analysis.ts';
 import { detectFocusedSection, hasFocusedSection, markSectionAsFocused, pickDefaultFocusedSection } from './researcher/focus.ts';
@@ -97,11 +97,13 @@ export class Researcher extends ResearcherBase implements Agent {
     let retriesLeft = opts._retriesLeft ?? maxRetries;
     this.actionResult = ActionResult.fromState(state);
     const stateHash = state.hash || this.actionResult.getStateHash();
+    const researchState = { ...state, hash: stateHash };
     if (!force && stateHash) {
       const cached = getCachedResearch(stateHash);
       if (cached) {
         debugLog('Previous research result found');
+        reportResearch(stateHash, cached);
         return cached;
       }
     }
@@ -138,10 +140,10 @@ export class Researcher extends ResearcherBase implements Agent {
       const combinedHtml = await this.actionResult!.combinedHtml();
       if (!deep && !force) {
-        const similar = await findSimilarResearch(combinedHtml);
+        const similar = await findSimilarResearch(combinedHtml, state.url);
         if (similar) {
           tag('operation').log('Similar research found, reusing cached result');
-          if (stateHash) saveResearch(stateHash, similar, combinedHtml);
+          if (stateHash) saveResearch(researchState, similar, combinedHtml);
           tag('multiline').log(formatResearchSummary(similar));
           tag('success').log('Research complete (reused)');
           await this.hooksRunner.runAfterHook('researcher', state.url);
@@ -285,7 +287,7 @@ export class Researcher extends ResearcherBase implements Agent {
       let researchFile: string | null = null;
       if (stateHash) {
-        researchFile = saveResearch(stateHash, result.text, combinedHtml);
+        researchFile = saveResearch(researchState, result.text, combinedHtml);
       }
       const summaryText = mdq(result.text).query('section2(/^summary/)').query('paragraph[0]').text().trim();

package/src/ai/rules.ts CHANGED Viewed

@@ -4,10 +4,6 @@ export const recommendedCodeceptCommands = ['I.click', 'I.type', 'I.fillField',
 const locatorPriorityRule = dedent`
   <locator_priority>
-  When the page context shows the element a ref, such as [ref=e14], there is no locator to select: click it with clickRef
-  and that ref. A ref names one exact element, so it never matches the wrong one and never has to be narrowed. Everything
-  below is for elements the context gives no ref for.
   Use the following priority when selecting locators:
   1. ARIA locators (first choice) - target browser's accessibility tree, most reliable
@@ -80,7 +76,7 @@ const locatorStrategyRule = dedent`
   NEVER include \`eidx\` attribute in any locator (ARIA, CSS, XPath). It is an internal annotation.
-  If <aria> section is not present or element is not found there, fall back to CSS/XPath locators from <html> section.
+  If the element is not found in the ARIA snapshot, fall back to CSS/XPath locators from page HTML.
   Stick to semantic attributes like role, aria-*, id, class, name, data-id, etc.
   Avoid IDs that follow framework auto-generation patterns (these change on every page load):

package/src/ai/session-analyst.ts CHANGED Viewed

@@ -4,6 +4,7 @@ import dedent from 'dedent';
 import { outputPath } from '../config.ts';
 import { Stats } from '../stats.ts';
 import type { Test } from '../test-plan.ts';
+import { tag } from '../utils/logger.ts';
 import type { Agent } from './agent.ts';
 import type { Provider } from './provider.ts';
@@ -117,6 +118,7 @@ export class SessionAnalyst implements Agent {
     const dir = path.dirname(filePath);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     writeFileSync(filePath, markdown);
+    tag('data').log('report', { path: filePath, content: markdown });
     return filePath;
   }

package/src/ai/tester.ts CHANGED Viewed

@@ -11,10 +11,11 @@ import { Observability } from '../observability.ts';
 import type { StateTransition } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Test, TestResult, type TestResultType } from '../test-plan.ts';
-import { compactAriaSnapshot, detectFocusArea } from '../utils/aria.ts';
+import { detectFocusArea } from '../utils/aria.ts';
 import { ErrorPageError, isErrorPage } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
+import { compactErrorMessage } from '../utils/strings.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import type { Captain } from './captain.ts';
 import type { Conversation } from './conversation.ts';
@@ -41,6 +42,7 @@ const SAMPLE_FILES: Record<string, string> = {
 export class Tester extends TaskAgent implements Agent {
   protected readonly ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
+  protected readonly DELEGATED_ACTION_TOOLS = ['interact'];
   protected readonly SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
   emoji = '🧪';
   private requestStore: RequestStore;
@@ -96,7 +98,7 @@ export class Tester extends TaskAgent implements Agent {
     return this.currentConversation;
   }
-  async test(task: Test): Promise<{ success: boolean }> {
+  async test(task: Test, opts: TestOptions = {}): Promise<{ success: boolean }> {
     Stats.tests++;
     const state = this.stateManager.getCurrentState();
     if (!state) throw new Error('No state found');
@@ -151,11 +153,11 @@ export class Tester extends TaskAgent implements Agent {
           expected: task.expected,
         },
       },
-      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest })
+      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest }, opts)
     );
   }
-  private async runTestSession(task: Test, initialState: ActionResult, conversation: Conversation, handlers: TestSessionHandlers): Promise<{ success: boolean }> {
+  private async runTestSession(task: Test, initialState: ActionResult, conversation: Conversation, handlers: TestSessionHandlers, opts: TestOptions): Promise<{ success: boolean }> {
     const { offFailedRequest } = handlers;
     if (this.pilot) {
@@ -187,15 +189,19 @@ export class Tester extends TaskAgent implements Agent {
       return { success: task.isSuccessful };
     }
-    debugLog(`Navigating to ${task.startUrl}`);
-    try {
-      await this.explorer.visit(task.startUrl!);
-    } catch (error) {
-      const result = await this.handleLoopError(task, error);
-      if (result === 'stop') {
-        offFailedRequest?.();
-        await this.cleanupStartedTest(task);
-        return { success: task.isSuccessful };
+    if (opts.startOnCurrentPage) debugLog(`Starting on the page already open at ${task.startUrl}`);
+    if (!opts.startOnCurrentPage) {
+      debugLog(`Navigating to ${task.startUrl}`);
+      try {
+        await this.explorer.visit(task.startUrl!);
+      } catch (error) {
+        const result = await this.handleLoopError(task, error);
+        if (result === 'stop') {
+          offFailedRequest?.();
+          await this.cleanupStartedTest(task);
+          return { success: task.isSuccessful };
+        }
       }
     }
@@ -271,8 +277,6 @@ export class Tester extends TaskAgent implements Agent {
           }
           conversation.cleanupTag('page_aria', '...cleaned aria snapshot...', 1);
-          conversation.cleanupTag('page_html', '...cleaned HTML snapshot...', 1);
-          conversation.cleanupTag('experience', '...cleaned experience...', 1);
           conversation.cleanupTag('applied_experience', '...cleaned past experience...', 1);
           conversation.cleanupTag('page_ui_map', '...cleaned UI map...', 1);
           conversation.cleanupTag('page_ui_map_overlay', '...cleaned UI overlay...', 1);
@@ -410,8 +414,6 @@ export class Tester extends TaskAgent implements Agent {
       this.stalledIterations = 0;
       tag('info').log(`Pilot extending test (${extensions}/${this.MAX_EXTENSIONS})`);
       conversation.cleanupTag('page_aria', '...trimmed...', 1);
-      conversation.cleanupTag('page_html', '...trimmed...', 0);
-      conversation.cleanupTag('experience', '...trimmed...', 0);
       conversation.cleanupTag('page_ui_map', '...trimmed...', 0);
       conversation.cleanupTag('page_ui_map_overlay', '...trimmed...', 0);
       conversation.compactToolResults(1);
@@ -451,7 +453,7 @@ export class Tester extends TaskAgent implements Agent {
     const currentState = this.getCurrentState();
     const stateChanged = previousState.url !== currentState.url || previousState.hash !== currentState.hash;
-    const actionTools = [...this.ACTION_TOOLS, ...this.SPECIAL_CONTEXT_ACTION_TOOLS];
+    const actionTools = [...this.ACTION_TOOLS, ...this.DELEGATED_ACTION_TOOLS, ...this.SPECIAL_CONTEXT_ACTION_TOOLS];
     const hasSuccessfulAction = toolExecutions.some((execution) => execution.wasSuccessful && actionTools.includes(execution.toolName));
     const hasSuccessfulAssertion = toolExecutions.some((execution) => execution.wasSuccessful && this.ASSERTION_TOOLS.includes(execution.toolName));
@@ -478,6 +480,7 @@ export class Tester extends TaskAgent implements Agent {
       <rules>
       Use tools ${this.ACTION_TOOLS.join(', ')} to interact with the page.
+      Fall back to interact() when those fail, when the step needs a sequence of actions, or when your context is not enough to locate the element.
       Use tool names exactly as listed in this prompt. Do not invent combined tool names, aliases, or names with channel markers such as "commentary".
       Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
       Do not do unsuccesful clicks again.
@@ -598,13 +601,13 @@ export class Tester extends TaskAgent implements Agent {
         </page>
         <page_aria>
-        ${await this.interactiveAriaWithRefs(currentState)}
+        ${currentState.getInteractiveARIA()}
         </page_aria>
         ${uiMapSection}
         Use <page_ui_map> to understand the page structure and its main elements.
-        However, <page_ui_map> is not always up to date, use <page_aria> and <page_html> to understand the ACTUAL state of the page
-        Do not interact with elements that are not listed in <page_aria> and <page_html>
+        However, <page_ui_map> is not always up to date, use <page_aria> to understand the ACTUAL state of the page
+        Do not interact with elements that are not listed in <page_aria> or in HTML returned by tools
         Refer to information on page sections in <page_ui_map> and use container CSS locators to interact with elements inside sections
       `;
       return context;
@@ -635,17 +638,11 @@ export class Tester extends TaskAgent implements Agent {
       </page>
       <page_aria>
-      ${await this.interactiveAriaWithRefs(currentState)}
+      ${currentState.getInteractiveARIA()}
       </page_aria>
     `;
   }
-  private async interactiveAriaWithRefs(state: ActionResult): Promise<string> {
-    const withRefs = await Promise.resolve(this.explorer?.withPage?.((page: any) => page.locator('body').ariaSnapshot({ mode: 'ai' }))).catch(() => null);
-    if (!withRefs) return state.getInteractiveARIA();
-    return compactAriaSnapshot(withRefs, false);
-  }
   private finishTest(task: Test): void {
     if (!task.result) {
       if (task.hasAchievedAll()) task.finish(TestResult.PASSED);
@@ -715,7 +712,7 @@ export class Tester extends TaskAgent implements Agent {
     <rules>
     - Refer to UI Map from <page_ui_map> to understand the page structure and its main elements
-    - Use only elements that exist in the provided ARIA tree or HTML, <page_aria> and <page_html>
+    - Use only elements that exist in <page_aria> or in HTML returned by tools
     - Use tool input schemas exactly as documented. Do not invent parameter names or add fields not listed by the tool schema.
     - Use click() for buttons, links, and clickable elements ONLY - do NOT include I.fillField() or I.type() commands in click() tool
     - click() commands array is for FALLBACK LOCATORS of the SAME element, NOT for clicking different elements in sequence. If you need to click two different elements, make two separate click() calls.
@@ -738,7 +735,8 @@ export class Tester extends TaskAgent implements Agent {
     - Check for error messages to understand if there are issues
     - Verify if data was correctly saved and changes are reflected on the page
     - By default, you receive accessibility tree data which shows interactive elements and page structure
-    - Understand current context by following <page_html>, <page_aria>, and <page_ui_map>
+    - Full page HTML is never injected automatically. When ARIA is not enough, delegate to the tools that read it: verify() to assert, interact() to act
+    - Understand current context by following <page_aria> and <page_ui_map>
     - Before submitting form, check all inputs were filled in correctly using see() tool
     - When you interact with form with inputs, ensure that you click corresponding button to save its data
     - Follow <locator_priority> rules when selecting locators for all tools
@@ -790,7 +788,6 @@ export class Tester extends TaskAgent implements Agent {
   private buildScenarioBlock(task: Test, actionResult: ActionResult): string {
     const knowledge = this.getKnowledge(actionResult);
-    const experience = this.getExperience(actionResult);
     return dedent`
       <task>
@@ -820,8 +817,6 @@ export class Tester extends TaskAgent implements Agent {
       ${this.buildAvailableFiles()}
       ${knowledge}
-      ${experience}
     `;
   }
@@ -943,7 +938,7 @@ export class Tester extends TaskAgent implements Agent {
           };
           if (resetAction.lastError) {
-            result.error = resetAction.lastError.toString();
+            result.error = compactErrorMessage(resetAction.lastError);
           }
           return result;
@@ -1160,3 +1155,7 @@ export class Tester extends TaskAgent implements Agent {
 interface TestSessionHandlers {
   offFailedRequest?: () => void;
 }
+export interface TestOptions {
+  startOnCurrentPage?: boolean;
+}

package/src/ai/tools.ts CHANGED Viewed

@@ -2,12 +2,13 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
-import type { ExperienceTracker } from '../experience-tracker.ts';
+import { type ExperienceTracker, renderExperienceRecipes } from '../experience-tracker.ts';
 import { Stats } from '../stats.ts';
 import { type Task, TestResult } from '../test-plan.js';
 import { LARGE_ARIA_CHANGE_THRESHOLD } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { createDebug, tag } from '../utils/logger.js';
+import { compactErrorMessage } from '../utils/strings.ts';
 import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
@@ -34,10 +35,6 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
       description: dedent`
         Click an element by trying multiple CodeceptJS commands in order until one succeeds.
-        Use this only for elements the page context gives you no ref for. When the element shows a ref such as [ref=e14],
-        call clickRef with that ref instead — composing a locator for an element that already has a ref is wasted work,
-        and a locator can match several elements where a ref cannot.
         Follow <locator_priority> from system prompt for locator selection.
         I.click(locator) - click element matching locator
@@ -98,7 +95,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           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();
+          if (action.lastError) attempt.error = errorText(action.lastError);
           attempts.push(attempt);
           if (success) {
@@ -124,7 +121,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           for (const retryCmd of retryCommands) {
             if (!(await action.attempt(retryCmd, explanation))) {
-              attempts.push({ command: retryCmd, success: false, error: action.lastError?.toString() });
+              attempts.push({ command: retryCmd, success: false, error: errorText(action.lastError) });
               continue;
             }
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, retryCmd);
@@ -151,41 +148,6 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
       },
     }),
-    clickRef: tool({
-      description: dedent`
-        Click an element by the ref the page context gave it, e.g. [ref=e14].
-        Prefer this over click() whenever the element you want carries a ref. A ref names one exact element, so it
-        cannot match several by mistake and never needs disambiguating — it is the fastest way to click.
-        Only pass a ref that appears in the page context you were given. Never invent or guess one.
-        If it reports the ref is gone, the page has been rebuilt: get fresh context and use the new ref.
-      `,
-      inputSchema: z.object({
-        ref: z.string().describe('The ref exactly as it appears in the page context, e.g. "e14"'),
-        element: z.string().describe('Role and name of the element you are clicking, for the record'),
-      }),
-      execute: async ({ ref, element }) => {
-        const activeNote = task.startNote(`Click ${element}`);
-        const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
-        const action = explorer.action();
-        const named = await describeRef(explorer, ref);
-        const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
-        if (!(await action.attempt(run, `Click ${element}`))) {
-          activeNote.commit(TestResult.FAILED);
-          return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
-            suggestion: 'The ref may belong to an older version of the page. Get fresh context and use the ref it gives, or fall back to click() with a locator.',
-          });
-        }
-        // a ref belongs to this session only, so the run is reported as the locator a later test can replay
-        const code = named ? `I.click(${JSON.stringify(named)})` : run;
-        const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, code);
-        await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-        return successToolResult('clickRef', { ...toolResult, code }, action);
-      },
-    }),
     hover: tool({
       description: dedent`
         Move the mouse cursor to an element to reveal hover-only controls.
@@ -237,7 +199,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
         for (const command of commands) {
           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();
+          if (action.lastError) attempt.error = errorText(action.lastError);
           attempts.push(attempt);
           if (!success) continue;
@@ -320,7 +282,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
               );
             }
-            const errorMsg = `pressKey fallback to type() failed: ${action.lastError?.toString()}`;
+            const errorMsg = `pressKey fallback to type() failed: ${errorText(action.lastError)}`;
             await commitNote(activeNote, TestResult.FAILED, toolResult, action);
             return failedToolResult('pressKey', errorMsg, {
               ...toolResult,
@@ -366,7 +328,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
             );
           }
-          const errorMsg = `pressKey() failed: ${action.lastError?.toString()}`;
+          const errorMsg = `pressKey() failed: ${errorText(action.lastError)}`;
           await commitNote(activeNote, TestResult.FAILED, toolResult, action);
           return failedToolResult('pressKey', errorMsg, {
             ...toolResult,
@@ -387,8 +349,6 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
         Execute raw CodeceptJS code block with multiple commands.
         USE THIS TOOL for typing text into fields: I.fillField, I.type
-        Do not put a click on a ref-bearing element in here — clickRef with its ref is cheaper and cannot mis-target.
         Follow <actions> from system prompt for available commands.
         Follow <locator_priority> from system prompt for locator selection.
@@ -448,7 +408,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, formLocator);
           if (action.lastError) {
-            const message = action.lastError ? String(action.lastError) : 'Unknown error';
+            const message = errorText(action.lastError);
             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.';
@@ -502,6 +462,45 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
   };
 }
+export function createRefTools({ explorer, stateManager }: ToolDeps, task: Task) {
+  return {
+    clickRef: tool({
+      description: dedent`
+        Click an element by the ref the page context gave it, e.g. [ref=e14].
+        Prefer this over click() whenever the element you want carries a ref. A ref names one exact element, so it
+        cannot match several by mistake and never needs disambiguating — it is the fastest way to click.
+        Only pass a ref that appears in the page context you were given. Never invent or guess one.
+        If it reports the ref is gone, the page has been rebuilt: get fresh context and use the new ref.
+      `,
+      inputSchema: z.object({
+        ref: z.string().describe('The ref exactly as it appears in the page context, e.g. "e14"'),
+        element: z.string().describe('Role and name of the element you are clicking, for the record'),
+      }),
+      execute: async ({ ref, element }) => {
+        const activeNote = task.startNote(`Click ${element}`);
+        const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
+        const action = explorer.action();
+        const named = await describeRef(explorer, ref);
+        const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+        if (!(await action.attempt(run, `Click ${element}`))) {
+          activeNote.commit(TestResult.FAILED);
+          return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
+            suggestion: 'The ref may belong to an older version of the page. Get fresh context and use the ref it gives, or fall back to click() with a locator.',
+          });
+        }
+        // a ref belongs to this session only, so the run is reported as the locator a later test can replay
+        const code = named ? `I.click(${JSON.stringify(named)})` : run;
+        const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, code);
+        await commitNote(activeNote, TestResult.PASSED, toolResult, action);
+        return successToolResult('clickRef', { ...toolResult, code }, action);
+      },
+    }),
+  };
+}
 export function createIframeTools({ explorer, stateManager }: ToolDeps) {
   return {
     exitIframe: tool({
@@ -627,7 +626,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
         DO NOT call this if:
         - You just performed an action (pageDiff already provided in response)
-        - You already have recent <page_html>/<page_aria> in context
+        - You already have a recent <page_aria> snapshot in context
         - You're about to perform an action (you'll get pageDiff after)
         Call ONLY when:
@@ -782,12 +781,18 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
     interact: tool({
       description: dedent`
-        Execute an action on the current page using AI-powered interaction.
-        Use this to perform actions like clicking buttons, selecting options, filling forms, etc.
-        The AI will generate and try multiple CodeceptJS code strategies to accomplish the instruction.
+        Delegate one step to the Navigator, which reads the full page HTML and tries multiple CodeceptJS strategies.
+        Slower than the direct action tools — use it as a fallback, not as the default.
+        Use when:
+        - direct action tools failed and you have no better locator to try
+        - the step needs a sequence of actions to complete
+        - the element is not in the context you have
+        Describe the outcome to reach, not the locator to use.
       `,
       inputSchema: z.object({
-        instruction: z.string().describe('What action to perform on the page, e.g. "select new suite option", "click the Submit button"'),
+        instruction: z.string().describe('The step to perform on the page, described by its intent'),
       }),
       execute: async ({ instruction }) => {
         try {
@@ -799,7 +804,8 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
           const previousState = ActionResult.fromState(currentState);
           const actionResult = ActionResult.fromState(currentState);
-          const success = await navigator.resolveState(instruction, actionResult);
+          const experience = renderExperienceRecipes(explorer.activeTest?.getAppliedExperience(actionResult) ?? []);
+          const success = await navigator.resolveState(instruction, actionResult, { experience });
           const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, instruction);
@@ -810,7 +816,10 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
             });
           }
-          return failedToolResult('interact', `Failed to execute: ${instruction}`, {
+          let reason = '';
+          if (navigator.lastFailureReason) reason = `: ${navigator.lastFailureReason}`;
+          return failedToolResult('interact', `Failed to execute: ${instruction}${reason}`, {
             ...toolResult,
             suggestion: 'The action could not be completed. Try a different instruction or use more specific element descriptions.',
           });
@@ -949,7 +958,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
         }
         const failData: Record<string, any> = { suggestion: 'Try reset() to return to the starting page.' };
-        if (action.lastError) failData.error = action.lastError.toString();
+        if (action.lastError) failData.error = errorText(action.lastError);
         return failedToolResult('back', `Failed to navigate back to ${targetUrl}`, failData);
       },
     }),
@@ -1012,7 +1021,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
         if (result.totalFound === 0) {
           return failedToolResult('xpathCheck', `No elements matched XPath: ${xpath}`, {
-            suggestion: 'Try a broader expression. Examples: //*[contains(@class, "btn")], //button, //*[contains(text(), "keyword")]',
+            suggestion: 'Do not guess another expression. Narrow down from what you know about the target: its role, its visible text, its nearest labelled ancestor. Add one constraint at a time.',
           });
         }
@@ -1109,7 +1118,12 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
   return tools;
 }
-const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';
+const PAGE_DIFF_SUGGESTION =
+  'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff. messages holds text the app showed in response, requests the calls it made and consoleErrors what it logged.';
+const FAILED_REQUEST_SUGGESTION = 'The server rejected a request made by this action (see requests). The UI accepted the interaction but the operation did not complete — read messages and consoleErrors for the reason and report it instead of repeating the action.';
+const NAVIGATED_SUGGESTION = 'The action left the page. Elements are never compared across pages, so this diff carries the move itself and what the app announced in transit — an empty element diff does not mean nothing happened.';
 const ARIA_OUTPUT_CAP = 4000;
 const HTML_OUTPUT_CAP = 6000;
@@ -1151,7 +1165,7 @@ function transformContainsCommand(command: string): string {
 }
 function errorText(error: unknown): string {
-  if (error instanceof Error) return error.toString();
+  if (error instanceof Error) return compactErrorMessage(error);
   return 'Unknown error occurred';
 }
@@ -1194,7 +1208,11 @@ export function successToolResult(action: string, data?: Record<string, any>, so
     const ariaChanges = data.pageDiff.ariaChanges || '';
     const urlChanged = data.pageDiff.urlChanged === true;
     const hasHtmlParts = Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
-    if (isMajorPageChange(data.pageDiff)) {
+    if (hasFailedRequest(data.pageDiff)) {
+      suggestion = `${FAILED_REQUEST_SUGGESTION} ${suggestion}`;
+    } else if (urlChanged) {
+      suggestion = `${NAVIGATED_SUGGESTION} ${suggestion}`;
+    } else 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.';
@@ -1210,10 +1228,15 @@ export function isMajorPageChange(pageDiff: PageDiff): boolean {
   return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
 }
+export function hasFailedRequest(pageDiff: PageDiff): boolean {
+  return (pageDiff.requests ?? []).some((request) => request.status >= 400);
+}
 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;
+  if (data.pageDiff.messages?.length) return true;
   return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
@@ -1275,6 +1298,10 @@ export function clickFailureSuggestion(attempts: Array<{ error?: string }>): str
     return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
   }
+  if (errors.some((e) => e.includes('SyntaxError'))) {
+    return 'The command string never parsed as JavaScript — quotes or brackets do not match. No element was looked up, so this tells you nothing about the page. Re-emit the same intent as valid CodeceptJS.';
+  }
   const notFound = errors.filter((e) => e.includes('was not found'));
   if (notFound.length && notFound.every((e) => e.includes('was not found inside element'))) {
@@ -1369,7 +1396,7 @@ function getNotFoundSuggestion(errorMessage: string): string | null {
     Element was not found. The locator does not exist on this page.
     1. Use see() to visually analyze what elements are actually on the page
     2. Use context() to get fresh HTML and ARIA snapshot
-    3. Use ONLY locators from <page_aria> or <page_html>
+    3. Use ONLY locators from <page_aria> or from HTML returned by context()
     4. Prefer ARIA locators: { "role": "button", "text": "visible text" }
   `;
 }