explorbot 0.1.8 → 0.1.10

package/dist/src/ai/navigator.js

@@ -1,16 +1,17 @@
 import dedent from 'dedent';
 import { ActionResult } from '../action-result.js';
-import { ExperienceTracker } from '../experience-tracker.js';
+import { ExperienceTracker, renderExperienceToc } from '../experience-tracker.js';
 import { KnowledgeTracker } from '../knowledge-tracker.js';
 import { normalizeUrl } from '../state-manager.js';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
+import { RulesLoader } from "../utils/rules-loader.js";
 import { Researcher } from "./researcher.js";
 import { actionRule, locatorRule } from './rules.js';
-import { RulesLoader } from "../utils/rules-loader.js";
 import { isInteractive } from './task-agent.js';
+import { createAgentTools } from "./tools.js";
 const debugLog = createDebug('explorbot:navigator');
 class Navigator {
     emoji = '🧭';
@@ -18,8 +19,6 @@ class Navigator {
     experienceCompactor;
     knowledgeTracker;
     experienceTracker;
-    currentAction = null;
-    currentUrl = null;
     hooksRunner;
     MAX_ATTEMPTS = Number.parseInt(process.env.MAX_ATTEMPTS || '5');
     systemPrompt = dedent `
@@ -85,9 +84,7 @@ class Navigator {
                 const actualPath = action.stateManager.getCurrentState()?.url || '';
                 const actionResult = action.actionResult || ActionResult.fromState(action.stateManager.getCurrentState());
                 const originalMessage = `Navigate to: ${url}. Current page: ${actualPath}`;
-                this.currentAction = action;
-                this.currentUrl = url;
-                const resolved = await this.resolveState(originalMessage, actionResult);
+                const resolved = await this.resolveState(originalMessage, actionResult, { action, expectedUrl: url });
                 if (!resolved) {
                     throw new Error(`Navigation to ${url} failed: redirected to ${actualPath} and could not resolve`);
                 }
@@ -99,9 +96,7 @@ class Navigator {
           And I expected to see the URL in the browser
           But I got error: ${action.lastError?.message || 'Navigation failed'}.
         `.trim();
-                this.currentAction = action;
-                this.currentUrl = url;
-                const resolved = await this.resolveState(originalMessage, actionResult);
+                const resolved = await this.resolveState(originalMessage, actionResult, { action, expectedUrl: url });
                 if (!resolved) {
                     throw new Error(`Navigation to ${url} failed: ${action.lastError?.message}`);
                 }
@@ -119,9 +114,11 @@ class Navigator {
             throw error;
         }
     }
-    async resolveState(message, actionResult) {
+    async resolveState(message, actionResult, opts) {
         tag('info').log('AI Navigator resolving state at', actionResult.url);
         debugLog('Resolution message:', message);
+        const action = opts?.action ?? this.explorer.createAction();
+        const expectedUrl = opts?.expectedUrl;
         let knowledge = '';
         let experience = '';
         const relevantKnowledge = this.knowledgeTracker.getRelevantKnowledge(actionResult);
@@ -133,24 +130,13 @@ class Navigator {
       ${knowledgeContent}
       </hint>`;
         }
-        const relevantExperience = this.experienceTracker.getRelevantExperience(actionResult).map((experience) => experience.content);
-        if (relevantExperience.length > 0) {
-            const experienceContent = relevantExperience.join('\n\n---\n\n');
-            experience = await this.experienceCompactor.compactExperience(experienceContent);
-            tag('substep').log(`Found ${relevantExperience.length} experience ${pluralize(relevantExperience.length, 'file')} for: ${actionResult.url}`);
-            experience = dedent `
-      <experience>
-      Here is the experience of interacting with the page.
-      Learn from it AND DO NOT REPEAT THE SAME MISTAKES.
-      If there was found successful solution to an issue, propose it as a first solution.
-      If there are no successful solutions, analyze failed intentions and actions to avoid them.
-      Do not try again same failed solutions
-
-      Focus on successful solutions and avoid actions and locators that caused errors in past.
-
-      ${experienceContent}
-
-      </experience>`;
+        if (!actionResult.isInsideIframe) {
+            const toc = this.experienceTracker.getExperienceTableOfContents(actionResult);
+            if (toc.length > 0) {
+                const totalSections = toc.reduce((sum, entry) => sum + entry.sections.length, 0);
+                tag('substep').log(`Found ${toc.length} experience ${pluralize(toc.length, 'file')} (${totalSections} sections) for: ${actionResult.url}`);
+                experience = renderExperienceToc(toc);
+            }
         }
         const prompt = dedent `
       <message>
@@ -185,6 +171,7 @@ class Navigator {
     `;
         const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
         conversation.addUserText(prompt);
+        const tools = this.buildExperienceTools();
         let codeBlocks = [];
         let htmlContextAdded = false;
         let codeBlockIndex = 0;
@@ -192,12 +179,12 @@ class Navigator {
         let resolved = false;
         await loop(async ({ stop }) => {
             if (codeBlocks.length === 0) {
-                const result = await this.provider.invokeConversation(conversation);
+                const result = await this.provider.invokeConversation(conversation, tools);
                 if (!result)
                     return;
                 const aiResponse = result?.response?.text;
                 debugLog('AI:', aiResponse?.split('\n')[0]);
-                debugLog('Received AI response:', aiResponse.length, 'characters');
+                debugLog('Received AI response:', aiResponse?.length ?? 0, 'characters');
                 codeBlocks = extractCodeBlocks(aiResponse ?? '');
                 codeBlockIndex = 0;
             }
@@ -227,22 +214,23 @@ class Navigator {
             }
             codeBlockIndex++;
             totalAttempts++;
+            await this.explorer.switchToMainFrame();
             debugLog(`Attempting resolution: ${codeBlock}`);
-            resolved = await this.currentAction.attempt(codeBlock, message);
-            if (this.currentUrl) {
-                await this.currentAction.getActor().wait(2);
-                const freshState = await this.currentAction.capturePageState();
-                if (normalizeUrl(freshState.url || '') === normalizeUrl(this.currentUrl)) {
+            resolved = await action.attempt(codeBlock, message);
+            if (expectedUrl) {
+                await action.getActor().wait(2);
+                const freshState = await action.capturePageState();
+                if (normalizeUrl(freshState.url || '') === normalizeUrl(expectedUrl)) {
                     resolved = true;
                 }
                 else if (resolved) {
-                    tag('warning').log(`URL verification failed: expected ${this.currentUrl}, got ${freshState.url}`);
+                    tag('warning').log(`URL verification failed: expected ${expectedUrl}, got ${freshState.url}`);
                     resolved = false;
                 }
             }
             if (resolved) {
                 tag('success').log('Navigation resolved successfully');
-                await this.experienceTracker.saveSuccessfulResolution(actionResult, message, codeBlock);
+                this.experienceTracker.writeAction(actionResult, { title: message, code: codeBlock });
                 stop();
                 return;
             }
@@ -256,9 +244,9 @@ class Navigator {
                 resolved = false;
             },
         });
-        if (!resolved && this.currentUrl) {
-            await this.currentAction.getActor().wait(1);
-            if (this.isOnExpectedPage(this.currentUrl, this.currentAction.stateManager)) {
+        if (!resolved && expectedUrl) {
+            await action.getActor().wait(1);
+            if (this.isOnExpectedPage(expectedUrl, action.stateManager)) {
                 resolved = true;
                 tag('success').log('Navigation resolved after delayed redirect');
             }
@@ -267,12 +255,12 @@ class Navigator {
             tag('error').log(`Navigation failed after ${totalAttempts} attempts`);
         }
         if (!resolved && isInteractive()) {
-            const userInput = await pause(`Navigator failed to resolve. Current: ${this.currentAction.stateManager.getCurrentState()?.url}\n` + `Target: ${this.currentUrl}\nEnter CodeceptJS commands (or press Enter to skip):`);
+            const userInput = await pause(`Navigator failed to resolve. Current: ${action.stateManager.getCurrentState()?.url}\n` + `Target: ${expectedUrl ?? '(none)'}\nEnter CodeceptJS commands (or press Enter to skip):`);
             if (userInput?.trim()) {
-                resolved = await this.currentAction.attempt(userInput, message);
-                if (resolved && this.currentUrl) {
-                    await this.currentAction.getActor().wait(1);
-                    if (!this.isOnExpectedPage(this.currentUrl, this.currentAction.stateManager)) {
+                resolved = await action.attempt(userInput, message);
+                if (resolved && expectedUrl) {
+                    await action.getActor().wait(1);
+                    if (!this.isOnExpectedPage(expectedUrl, action.stateManager)) {
                         resolved = false;
                     }
                 }
@@ -280,6 +268,23 @@ class Navigator {
         }
         return resolved;
     }
+    buildExperienceTools() {
+        const stateManager = this.explorer.getStateManager();
+        const getState = () => {
+            const s = stateManager.getCurrentState();
+            return s ? ActionResult.fromState(s) : null;
+        };
+        const { learn_experience } = createAgentTools({
+            explorer: this.explorer,
+            researcher: null,
+            navigator: this,
+            experienceTracker: this.experienceTracker,
+            getState,
+        });
+        if (!learn_experience)
+            return undefined;
+        return { learn_experience };
+    }
     async freeSail(opts, actionResult) {
         const stateManager = this.explorer.getStateManager();
         const state = stateManager.getCurrentState();
@@ -403,20 +408,13 @@ class Navigator {
       ${knowledgeContent}
       </hint>`;
         }
-        const relevantExperience = this.experienceTracker.getRelevantExperience(actionResult).map((exp) => exp.content);
-        if (relevantExperience.length > 0) {
-            const experienceContent = relevantExperience.join('\n\n---\n\n');
-            experience = await this.experienceCompactor.compactExperience(experienceContent);
-            tag('substep').log(`Found ${relevantExperience.length} experience ${pluralize(relevantExperience.length, 'file')} for: ${actionResult.url}`);
-            experience = dedent `
-      <experience>
-      Here is the experience of interacting with the page.
-      Learn from it AND DO NOT REPEAT THE SAME MISTAKES.
-      If there was found successful solution to an issue, propose it as a first solution.
-
-      ${experienceContent}
-
-      </experience>`;
+        if (!actionResult.isInsideIframe) {
+            const toc = this.experienceTracker.getExperienceTableOfContents(actionResult);
+            if (toc.length > 0) {
+                const totalSections = toc.reduce((sum, entry) => sum + entry.sections.length, 0);
+                tag('substep').log(`Found ${toc.length} experience ${pluralize(toc.length, 'file')} (${totalSections} sections) for: ${actionResult.url}`);
+                experience = renderExperienceToc(toc);
+            }
         }
         const prompt = dedent `
       <message>
@@ -454,16 +452,17 @@ class Navigator {
         tag('debug').log('Prompt:', prompt);
         const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
         conversation.addUserText(prompt);
+        const tools = this.buildExperienceTools();
         let codeBlocks = [];
         const successfulCodes = [];
         const action = this.explorer.createAction();
         await loop(async ({ stop, iteration }) => {
             if (codeBlocks.length === 0) {
-                const result = await this.provider.invokeConversation(conversation);
+                const result = await this.provider.invokeConversation(conversation, tools);
                 if (!result)
                     return;
                 const aiResponse = result?.response?.text;
-                debugLog('Received AI response:', aiResponse.length, 'characters');
+                debugLog('Received AI response:', aiResponse?.length ?? 0, 'characters');
                 tag('step').log('Verifying assertion...');
                 codeBlocks = extractCodeBlocks(aiResponse ?? '');
             }
@@ -475,6 +474,7 @@ class Navigator {
                 stop();
                 return;
             }
+            await this.explorer.switchToMainFrame();
             const verified = await action.attempt(codeBlock, message, false);
             if (verified) {
                 tag('success').log('Verification passed');

package/dist/src/ai/pilot.js

@@ -418,6 +418,28 @@ export class Pilot {
             const verifyLines = verifications.map(([a, v]) => `${v ? 'PASS' : 'FAIL'}: ${a}`);
             lines.push(`verifications: ${verifyLines.join(', ')}`);
         }
+        const consoleErrors = (state.browserLogs ?? []).filter((l) => (l.type || l.level) === 'error');
+        if (consoleErrors.length > 0) {
+            const sample = consoleErrors
+                .slice(0, 3)
+                .map((e) => e.text || e.message || String(e))
+                .join(' | ');
+            lines.push(`console errors: ${consoleErrors.length} (${sample})`);
+        }
+        else {
+            lines.push('console errors: none');
+        }
+        const failedRequests = this.explorer.getRequestStore()?.getFailedRequests() ?? [];
+        if (failedRequests.length > 0) {
+            const sample = failedRequests
+                .slice(-5)
+                .map((r) => `${r.method} ${r.path} → ${r.status}`)
+                .join(', ');
+            lines.push(`network errors: ${sample}`);
+        }
+        else {
+            lines.push('network errors: none');
+        }
         const interactiveNodes = collectInteractiveNodes(state.ariaSnapshot);
         const disabledButtons = interactiveNodes.filter((n) => n.role === 'button' && n.disabled === true && n.name).map((n) => n.name);
         lines.push(`disabled buttons: ${disabledButtons.length > 0 ? disabledButtons.join(', ') : 'none'}`);

package/dist/src/ai/planner/subpages.js

@@ -1,7 +1,7 @@
 import dedent from 'dedent';
 import { z } from 'zod';
-import { ConfigParser } from "../../config.js";
 import { normalizeUrl } from "../../state-manager.js";
+import { isDynamicSegment } from "../../utils/url-matcher.js";
 const planRegistry = new Map();
 export function registerPlan(url, plan, feature, stateHash) {
     const key = buildKey(url, feature);
@@ -27,35 +27,6 @@ function buildKey(url, feature) {
         return `${normalized}::${feature}`;
     return normalized;
 }
-export function isDynamicSegment(segment) {
-    try {
-        const configRegex = ConfigParser.getInstance().getConfig().dynamicPageRegex;
-        if (configRegex)
-            return new RegExp(configRegex, 'i').test(segment);
-    }
-    catch {
-        /* config not loaded yet */
-    }
-    // numeric: /users/123
-    if (/^\d+$/.test(segment))
-        return true;
-    // UUID: /items/550e8400-e29b-41d4-a716-446655440000
-    if (/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(segment))
-        return true;
-    // ULID: /items/01ARZ3NDEKTSV4RRFFQ69G5FAV
-    if (/^[0-9A-HJKMNP-TV-Z]{26}$/.test(segment))
-        return true;
-    // hex ID (4+ chars): /suite/70dae98a
-    if (/^[a-f0-9]{4,}$/i.test(segment))
-        return true;
-    // hex-prefixed slug (8+ hex before dash): /suite/95ef0c94-mobile
-    if (/^[a-f0-9]{8,}-/i.test(segment))
-        return true;
-    // short mixed alphanumeric (digits + letters, ≤8 chars, no dash): /item/x7f2
-    if (segment.length <= 8 && !segment.includes('-') && /\d/.test(segment) && /[a-z]/i.test(segment))
-        return true;
-    return false;
-}
 export function isTemplateMatch(urlA, urlB) {
     const partsA = normalizeUrl(urlA).split('/');
     const partsB = normalizeUrl(urlB).split('/');

package/dist/src/ai/planner.js

@@ -6,19 +6,19 @@ import { ConfigParser } from "../config.js";
 import { ExperienceTracker } from "../experience-tracker.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
+import { Suite } from "../suite.js";
 import { Plan, Test } from "../test-plan.js";
-import { planToCompactAiContext } from "../utils/test-plan-markdown.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { jsonToTable } from "../utils/markdown-parser.js";
 import { mdq } from '../utils/markdown-query.js';
+import { planToCompactAiContext } from "../utils/test-plan-markdown.js";
 import { Conversation } from "./conversation.js";
-import { getActiveStyle, getStyles } from "./planner/styles.js";
 import { WithSessionDedup } from "./planner/session-dedup.js";
+import { getActiveStyle, getStyles } from "./planner/styles.js";
 import { WithSubPages, getPlannedByStateHash, getRegisteredPlan, registerPlan } from "./planner/subpages.js";
+import { POSSIBLE_SECTIONS, Researcher } from "./researcher.js";
 import { findSimilarStateHash } from "./researcher/cache.js";
 import { hasFocusedSection } from "./researcher/focus.js";
-import { POSSIBLE_SECTIONS, Researcher } from "./researcher.js";
-import { Suite } from "../suite.js";
 import { fileUploadRule, protectionRule } from "./rules.js";
 const debugLog = createDebug('explorbot:planner');
 const TasksSchema = z.object({

package/dist/src/ai/provider.js

@@ -2,12 +2,12 @@ import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
 import { generateObject, generateText } from 'ai';
 import { clearActivity, setActivity } from "../activity.js";
-import { RulesLoader } from "../utils/rules-loader.js";
 import { executionController } from "../execution-controller.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { withRetry } from '../utils/retry.js';
+import { RulesLoader } from "../utils/rules-loader.js";
 import { Conversation } from './conversation.js';
 const debugLog = createDebug('explorbot:provider');
 const promptLog = createDebug('explorbot:provider:out');

package/dist/src/ai/rerunner.js

@@ -7,8 +7,8 @@ import { highlight } from 'cli-highlight';
 import * as codeceptjs from 'codeceptjs';
 import heal from 'codeceptjs/lib/heal';
 import aiTracePlugin from 'codeceptjs/lib/plugin/aiTrace';
-import figureSet from 'figures';
 import dedent from 'dedent';
+import figureSet from 'figures';
 import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { setActivity } from "../activity.js";
@@ -16,11 +16,11 @@ import { Stats } from "../stats.js";
 import { Task, Test, TestResult } from "../test-plan.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
+import { RulesLoader } from "../utils/rules-loader.js";
 import { loadTestSuites, printTestList } from "../utils/test-files.js";
 import { toolExecutionLabel } from "./conversation.js";
-import { locatorRule, actionRule, sectionContextRule } from "./rules.js";
+import { actionRule, locatorRule, sectionContextRule } from "./rules.js";
 import { TaskAgent } from "./task-agent.js";
-import { RulesLoader } from "../utils/rules-loader.js";
 import { createCodeceptJSTools } from "./tools.js";
 const debugLog = createDebug('explorbot:rerunner');
 export class Rerunner extends TaskAgent {

package/dist/src/ai/researcher/deep-analysis.js

@@ -1,7 +1,7 @@
 import dedent from 'dedent';
 import { ActionResult } from '../../action-result.js';
-import { detectFocusArea, diffAriaSnapshots } from "../../utils/aria.js";
 import { executionController } from "../../execution-controller.js";
+import { detectFocusArea, diffAriaSnapshots } from "../../utils/aria.js";
 import { tag } from '../../utils/logger.js';
 import { mdq } from "../../utils/markdown-query.js";
 import { getCachedResearch, saveResearch } from "./cache.js";

package/dist/src/ai/researcher/fingerprint-worker.js

@@ -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.js";

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

@@ -4,8 +4,8 @@ import { parseAriaLocator } from "../../utils/aria.js";
 import { tag } from '../../utils/logger.js';
 import { mdq } from "../../utils/markdown-query.js";
 import { WebElement } from "../../utils/web-element.js";
-import { FOCUSED_MARKER } from "./focus.js";
 import { locatorRule as generalLocatorRuleText } from '../rules.js';
+import { FOCUSED_MARKER } from "./focus.js";
 import { debugLog } from "./mixin.js";
 import { parseResearchSections } from "./parser.js";
 function firstCssSegment(css) {

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,17 @@ 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, isErrorPage } 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 +23,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 = {
@@ -102,14 +102,7 @@ export class Researcher extends ResearcherBase {
                 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.
-          `;
+                    throw new ErrorPageError(state.url, this.actionResult.title);
                 }
             }
             debugLog('Researching web page:', this.actionResult.url);

package/dist/src/ai/tools.js

@@ -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
@@ -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({

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/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')

package/dist/src/commands/add-rule-command.js

@@ -7,7 +7,7 @@ import { BaseCommand } from './base-command.js';
 export class AddRuleCommand extends BaseCommand {
     name = 'add-rule';
     description = 'Create a rule file for an agent';
-    suggestions = ['/add-rule researcher check-tooltips'];
+    suggestions = [{ command: 'add-rule researcher check-tooltips', hint: 'example — add a rule for the researcher agent' }];
     async execute(args) {
         const parts = args.trim().split(/\s+/);
         const agentName = parts[0] || '';

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

@@ -1,4 +1,8 @@
+import chalk from 'chalk';
 import { Command } from 'commander';
+import { isInteractive } from '../ai/task-agent.js';
+import { getCliName } from '../utils/cli-name.js';
+import { tag } from '../utils/logger.js';
 export class BaseCommand {
     aliases = [];
     options = [];
@@ -11,6 +15,22 @@ export class BaseCommand {
     matches(commandName) {
         return this.name === commandName || this.aliases.includes(commandName);
     }
+    printSuggestions() {
+        if (this.suggestions.length === 0)
+            return;
+        const prefix = isInteractive() ? '/' : `${getCliName()} `;
+        tag('info').log('');
+        tag('info').log(chalk.bold('Suggested:'));
+        for (const { command, hint } of this.suggestions) {
+            tag('info').log('');
+            if (!command) {
+                tag('info').log(chalk.dim(hint));
+                continue;
+            }
+            tag('info').log(chalk.dim(`${hint}:`));
+            tag('info').log(`  ${chalk.yellow(`${prefix}${command}`)}`);
+        }
+    }
     parseArgs(args) {
         const cmd = new Command();
         cmd.exitOverride();