explorbot 0.5.3 → 0.5.4

package/src/ai/pilot.ts

@@ -8,7 +8,7 @@ import type Explorer from '../explorer.ts';
 import type { PlaywrightRecorder } from '../playwright-recorder.ts';
 import type { StateManager } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
-import { type Test, TestResult, TestStatus } from '../test-plan.ts';
+import { SettledExpectation, type SettledStatus, type Test, TestResult, TestStatus } from '../test-plan.ts';
 import { collectInteractiveNodes } from '../utils/aria.ts';
 import { ErrorPageError } from '../utils/error-page.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -39,6 +39,12 @@ const OUTCOME_STATUS: Record<string, SettledStatus> = {
   'The run shows this outcome did not happen.': 'failed',
 };
 
+const CONTRADICTION_RESOLUTION: Record<string, { status: SettledStatus; resolution: string }> = {
+  'The page structure agrees with the screenshot, and the outcome happened.': { status: 'passed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+  'The page structure agrees with the screenshot, and the outcome did not happen.': { status: 'failed', resolution: 'the page structure agrees with the screenshot, so the run log was wrong' },
+  'The page structure agrees with the run log: the page holds it, but the screenshot does not show it.': { status: 'contradiction', resolution: 'the page structure agrees with the run log: the page holds it but does not display it, a likely rendering bug' },
+};
+
 export class Pilot implements Agent {
   emoji = '🧭';
   private provider: Provider;
@@ -619,7 +625,7 @@ export class Pilot implements Agent {
     let settledByJudge = new Map<string, SettledStatus>();
     if (!image) settledByJudge = await this.settleByJudge(task, undecided);
     undecided = undecided.filter((text) => !settledByJudge.has(text));
-    if (!undecided.length) return task.expected.map((text) => ({ text, status: settledByJudge.get(text) || decided(text) }));
+    if (!undecided.length) return task.expected.map((text) => new SettledExpectation(text, settledByJudge.get(text) || decided(text)));
 
     const schema = z.object({
       outcomes: z.array(
@@ -691,14 +697,36 @@ export class Pilot implements Agent {
     if (!response) response = await settle(userContent, this.provider.getAgenticModel('pilot'));
 
     const judged = new Map((response?.object?.outcomes || []).map((outcome: any) => [outcome.expectation, outcome]));
-    return task.expected.map((text) => {
+    const settled = task.expected.map((text) => {
       const byJudge = settledByJudge.get(text);
-      if (byJudge) return { text, status: byJudge };
-      if (!undecided.includes(text)) return { text, status: decided(text) };
+      if (byJudge) return new SettledExpectation(text, byJudge);
+      if (!undecided.includes(text)) return new SettledExpectation(text, decided(text));
       const outcome = judged.get(text) as { status: SettledStatus; evidence?: string } | undefined;
-      if (!outcome) return { text, status: 'unverified' as SettledStatus };
-      return { text, status: outcome.status || 'unverified', evidence: outcome.evidence };
+      if (!outcome) return new SettledExpectation(text, 'unverified');
+      return new SettledExpectation(text, outcome.status || 'unverified', outcome.evidence);
     });
+    return this.resolveContradictions(settled, finalState);
+  }
+
+  private async resolveContradictions(outcomes: SettledExpectation[], finalState?: ActionResult): Promise<SettledExpectation[]> {
+    const judge = this.judge;
+    if (!judge || !finalState) return outcomes;
+    if (!outcomes.some((outcome) => outcome.contradicted)) return outcomes;
+
+    const page = finalState.getCompactARIA().slice(0, JUDGE_PAGE_CAP);
+    return Promise.all(
+      outcomes.map(async (outcome) => {
+        if (!outcome.contradicted) return outcome;
+        const decision = await judge.decide(`The screenshot and the run log disagree about the expected outcome: ${outcome.text}. Which side does the page structure support?`, [...Object.keys(CONTRADICTION_RESOLUTION), UNDECIDED], {
+          expectation: outcome.text,
+          disagreement: outcome.evidence || '',
+          page,
+        });
+        const resolved = CONTRADICTION_RESOLUTION[decision.value ?? ''];
+        if (!resolved) return outcome;
+        return outcome.resolve(resolved.status, resolved.resolution);
+      })
+    );
   }
 
   private async settleByJudge(task: Test, expectations: string[]): Promise<Map<string, SettledStatus>> {
@@ -1275,11 +1303,3 @@ export class Pilot implements Agent {
     `;
   }
 }
-
-export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
-
-export interface SettledExpectation {
-  text: string;
-  status: SettledStatus;
-  evidence?: string;
-}

package/src/ai/researcher.ts

@@ -103,8 +103,8 @@ export class Researcher extends ResearcherBase implements Agent {
     `;
   }
 
-  async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; _retriesLeft?: number } = {}): Promise<string> {
-    const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
+  async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; light?: boolean; _retriesLeft?: number } = {}): Promise<string> {
+    const { screenshot = false, force = false, deep = false, data = false, fix = true, light = false } = opts;
     const maxRetries = this.settings.retries ?? 2;
     let retriesLeft = opts._retriesLeft ?? maxRetries;
     this.actionResult = ActionResult.fromState(state);
@@ -133,6 +133,7 @@ export class Researcher extends ResearcherBase implements Agent {
     return Observability.run(sessionName, { tags: ['researcher'], sessionId: stateHash }, async () => {
       const displayUrl = state.fullUrl || state.url;
       tag('info').log(`Researching ${displayUrl} to understand the context...`);
+      if (light) tag('info').log('Light research: single pass, locator verification skipped');
       setActivity(`${this.emoji} Researching...`, 'action');
 
       await this.ensureNavigated(displayUrl, screenshot && this.provider.hasVision());
@@ -171,7 +172,7 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       const isOnCurrentState = this.actionResult!.getStateHash() === this.stateManager.getCurrentState()?.hash;
-      this.hasScreenshotToAnalyze = screenshot && this.provider.hasVision() && isOnCurrentState;
+      this.hasScreenshotToAnalyze = !light && screenshot && this.provider.hasVision() && isOnCurrentState;
 
       const conversation = this.provider.startConversation(this.getSystemMessage(), 'researcher');
 
@@ -205,13 +206,13 @@ export class Researcher extends ResearcherBase implements Agent {
       result.parseLocators();
       debugLog(`Extracted ${result.locators.length} locators from research`);
 
-      if (!interrupted() && result.locators.length === 0 && retriesLeft > 0) {
+      if (!light && !interrupted() && result.locators.length === 0 && retriesLeft > 0) {
         tag('warning').log(`No locators parsed, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
         await new Promise((r) => setTimeout(r, 1000));
         return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 } as any);
       }
 
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         const brokenContainers = await this.resolveContainers(result);
         const containerCount = result.containers.length;
         if (containerCount > 0 && brokenContainers.length === containerCount && retriesLeft > 0) {
@@ -232,7 +233,7 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       // Stage 3: Fix broken sections via AI conversation continuation
-      if (!interrupted() && fix && result.locators.some((l) => l.valid === false)) {
+      if (!light && !interrupted() && fix && result.locators.some((l) => l.valid === false)) {
         await this.fixBrokenSections(result, activeConversation);
       }
 
@@ -273,12 +274,12 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       // Stage 5: Backfill broken elements
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         await this.backfillCoordinates(result);
         await this.backfillBrokenLocators(result);
       }
 
-      if (!interrupted()) {
+      if (!light && !interrupted()) {
         await this.detectPagination(result);
       }
 
@@ -309,7 +310,7 @@ export class Researcher extends ResearcherBase implements Agent {
       result.cleanup();
 
       let researchFile: string | null = null;
-      if (stateHash) {
+      if (stateHash && !light) {
         researchFile = saveResearch(researchState, result.text, combinedHtml);
       }
 

package/src/ai/tools.ts

@@ -112,7 +112,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
         let ambiguityError: Error | null = null;
 
         for (let i = 0; i < commands.length; i++) {
-          const command = transformContainsCommand(commands[i]);
+          let command = transformContainsCommand(commands[i]);
           let success = await action.attempt(command, explanation);
 
           const attempt: { command: string; success: boolean; error?: string } = { command, success };
@@ -125,10 +125,14 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDep
               const labels = (await extractWebElements(ambiguityError))?.map((el) => el.label) || [];
               const index = await judge.pick(PICK_ELEMENT_QUESTION, labels, { intent: explanation, task: task.description });
               if (index) success = await action.attemptExactElementIndex(command, index, explanation);
+              if (success) command = action.executedSteps.map((step) => step.command).join('\n') || command;
             }
           }
 
           if (success) {
+            attempt.command = command;
+            attempt.success = true;
+            attempt.error = undefined;
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
 
             if (!hasObservablePageChange(toolResult)) {

package/src/explorbot.ts

@@ -155,7 +155,7 @@ export class ExplorBot {
   }
 
   async visit(url: string): Promise<void> {
-    return this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
+    await this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
   }
 
   async openTab(): Promise<void> {

package/src/test-plan.ts

@@ -66,6 +66,29 @@ export class ActiveNote {
   }
 }
 
+export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';
+
+export class SettledExpectation {
+  constructor(
+    readonly text: string,
+    readonly status: SettledStatus,
+    readonly evidence?: string,
+    readonly resolution?: string
+  ) {}
+
+  get failed(): boolean {
+    return this.status === 'failed';
+  }
+
+  get contradicted(): boolean {
+    return this.status === 'contradiction';
+  }
+
+  resolve(status: SettledStatus, resolution: string): SettledExpectation {
+    return new SettledExpectation(this.text, status, this.evidence, resolution);
+  }
+}
+
 export interface StepData {
   text: string;
   duration?: number;

package/src/utils/code-extractor.ts

@@ -3,6 +3,9 @@ import { createDebug } from './logger.js';
 const debugLog = createDebug('explorbot:code-extractor');
 
 const JS_LANGUAGES = new Set(['', 'js', 'javascript']);
+const QUOTES = ["'", '"', '`'];
+const OPENING_BRACKETS = ['(', '[', '{'];
+const CLOSING_BRACKETS = [')', ']', '}'];
 
 export function extractCodeBlocks(aiResponse: string): string[] {
   const codeBlockRegex = /```([^\n`]*)\n([\s\S]*?)\n```/g;
@@ -24,3 +27,41 @@ export function extractCodeBlocks(aiResponse: string): string[] {
 
   return codeBlocks;
 }
+
+export function splitTopLevel(code: string, separator: string): string[] {
+  const parts: string[] = [];
+  let current = '';
+  let depth = 0;
+  let quote = '';
+
+  for (let i = 0; i < code.length; i++) {
+    const char = code[i];
+
+    if (quote) {
+      current += char;
+      if (char === '\\') current += code[++i] || '';
+      if (char === quote) quote = '';
+      continue;
+    }
+
+    if (char === '/' && code[i + 1] === '/') {
+      while (i + 1 < code.length && code[i + 1] !== '\n') i++;
+      continue;
+    }
+
+    if (char === separator && depth <= 0) {
+      parts.push(current);
+      current = '';
+      depth = 0;
+      continue;
+    }
+
+    current += char;
+    if (QUOTES.includes(char)) quote = char;
+    if (OPENING_BRACKETS.includes(char)) depth++;
+    if (CLOSING_BRACKETS.includes(char)) depth--;
+  }
+
+  parts.push(current);
+  return parts;
+}

package/src/utils/html.ts

@@ -88,6 +88,7 @@ export const EXPLORBOT_ATTRS = {
   coveredBy: 'data-explorbot-covered-by',
   context: 'data-explorbot-context',
   eidx: 'data-explorbot-eidx',
+  hidden: 'data-explorbot-hidden',
   hit: 'data-explorbot-hit',
   variant: 'data-explorbot-variant',
 } as const;
@@ -189,6 +190,17 @@ export function captureHtmlForSnapshot(): string {
     }
   }
 
+  const liveElements = Array.from(document.body?.querySelectorAll('*') || []);
+  const clonedElements = Array.from(clone.querySelector('body')?.querySelectorAll('*') || []);
+  for (let i = 0; i < liveElements.length; i++) {
+    const source = liveElements[i];
+    if (source.matches('input, textarea, select, option, optgroup')) continue;
+    if (source.checkVisibility()) continue;
+    if (!source.parentElement?.checkVisibility()) continue;
+    if (getComputedStyle(source).display === 'contents') continue;
+    clonedElements[i]?.setAttribute('data-explorbot-hidden', 'true');
+  }
+
   return clone.outerHTML;
 }
 
@@ -1493,7 +1505,27 @@ function getAttribute(element: parse5TreeAdapter.Element, name: string): string
   return attr?.value;
 }
 
+function getImgAlt(element: parse5TreeAdapter.Element): string {
+  let alt = '';
+
+  function processNode(node: parse5TreeAdapter.Node) {
+    if (alt) return;
+    if ('tagName' in node) {
+      const el = node as parse5TreeAdapter.Element;
+      if (el.tagName.toLowerCase() === 'img') {
+        alt = getAttribute(el, 'alt') || '';
+        return;
+      }
+    }
+    if ('childNodes' in node) node.childNodes.forEach(processNode);
+  }
+
+  processNode(element);
+  return alt;
+}
+
 function hasHiddenClass(element: parse5TreeAdapter.Element): boolean {
+  if (getAttribute(element, EXPLORBOT_ATTRS.hidden)) return true;
   const classAttr = element.attrs.find((attr) => attr.name === 'class');
   if (!classAttr) return false;
 
@@ -1553,7 +1585,7 @@ export function extractLinks(html: string): ExtractedLink[] {
         if (href) {
           const shouldSkip = skipPrefixes.some((prefix) => href.startsWith(prefix));
           if (!shouldSkip) {
-            const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element);
+            const rawTitle = getAttribute(element, 'aria-label') || getTextContent(element) || getImgAlt(element);
             const title = sanitizeLinkTitle(rawTitle);
             if (title && title.length <= 100) {
               const key = `${href}|${title}`;

package/src/utils/mdq/cli.ts

@@ -1,5 +1,5 @@
 import { readFileSync, writeFileSync } from 'node:fs';
-import { Command } from 'commander';
+import { Command, type CommanderError } from 'commander';
 import { type MarkdownQuery, MdqError, mdq } from './query.ts';
 
 const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend', 'append', 'addRow', 'addItem', 'set'] as const;
@@ -7,7 +7,7 @@ const EDIT_FLAGS = ['remove', 'replace', 'insertBefore', 'insertAfter', 'prepend
 export async function runMdq(argv: string[], readStdin: StdinReader): Promise<CliResult> {
   const program = new Command();
   program
-    .name('mdq')
+    .name('mdq-cli')
     .description('query and edit markdown')
     .argument('[selector]', 'markdown selector')
     .argument('[file]', 'file to read; stdin when omitted')
@@ -31,6 +31,7 @@ export async function runMdq(argv: string[], readStdin: StdinReader): Promise<Cl
   try {
     program.parse(argv, { from: 'user' });
   } catch (error) {
+    if ((error as CommanderError).code === 'commander.helpDisplayed') return { output: program.helpInformation(), code: 0 };
     return { output: String((error as Error).message), code: 2 };
   }
 

package/src/utils/web-sandbox.ts

@@ -1,6 +1,7 @@
 import { faker } from '@faker-js/faker';
 import { hopeThat, retryTo, tryTo, within } from 'codeceptjs/lib/effects';
 import step from 'codeceptjs/steps';
+import { splitTopLevel } from './code-extractor.ts';
 
 const SHADOWED_GLOBALS = ['process', 'global', 'globalThis', 'fetch', 'Bun', 'require', 'module', 'exports'];
 const ALLOWED_COMMAND_HEADS = ['I.', 'page.', 'await page.', 'await I.'];
@@ -9,10 +10,9 @@ const PLAYWRIGHT_ARG_NAMES = ['page'];
 const CODECEPT_ARG_NAMES = ['I', 'tryTo', 'retryTo', 'within', 'hopeThat', 'step', 'faker'];
 
 export function sanitizeCodeBlock(code: string): string {
-  return code
-    .split('\n')
-    .map((line) => line.trim())
-    .filter((line) => ALLOWED_COMMAND_HEADS.some((head) => line.startsWith(head)))
+  return splitTopLevel(code, '\n')
+    .map((statement) => statement.trim())
+    .filter((statement) => ALLOWED_COMMAND_HEADS.some((head) => statement.startsWith(head)))
     .join('\n');
 }