explorbot 0.1.27 → 0.1.29

package/dist/src/action.js

@@ -13,8 +13,8 @@ import { Observability } from "./observability.js";
 import { htmlCombinedSnapshot, minifyHtml } from './utils/html.js';
 import { createDebug, setStepSpanParent, tag } from './utils/logger.js';
 import { safeFilename } from "./utils/strings.js";
+import { isFatalBrowserError } from "./utils/browser-errors.js";
 const debugLog = createDebug('explorbot:action');
-const FATAL_BROWSER_ERRORS = /Frame was detached|Target closed|Execution context was destroyed|Protocol error|Session closed/i;
 class Action {
     actor;
     stateManager;
@@ -28,6 +28,7 @@ class Action {
     playwrightGroupId = null;
     assertionSteps = [];
     recorder;
+    mainDocumentStatus = undefined;
     constructor(actor, stateManager, recorder) {
         this.actor = actor;
         this.stateManager = stateManager;
@@ -63,20 +64,25 @@ class Action {
             const page = this.playwrightHelper.page;
             const frame = this.playwrightHelper.frame;
             await page?.waitForLoadState('domcontentloaded', { timeout: 10000 })?.catch(() => { });
-            const grabAll = () => Promise.all([this.actor.grabSource(), this.actor.grabTitle(), this.captureBrowserLogs()]);
+            await waitForUsablePageDom(page);
+            const grabAll = () => Promise.all([captureHtml(page, frame, this.actor), captureTitle(page, this.actor), this.captureBrowserLogs()]);
             const [html, title, browserLogs] = await grabAll().catch(async (err) => {
                 const msg = err instanceof Error ? err.message : String(err);
                 if (!/navigating and changing the content/i.test(msg))
                     throw err;
                 await page?.waitForLoadState('domcontentloaded', { timeout: 10000 })?.catch(() => { });
+                await waitForUsablePageDom(page);
                 return grabAll();
             });
             const url = page?.url() || (await this.actor.grabCurrentUrl?.());
             let screenshotFile = undefined;
+            const statesDir = outputPath('states');
+            fs.mkdirSync(statesDir, { recursive: true });
             if (includeScreenshot) {
                 const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
-                screenshotFile = await this.actor
-                    .saveScreenshot(filename)
+                const screenshotPath = join(statesDir, filename);
+                screenshotFile = await page
+                    ?.screenshot({ path: screenshotPath, fullPage: true })
                     .then(() => filename)
                     .catch((err) => {
                     debugLog('Screenshot failed, continuing without it:', err);
@@ -84,8 +90,6 @@ class Action {
                 });
             }
             // Save HTML to file
-            const statesDir = outputPath('states');
-            fs.mkdirSync(statesDir, { recursive: true });
             const htmlFile = safeFilename(`${stateHash}_${timestamp}`, '.html');
             const htmlPath = join(statesDir, htmlFile);
             fs.writeFileSync(htmlPath, html, 'utf8');
@@ -121,6 +125,7 @@ class Action {
             const result = new ActionResult({
                 html,
                 title,
+                httpStatus: await this.captureMainDocumentStatus(),
                 url,
                 browserLogs,
                 htmlFile,
@@ -136,13 +141,57 @@ class Action {
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            if (FATAL_BROWSER_ERRORS.test(msg))
+            if (isFatalBrowserError(err))
                 throw err;
             debugLog('capturePageState failed with non-fatal error:', msg);
             const url = this.playwrightHelper.page?.url?.() || '';
             return new ActionResult({ url, error: msg });
         }
     }
+    async captureMainDocumentStatus() {
+        if (this.mainDocumentStatus)
+            return this.mainDocumentStatus;
+        try {
+            const page = this.playwrightHelper.page;
+            const status = await page.evaluate(() => {
+                const navigation = performance.getEntriesByType('navigation').at(-1);
+                if (!navigation)
+                    return undefined;
+                if (new URL(navigation.name).href !== window.location.href)
+                    return undefined;
+                return navigation.responseStatus;
+            });
+            if (typeof status !== 'number')
+                return undefined;
+            if (status <= 0)
+                return undefined;
+            return status;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    captureMainDocumentResponse() {
+        const page = this.playwrightHelper.page;
+        if (!page?.on || !page?.off)
+            return () => { };
+        this.mainDocumentStatus = undefined;
+        const handler = (response) => {
+            const request = response.request();
+            if (request.resourceType() !== 'document')
+                return;
+            if (response.frame() !== page.mainFrame())
+                return;
+            const status = response.status();
+            if (typeof status !== 'number')
+                return;
+            if (status <= 0)
+                return;
+            this.mainDocumentStatus = status;
+        };
+        page.on('response', handler);
+        return () => page.off('response', handler);
+    }
     /**
      * Capture HTML snapshots of all iframes on the page
      */
@@ -200,6 +249,7 @@ class Action {
         const stepListener = attachStepLogger(executedSteps, assertionSteps);
         const groupId = this.recorder ? await this.recorder.beginAction(codeString) : null;
         this.playwrightGroupId = groupId;
+        const detachMainDocumentResponse = this.captureMainDocumentResponse();
         const activeSpan = Observability.getSpan();
         const tracer = trace.getTracer('ai');
         const stepSpan = activeSpan ? tracer.startSpan('codeceptjs.step', undefined, trace.setSpan(context.active(), activeSpan)) : null;
@@ -242,6 +292,7 @@ class Action {
             throw err;
         }
         finally {
+            detachMainDocumentResponse();
             if (groupId)
                 await this.recorder.endAction();
             detachStepLogger(stepListener);
@@ -330,6 +381,8 @@ class Action {
         }
         catch (error) {
             this.lastError = error;
+            if (isFatalBrowserError(error))
+                throw error;
             debugLog(`Attempt failed: ${codeBlock}: ${errorToString(error) || this.lastError?.toString()}`);
             return false;
         }
@@ -354,6 +407,34 @@ function errorToString(error) {
     }
     return error.message || error.toString();
 }
+async function waitForUsablePageDom(page) {
+    if (!page?.waitForFunction)
+        return;
+    await page
+        .waitForFunction(() => {
+        const body = document.body;
+        if (!body)
+            return false;
+        return body.children.length > 0 || body.textContent?.trim().length > 0;
+    }, undefined, { timeout: 5000 })
+        .catch(() => { });
+}
+async function captureHtml(page, frame, actor) {
+    if (frame?.content)
+        return frame.content();
+    if (page?.content)
+        return page.content();
+    if (actor?.grabSource)
+        return actor.grabSource();
+    throw new Error('Playwright page is unavailable for HTML capture');
+}
+async function captureTitle(page, actor) {
+    if (page?.title)
+        return page.title();
+    if (actor?.grabTitle)
+        return actor.grabTitle();
+    return '';
+}
 function sanitizeCodeBlock(code) {
     return code
         .split('\n')

package/dist/src/ai/captain/file-tools.js

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+export const CAPTAIN_ARTIFACT_DIRS = ['reports', 'plans', 'tests', 'states'];
+export const CAPTAIN_ALLOWED_READ_DIRS = ['output', 'knowledge', 'experience'];
+export const CAPTAIN_ARTIFACT_SCAN_LIMIT = 200;
+export const CAPTAIN_ARTIFACT_LIST_LIMIT = 20;
+export const CAPTAIN_READ_FILE_DEFAULT_LIMIT = 12000;
+export const CAPTAIN_READ_FILE_MAX_LIMIT = 50000;
+export const CAPTAIN_READ_FILE_MIN_LIMIT = 1000;
+export function listRecentArtifacts(outputDir) {
+    const artifacts = [];
+    for (const dir of CAPTAIN_ARTIFACT_DIRS) {
+        if (artifacts.length >= CAPTAIN_ARTIFACT_SCAN_LIMIT)
+            break;
+        const targetDir = join(outputDir, dir);
+        if (!existsSync(targetDir))
+            continue;
+        collectArtifacts(outputDir, targetDir, artifacts);
+    }
+    return artifacts
+        .sort((a, b) => b.timestamp - a.timestamp)
+        .slice(0, CAPTAIN_ARTIFACT_LIST_LIMIT)
+        .map(({ timestamp, ...artifact }) => artifact);
+}
+export function readCaptainFile(projectRoot, input, allowedDirs = CAPTAIN_ALLOWED_READ_DIRS) {
+    const resolved = resolveReadableFile(projectRoot, input.path, allowedDirs);
+    if (!resolved) {
+        return { success: false, message: 'File is outside allowed directories' };
+    }
+    if (!existsSync(resolved)) {
+        return { success: false, message: `File not found: ${input.path}` };
+    }
+    if (!statSync(resolved).isFile()) {
+        return { success: false, message: `Not a file: ${input.path}` };
+    }
+    const maxChars = normalizeMaxChars(input.maxChars);
+    const fullContent = readFileSync(resolved, 'utf8');
+    const content = selectContent(fullContent, input);
+    return {
+        success: true,
+        path: relative(projectRoot || process.cwd(), resolved),
+        truncated: content.length > maxChars,
+        content: content.slice(0, maxChars),
+    };
+}
+function collectArtifacts(outputDir, targetDir, artifacts) {
+    for (const entry of readdirSync(targetDir, { withFileTypes: true })) {
+        if (artifacts.length >= CAPTAIN_ARTIFACT_SCAN_LIMIT)
+            return;
+        const entryPath = join(targetDir, entry.name);
+        if (entry.isDirectory()) {
+            collectArtifacts(outputDir, entryPath, artifacts);
+            continue;
+        }
+        const stats = statSync(entryPath);
+        artifacts.push({
+            path: relative(outputDir, entryPath),
+            size: stats.size,
+            modifiedAt: stats.mtime.toISOString(),
+            timestamp: stats.mtimeMs,
+        });
+    }
+}
+function resolveReadableFile(projectRoot, requestedPath, allowedDirs) {
+    if (!projectRoot)
+        return null;
+    let cleanPath = requestedPath.trim();
+    const projectName = basename(projectRoot);
+    if (cleanPath.startsWith(`${projectName}/`) || cleanPath.startsWith(`${projectName}\\`)) {
+        cleanPath = cleanPath.slice(projectName.length + 1);
+    }
+    const resolved = isAbsolute(cleanPath) ? resolve(cleanPath) : resolve(projectRoot, cleanPath);
+    const allowedRoots = allowedDirs.map((dir) => resolve(projectRoot, dir));
+    for (const root of allowedRoots) {
+        const rel = relative(root, resolved);
+        if (!rel || (!rel.startsWith('..') && !isAbsolute(rel)))
+            return resolved;
+    }
+    return null;
+}
+function selectContent(content, input) {
+    if (!input.startLine && !input.endLine)
+        return content;
+    const lines = content.split(/\r?\n/);
+    const startIndex = resolveLineIndex(input.startLine, lines.length, 1);
+    const endIndex = resolveLineIndex(input.endLine, lines.length, lines.length);
+    if (endIndex < startIndex)
+        return '';
+    return lines.slice(startIndex - 1, endIndex).join('\n');
+}
+function resolveLineIndex(line, totalLines, fallback) {
+    if (!line)
+        return fallback;
+    if (line < 0)
+        return Math.max(1, totalLines + line + 1);
+    return Math.min(Math.max(1, line), totalLines);
+}
+function normalizeMaxChars(maxChars) {
+    return Math.max(CAPTAIN_READ_FILE_MIN_LIMIT, Math.min(maxChars || CAPTAIN_READ_FILE_DEFAULT_LIMIT, CAPTAIN_READ_FILE_MAX_LIMIT));
+}

package/dist/src/ai/captain/idle-mode.js

@@ -4,6 +4,7 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ConfigParser } from "../../config.js";
 import { Test } from "../../test-plan.js";
+import { listRecentArtifacts, readCaptainFile } from "./file-tools.js";
 import { resolveProjectRoot } from "./mixin.js";
 let cachedBashTool = null;
 export function WithIdleMode(Base) {
@@ -13,6 +14,8 @@ export function WithIdleMode(Base) {
             const config = ConfigParser.getInstance().getConfig();
             const knowledgeDir = config.dirs?.knowledge || 'knowledge';
             const experienceDir = config.dirs?.experience || 'experience';
+            const outputDir = config.dirs?.output || 'output';
+            const readableDirs = [outputDir, knowledgeDir, experienceDir];
             if (!cachedBashTool && projectRoot) {
                 cachedBashTool = await createBashTool({
                     destination: projectRoot,
@@ -69,6 +72,53 @@ export function WithIdleMode(Base) {
                         return { success: true, tests: plan.tests.length };
                     },
                 }),
+                project: tool({
+                    description: dedent `
+            Inspect Explorbot project configuration and recent generated artifacts.
+            Use this before answering questions about setup, previous sessions, reports, saved plans, or output files.
+          `,
+                    inputSchema: z.object({
+                        view: z.enum(['config', 'artifacts']).optional().describe('config shows setup summary; artifacts lists recent generated files'),
+                    }),
+                    execute: async ({ view }) => {
+                        const parser = ConfigParser.getInstance();
+                        const config = parser.getConfig();
+                        const outputDir = parser.getOutputDir();
+                        if (view === 'artifacts') {
+                            return {
+                                success: true,
+                                outputDir,
+                                artifacts: listRecentArtifacts(outputDir),
+                                suggestion: 'Use readFile to inspect specific reports, plans, logs, generated tests, knowledge, or experience files.',
+                            };
+                        }
+                        return {
+                            success: true,
+                            configPath: parser.getConfigPath(),
+                            baseUrl: config.playwright?.url,
+                            browser: config.playwright?.browser,
+                            headed: config.playwright?.show === true,
+                            dirs: config.dirs,
+                            agents: Object.fromEntries(Object.entries(config.ai?.agents || {}).map(([name, agentConfig]) => [name, { enabled: agentConfig?.enabled !== false, hasModelOverride: !!agentConfig?.model }])),
+                            reporterEnabled: config.reporter?.enabled === true,
+                            apiEnabled: !!config.api,
+                        };
+                    },
+                }),
+                readFile: tool({
+                    description: dedent `
+            Read a specific Explorbot project file for analysis.
+            Use this for explicit user questions about reports, plans, logs, generated tests, knowledge, or experience files.
+            Prefer this over bash() for reading file contents after bash has found the file.
+          `,
+                    inputSchema: z.object({
+                        path: z.string().describe('Path inside output, knowledge, or experience directories'),
+                        startLine: z.number().optional().describe('First line to read, 1-based. Negative values count from the end of the file'),
+                        endLine: z.number().optional().describe('Last line to read, 1-based and inclusive. Negative values count from the end of the file'),
+                        maxChars: z.number().optional().describe('Maximum characters to return, default 12000'),
+                    }),
+                    execute: async (input) => readCaptainFile(projectRoot, input, readableDirs),
+                }),
             };
             if (cachedBashTool) {
                 tools.bash = cachedBashTool.bash;
@@ -79,17 +129,31 @@ export function WithIdleMode(Base) {
             const config = ConfigParser.getInstance().getConfig();
             const knowledgeDir = config.dirs?.knowledge || 'knowledge';
             const experienceDir = config.dirs?.experience || 'experience';
+            const outputDir = config.dirs?.output || 'output';
             return dedent `
         <idle_capabilities>
         - Plan management: updatePlan() — replace or append tests in the current plan
-        - bash() — run shell commands for file operations
-          - READ from: ${knowledgeDir}/, ${experienceDir}/, output/
-          - WRITE to: ${knowledgeDir}/, ${experienceDir}/ only (NOT output/)
-          - Use ls to list files, cat to read small files
-          - Use head/tail for large files to avoid excessive output
-          - Use grep to search file contents
+        - readFile() — read specific report, plan, log, generated test, knowledge, or experience file content
+        - bash() — discover files and inspect file metadata
+          - READ from: ${knowledgeDir}/, ${experienceDir}/, ${outputDir}/
+          - WRITE to: ${knowledgeDir}/, ${experienceDir}/ only (NOT ${outputDir}/)
+          - Use wc -l -c file.txt to inspect size
+          - Use file file.txt to inspect type
+          - Use find . -name "*.md" to discover files
+          - Use grep -n "keyword" file.txt to find matching lines
+          - Use ls -lh to list files
         </idle_capabilities>
 
+        <file_reading>
+        Use bash() for file discovery and search. Once the needed file and line range are known,
+        use readFile() to read its contents. Do not use bash() to print file contents.
+        </file_reading>
+
+        <project_inspection>
+        Use project({ view: "config" }) before explaining Explorbot setup or suggesting config improvements.
+        Use project({ view: "artifacts" }) before answering questions about previous sessions, reports, plans, generated tests, or logs.
+        </project_inspection>
+
         <knowledge_saving>
         When user shares credentials, selectors, or important domain info during conversation,
         suggest saving it to a knowledge file using bash tool.

package/dist/src/ai/captain/web-mode.js

@@ -45,19 +45,49 @@ export function WithWebMode(Base) {
                     description: dedent `
             Direct browser access via Playwright. Use for diagnostics and browser management.
             Actions:
+            - status: Inspect browser/page availability, URL, title, tab count
             - evaluate: Run JavaScript in browser context (localStorage, cookies, DOM, console)
             - closeTabs: Close all browser tabs except the current one
-            - screenshot: Take a screenshot of current page
             - reload: Reload the current page
+            - screenshot: Take a screenshot of current page
+            - recover: Recover from a closed/crashed page using Explorer recovery
+            - restart: Restart the browser when page/context recovery is not enough
+            - openFreshTab: Open a fresh tab in the current browser context
           `,
                     inputSchema: z.object({
-                        action: z.enum(['evaluate', 'closeTabs', 'screenshot', 'reload']).describe('Browser action to perform'),
+                        action: z.enum(['status', 'evaluate', 'closeTabs', 'reload', 'screenshot', 'recover', 'restart', 'openFreshTab']).describe('Browser action to perform'),
                         code: z.string().optional().describe('JavaScript code for evaluate action'),
                     }),
                     execute: async ({ action, code }) => {
-                        const page = ctx.explorBot.getExplorer().playwrightHelper?.page;
-                        if (!page)
-                            return { success: false, message: 'No browser page available' };
+                        const explorer = ctx.explorBot.getExplorer();
+                        if (action === 'status') {
+                            const page = explorer.playwrightHelper?.page;
+                            const pages = page?.context?.().pages?.() || [];
+                            return {
+                                success: true,
+                                hasPage: !!page,
+                                isClosed: page?.isClosed?.() || false,
+                                url: page && !page.isClosed?.() ? await page.url() : null,
+                                title: page && !page.isClosed?.() ? await page.title().catch(() => null) : null,
+                                tabs: pages.length,
+                            };
+                        }
+                        if (action === 'recover') {
+                            const recovered = await explorer.recoverFromBrowserError();
+                            return { success: recovered, message: recovered ? 'Browser page recovered' : 'Browser recovery failed' };
+                        }
+                        if (action === 'restart') {
+                            const restarted = await explorer.restartBrowser();
+                            return { success: restarted, message: restarted ? 'Browser restarted' : 'Browser restart failed' };
+                        }
+                        if (action === 'openFreshTab') {
+                            await ctx.explorBot.openFreshTab();
+                            const state = explorer.getStateManager().getCurrentState();
+                            return { success: true, url: state?.url, title: state?.title };
+                        }
+                        const page = explorer.playwrightHelper?.page;
+                        if (!page || page.isClosed?.())
+                            return { success: false, message: 'No browser page available. Try browser({ action: "recover" }) first.' };
                         if (action === 'evaluate') {
                             if (!code)
                                 return { success: false, message: 'Code required for evaluate action' };
@@ -106,7 +136,7 @@ export function WithWebMode(Base) {
         <web_capabilities>
         - Page actions: click, pressKey, form (CodeceptJS tools)
         - Navigation: navigate() — AI-powered navigation to URLs or page descriptions
-        - Browser diagnostics: browser() — evaluate JS, close tabs, screenshot, reload
+        - Browser diagnostics: browser() — inspect status, evaluate JS, close tabs, screenshot, reload, recover closed/crashed pages, restart browser, open a fresh tab
         - Visual analysis: see() — screenshot-based page verification
         - Context refresh: context() — get fresh HTML/ARIA snapshot
         - Visual fallback: visualClick() — coordinate-based click when locators fail

package/dist/src/ai/captain.js

@@ -18,7 +18,6 @@ import { TaskAgent } from "./task-agent.js";
 const MAX_STEPS = 15;
 const CaptainBase = WithTestMode(WithWebMode(WithIdleMode(TaskAgent)));
 export class Captain extends CaptainBase {
-    ACTION_TOOLS = ['click', 'pressKey', 'form', 'navigate'];
     emoji = '🧑‍✈️';
     explorBot;
     conversation = null;
@@ -56,6 +55,12 @@ export class Captain extends CaptainBase {
     }
     trackToolExecutions(toolExecutions) {
         super.trackToolExecutions(toolExecutions);
+        if (toolExecutions.length > 0) {
+            this.recentToolCalls.push(...toolExecutions);
+            if (this.recentToolCalls.length > 20) {
+                this.recentToolCalls = this.recentToolCalls.slice(-20);
+            }
+        }
         for (const exec of toolExecutions) {
             const label = toolExecutionLabel(exec.input);
             if (!label)
@@ -64,15 +69,20 @@ export class Captain extends CaptainBase {
             tag('substep').log(`${icon} ${label}`);
         }
     }
-    detectMode() {
-        if (this.explorBot.getExplorer().activeTest)
+    getMode() {
+        const explorer = this.explorBot.getExplorer();
+        const activeTest = explorer.activeTest;
+        const page = explorer.playwrightHelper?.page;
+        if (activeTest && (!page || page.isClosed?.()))
+            return 'heal';
+        if (activeTest)
             return 'test';
-        if (this.explorBot.getExplorer().getStateManager().getCurrentState())
+        if (explorer.getStateManager().getCurrentState())
             return 'web';
         return 'idle';
     }
     systemPrompt() {
-        const mode = this.detectMode();
+        const mode = this.getMode();
         const currentUrl = this.explorBot.getExplorer().getStateManager().getCurrentState()?.url;
         const customPrompt = this.explorBot.getProvider().getSystemPromptForAgent('captain', currentUrl);
         return dedent `
@@ -85,18 +95,21 @@ export class Captain extends CaptainBase {
     - idle: plan management, file operations, knowledge. Always available.
     - web: page interaction, navigation, browser diagnostics. When working with a web page.
     - test: test analysis, state inspection. When a test is running or analyzing results.
+    - heal: browser/test recovery. When a test is running and browser state is broken or unavailable.
     </modes>
 
     ${this.idleModePrompt()}
-    ${mode === 'web' ? this.webModePrompt() : ''}
-    ${mode === 'test' ? this.testModePrompt() : ''}
+    ${mode === 'web' || mode === 'heal' ? this.webModePrompt() : ''}
+    ${mode === 'test' || mode === 'heal' ? this.testModePrompt() : ''}
 
     <rules>
     - After a successful action, if the pageDiff confirms the goal, call done() immediately — do not verify with see() or context() unless the user explicitly asked for verification
     - Prefer completing in fewer tool calls over thoroughness
     - NEVER run tests unless the user explicitly asks
-    ${mode === 'web' ? this.webModeRules() : ''}
-    ${mode === 'test' ? this.testModeRules() : ''}
+    - If you are answering with information rather than completing a browser action, include the actual user-facing answer in done({ details }). Do not only say that it was shown or explained.
+    ${mode === 'web' || mode === 'heal' ? this.webModeRules() : ''}
+    ${mode === 'test' || mode === 'heal' ? this.testModeRules() : ''}
+    ${mode === 'heal' ? '- First diagnose browser availability, then recover the browser/page before continuing test analysis.' : ''}
     </rules>
 
     ${customPrompt || ''}
@@ -228,9 +241,20 @@ export class Captain extends CaptainBase {
                 description: 'Call when the user request is fulfilled.',
                 inputSchema: z.object({
                     summary: z.string().describe('What was done'),
+                    details: z.string().optional().describe('Actual user-facing content. Required when the user asked to show, display, explain, summarize, compare, or diagnose information.'),
                 }),
-                execute: async ({ summary }) => {
+                execute: async ({ summary, details }) => {
                     debugLog('done', summary);
+                    if (!details?.trim() && !this.canCompleteWithoutDetails()) {
+                        return {
+                            success: false,
+                            message: 'No user-facing result was provided. Call done() again with the actual answer in details, or complete a browser action first.',
+                        };
+                    }
+                    if (details?.trim()) {
+                        tag('details').log(details);
+                        task.addNote(details);
+                    }
                     task.addNote(summary);
                     onDone(summary);
                     return { success: true, summary };
@@ -239,6 +263,9 @@ export class Captain extends CaptainBase {
             runCommand: tool({
                 description: dedent `
           Execute a TUI command. Returns log output from command execution.
+          Use only when the user explicitly asks to run a slash command.
+          Never use this to analyze files, reports, logs, plans, generated tests, knowledge, or experience.
+          Never run a slash command unless the user request itself starts with that slash command.
           ${this.commandDescriptions
                     .map((c) => {
                     const opts = c.options ? ` (${c.options})` : '';
@@ -253,6 +280,13 @@ export class Captain extends CaptainBase {
                     if (!this.commandExecutor)
                         return { success: false, message: 'Command executor not available' };
                     const cmd = command.startsWith('/') ? command : `/${command}`;
+                    if (!isExplicitSlashRequest(task.description, cmd)) {
+                        return {
+                            success: false,
+                            command: cmd,
+                            message: 'Command blocked: slash commands require an explicit matching slash-command request from the user.',
+                        };
+                    }
                     startLogCapture();
                     try {
                         await this.commandExecutor(cmd);
@@ -265,10 +299,12 @@ export class Captain extends CaptainBase {
         };
     }
     async tools(task, onDone) {
-        const mode = this.detectMode();
+        const mode = this.getMode();
         const ctx = { explorBot: this.explorBot, task };
         const core = this.coreTools(task, onDone);
         const idle = await this.idleModeTools(ctx);
+        if (mode === 'heal')
+            return { ...core, ...idle, ...this.testModeTools(ctx), ...this.webModeTools(ctx) };
         if (mode === 'test')
             return { ...core, ...idle, ...this.testModeTools(ctx) };
         if (mode === 'web')
@@ -333,17 +369,24 @@ export class Captain extends CaptainBase {
         }
         return result.object;
     }
+    async processExecutionError(error, activeTest) {
+        const explorer = this.explorBot.getExplorer();
+        const result = await explorer.handleExecutionError(error);
+        return {
+            ...result,
+            message: result.recovered ? `${result.message}\nContinue the test "${activeTest.scenario}" from the restored page.` : result.message,
+        };
+    }
+    canCompleteWithoutDetails() {
+        return (this.recentToolCalls || []).some(hasBrowserCompletionEvidence);
+    }
     async handle(input, options = {}) {
         const stateManager = this.explorBot.getExplorer().getStateManager();
         const initialState = stateManager.getCurrentState();
-        if (!initialState) {
-            tag('warning').log('No page loaded. Use /navigate or I.amOnPage() first.');
-            return null;
-        }
         const conversation = options.reset ? this.resetConversation() : this.ensureConversation();
         let isDone = false;
         let finalSummary = null;
-        const startUrl = initialState.url || '';
+        const startUrl = initialState?.url || '';
         const task = new Task(input, startUrl);
         const onDone = (summary) => {
             isDone = true;
@@ -376,11 +419,13 @@ export class Captain extends CaptainBase {
                 return;
             }
             const currentState = stateManager.getCurrentState();
-            if (!currentState) {
+            if (!currentState && this.getMode() !== 'idle') {
                 stop();
                 return;
             }
-            await this.reinjectContextIfNeeded(conversation, currentState);
+            if (currentState) {
+                await this.reinjectContextIfNeeded(conversation, currentState);
+            }
             if (userInput) {
                 const newContext = await this.getPageContext();
                 conversation.addUserText(dedent `
@@ -410,7 +455,7 @@ export class Captain extends CaptainBase {
             }
             if (result?.toolExecutions?.length) {
                 const lastExec = result.toolExecutions[result.toolExecutions.length - 1];
-                if (lastExec.wasSuccessful && this.ACTION_TOOLS.includes(lastExec.toolName)) {
+                if (hasBrowserCompletionEvidence(lastExec)) {
                     conversation.addUserText('Action succeeded. If the goal is achieved, call done() now with a brief summary.');
                 }
             }
@@ -437,3 +482,26 @@ export class Captain extends CaptainBase {
     }
 }
 export default Captain;
+function isExplicitSlashRequest(input, command) {
+    const requested = slashCommandToken(input);
+    const actual = slashCommandToken(command);
+    if (!requested || !actual)
+        return false;
+    return requested === actual;
+}
+function slashCommandToken(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('/'))
+        return null;
+    for (let i = 1; i < trimmed.length; i++) {
+        if (trimmed[i] <= ' ')
+            return trimmed.slice(0, i);
+    }
+    return trimmed;
+}
+function hasBrowserCompletionEvidence(execution) {
+    if (!execution?.wasSuccessful)
+        return false;
+    const output = execution.output || {};
+    return Boolean(output.pageDiff || output.code || output.playwrightGroupId);
+}