explorbot 0.1.9 → 0.1.11

package/src/ai/researcher/fingerprint-worker.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from '../../utils/html-diff.ts';

package/src/ai/researcher/locators.ts

@@ -1,15 +1,15 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../../action-result.js';
-import type Explorer from '../../explorer.ts';
 import { executionController } from '../../execution-controller.ts';
+import type Explorer from '../../explorer.ts';
 import { parseAriaLocator } from '../../utils/aria.ts';
 import { tag } from '../../utils/logger.js';
 import { mdq } from '../../utils/markdown-query.ts';
 import { WebElement } from '../../utils/web-element.ts';
-import { FOCUSED_MARKER } from './focus.ts';
 import type { Conversation } from '../conversation.ts';
 import type { Provider } from '../provider.js';
 import { locatorRule as generalLocatorRuleText } from '../rules.js';
+import { FOCUSED_MARKER } from './focus.ts';
 import { type Constructor, debugLog } from './mixin.ts';
 import { parseResearchSections } from './parser.ts';
 import type { ResearchResult } from './research-result.ts';

package/src/ai/researcher/sections.ts

@@ -37,7 +37,13 @@ export function WithSections<T extends Constructor>(Base: T) {
       const parts: string[] = [];
       for (const [name, description] of targets) {
         if (executionController.isInterrupted()) break;
-        const text = await this._researchSingleSection(name, description, ariaSnapshot, focusCss);
+        let text = '';
+        try {
+          text = await this._researchSingleSection(name, description, ariaSnapshot, focusCss);
+        } catch (err) {
+          tag('warning').log(`Section "${name}" research failed, skipping: ${err instanceof Error ? err.message : err}`);
+          continue;
+        }
         if (!text) continue;
         const trimmed = text.trim();
         if (trimmed === 'NOT_PRESENT' || trimmed.startsWith('NOT_PRESENT')) continue;

package/src/ai/researcher.ts

@@ -3,6 +3,7 @@ import dedent from 'dedent';
 import { ActionResult } from '../action-result.js';
 import { setActivity } from '../activity.ts';
 import { ConfigParser, outputPath } from '../config.ts';
+import { executionController } from '../execution-controller.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
 import type { KnowledgeTracker } from '../knowledge-tracker.ts';
@@ -11,13 +12,12 @@ import type { StateManager } from '../state-manager.js';
 import { WebPageState } from '../state-manager.js';
 import { Stats } from '../stats.ts';
 import { diffAriaSnapshots } from '../utils/aria.ts';
-import { isErrorPage } from '../utils/error-page.ts';
+import { ErrorPageError, detectPageCondition } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { isBodyEmpty } from '../utils/html.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { mdq } from '../utils/markdown-query.ts';
-import { withRetry } from '../utils/retry.ts';
-import { executionController } from '../execution-controller.ts';
+import { RulesLoader } from '../utils/rules-loader.ts';
 import type { Agent } from './agent.js';
 import type { Navigator } from './navigator.ts';
 import { ContextLengthError, type Provider } from './provider.js';
@@ -30,7 +30,6 @@ import { extractValidContainers, formatResearchSummary, parseResearchSections }
 import { ResearchResult } from './researcher/research-result.ts';
 import { type SectionMethods, WithSections } from './researcher/sections.ts';
 import { locatorRule as generalLocatorRuleText } from './rules.js';
-import { RulesLoader } from '../utils/rules-loader.ts';
 import { TaskAgent } from './task-agent.ts';
 
 export type { Locator } from './researcher/locators.ts';
@@ -132,18 +131,15 @@ export class Researcher extends ResearcherBase implements Agent {
       debugLog(`Annotated ${annotatedElements.length} interactive elements with eidx`);
       this.actionResult = await this.explorer.createAction().capturePageState({ includeScreenshot: screenshot && this.provider.hasVision() });
 
-      if (isErrorPage(this.actionResult!)) {
-        const recovered = await this.waitForPageLoad(screenshot);
-        if (!recovered) {
-          tag('warning').log(`Detected error page at ${state.url}`);
-          return dedent`
-            ## Error Page Detected
-
-            URL: ${state.url}
-            Title: ${this.actionResult!.title || 'N/A'}
-
-            Research skipped. Navigate to a valid page to continue.
-          `;
+      const condition = detectPageCondition(this.actionResult!);
+      if (condition === 'error') {
+        tag('warning').log(`Detected error page at ${state.url}`);
+        throw new ErrorPageError(state.url, this.actionResult!.title);
+      }
+      if (condition === 'loading') {
+        const settled = await this.waitUntilSettled(screenshot);
+        if (!settled) {
+          tag('warning').log(`Page at ${state.url} did not finish loading within timeout, continuing with best-effort research`);
         }
       }
 
@@ -350,43 +346,52 @@ export class Researcher extends ResearcherBase implements Agent {
       return;
     }
 
-    if (isEmpty) {
-      debugLog('HTML body is empty, refreshing page');
-      tag('step').log('Page body is empty, refreshing...');
-    } else {
-      debugLog('Not on current state, navigating to URL');
-      tag('step').log('Navigating to URL...');
+    if (isEmpty && isOnCurrentState) {
+      debugLog('HTML body empty on current URL, waiting for content');
+      tag('step').log('Page body is empty, waiting for content...');
+      await this.waitUntilSettled(screenshot ?? false);
+      return;
     }
 
+    debugLog('Not on current state, navigating to URL');
+    tag('step').log('Navigating to URL...');
+
     await this.explorer.visit(url);
     this.actionResult = await this.explorer.createAction().capturePageState({ includeScreenshot: screenshot ?? false });
   }
 
-  private async waitForPageLoad(screenshot: boolean): Promise<boolean> {
+  private async waitUntilSettled(screenshot: boolean): Promise<boolean> {
     const errorPageTimeout = (this.explorer.getConfig().ai?.agents?.researcher as any)?.errorPageTimeout ?? 10;
     if (errorPageTimeout <= 0) return false;
 
+    const page = this.explorer.playwrightHelper.page;
+    const includeScreenshot = screenshot && this.provider.hasVision();
+
     try {
-      await withRetry(
-        async () => {
-          await this.explorer.annotateElements();
-          this.actionResult = await this.explorer.createAction().capturePageState({
-            includeScreenshot: screenshot && this.provider.hasVision(),
-          });
-          if (isErrorPage(this.actionResult!)) throw new Error('Error page detected');
-        },
-        {
-          maxAttempts: Math.ceil(errorPageTimeout / 3) + 1,
-          baseDelay: 1000,
-          maxDelay: 5000,
-          backoffMultiplier: 2,
-          retryCondition: (e) => e.message === 'Error page detected',
-        }
-      );
-      return true;
-    } catch {
-      return false;
+      await page?.waitForLoadState('networkidle', { timeout: errorPageTimeout * 1000 });
+    } catch {}
+
+    await this.explorer.annotateElements();
+    this.actionResult = await this.explorer.createAction().capturePageState({ includeScreenshot });
+
+    let condition = detectPageCondition(this.actionResult!);
+    if (condition === 'error') {
+      throw new ErrorPageError(this.actionResult!.url, this.actionResult!.title);
+    }
+    if (condition === 'ok') return true;
+
+    for (let i = 0; i < 3; i++) {
+      await new Promise((r) => setTimeout(r, 1000));
+      await this.explorer.annotateElements();
+      this.actionResult = await this.explorer.createAction().capturePageState({ includeScreenshot });
+      condition = detectPageCondition(this.actionResult!);
+      if (condition === 'error') {
+        throw new ErrorPageError(this.actionResult!.url, this.actionResult!.title);
+      }
+      if (condition === 'ok') return true;
     }
+
+    return false;
   }
 
   private getConfiguredSections(): Record<string, string> {

package/src/ai/rules.ts

@@ -167,6 +167,21 @@ export const focusedElementRule = dedent`
   </focused_element_actions>
 `;
 
+export const unexpectedPopupRule = dedent`
+  <unexpected_popup_rule>
+  If a modal/popup appeared that you didn't expect, dismiss it first before continuing with original task.
+  If elements become hidden or unclickable (timeout errors on visible elements), a dialog or overlay may have appeared on top.
+  If a click error mentions "intercepts pointer events", another element is covering the target — dismiss it first.
+  If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
+
+  Dismiss strategy (try in order):
+  1. I.clickXY(0, 0) — click outside the popup to close it
+  2. I.pressKey('Escape') — press Escape to dismiss
+  3. I.click('Cancel') — click Cancel button if present
+  4. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  </unexpected_popup_rule>
+`;
+
 export const sectionContextRule = dedent`
   <section_context_rule>
   Context parameter is DEFAULT for all interactions. ALWAYS use container from UI map sections unless locator is XPath or unique ID.
@@ -192,17 +207,7 @@ export const sectionContextRule = dedent`
   - Locator is a unique ID (#specific-element)
   </section_context_rule>
 
-  <unexpected_popup_rule>
-  If a modal/popup appeared that you didn't expect, dismiss it first before continuing with original task.
-  If elements become hidden or unclickable (timeout errors on visible elements), a dialog or overlay may have appeared on top.
-  If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
-
-  Dismiss strategy (try in order):
-  1. I.clickXY(0, 0) — click outside the popup to close it
-  2. I.pressKey('Escape') — press Escape to dismiss
-  3. I.click('Cancel') — click Cancel button if present
-  4. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
-  </unexpected_popup_rule>
+  ${unexpectedPopupRule}
 `;
 
 export function multipleTabsRule(tabs: Array<{ url: string; title: string }>): string {
@@ -274,12 +279,19 @@ export const actionRule = dedent`
     I.fillField('Username', 'John', '.login-form'); // fills Username inside .login-form
     I.fillField('Username', 'John'); // fills the field located by name or placeholder or label "Username" with the text "John"
     I.fillField('//user/input', 'John'); // fills the field located by XPath "//user/input" with the text "John"
-  </example>  
+    I.fillField('Description', 'Hello world', '.editor'); // works for rich text / code editors too
+  </example>
+
+  I.fillField handles plain inputs, textareas, contenteditable regions, and rich text / code editors
+  (Monaco, ProseMirror, CodeMirror, TipTap, Quill, Draft.js, Slate, etc.) transparently.
+  ALWAYS use I.fillField for rich editors — target the editor container or its nearest label/heading with a normal locator.
+  Do NOT open the editor with raw JS (executeScript, page.evaluate), do NOT dispatch synthetic events,
+  do NOT call the editor's own API (monaco.editor.setValue, view.dispatch, etc.) to write text.
 
   ### I.type
 
-  Types text into the currently focused element. Use when fillField doesn't work,
-  for instance, for highly customized input fields like Monaco editors or rich text editors.
+  Types text into the currently focused element. Use only when there is no locator you can pass to I.fillField —
+  e.g. the target is implicit (a just-opened command palette, an autocomplete that steals focus, a canvas-based surface).
 
   I.type(<text>)
 
@@ -291,6 +303,7 @@ export const actionRule = dedent`
   DOES NOT receive any locator, just text to type.
   NEVER write: I.type('text', locator) or I.type('text', {locator: '...'}) — this is INVALID.
   To type into a specific field: use I.fillField(locator, text) or I.click(locator) then I.type(text).
+  Do NOT reach for I.type just because the target looks like a rich editor — I.fillField handles those.
 
   ### I.pressKey
 

package/src/ai/task-agent.ts

@@ -1,6 +1,6 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../action-result.js';
-import { renderExperienceToc, type ExperienceTracker } from '../experience-tracker.js';
+import { type ExperienceTracker, renderExperienceToc } from '../experience-tracker.js';
 import type { KnowledgeTracker } from '../knowledge-tracker.js';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 

package/src/ai/tester.ts

@@ -8,10 +8,12 @@ import { setActivity } from '../activity.ts';
 import { ConfigParser } from '../config.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
+import { Observability } from '../observability.ts';
 import type { StateTransition, WebPageState } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Note, type Test, TestResult, type TestResultType } from '../test-plan.ts';
 import { detectFocusArea, extractFocusedElement } from '../utils/aria.ts';
+import { ErrorPageError } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { codeToMarkdown } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -154,10 +156,39 @@ export class Tester extends TaskAgent implements Agent {
     const initialPrompt = await this.buildTestPrompt(task, initialState);
     conversation.addUserText(initialPrompt);
 
+    return await Observability.run(
+      `test: ${task.scenario}`,
+      {
+        sessionId: task.sessionName,
+        tags: ['tester'],
+        input: {
+          scenario: task.scenario,
+          startUrl: task.startUrl,
+          expected: task.expected,
+        },
+      },
+      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest, page, onPageError, onConsoleMessage })
+    );
+  }
+
+  private async runTestSession(task: Test, initialState: ActionResult, conversation: Conversation, handlers: { offFailedRequest?: () => void; page: any; onPageError: (err: Error) => void; onConsoleMessage: (msg: any) => void }): Promise<{ success: boolean }> {
+    const { offFailedRequest, page, onPageError, onConsoleMessage } = handlers;
+
     if (this.pilot) {
-      const plan = await this.pilot.planTest(task, initialState);
-      if (plan) {
-        conversation.addUserText(`Pilot's test plan:\n${plan}\n\nFollow this plan while executing the test.`);
+      try {
+        const plan = await this.pilot.planTest(task, initialState);
+        if (plan) {
+          conversation.addUserText(`Pilot's test plan:\n${plan}\n\nFollow this plan while executing the test.`);
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        tag('error').log(`Pilot planning failed: ${message}`);
+        task.addNote(`Planning failed: ${message}`, TestResult.FAILED);
+        task.finish(TestResult.FAILED);
+        offFailedRequest?.();
+        page?.off('pageerror', onPageError);
+        page?.off('console', onConsoleMessage);
+        return { success: false };
       }
     }
 
@@ -173,6 +204,7 @@ export class Tester extends TaskAgent implements Agent {
     await this.hooksRunner.runBeforeHook('tester', currentUrl);
 
     const offStateChange = this.explorer.getStateManager().onStateChange((event: StateTransition) => {
+      if (task.hasFinished) return;
       if (event.toState?.url === event.fromState?.url) return;
       task.addNote(`Navigated to ${event.toState?.url}`, TestResult.PASSED);
       task.states.push(event.toState);
@@ -224,6 +256,10 @@ export class Tester extends TaskAgent implements Agent {
           conversation.cleanupTag('page_aria', '...cleaned aria snapshot...', 2);
           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);
+          conversation.compactToolResults(3);
 
           if (iteration > 1) {
             const isNewPage = this.previousUrl !== null && this.previousUrl !== currentState.url;
@@ -245,6 +281,7 @@ export class Tester extends TaskAgent implements Agent {
           const result = await this.provider.invokeConversation(conversation, tools, {
             maxToolRoundtrips: 5,
             toolChoice: 'required',
+            stopWhen: () => task.hasFinished,
           });
 
           if (!result) throw new Error('Failed to get response from provider');
@@ -329,21 +366,11 @@ export class Tester extends TaskAgent implements Agent {
                 context.setUserInput(result.message);
               }
             : undefined,
-          observability: {
-            name: `test: ${task.scenario}`,
-            agent: 'tester',
-            sessionId: task.sessionName,
-            metadata: {
-              input: {
-                scenario: task.scenario,
-                startUrl: task.startUrl,
-                expected: task.expected,
-              },
-            },
-          },
           catch: async ({ error, stop }) => {
             tag('error').log(`Test execution error: ${error}`);
-            task.addNote(`Execution error: ${error instanceof Error ? error.message : String(error)}`);
+            if (!task.hasFinished) {
+              task.addNote(`Execution error: ${error instanceof Error ? error.message : String(error)}`);
+            }
             stop();
           },
         }
@@ -352,13 +379,19 @@ export class Tester extends TaskAgent implements Agent {
       if (task.hasFinished) break;
 
       const finalState = this.getCurrentState();
-      const wantsContinue = await this.pilot!.finalReview(task, finalState, conversation);
+      const wantsContinue = await this.pilot!.finalReview(task, finalState, conversation, this.navigator);
 
       if (!wantsContinue || task.hasFinished) break;
       if (extensions >= this.MAX_EXTENSIONS) break;
 
       extensions++;
       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);
       shouldContinue = true;
     }
 
@@ -464,7 +497,13 @@ export class Tester extends TaskAgent implements Agent {
     }
 
     if (isNewUrl) {
-      const research = await this.researcher.research(currentState);
+      let research = '';
+      try {
+        research = await this.researcher.research(currentState);
+      } catch (err) {
+        if (!(err instanceof ErrorPageError)) throw err;
+        tag('warning').log(`Research skipped: ${err.message}`);
+      }
       this.pageStateHash = currentStateHash;
       this.pageActionResult = currentState;
       let uiMapSection = '';
@@ -646,7 +685,7 @@ export class Tester extends TaskAgent implements Agent {
     - Use finish() to complete the test, not record(). record() is for intermediate notes.
     - Call finish(verify) when all goals are achieved — provide an assertion to verify
     - ONLY call stop() if the scenario itself is completely irrelevant to this page and no expectations can be achieved
-    - Use reset() to navigate back to the initial page if needed. Do not call it if you are already on the initial page
+    - Use reset() ONLY as a last resort when the current page cannot host the scenario. Never reset after a successful flow just because an assertion or milestone did not match — verify differently or record() the finding instead. Reset is destructive and does not undo server-side side effects.
     - Be precise with locators (CSS or XPath)
     - Each click/type call returns the new page state automatically
     - Check for success messages from tool calls to verify if expected outcomes are achieved
@@ -769,13 +808,25 @@ export class Tester extends TaskAgent implements Agent {
     return {
       reset: tool({
         description: dedent`
-          Reset the testing flow by navigating back to the original page.
-          Use this when navigated too far from the desired state and
-          there's no clear path to achieve the expected result. This restarts the
-          testing flow from a known good state.
+          Navigate back to the start URL and discard progress in this iteration.
+          Reset is a LAST RESORT. It is destructive — any side effects already produced on the
+          server (records created, forms submitted) persist and cannot be undone by resetting.
+
+          Use reset ONLY for:
+          - navigation dead-ends where the current page cannot host the scenario
+          - irrecoverable errors that leave no actionable path forward
+
+          Do NOT use reset when:
+          - the previous action already succeeded (URL changed, record visible, confirmation shown)
+            and an assertion did not match — verify differently, record(), or finish() instead
+          - an expectation/milestone does not match app behavior but the flow worked — the work is
+            done; resetting just creates duplicates
+          - you want to "try again" after submitting a form — submitting again creates a duplicate
+
+          Pilot will review every reset and may veto it.
         `,
         inputSchema: z.object({
-          reason: z.string().optional().describe('Explanation why you need to navigate'),
+          reason: z.string().optional().describe('Explanation why reset is the only option'),
         }),
         execute: async ({ reason }) => {
           if (this.getCurrentState().isInsideIframe) {
@@ -791,6 +842,20 @@ export class Tester extends TaskAgent implements Agent {
             };
           }
 
+          task.resetCount += 1;
+
+          if (this.pilot) {
+            const currentStateForReview = this.getCurrentState();
+            const allowed = await this.pilot.reviewReset(task, currentStateForReview, reason ?? '', conversation);
+            if (!allowed) {
+              return {
+                success: false,
+                action: 'reset',
+                message: 'Reset rejected by Pilot; Continue execution',
+              };
+            }
+          }
+
           const explanation = reason ? `${reason} (RESET)` : 'Resetting to initial page';
           const targetUrl = resetUrl!;
           task.addNote(explanation);
@@ -874,11 +939,14 @@ export class Tester extends TaskAgent implements Agent {
           verify: z.string().describe('Specific assertion to verify on the page before finishing (e.g., "New item appears in the list")'),
         }),
         execute: async ({ verify }) => {
+          if (task.hasFinished) {
+            return { success: true, action: 'finish', message: 'already finished' };
+          }
           task.addNote(`Finish requested: ${verify}`);
 
           if (this.pilot) {
             const currentState = this.getCurrentState();
-            await this.pilot.reviewFinish(task, currentState, conversation);
+            await this.pilot.reviewFinish(task, currentState, conversation, this.navigator);
             if (!task.hasFinished) {
               return {
                 success: false,
@@ -953,7 +1021,7 @@ export class Tester extends TaskAgent implements Agent {
           if (input.status !== null && task.isComplete()) {
             if (this.pilot) {
               const currentState = this.getCurrentState();
-              await this.pilot.reviewCompletion(task, currentState, conversation);
+              await this.pilot.reviewCompletion(task, currentState, conversation, this.navigator);
             } else {
               const hasPassed = task.hasAchievedAny();
               task.finish(hasPassed ? TestResult.PASSED : TestResult.FAILED);

package/src/ai/tools.ts

@@ -10,9 +10,9 @@ import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
 import { Navigator } from './navigator.ts';
+import type { AIProvider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { sectionContextRule } from './rules.ts';
-import type { AIProvider } from './provider.ts';
 import { isInteractive } from './task-agent.ts';
 
 const debugLog = createDebug('explorbot:tools');
@@ -100,7 +100,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
               activeNote.screenshot = await action.saveScreenshot();
             }
             activeNote.commit(TestResult.PASSED);
-            return successToolResult('click', { ...toolResult, attempts, code: command });
+            return successToolResult('click', { ...toolResult, attempts, code: command }, action);
           }
         }
 
@@ -128,7 +128,7 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
               activeNote.screenshot = await action.saveScreenshot();
             }
             activeNote.commit(TestResult.PASSED);
-            return successToolResult('click', { ...toolResult, attempts, code: retryCmd, disambiguated: true });
+            return successToolResult('click', { ...toolResult, attempts, code: retryCmd, disambiguated: true }, action);
           }
         }
 
@@ -208,12 +208,16 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
                 activeNote.screenshot = await action.saveScreenshot();
               }
               activeNote.commit(TestResult.PASSED);
-              return successToolResult('pressKey', {
-                ...toolResult,
-                message: `Automatically used type() for "${key}" (not a standard key press)`,
-                code: typeCommand,
-                fallback: true,
-              });
+              return successToolResult(
+                'pressKey',
+                {
+                  ...toolResult,
+                  message: `Automatically used type() for "${key}" (not a standard key press)`,
+                  code: typeCommand,
+                  fallback: true,
+                },
+                action
+              );
             }
 
             const errorMsg = `pressKey fallback to type() failed: ${action.lastError?.toString()}`;
@@ -261,11 +265,15 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
               activeNote.screenshot = await action.saveScreenshot();
             }
             activeNote.commit(TestResult.PASSED);
-            return successToolResult('pressKey', {
-              ...toolResult,
-              message: `Pressed key: ${key}${modifier ? ` with modifier(s): ${Array.isArray(modifier) ? modifier.join('+') : modifier}` : ''}`,
-              code: pressKeyCommand,
-            });
+            return successToolResult(
+              'pressKey',
+              {
+                ...toolResult,
+                message: `Pressed key: ${key}${modifier ? ` with modifier(s): ${Array.isArray(modifier) ? modifier.join('+') : modifier}` : ''}`,
+                code: pressKeyCommand,
+              },
+              action
+            );
           }
 
           const errorMsg = `pressKey() failed: ${action.lastError?.toString()}`;
@@ -289,14 +297,16 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
     form: tool({
       description: dedent`
         Execute raw CodeceptJS code block with multiple commands.
-        USE THIS TOOL for all keyboard interactions: I.fillField, I.type, I.pressKey
+        USE THIS TOOL for typing text into fields: I.fillField, I.type
 
         Follow <actions> from system prompt for available commands.
         Follow <locator_priority> from system prompt for locator selection.
 
+        I.type(text) types the literal characters of its argument into the focused element.
+        To press key combination or special keys (Ctrl, Meta, Esc) use I.pressKey instead.
+
         Use cases:
         - Typing into input fields (I.fillField, I.type)
-        - Pressing keyboard keys (I.pressKey)
         - Working with iframes (switch context with I.switchTo)
         - Performing multiple form actions in a single batch
         - Complex interactions requiring sequential commands
@@ -381,13 +391,17 @@ export function createCodeceptJSTools(explorer: Explorer, task: Task) {
             activeNote.screenshot = await action.saveScreenshot();
           }
           activeNote.commit(TestResult.PASSED);
-          return successToolResult('form', {
-            ...toolResult,
-            message: `Form completed successfully with ${lines.length} commands.`,
-            commandsExecuted: lines.length,
-            code: codeBlock,
-            suggestion: 'Verify the form was filled in correctly using see() tool. If needed to submit: try click() tool or form() with I.pressKey("Enter").',
-          });
+          return successToolResult(
+            'form',
+            {
+              ...toolResult,
+              message: `Form completed successfully with ${lines.length} commands.`,
+              commandsExecuted: lines.length,
+              code: codeBlock,
+              suggestion: 'Verify the form was filled in correctly using see() tool. If needed to submit: try click() tool or form() with I.pressKey("Enter").',
+            },
+            action
+          );
         } catch (error) {
           activeNote.commit(TestResult.FAILED);
           const errorMessage = error instanceof Error ? error.toString() : 'Unknown error occurred';
@@ -587,10 +601,14 @@ export function createAgentTools({
           const result = await navigator.verifyState(assertion, actionResult);
 
           if (result.verified) {
-            return successToolResult('verify', {
-              message: `Verification passed: ${assertion}`,
-              code: result.successfulCodes.join('\n'),
-            });
+            return successToolResult(
+              'verify',
+              {
+                message: `Verification passed: ${assertion}`,
+                code: result.successfulCodes.join('\n'),
+              },
+              { assertionSteps: result.assertionSteps }
+            );
           }
 
           return failedToolResult('verify', `Verification failed: ${assertion}`, {
@@ -957,7 +975,7 @@ export function createAgentTools({
     tools.learn_experience = tool({
       description: dedent`
         Read the full body of a specific experience section listed in <experience>.
-        The TOC shows entries like "A.1 ## Successful Flow: ...". Pass the fileTag and sectionIndex.
+        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({
@@ -1015,8 +1033,14 @@ function countAriaChanges(ariaChanges: string): number {
   return addedCount + removedCount;
 }
 
-function successToolResult(action: string, data?: Record<string, any>) {
+function successToolResult(action: string, data?: Record<string, any>, source?: { playwrightGroupId?: string | null; assertionSteps?: any[] }) {
   const result: Record<string, any> = { success: true, action, ...data };
+  if (source?.playwrightGroupId) {
+    result.playwrightGroupId = source.playwrightGroupId;
+  }
+  if (source?.assertionSteps?.length) {
+    result.assertionSteps = source.assertionSteps;
+  }
   if (data?.pageDiff) {
     let suggestion = PAGE_DIFF_SUGGESTION;
     const ariaChanges = data.pageDiff.ariaChanges || '';