explorbot 0.5.9 → 0.6.0

package/src/action.ts

@@ -34,8 +34,6 @@ class Action {
   public actionResult: ActionResult | null = null;
   private config: ExplorbotConfig;
 
-  // action info
-  private action: string | null = null;
   public lastError: Error | null = null;
   public playwrightHelper: any;
   public playwrightGroupId: string | null = null;
@@ -389,8 +387,6 @@ class Action {
   }
 
   private async executeOnce(code: string, verbatim = false): Promise<Action> {
-    let error: Error | null = null;
-
     setActivity('🔎 Browsing...', 'action');
 
     let codeString = code.replace(/^\(I\) => /, '').trim();
@@ -441,7 +437,6 @@ class Action {
       this.assertionSteps = assertionSteps;
     } catch (err) {
       debugLog('Action error', errorToString(err));
-      error = err as Error;
       if (!isPlaywright) {
         await recorder.reset();
         await recorder.start();

package/src/ai/captain/idle-mode.ts

@@ -3,7 +3,9 @@ import { createBashTool } from 'bash-tool';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ConfigParser } from '../../config.ts';
-import { Test } from '../../test-plan.ts';
+import { Plan, Test } from '../../test-plan.ts';
+import { getStyles } from '../planner/styles.ts';
+import { PlanningBlockedError } from '../../utils/error-page.ts';
 import { listRecentArtifacts, readCaptainFile } from './file-tools.ts';
 import { type Constructor, type ModeContext, resolveProjectRoot } from './mixin.ts';
 
@@ -36,11 +38,18 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
       }
 
       const tools: Record<string, any> = {
-        updatePlan: tool({
-          description: 'Update the current plan by replacing or appending tests',
+        plan: tool({
+          description: dedent`
+            Plan tests for the current page. Adds them to the current plan when it is for this page, otherwise starts a new plan.
+            Without tests, the Planner writes the tests. With tests, exactly those tests are added and the Planner does not run: use it for tests the user dictates.
+            Returns how many tests were added, or why planning failed.
+          `,
           inputSchema: z.object({
-            action: z.enum(['replace', 'append']).optional().describe('replace clears existing tests, append keeps them'),
-            title: z.string().optional().describe('New plan title'),
+            feature: z.string().optional().describe('Focus area for the Planner'),
+            style: z
+              .enum(Object.keys(getStyles()) as [string, ...string[]])
+              .optional()
+              .describe('Planning style for the Planner; omit to let it choose'),
             tests: z
               .array(
                 z.object({
@@ -49,33 +58,36 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
                   expected: z.array(z.string()).optional(),
                 })
               )
-              .optional(),
+              .optional()
+              .describe('Tests to add as written, without running the Planner'),
+            replace: z.boolean().optional().describe('Remove the tests already in this page plan first'),
+            title: z.string().optional().describe('New plan title'),
           }),
-          execute: async ({ action, title, tests }) => {
+          execute: async ({ feature, style, tests, replace, title }) => {
+            if (ctx.blocker instanceof PlanningBlockedError) {
+              feature = ctx.blocker.feature;
+              style = ctx.blocker.style;
+            }
+            const url = ctx.explorBot.stateManager().getCurrentState()?.url || '';
             let plan = ctx.explorBot.getCurrentPlan();
-            if (!plan) {
-              plan = await ctx.explorBot.plan();
+            if (plan?.url && plan.url !== url) plan = undefined;
+            if (replace) plan?.tests.splice(0);
+            const before = new Set(plan?.tests ?? []);
+            if (!tests?.length) {
+              plan = await ctx.explorBot.plan(feature, { style });
+              const error = ctx.explorBot.lastPlanError;
+              if (error) return { success: false, message: error.message };
             }
             if (!plan) {
-              return { success: false, message: 'Plan unavailable' };
-            }
-            if (title) {
-              plan.title = title;
+              plan = new Plan(url);
+              ctx.explorBot.setCurrentPlan(plan);
             }
-            if (tests?.length) {
-              if (!action || action === 'replace') {
-                plan.tests.length = 0;
-              }
-              const currentUrl = ctx.explorBot.stateManager().getCurrentState()?.url || '';
-              for (const testInput of tests) {
-                const priority = testInput.priority || 'normal';
-                const expected = testInput.expected?.length ? testInput.expected : [];
-                const test = new Test(testInput.scenario, priority, expected, currentUrl);
-                plan.addTest(test);
-              }
+            for (const t of tests ?? []) {
+              plan.addTest(new Test(t.scenario, t.priority || 'normal', t.expected ?? [], url));
             }
+            if (title) plan.title = title;
             plan.updateStatus();
-            return { success: true, tests: plan.tests.length };
+            return { success: true, testsAdded: plan.tests.filter((t) => !before.has(t)).length, tests: plan.tests.length };
           },
         }),
         project: tool({
@@ -144,7 +156,7 @@ export function WithIdleMode<T extends Constructor>(Base: T) {
 
       return dedent`
         <idle_capabilities>
-        - Plan management: updatePlan() — replace or append tests in the current plan
+        - Plan management: plan() — run the Planner on the current page, or add tests you write yourself
         - 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}/

package/src/ai/captain/mixin.ts

@@ -1,7 +1,7 @@
-import { dirname } from 'node:path';
 import { ConfigParser } from '../../config.ts';
 import type { ExplorBot } from '../../explorbot.ts';
 import type { Task } from '../../test-plan.ts';
+import type { BlockedError } from '../../utils/error-page.ts';
 import { createDebug } from '../../utils/logger.js';
 
 export type Constructor<T = object> = new (...args: any[]) => T;
@@ -13,6 +13,7 @@ export type CaptainMode = 'idle' | 'web' | 'test' | 'heal';
 export interface ModeContext {
   explorBot: ExplorBot;
   task: Task;
+  blocker: BlockedError | null;
 }
 
 export function resolveProjectRoot(): string | null {

package/src/ai/captain/web-mode.ts

@@ -1,6 +1,7 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
+import { pageEvidence } from '../judge.ts';
 import { actionRule, locatorRule, sectionContextRule } from '../rules.ts';
 import { createAgentTools, createCodeceptJSTools } from '../tools.ts';
 import { type Constructor, type ModeContext, debugLog } from './mixin.ts';
@@ -37,6 +38,16 @@ export function WithWebMode<T extends Constructor>(Base: T) {
           },
         }),
 
+        oracle: tool({
+          description: 'Ask a yes/no question about the current page. Much cheaper than see or context.',
+          inputSchema: z.object({ question: z.string() }),
+          execute: async ({ question }) => {
+            const captured = await ctx.explorBot.getExplorer().capture({ screenshot: true });
+            const holds = await ctx.explorBot.getProvider().oracle(question, pageEvidence(captured), { agentName: 'captain', screenshot: captured.screenshot, telemetry: { functionId: 'captain.oracle' } });
+            return { success: holds !== null, question, answer: holds };
+          },
+        }),
+
         browser: tool({
           description: dedent`
             Direct browser access via Playwright. Use for diagnostics and browser management.
@@ -157,6 +168,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
         - click() accepts array of commands to try in order — include ARIA, CSS, XPath variants
         - If click() fails with all provided commands, use visualClick() tool as fallback
         - When an action fails or result is unexpected, investigate or inform the user instead of retrying silently
+        - For a quick yes/no question about the page, use oracle instead of see or context
       `;
     }
   };

package/src/ai/captain.ts

@@ -7,6 +7,7 @@ import type { ExplorBot } from '../explorbot.ts';
 import type { WebPageState } from '../state-manager.ts';
 import { Task, Test } from '../test-plan.ts';
 import { formatHeadings } from '../utils/context-formatter.ts';
+import { BlockedError } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { startLogCapture, stopLogCapture, tag } from '../utils/logger.js';
 import { loop } from '../utils/loop.js';
@@ -21,6 +22,7 @@ import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { TaskAgent } from './task-agent.ts';
+import type { SupervisorAction } from './tester.ts';
 import { createLearnExperienceTool, withdrawVisionTools } from './tools.ts';
 
 const MAX_STEPS = 15;
@@ -35,6 +37,9 @@ export class Captain extends CaptainBase implements Agent {
   private hooksRunner: HooksRunner | null = null;
   private commandExecutor: ((cmd: string) => Promise<void>) | null = null;
   private commandDescriptions: { name: string; description: string; options: string }[] = [];
+  private unresolvedBlockers = new Set<string>();
+  private handling = false;
+  private blocker: BlockedError | null = null;
 
   constructor(explorBot: ExplorBot) {
     super();
@@ -123,6 +128,7 @@ export class Captain extends CaptainBase implements Agent {
     - 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
+    - When an agent reports it is blocked, decide which agent can resolve it and delegate to that agent
     - 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() : ''}
@@ -304,7 +310,7 @@ export class Captain extends CaptainBase implements Agent {
 
   private async tools(task: Task, onDone: (summary: string) => void) {
     const mode = this.getMode();
-    const ctx: ModeContext = { explorBot: this.explorBot, task };
+    const ctx: ModeContext = { explorBot: this.explorBot, task, blocker: this.blocker };
     const core = this.coreTools(task, onDone);
     const idle = await this.idleModeTools(ctx);
 
@@ -437,6 +443,7 @@ export class Captain extends CaptainBase implements Agent {
 
     conversation.addUserText(initialPrompt);
 
+    this.handling = true;
     await loop(
       async ({ stop, iteration, userInput }) => {
         debugLog(`Captain iteration ${iteration}`);
@@ -510,7 +517,9 @@ export class Captain extends CaptainBase implements Agent {
           stop();
         },
       }
-    );
+    ).finally(() => {
+      this.handling = false;
+    });
 
     const finalUrl = stateManager.getCurrentState()?.url || startUrl;
     await this.getHooksRunner().runAfterHook('captain', finalUrl);
@@ -523,15 +532,24 @@ export class Captain extends CaptainBase implements Agent {
 
     return null;
   }
+
+  async resolveBlocker(error: unknown, resolved: () => boolean | Promise<boolean>): Promise<boolean> {
+    if (!(error instanceof BlockedError) || this.handling) return false;
+    const key = `${error.name} ${error.url} ${error.blocker}`;
+    if (this.unresolvedBlockers.has(key)) return false;
+    tag('info').log(`Captain takes over: ${error.message}`);
+    this.blocker = error;
+    await this.handle(error.request, { reset: true }).finally(() => {
+      this.blocker = null;
+    });
+    if (await resolved()) return true;
+    this.unresolvedBlockers.add(key);
+    return false;
+  }
 }
 
 export default Captain;
 
-interface SupervisorAction {
-  action: 'inject' | 'stop' | 'pass' | 'skip';
-  message: string;
-}
-
 interface ExecutionRecoveryAction {
   action: 'continue' | 'stop';
   message: string;

package/src/ai/driller.ts

@@ -15,7 +15,6 @@ import { eidxInContainer } from '../utils/web-eidx.ts';
 import { WebElement } from '../utils/web-element.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import type { Navigator } from './navigator.ts';
-import type { Provider } from './provider.ts';
 import { drillLocatorRule } from './rules.ts';
 import { TaskAgent, isInteractive } from './task-agent.ts';
 import { createCodeceptJSTools, createLearnExperienceTool } from './tools.ts';
@@ -177,7 +176,7 @@ export class Driller extends TaskAgent implements Agent {
     setActivity(`${this.emoji} Capturing annotated page state...`, 'action');
     const action = this.explorer.action();
     try {
-      const annotated = await Promise.race([
+      await Promise.race([
         this.explorer.withPage(annotatePageElements),
         new Promise<never>((_, reject) => {
           setTimeout(() => reject(new Error('annotateElements timeout')), 15000);

package/src/ai/experience-compactor.ts

@@ -1,5 +1,5 @@
 import { unlinkSync } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, relative } from 'node:path';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { type ExperienceFile, type ExperienceTracker, RECENT_WINDOW_DAYS } from '../experience-tracker.js';
@@ -322,7 +322,7 @@ export class ExperienceCompactor implements Agent {
     };
 
     this.experienceTracker.writeExperienceFile(targetStateHash, combinedContent, newFrontmatter);
-    log(`Merged ${group.files.length} experience files into ${targetFile.filePath}`);
+    log(`Merged ${group.files.length} experience files into ${relative(process.cwd(), targetFile.filePath)}`);
     debugLog('New URL pattern:', group.pattern);
 
     for (const sourceFile of sourceFiles) {

package/src/ai/judge.ts

@@ -1,7 +1,8 @@
 import { clearActivity, setActivity } from '../activity.ts';
+import type { ActionResult } from '../action-result.ts';
 import type { AIConfig } from '../config.ts';
 import { Observability } from '../observability.ts';
-import { createDebug } from '../utils/logger.ts';
+import { createDebug, tag } from '../utils/logger.ts';
 import { JudgeProvider } from './judge-provider.ts';
 
 const debugLog = createDebug('explorbot:judge');
@@ -29,6 +30,8 @@ export class Decision {
 }
 
 export class Judge {
+  private failureReported = false;
+
   constructor(
     private provider: JudgeProvider,
     private enabled: { tool: boolean; direct: boolean },
@@ -93,6 +96,8 @@ export class Judge {
 
   private recordFailure(error: unknown): null {
     debugLog('judge declined: %s', error);
+    if (!this.failureReported) tag('warning').log(`Decision model ${this.provider.model} failed (${error}); continuing without it`);
+    this.failureReported = true;
     const span = Observability.getSpan();
     span?.setAttribute('ai.telemetry.metadata.judgeError', String(error));
     span?.setAttribute('langfuse.observation.level', 'ERROR');
@@ -100,3 +105,7 @@ export class Judge {
     return null;
   }
 }
+
+export function pageEvidence(actionResult: ActionResult) {
+  return { url: actionResult.url, title: actionResult.title, page: actionResult.getCompactARIA().slice(0, JUDGE_PAGE_CAP) };
+}

package/src/ai/navigator.ts

@@ -13,7 +13,7 @@ import { type StateManager, normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
-import { isLoginPage } from '../utils/error-page.ts';
+import { NavigationBlockedError, isLoginPage } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
@@ -22,7 +22,6 @@ import { normalizeInlineText } from '../utils/strings.ts';
 import { extractStatePath, isSameHostFamily, matchesNavigationUrl } from '../utils/url-matcher.js';
 import type { UrlFilter } from '../utils/url-filter.ts';
 import type { Agent, AgentDeps } from './agent.js';
-import type { Conversation } from './conversation.js';
 import { type Decision, JUDGE_PAGE_CAP, type Judge, UNDECIDED } from './judge.ts';
 import type { Provider } from './provider.js';
 import { Researcher } from './researcher.ts';
@@ -31,6 +30,7 @@ import { isInteractive } from './task-agent.js';
 import { createLearnExperienceTool } from './tools.ts';
 
 const debugLog = createDebug('explorbot:navigator');
+const MAX_TRIED_STEPS = 5;
 
 class Navigator implements Agent {
   emoji = '🧭';
@@ -138,6 +138,10 @@ class Navigator implements Agent {
     return matchesNavigationUrl(expectedUrl, currentUrl);
   }
 
+  isOn(url: string): boolean {
+    return this.isOnExpectedPage(url, this.stateManager);
+  }
+
   async visit(url: string, opts: { recover?: boolean } = {}): Promise<boolean> {
     return this.visitOnce(url, opts.recover !== false);
   }
@@ -195,8 +199,9 @@ class Navigator implements Agent {
   }
 
   private navigationError(url: string, fallback: string): Error {
-    if (this.lastFailureReason) return new Error(`Navigation to ${url} failed: ${this.lastFailureReason}`);
-    return new Error(`Navigation to ${url} failed: ${fallback}`);
+    const currentUrl = this.stateManager.getCurrentState()?.url || '';
+    const tried = this.executedSteps.slice(-MAX_TRIED_STEPS).map((step) => step.command);
+    return new NavigationBlockedError(url, currentUrl, this.lastFailureReason || fallback, tried);
   }
 
   private failureReason(stopReason: string | null, knowledge: string, url: string): string | null {
@@ -402,7 +407,7 @@ class Navigator implements Agent {
         Propose different solutions to achieve the result.
         Solution should be valid CodeceptJS code.
         Use only data from the <page> context to plan the solution.
-        The page is given as an ARIA snapshot only: use ARIA and text locators from it.
+        The page is given as an ARIA snapshot only: use ARIA and text locators from it; propose CSS/XPath only once <page_html> is provided.
         Full HTML is provided if these solutions fail.
         Try various ways to achieve the result
       </task>
@@ -772,7 +777,7 @@ class Navigator implements Agent {
         Do not generate assertions that would pass even if the specific claim is false.
       </task>
 
-      ${RulesLoader.loadRules('navigator', ['verification-actions'], actionResult.url || '')}
+      ${RulesLoader.loadRules('navigator', ['verification-actions', 'verification-output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.verifyAttempts))}
 
       ${experience}
 
@@ -858,7 +863,7 @@ class Navigator implements Agent {
 
     const totalAttempted = Math.min(codeBlocks.length, this.verifyAttempts);
     let verified = successfulCodes.length > 0 && !failures;
-    if (successfulCodes.length && failures) verified = await this.provider.oracle(message, { assertions: results.map(({ code, passed, error }) => ({ code, passed, error })) }, { agentName: 'navigator', telemetry: { functionId: 'navigator.verifyState' } });
+    if (successfulCodes.length && failures) verified = (await this.provider.oracle(message, { assertions: results.map(({ code, passed, error }) => ({ code, passed, error })) }, { agentName: 'navigator', telemetry: { functionId: 'navigator.verifyState' } })) === true;
     if (alreadyVerified) verified = true;
 
     const inexpressible = !alreadyVerified && totalAttempted === 0;

package/src/ai/planner/subpages.ts

@@ -3,7 +3,6 @@ import { z } from 'zod';
 import { normalizeUrl } from '../../state-manager.ts';
 import type { StateManager } from '../../state-manager.ts';
 import type { Plan } from '../../test-plan.ts';
-import { tag } from '../../utils/logger.ts';
 import { isSamePageFamily } from '../../utils/url-matcher.ts';
 import type { Provider } from '../provider.ts';
 import type { Constructor } from '../researcher/mixin.ts';
@@ -85,7 +84,7 @@ export function WithSubPages<T extends Constructor>(Base: T) {
     async pickNextSubPage(candidates: SubPageCandidate[]): Promise<{ url: string; reason: string } | null> {
       if (candidates.length === 0) return null;
 
-      const plannedEntries = [...planRegistry.entries()].map(([key, record]) => `- ${record.url} (${record.plan.tests.length} tests${record.feature ? `, feature: ${record.feature}` : ''})`).join('\n');
+      const plannedEntries = [...planRegistry.entries()].map(([, record]) => `- ${record.url} (${record.plan.tests.length} tests${record.feature ? `, feature: ${record.feature}` : ''})`).join('\n');
 
       const candidateList = candidates.map((c) => `- ${c.url} (visits: ${c.visitCount}${c.title ? `, title: "${c.title}"` : ''}${c.h1 ? `, h1: "${c.h1}"` : ''})`).join('\n');