explorbot 0.1.22 → 0.1.24

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

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

@@ -21,7 +21,7 @@ export function WithWebMode(Base) {
                     return state ? ActionResult.fromState(state) : null;
                 },
             });
-            const { see, context, visualClick, learn_experience } = agentTools;
+            const { see, context, visualClick, learnExperience } = agentTools;
             return {
                 navigate: tool({
                     description: 'Navigate to a URL or page description using AI-powered navigation.',
@@ -98,7 +98,7 @@ export function WithWebMode(Base) {
                 see,
                 context,
                 visualClick,
-                learn_experience,
+                learnExperience,
             };
         }
         webModePrompt() {

package/dist/src/ai/navigator.js

@@ -448,16 +448,16 @@ class Navigator {
             const s = stateManager.getCurrentState();
             return s ? ActionResult.fromState(s) : null;
         };
-        const { learn_experience } = createAgentTools({
+        const { learnExperience } = createAgentTools({
             explorer: this.explorer,
             researcher: null,
             navigator: this,
             experienceTracker: this.experienceTracker,
             getState,
         });
-        if (!learn_experience)
+        if (!learnExperience)
             return undefined;
-        return { learn_experience };
+        return { learnExperience };
     }
     async freeSail(opts, actionResult) {
         const stateManager = this.explorer.getStateManager();

package/dist/src/ai/pilot.js

@@ -389,12 +389,12 @@ export class Pilot {
         the elements needed for the scenario. The page summary does not list every element.
         Prefer interacting with the current page over navigating away.
 
-        If you load a recipe via learn_experience, do NOT rewrite its code in your plan — the
+        If you load a recipe via learnExperience, do NOT rewrite its code in your plan — the
         raw recipe is forwarded to Tester automatically. Reference it by step ("apply recipe
         steps 1–3, then…") and call out anywhere your scenario diverges from it.
 
         Be concise and specific. Tester will follow your plan.
-      `, 'pilot.planTest', { tools: true, planningOnly: true, maxToolRoundtrips: 3, task });
+      `, 'pilot.planTest', { tools: true, maxToolRoundtrips: 3, task });
     }
     async reviewNewPage(task, currentState, testerConversation) {
         if (!this.conversation)
@@ -484,7 +484,7 @@ export class Pilot {
         this.conversation.addUserText(finalUserText);
         let tools;
         if (opts.tools) {
-            tools = opts.planningOnly ? this.pickPlanningTools() : this.agentTools;
+            tools = this.pickPlanningTools();
         }
         if (opts.tools && opts.task) {
             tools = { ...tools, ...this.buildPreconditionTool(opts.task) };
@@ -496,7 +496,7 @@ export class Pilot {
             experimental_telemetry: { functionId },
         });
         const text = result?.response?.text || '';
-        const learned = (result?.toolExecutions || []).filter((e) => e.toolName === 'learn_experience' && e.output?.content).map((e) => e.output.content);
+        const learned = (result?.toolExecutions || []).filter((e) => e.toolName === 'learnExperience' && e.output?.content).map((e) => e.output.content);
         if (learned.length === 0)
             return text;
         return dedent `
@@ -521,7 +521,7 @@ export class Pilot {
         return renderExperienceToc(toc);
     }
     pickPlanningTools() {
-        const { see, context, verify, research, getVisitedStates, xpathCheck, learn_experience } = this.agentTools ?? {};
+        const { see, context, verify, research, getVisitedStates, xpathCheck, learnExperience, askUser } = this.agentTools ?? {};
         const planning = {};
         if (see)
             planning.see = see;
@@ -535,8 +535,10 @@ export class Pilot {
             planning.getVisitedStates = getVisitedStates;
         if (xpathCheck)
             planning.xpathCheck = xpathCheck;
-        if (learn_experience)
-            planning.learn_experience = learn_experience;
+        if (learnExperience)
+            planning.learnExperience = learnExperience;
+        if (askUser)
+            planning.askUser = askUser;
         return planning;
     }
     buildPreconditionTool(task) {

package/dist/src/ai/tester.js

@@ -668,7 +668,7 @@ export class Tester extends TaskAgent {
     - When filling complex form with lot of actions performed, use see() to look which fields were filled and which are not
     - When verify() fails, use see() to visually confirm the result — visual confirmation is equally valid evidence
     - For visual state verification (active tabs, selected items, counts, colors), prefer see() over DOM-based verify()
-    - When click() fails and element is visually present, use visualClick() as fallback
+    - When click() fails on an element you can see — or believe is there but may look different — you MUST try visualClick() before giving up; don't repeat visualClick in a row
     - If you land on a "Not Found", 404, or error page that is NOT part of the scenario, call reset() immediately to return to the initial page and try again
     - If you see a server error page (500, 503, etc.), record it with record({ notes: ["Server error on /path"], status: "fail" }) and call reset() to continue testing
     </rules>

package/dist/src/ai/tools.js

@@ -391,7 +391,7 @@ export function createSpecialContextTools(explorer, context) {
         }),
     };
 }
-export function createAgentTools({ explorer, researcher, navigator, experienceTracker, getState, }) {
+export function createAgentTools({ explorer, researcher, navigator, experienceTracker, getState, supervisor, }) {
     let visionDisabled = false;
     const tools = {
         see: tool({
@@ -685,41 +685,6 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
                 }
             },
         }),
-        askUser: tool({
-            description: dedent `
-        Ask the user for help when you're stuck or unsure how to proceed.
-        Only available in interactive mode (TUI).
-
-        Use when:
-        - Locator-based clicks keep failing
-        - You can't find an element that should exist
-        - Form interaction isn't working as expected
-        - You need clarification on what action to take
-      `,
-            inputSchema: z.object({
-                question: z.string().describe('What you need help with - be specific about what failed'),
-                context: z.string().optional().describe('Relevant context like locators tried, errors received'),
-            }),
-            execute: async ({ question, context }) => {
-                if (!isInteractive()) {
-                    return {
-                        success: false,
-                        message: 'User input not available in non-interactive mode',
-                        suggestion: 'Continue with automated recovery',
-                    };
-                }
-                const prompt = context ? `${question}\n\nContext: ${context}\n\nYour suggestion ("skip" to continue):` : `${question}\n\nYour suggestion ("skip" to continue):`;
-                const userInput = await pause(prompt);
-                if (!userInput || userInput.toLowerCase() === 'skip') {
-                    return { success: false, message: 'User skipped' };
-                }
-                return {
-                    success: true,
-                    userSuggestion: userInput,
-                    instruction: 'Follow the user suggestion. Use interact() tool to execute.',
-                };
-            },
-        }),
         back: tool({
             description: dedent `
         Navigate back to the previous page (most recent URL different from current).
@@ -834,7 +799,7 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
         }),
     };
     if (experienceTracker && getState) {
-        tools.learn_experience = tool({
+        tools.learnExperience = tool({
             description: dedent `
         Read the full body of a specific experience section listed in <experience>.
         The TOC shows entries like "A.1 ## FLOW: ..." or "A.2 ## ACTION: ...". Pass the fileTag and sectionIndex.
@@ -857,6 +822,43 @@ export function createAgentTools({ explorer, researcher, navigator, experienceTr
             },
         });
     }
+    if (supervisor) {
+        tools.askUser = tool({
+            description: dedent `
+        Ask the user for help when automated recovery is stuck or the next step is unclear.
+        Only available in interactive mode (TUI).
+
+        Use when:
+        - The Tester keeps failing the same locator/element
+        - An element that should exist cannot be found
+        - Form interaction isn't working as expected
+        - You need a human decision on how to proceed
+      `,
+            inputSchema: z.object({
+                question: z.string().describe('What you need help with - be specific about what failed'),
+                context: z.string().optional().describe('Relevant context like locators tried, errors received'),
+            }),
+            execute: async ({ question, context }) => {
+                if (!isInteractive()) {
+                    return {
+                        success: false,
+                        message: 'User input not available in non-interactive mode',
+                        suggestion: 'Continue with automated recovery',
+                    };
+                }
+                const prompt = context ? `${question}\n\nContext: ${context}\n\nYour suggestion ("skip" to continue):` : `${question}\n\nYour suggestion ("skip" to continue):`;
+                const userInput = await pause(prompt);
+                if (!userInput || userInput.toLowerCase() === 'skip') {
+                    return { success: false, message: 'User skipped' };
+                }
+                return {
+                    success: true,
+                    userSuggestion: userInput,
+                    instruction: 'Relay this suggestion to the Tester as the next concrete step.',
+                };
+            },
+        });
+    }
     return tools;
 }
 const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';

package/dist/src/experience-tracker.js

@@ -455,7 +455,7 @@ export function renderExperienceToc(toc) {
     lines.push('Locators and step ordering worked then; the page may have changed since.');
     lines.push('Treat as a starting hypothesis, not ground truth. If a step fails, fall back to ARIA/UI-map.');
     lines.push('FLOW: = multi-step recipe (bullets + code + discovery). ACTION: = single-step snippet (one code block).');
-    lines.push('Call learn_experience({ fileTag, sectionIndex }) to read a section when it looks relevant to the current step.');
+    lines.push('Call learnExperience({ fileTag, sectionIndex }) to read a section when it looks relevant to the current step.');
     lines.push('');
     for (const entry of toc) {
         lines.push(`File ${entry.fileTag} ${entry.url}:`);

package/dist/src/explorbot.js

@@ -170,7 +170,7 @@ export class ExplorBot {
                 const state = stateManager.getCurrentState();
                 return state ? ActionResult.fromState(state) : null;
             };
-            const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState });
+            const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState, supervisor: true });
             return new Pilot(ai, tools, researcher, explorer, experienceTracker);
         }));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

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

@@ -22,7 +22,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
           return state ? ActionResult.fromState(state) : null;
         },
       });
-      const { see, context, visualClick, learn_experience } = agentTools;
+      const { see, context, visualClick, learnExperience } = agentTools;
 
       return {
         navigate: tool({
@@ -103,7 +103,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
         see,
         context,
         visualClick,
-        learn_experience,
+        learnExperience,
       };
     }
 

package/src/ai/navigator.ts

@@ -481,21 +481,21 @@ class Navigator implements Agent {
     return resolved;
   }
 
-  private buildExperienceTools(): { learn_experience: unknown } | undefined {
+  private buildExperienceTools(): { learnExperience: unknown } | undefined {
     const stateManager = this.explorer.getStateManager();
     const getState = () => {
       const s = stateManager.getCurrentState();
       return s ? ActionResult.fromState(s) : null;
     };
-    const { learn_experience } = createAgentTools({
+    const { learnExperience } = createAgentTools({
       explorer: this.explorer,
       researcher: null as unknown as Researcher,
       navigator: this,
       experienceTracker: this.experienceTracker,
       getState,
     });
-    if (!learn_experience) return undefined;
-    return { learn_experience };
+    if (!learnExperience) return undefined;
+    return { learnExperience };
   }
 
   async freeSail(opts?: { strategy?: 'deep' | 'shallow'; scope?: string; visitedUrls?: Set<string> }, actionResult?: ActionResult): Promise<{ target: string; reason: string } | null> {

package/src/ai/pilot.ts

@@ -439,14 +439,14 @@ export class Pilot implements Agent {
         the elements needed for the scenario. The page summary does not list every element.
         Prefer interacting with the current page over navigating away.
 
-        If you load a recipe via learn_experience, do NOT rewrite its code in your plan — the
+        If you load a recipe via learnExperience, do NOT rewrite its code in your plan — the
         raw recipe is forwarded to Tester automatically. Reference it by step ("apply recipe
         steps 1–3, then…") and call out anywhere your scenario diverges from it.
 
         Be concise and specific. Tester will follow your plan.
       `,
       'pilot.planTest',
-      { tools: true, planningOnly: true, maxToolRoundtrips: 3, task }
+      { tools: true, maxToolRoundtrips: 3, task }
     );
   }
 
@@ -547,7 +547,7 @@ export class Pilot implements Agent {
     return `CHECKED: ${checked.length > 0 ? checked.join(', ') : 'none'}\nREMAINING: ${remaining.length > 0 ? remaining.join(', ') : 'none'}`;
   }
 
-  private async sendToPilot(userText: string, functionId: string, opts: { tools?: boolean; planningOnly?: boolean; maxToolRoundtrips?: number; task?: Test } = {}): Promise<string> {
+  private async sendToPilot(userText: string, functionId: string, opts: { tools?: boolean; maxToolRoundtrips?: number; task?: Test } = {}): Promise<string> {
     debugLog(`sendToPilot: ${functionId}, tools: ${!!opts.tools}, roundtrips: ${opts.maxToolRoundtrips ?? 0}`);
 
     let finalUserText = userText;
@@ -560,7 +560,7 @@ export class Pilot implements Agent {
     this.conversation!.addUserText(finalUserText);
     let tools: any;
     if (opts.tools) {
-      tools = opts.planningOnly ? this.pickPlanningTools() : this.agentTools;
+      tools = this.pickPlanningTools();
     }
 
     if (opts.tools && opts.task) {
@@ -574,7 +574,7 @@ export class Pilot implements Agent {
       experimental_telemetry: { functionId },
     });
     const text = result?.response?.text || '';
-    const learned = (result?.toolExecutions || []).filter((e: any) => e.toolName === 'learn_experience' && e.output?.content).map((e: any) => e.output.content);
+    const learned = (result?.toolExecutions || []).filter((e: any) => e.toolName === 'learnExperience' && e.output?.content).map((e: any) => e.output.content);
     if (learned.length === 0) return text;
     return dedent`
       ${text}
@@ -598,7 +598,7 @@ export class Pilot implements Agent {
   }
 
   private pickPlanningTools() {
-    const { see, context, verify, research, getVisitedStates, xpathCheck, learn_experience } = this.agentTools ?? {};
+    const { see, context, verify, research, getVisitedStates, xpathCheck, learnExperience, askUser } = this.agentTools ?? {};
     const planning: Record<string, unknown> = {};
     if (see) planning.see = see;
     if (context) planning.context = context;
@@ -606,7 +606,8 @@ export class Pilot implements Agent {
     if (research) planning.research = research;
     if (getVisitedStates) planning.getVisitedStates = getVisitedStates;
     if (xpathCheck) planning.xpathCheck = xpathCheck;
-    if (learn_experience) planning.learn_experience = learn_experience;
+    if (learnExperience) planning.learnExperience = learnExperience;
+    if (askUser) planning.askUser = askUser;
     return planning;
   }
 

package/src/ai/tester.ts

@@ -750,7 +750,7 @@ export class Tester extends TaskAgent implements Agent {
     - When filling complex form with lot of actions performed, use see() to look which fields were filled and which are not
     - When verify() fails, use see() to visually confirm the result — visual confirmation is equally valid evidence
     - For visual state verification (active tabs, selected items, counts, colors), prefer see() over DOM-based verify()
-    - When click() fails and element is visually present, use visualClick() as fallback
+    - When click() fails on an element you can see — or believe is there but may look different — you MUST try visualClick() before giving up; don't repeat visualClick in a row
     - If you land on a "Not Found", 404, or error page that is NOT part of the scenario, call reset() immediately to return to the initial page and try again
     - If you see a server error page (500, 503, etc.), record it with record({ notes: ["Server error on /path"], status: "fail" }) and call reset() to continue testing
     </rules>

package/src/ai/tools.ts

@@ -466,12 +466,14 @@ export function createAgentTools({
   navigator,
   experienceTracker,
   getState,
+  supervisor,
 }: {
   explorer: Explorer;
   researcher: Researcher;
   navigator: Navigator;
   experienceTracker?: ExperienceTracker;
   getState?: () => ActionResult | null;
+  supervisor?: boolean;
 }): any {
   let visionDisabled = false;
 
@@ -803,46 +805,6 @@ export function createAgentTools({
       },
     }),
 
-    askUser: tool({
-      description: dedent`
-        Ask the user for help when you're stuck or unsure how to proceed.
-        Only available in interactive mode (TUI).
-
-        Use when:
-        - Locator-based clicks keep failing
-        - You can't find an element that should exist
-        - Form interaction isn't working as expected
-        - You need clarification on what action to take
-      `,
-      inputSchema: z.object({
-        question: z.string().describe('What you need help with - be specific about what failed'),
-        context: z.string().optional().describe('Relevant context like locators tried, errors received'),
-      }),
-      execute: async ({ question, context }) => {
-        if (!isInteractive()) {
-          return {
-            success: false,
-            message: 'User input not available in non-interactive mode',
-            suggestion: 'Continue with automated recovery',
-          };
-        }
-
-        const prompt = context ? `${question}\n\nContext: ${context}\n\nYour suggestion ("skip" to continue):` : `${question}\n\nYour suggestion ("skip" to continue):`;
-
-        const userInput = await pause(prompt);
-
-        if (!userInput || userInput.toLowerCase() === 'skip') {
-          return { success: false, message: 'User skipped' };
-        }
-
-        return {
-          success: true,
-          userSuggestion: userInput,
-          instruction: 'Follow the user suggestion. Use interact() tool to execute.',
-        };
-      },
-    }),
-
     back: tool({
       description: dedent`
         Navigate back to the previous page (most recent URL different from current).
@@ -973,7 +935,7 @@ export function createAgentTools({
   };
 
   if (experienceTracker && getState) {
-    tools.learn_experience = tool({
+    tools.learnExperience = tool({
       description: dedent`
         Read the full body of a specific experience section listed in <experience>.
         The TOC shows entries like "A.1 ## FLOW: ..." or "A.2 ## ACTION: ...". Pass the fileTag and sectionIndex.
@@ -997,6 +959,48 @@ export function createAgentTools({
     });
   }
 
+  if (supervisor) {
+    tools.askUser = tool({
+      description: dedent`
+        Ask the user for help when automated recovery is stuck or the next step is unclear.
+        Only available in interactive mode (TUI).
+
+        Use when:
+        - The Tester keeps failing the same locator/element
+        - An element that should exist cannot be found
+        - Form interaction isn't working as expected
+        - You need a human decision on how to proceed
+      `,
+      inputSchema: z.object({
+        question: z.string().describe('What you need help with - be specific about what failed'),
+        context: z.string().optional().describe('Relevant context like locators tried, errors received'),
+      }),
+      execute: async ({ question, context }) => {
+        if (!isInteractive()) {
+          return {
+            success: false,
+            message: 'User input not available in non-interactive mode',
+            suggestion: 'Continue with automated recovery',
+          };
+        }
+
+        const prompt = context ? `${question}\n\nContext: ${context}\n\nYour suggestion ("skip" to continue):` : `${question}\n\nYour suggestion ("skip" to continue):`;
+
+        const userInput = await pause(prompt);
+
+        if (!userInput || userInput.toLowerCase() === 'skip') {
+          return { success: false, message: 'User skipped' };
+        }
+
+        return {
+          success: true,
+          userSuggestion: userInput,
+          instruction: 'Relay this suggestion to the Tester as the next concrete step.',
+        };
+      },
+    });
+  }
+
   return tools;
 }
 

package/src/experience-tracker.ts

@@ -499,7 +499,7 @@ export function renderExperienceToc(toc: ExperienceTocEntry[]): string {
   lines.push('Locators and step ordering worked then; the page may have changed since.');
   lines.push('Treat as a starting hypothesis, not ground truth. If a step fails, fall back to ARIA/UI-map.');
   lines.push('FLOW: = multi-step recipe (bullets + code + discovery). ACTION: = single-step snippet (one code block).');
-  lines.push('Call learn_experience({ fileTag, sectionIndex }) to read a section when it looks relevant to the current step.');
+  lines.push('Call learnExperience({ fileTag, sectionIndex }) to read a section when it looks relevant to the current step.');
   lines.push('');
   for (const entry of toc) {
     lines.push(`File ${entry.fileTag} ${entry.url}:`);

package/src/explorbot.ts

@@ -210,7 +210,7 @@ export class ExplorBot {
         const state = stateManager.getCurrentState();
         return state ? ActionResult.fromState(state) : null;
       };
-      const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState });
+      const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState, supervisor: true });
       return new Pilot(ai, tools, researcher, explorer, experienceTracker);
     }));
   }