explorbot 0.1.9 → 0.1.11

package/dist/src/ai/researcher/sections.js

@@ -22,7 +22,14 @@ export function WithSections(Base) {
             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();

package/dist/src/ai/researcher.js

@@ -2,16 +2,16 @@ import dedent from 'dedent';
 import { ActionResult } from '../action-result.js';
 import { setActivity } from "../activity.js";
 import { outputPath } from "../config.js";
+import { executionController } from "../execution-controller.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
 import { diffAriaSnapshots } from "../utils/aria.js";
-import { isErrorPage } from "../utils/error-page.js";
+import { ErrorPageError, detectPageCondition } from "../utils/error-page.js";
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { isBodyEmpty } from "../utils/html.js";
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { mdq } from "../utils/markdown-query.js";
-import { withRetry } from "../utils/retry.js";
-import { executionController } from "../execution-controller.js";
+import { RulesLoader } from "../utils/rules-loader.js";
 import { ContextLengthError } from './provider.js';
 import { findSimilarResearch, getCachedResearch, saveResearch } from "./researcher/cache.js";
 import { WithCoordinates } from "./researcher/coordinates.js";
@@ -22,7 +22,6 @@ import { extractValidContainers, formatResearchSummary, parseResearchSections }
 import { ResearchResult } from "./researcher/research-result.js";
 import { WithSections } from "./researcher/sections.js";
 import { locatorRule as generalLocatorRuleText } from './rules.js';
-import { RulesLoader } from "../utils/rules-loader.js";
 import { TaskAgent } from "./task-agent.js";
 const debugLog = createDebug('explorbot:researcher');
 export const POSSIBLE_SECTIONS = {
@@ -98,18 +97,15 @@ export class Researcher extends ResearcherBase {
             const annotatedElements = await this.explorer.annotateElements();
             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`);
                 }
             }
             debugLog('Researching web page:', this.actionResult.url);
@@ -292,41 +288,47 @@ export class Researcher extends ResearcherBase {
             }
             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 });
     }
-    async waitForPageLoad(screenshot) {
+    async waitUntilSettled(screenshot) {
         const errorPageTimeout = this.explorer.getConfig().ai?.agents?.researcher?.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;
+            await page?.waitForLoadState('networkidle', { timeout: errorPageTimeout * 1000 });
         }
-        catch {
-            return false;
+        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;
     }
     getConfiguredSections() {
         const configSections = this.explorer.getConfig().ai?.agents?.researcher?.sections;

package/dist/src/ai/rules.js

@@ -161,6 +161,20 @@ export const focusedElementRule = dedent `
   If focus is on wrong element, click the correct field first.
   </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.
@@ -186,17 +200,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) {
     const tabsList = tabs.map((tab, i) => `  ${i + 1}. ${tab.title} - ${tab.url}`).join('\n');
@@ -265,12 +269,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>)
 
@@ -282,6 +293,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/dist/src/ai/tester.js

@@ -6,9 +6,11 @@ import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { setActivity } from "../activity.js";
 import { ConfigParser } from "../config.js";
+import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
 import { TestResult } from "../test-plan.js";
 import { detectFocusArea, extractFocusedElement } from "../utils/aria.js";
+import { ErrorPageError } from "../utils/error-page.js";
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
@@ -121,10 +123,34 @@ export class Tester extends TaskAgent {
         // Note: Markdown saving functionality removed from Conversation class
         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 }));
+    }
+    async runTestSession(task, initialState, conversation, handlers) {
+        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 };
             }
         }
         debugLog('Starting test execution with tools');
@@ -135,6 +161,8 @@ export class Tester extends TaskAgent {
         const currentUrl = this.explorer.getStateManager().getCurrentState()?.url || task.startUrl || '';
         await this.hooksRunner.runBeforeHook('tester', currentUrl);
         const offStateChange = this.explorer.getStateManager().onStateChange((event) => {
+            if (task.hasFinished)
+                return;
             if (event.toState?.url === event.fromState?.url)
                 return;
             task.addNote(`Navigated to ${event.toState?.url}`, TestResult.PASSED);
@@ -178,6 +206,10 @@ export class Tester extends TaskAgent {
                 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;
                     let nextStep = '';
@@ -199,6 +231,7 @@ export class Tester extends TaskAgent {
                 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');
@@ -273,34 +306,30 @@ export class Tester extends TaskAgent {
                         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();
                 },
             });
             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;
         }
         const finalUrl = this.explorer.getStateManager().getCurrentState()?.url || currentUrl;
@@ -391,7 +420,15 @@ export class Tester extends TaskAgent {
             this.explorer.clearOtherTabsInfo();
         }
         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 = '';
@@ -562,7 +599,7 @@ export class Tester extends TaskAgent {
     - 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
@@ -678,13 +715,25 @@ export class Tester extends TaskAgent {
         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) {
@@ -698,6 +747,18 @@ export class Tester extends TaskAgent {
                             action: 'reset',
                         };
                     }
+                    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);
@@ -776,10 +837,13 @@ export class Tester extends TaskAgent {
                     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,
@@ -852,7 +916,7 @@ export class Tester extends TaskAgent {
                     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();

package/dist/src/ai/tools.js

@@ -84,7 +84,7 @@ export function createCodeceptJSTools(explorer, 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);
                     }
                 }
                 let disambiguated = null;
@@ -109,7 +109,7 @@ export function createCodeceptJSTools(explorer, 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);
                     }
                 }
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
@@ -183,7 +183,7 @@ export function createCodeceptJSTools(explorer, task) {
                                 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()}`;
                         if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
@@ -229,7 +229,7 @@ export function createCodeceptJSTools(explorer, task) {
                             ...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()}`;
                     if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
@@ -252,14 +252,16 @@ export function createCodeceptJSTools(explorer, 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
@@ -336,7 +338,7 @@ export function createCodeceptJSTools(explorer, task) {
                         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);
@@ -509,7 +511,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                         return successToolResult('verify', {
                             message: `Verification passed: ${assertion}`,
                             code: result.successfulCodes.join('\n'),
-                        });
+                        }, { assertionSteps: result.assertionSteps });
                     }
                     return failedToolResult('verify', `Verification failed: ${assertion}`, {
                         suggestion: 'The assertion could not be verified. Check if the condition is actually present on the page or try a different assertion.',
@@ -834,7 +836,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
         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({
@@ -884,8 +886,14 @@ function countAriaChanges(ariaChanges) {
     const removedCount = removedMatch ? Number.parseInt(removedMatch[1]) : 0;
     return addedCount + removedCount;
 }
-function successToolResult(action, data) {
+function successToolResult(action, data, source) {
     const result = { 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 || '';

package/dist/src/api/request-store.js

@@ -5,6 +5,8 @@ const AUTH_HEADERS = ['authorization', 'cookie', 'x-api-key', 'x-csrf-token'];
 export class RequestStore {
     capturedRequests = [];
     madeRequests = [];
+    failedRequests = [];
+    onFailedListeners = [];
     outputDir;
     constructor(outputDir) {
         this.outputDir = outputDir;
@@ -13,6 +15,23 @@ export class RequestStore {
         this.capturedRequests.push(result);
         result.save(this.outputDir);
     }
+    addFailedRequest(result) {
+        this.failedRequests.push(result);
+        for (const cb of this.onFailedListeners) {
+            cb(result);
+        }
+    }
+    getFailedRequests() {
+        return this.failedRequests;
+    }
+    onFailedRequest(cb) {
+        this.onFailedListeners.push(cb);
+        return () => {
+            const idx = this.onFailedListeners.indexOf(cb);
+            if (idx !== -1)
+                this.onFailedListeners.splice(idx, 1);
+        };
+    }
     addMadeRequest(result) {
         this.madeRequests.push(result);
         result.save(this.outputDir);
@@ -101,6 +120,7 @@ export class RequestStore {
     clear() {
         this.capturedRequests = [];
         this.madeRequests = [];
+        this.failedRequests = [];
     }
 }
 function normalizePathPattern(urlPath) {

package/dist/src/api/xhr-capture.js

@@ -32,15 +32,31 @@ export class XhrCapture {
         if (resourceType !== 'xhr' && resourceType !== 'fetch')
             return;
         const method = request.method();
-        if (!WRITE_METHODS.has(method))
-            return;
         const url = request.url();
         if (!url.startsWith(this.baseOrigin))
             return;
+        const status = response.status();
+        if (status >= 400) {
+            const failedUrl = new URL(url);
+            const failure = new RequestResult({
+                id: generateRequestId(method, failedUrl.pathname, 'fail_'),
+                method,
+                path: failedUrl.pathname,
+                fullUrl: failedUrl.pathname + failedUrl.search,
+                requestHeaders: {},
+                status,
+                statusText: response.statusText(),
+                responseHeaders: {},
+                timing: 0,
+                timestamp: new Date(),
+            });
+            this.store.addFailedRequest(failure);
+        }
+        if (!WRITE_METHODS.has(method))
+            return;
         const contentType = response.headers()['content-type'] || '';
         if (!JSON_CONTENT_TYPES.test(contentType))
             return;
-        const status = response.status();
         if (status === 304)
             return;
         const parsedUrl = new URL(url);

package/dist/src/browser-server.js

@@ -2,7 +2,9 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from '
 import path from 'node:path';
 import { chromium, firefox, webkit } from 'playwright-core';
 import { ConfigParser } from './config.js';
-import { log, tag } from './utils/logger.js';
+import { getCliName } from "./utils/cli-name.js";
+import { log } from './utils/logger.js';
+import { printNextSteps } from "./utils/next-steps.js";
 const ENDPOINT_FILENAME = '.browser-endpoint';
 function getEndpointFilePath() {
     const configParser = ConfigParser.getInstance();
@@ -50,8 +52,19 @@ async function launchServer(opts) {
     const wsEndpoint = server.wsEndpoint();
     writeEndpoint(wsEndpoint);
     log(`Browser server started: ${browserName} (${opts.show ? 'headed' : 'headless'})`);
-    tag('info').log(`WebSocket endpoint: ${wsEndpoint}`);
-    tag('info').log(`Endpoint saved to: ${getEndpointFilePath()}`);
+    const cli = getCliName();
+    const sections = [
+        {
+            label: 'Browser server',
+            path: getEndpointFilePath(),
+            commands: [
+                { label: 'Endpoint', command: wsEndpoint },
+                { label: 'Status', command: `${cli} browser status` },
+                { label: 'Stop', command: `${cli} browser stop` },
+            ],
+        },
+    ];
+    printNextSteps(sections);
     return server;
 }
 async function getAliveEndpoint() {

package/dist/src/command-handler.js

@@ -105,7 +105,7 @@ export class CommandHandler {
                 this.runningCommands.add(command.name);
                 try {
                     await command.execute(argsString);
-                    command.suggestions.forEach((s) => tag('step').log(s));
+                    command.printSuggestions();
                 }
                 catch (error) {
                     if (error?.name === 'AbortError')