explorbot 0.4.6 → 0.4.8

package/src/ai/researcher/pagination.ts

@@ -0,0 +1,68 @@
+import type Explorer from '../../explorer.ts';
+import { mdq } from '../../utils/markdown-query.ts';
+import { type ListMeasure, type PaginationStrategy, inspectList, restoreScroll } from '../../utils/pagination.ts';
+import { type Constructor, debugLog } from './mixin.ts';
+import { extractPaginationFromBlockquote, parseDataSections, parseResearchSections } from './parser.ts';
+import type { ResearchResult } from './research-result.ts';
+
+export function WithPagination<T extends Constructor>(Base: T) {
+  return class extends Base {
+    declare explorer: Explorer;
+
+    async detectPagination(result: ResearchResult): Promise<void> {
+      const sections = [...parseResearchSections(result.text), ...parseDataSections(result.text)];
+
+      for (const section of sections) {
+        const css = section.containerCss;
+        if (!css) continue;
+        if (extractPaginationFromBlockquote(section.rawMarkdown)) continue;
+
+        const strategy = await this.probeSection(css);
+        if (!strategy) continue;
+
+        this.recordPagination(result, section.name, strategy);
+        debugLog(`Pagination in "${section.name}": ${strategy}`);
+      }
+    }
+
+    private async probeSection(css: string): Promise<PaginationStrategy | null> {
+      const before = await this.measure(css);
+      if (!before) return null;
+      if (before.hasPagingControls) return 'controls';
+      if (before.isFeed) return 'infinite';
+      if (!before.scrolls) return null;
+
+      const action = this.explorer.action();
+      const scrolled = await action.attempt(`I.scrollTo('${css} > *:last-child')`).catch(() => false);
+      if (!scrolled) return null;
+
+      const after = await this.measure(css);
+      await this.explorer.withPage((page) => page.evaluate(restoreScroll, { css, scrollTop: before.scrollTop, pageScrollY: before.pageScrollY })).catch(() => {});
+
+      if (!after) return null;
+      if (after.items > before.items) return 'infinite';
+      return null;
+    }
+
+    private measure(css: string): Promise<ListMeasure | null> {
+      return this.explorer
+        .withPage((page) => page.evaluate(inspectList, css))
+        .catch((err: Error) => {
+          debugLog(`List measurement failed for '${css}': ${err.message}`);
+          return null;
+        });
+    }
+
+    private recordPagination(result: ResearchResult, name: string, strategy: PaginationStrategy): void {
+      const escaped = name.replace(/"/g, '\\"');
+      let sectionQuery = mdq(result.text).query(`section2(~"${escaped}")`);
+      if (sectionQuery.count() === 0) sectionQuery = mdq(result.text).query(`section3(~"${escaped}")`);
+      if (sectionQuery.count() === 0) return;
+      result.text = sectionQuery.query('blockquote[0]').setKeyValue('Pagination', strategy);
+    }
+  };
+}
+
+export interface PaginationMethods {
+  detectPagination(result: ResearchResult): Promise<void>;
+}

package/src/ai/researcher/parser.ts

@@ -2,6 +2,7 @@ import { parseAriaLocator } from '../../utils/aria.ts';
 import { pluralize } from '../../utils/logger.ts';
 import { jsonToTable, parseSections, tableToJson } from '../../utils/markdown-parser.ts';
 import { mdq } from '../../utils/markdown-query.ts';
+import type { PaginationStrategy } from '../../utils/pagination.ts';
 import { FOCUSED_MARKER } from './focus.ts';
 
 export interface ResearchElement {
@@ -84,11 +85,9 @@ export function mapRowToElement(row: Record<string, string>): ResearchElement |
 }
 
 export function extractContainerFromBlockquote(sectionMarkdown: string): string | null {
-  const bq = mdq(sectionMarkdown).query('blockquote[0]').text().trim();
-  if (!bq) return null;
-  const match = bq.match(/Container:\s*(.+)/i);
-  if (!match) return null;
-  const css = normalizeLocatorValue(match[1]);
+  const entry = mdq(sectionMarkdown).query('blockquote[0]').keyValue().container;
+  if (!entry) return null;
+  const css = normalizeLocatorValue(entry);
   if (!css || !/^[.#\[\w]/.test(css)) return null;
   return css;
 }
@@ -108,6 +107,25 @@ export function parseResearchSections(markdown: string): ResearchSection[] {
     });
 }
 
+export function parseDataSections(markdown: string): ResearchSection[] {
+  return parseSections(markdown)
+    .filter((s) => s.name.toLowerCase().startsWith('data:'))
+    .map((section) => ({
+      name: section.name,
+      containerCss: extractContainerFromBlockquote(section.rawMarkdown),
+      elements: [],
+      rawMarkdown: section.rawMarkdown,
+      isExtended: false,
+    }));
+}
+
+export function extractPaginationFromBlockquote(sectionMarkdown: string): PaginationStrategy | null {
+  const value = mdq(sectionMarkdown).query('blockquote[0]').keyValue().pagination?.toLowerCase();
+  if (value === 'controls') return 'controls';
+  if (value === 'infinite') return 'infinite';
+  return null;
+}
+
 export function extractValidContainers(researchText: string, opts?: { exclude?: string[] }): Array<{ css: string; label: string }> {
   const exclude = opts?.exclude || [];
   return parseResearchSections(researchText)

package/src/ai/researcher/sections.ts

@@ -78,7 +78,7 @@ export function WithSections<T extends Constructor>(Base: T) {
 
     private async _researchSingleSection(name: string, description: string, ariaSnapshot: string, focusCss: string | null): Promise<string> {
       const currentUrl = this.stateManager.getCurrentState()?.url || '';
-      const rules = RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl);
+      const rules = RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules', 'pagination'], currentUrl);
       const url = this.actionResult?.url || 'Unknown';
       const title = this.actionResult?.title || 'Unknown';
 

package/src/ai/researcher.ts

@@ -24,6 +24,7 @@ import { type CoordinateMethods, WithCoordinates } from './researcher/coordinate
 import { type DeepAnalysisMethods, WithDeepAnalysis } from './researcher/deep-analysis.ts';
 import { detectFocusedSection, hasFocusedSection, markSectionAsFocused, pickDefaultFocusedSection } from './researcher/focus.ts';
 import { type LocatorMethods, WithLocators } from './researcher/locators.ts';
+import { type PaginationMethods, WithPagination } from './researcher/pagination.ts';
 import { extractValidContainers, formatResearchSummary, parseResearchSections } from './researcher/parser.ts';
 import { ResearchResult } from './researcher/research-result.ts';
 import { type SectionMethods, WithSections } from './researcher/sections.ts';
@@ -44,9 +45,9 @@ export const POSSIBLE_SECTIONS = {
   navigation: 'main navigation (top bar, sidebar, breadcrumbs)',
 };
 
-const ResearcherBase = WithSections(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent as unknown as new (...args: any[]) => TaskAgent))));
+const ResearcherBase = WithSections(WithPagination(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent as unknown as new (...args: any[]) => TaskAgent)))));
 
-export interface Researcher extends LocatorMethods, CoordinateMethods, DeepAnalysisMethods, SectionMethods {}
+export interface Researcher extends LocatorMethods, CoordinateMethods, DeepAnalysisMethods, SectionMethods, PaginationMethods {}
 
 export class Researcher extends ResearcherBase implements Agent {
   protected readonly ACTION_TOOLS = ['click'];
@@ -277,6 +278,10 @@ export class Researcher extends ResearcherBase implements Agent {
         await this.backfillBrokenLocators(result);
       }
 
+      if (!interrupted()) {
+        await this.detectPagination(result);
+      }
+
       // Focused section: final fallback (vision-only — without a screenshot we don't infer focus)
       if (this.hasScreenshotToAnalyze && !hasFocusedSection(result.text)) {
         const sections = parseResearchSections(result.text);
@@ -426,7 +431,7 @@ export class Researcher extends ResearcherBase implements Agent {
 
       ${generalLocatorRuleText}
 
-      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl)}
+      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules', 'pagination'], currentUrl)}
 
       <section_identification>
       Identify page sections in this priority order:
@@ -502,6 +507,7 @@ export class Researcher extends ResearcherBase implements Agent {
       - When a section contains a list of similar data items (records, entities, rows — content that varies by data, not by app UI), output it as a Data section with NO table.
       - Data section heading MUST be a level-2 heading (##) that starts exactly with "Data:" — for example: "## Data: Suites List". Do NOT use ### or add section numbers.
       - Data sections must NOT include a UI map table. Only include the container and a brief summary line.
+      - When the data list has controls that move between pages of the collection, add "> Pagination: controls" under its container.
       - Example data section:
 
       ## Data: Suites List

package/src/ai/rules.ts

@@ -188,6 +188,7 @@ export const capabilityGroundingRule = dedent`
   When a scenario depends on a named action, menu item, status, option, workflow, or feature,
   that capability must be visible or explicitly confirmed in the current research/page context
   for the same target entity type.
+  Ground on the scenario's outcome, not a planned step's control label — a missing label is not a missing capability.
 
   Do not transfer capabilities between similar entities, rows, lists, detail pages, or menus.
   Do not replace a requested action with a synonym or related action unless the UI explicitly
@@ -349,6 +350,22 @@ export const actionRule = dedent`
   For checkboxes, prefer I.checkOption/I.uncheckOption over I.click.
 
 
+  ### I.scrollTo
+
+  scrolls until the element is in view
+
+  I.scrollTo(<locator>)
+
+  Scrolls every scrollable ancestor of the target, so it reaches an element inside a container
+  that has its own scrollbar. I.scrollPageToBottom() moves only the page itself.
+
+  <example>
+    I.scrollTo('.rows > *:last-child');
+    I.scrollTo({ role: 'listitem', text: 'Last entry' });
+    I.scrollPageToBottom();
+  </example>
+
+
   ### I.fillField
 
   fills the field with the given value

package/src/ai/scout.ts

@@ -56,13 +56,20 @@ export class Scout implements Agent {
           agentName: 'scout',
         });
 
+        const responseText = invokeResult?.response?.text;
+        if (responseText?.trim()) {
+          finishFromText(responseText);
+          stop();
+          return;
+        }
+
         if (!invokeResult?.toolExecutions?.length) {
-          finishFromText(invokeResult?.response?.text);
           stop();
           return;
         }
 
-        if (iteration >= MAX_ITERATIONS) {
+        if (iteration >= MAX_ITERATIONS - 1) {
+          conversation.addUserText('Exploration time is over. Report your findings now as your final message.');
           const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
           finishFromText(final?.response?.text);
           stop();

package/src/ai/tester.ts

@@ -41,7 +41,7 @@ const SAMPLE_FILES: Record<string, string> = {
 
 export class Tester extends TaskAgent implements Agent {
   protected readonly ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
-  protected readonly DELEGATED_ACTION_TOOLS = ['interact'];
+  protected readonly DELEGATED_ACTION_TOOLS = ['interact', 'visualClick'];
   protected readonly SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
   emoji = '🧪';
   private requestStore: RequestStore;

package/src/ai/tools.ts

@@ -374,6 +374,8 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
         - Working with iframes (switch context with I.switchTo)
         - Performing multiple form actions in a single batch
         - Complex interactions requiring sequential commands
+        - Reaching items further down a list (I.scrollTo)
+        - Reloading the page to prove a change outlived it (I.reloadPage)
 
         Example - filling a form with context (PREFERRED):
         I.fillField('Username', 'John', '.login-form')
@@ -386,7 +388,7 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
         I.selectOption({"role":"combobox","text":"Category"}, 'Technology')
 
         Do not submit form - use verify() first to check fields were filled correctly, then click() to submit.
-        Do not use: wait functions, amOnPage, reloadPage, saveScreenshot        
+        Do not use: wait functions, amOnPage, saveScreenshot        
       `,
       inputSchema: z.object({
         codeBlock: z.string().describe('Valid CodeceptJS code starting with I. Can contain multiple commands separated by newlines.'),
@@ -441,10 +443,10 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
 
           if (!hasObservablePageChange(toolResult)) {
             activeNote.commit(TestResult.FAILED);
-            return failedToolResult('form', 'Form command executed, but no observable page or form-state change was captured.', {
+            return failedToolResult('form', 'Command executed, but nothing on the page changed: no navigation, no ARIA change, no HTML change and no request.', {
               ...toolResult,
               code: codeBlock,
-              suggestion: 'Treat the field/form action as not completed. Re-locate the editable control, check whether another UI layer is active, then retry and verify the field value before submitting.',
+              suggestion: 'The command ran without reaching anything. Re-locate the target, check whether another UI layer is active, then retry. If the goal was to load more of a list, no change means the collection has ended.',
             });
           }
           await commitNote(activeNote, TestResult.PASSED, toolResult, action);
@@ -1238,7 +1240,10 @@ export function successToolResult(action: string, data?: Record<string, any>, so
 }
 
 export function isMajorPageChange(pageDiff: PageDiff): boolean {
-  return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
+  if (pageDiff.urlChanged === true) return false;
+  if ((pageDiff.ariaChangeCount ?? 0) < LARGE_ARIA_CHANGE_THRESHOLD) return false;
+  if (pageDiff.ariaRemoved === 0 && (pageDiff.ariaAdded ?? 0) > 0) return false;
+  return true;
 }
 
 export function hasFailedRequest(pageDiff: PageDiff): boolean {

package/src/commands/options/ws-option.ts

@@ -6,6 +6,20 @@ export class WsOption extends BaseOption {
   flags = '--ws <url>';
   description = 'Stream this run to a remote UI over WebSocket';
 
+  /**
+   * An open socket holds the event loop, and `WebSocket` has no `unref` on
+   * either runtime — so a command that ends by returning rather than through
+   * `showStatsAndExit` would never exit once it is attached. The option that
+   * opened the connection is what closes it.
+   */
+  override register(command: Command): void {
+    super.register(command);
+    command.hook('postAction', async () => {
+      if (!remote.isAttached()) return;
+      await remote.close(0);
+    });
+  }
+
   protected apply(options: Record<string, any>, command: Command): void {
     const url = options.ws || process.env.EXPLORBOT_WS_URL;
     if (!url) return;

package/src/config.ts

@@ -677,17 +677,7 @@ export class ConfigParser {
       config.playwright.url = options.baseUrl;
     }
 
-    if (config.ai) {
-      const langfuse = config.ai.langfuse;
-      const publicKey = langfuse?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
-      const secretKey = langfuse?.secretKey || process.env.LANGFUSE_SECRET_KEY;
-      config.ai.langfuse = {
-        enabled: langfuse?.enabled ?? Boolean(publicKey && secretKey),
-        publicKey,
-        secretKey,
-        baseUrl: langfuse?.baseUrl || process.env.LANGFUSE_BASE_URL || process.env.LANGFUSE_HOST,
-      };
-    }
+    resolveLangfuse(config.ai);
 
     return config;
   }
@@ -857,6 +847,20 @@ export async function resolveConfigModels(ai?: AIConfig): Promise<void> {
   }
 }
 
+export function resolveLangfuse(ai?: AIConfig): void {
+  if (!ai) return;
+
+  const langfuse = ai.langfuse;
+  const publicKey = langfuse?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
+  const secretKey = langfuse?.secretKey || process.env.LANGFUSE_SECRET_KEY;
+  ai.langfuse = {
+    enabled: langfuse?.enabled ?? Boolean(publicKey && secretKey),
+    publicKey,
+    secretKey,
+    baseUrl: langfuse?.baseUrl || process.env.LANGFUSE_BASE_URL || process.env.LANGFUSE_HOST,
+  };
+}
+
 export function resolveOutputRoot(baseUrl?: string): string {
   if (cachedOutputRoot) return cachedOutputRoot;
 

package/src/remote.ts

@@ -28,6 +28,7 @@ export class Remote implements LogDestination {
   private asks = new Map<string, (value: string | null) => void>();
   private askCounter = 0;
   private lastActivity: string | null = null;
+  private closing: Promise<void> | null = null;
 
   attach(url: string, command: string): void {
     if (this.url) return;
@@ -73,21 +74,10 @@ export class Remote implements LogDestination {
     });
   }
 
-  async close(exitCode: number): Promise<void> {
-    if (!this.url) return;
-    this.send('result', { ok: exitCode === 0, exitCode });
-    await this.flush();
-
-    this.url = null;
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
-    // Whoever asks next has nobody to ask — leaving the callback installed would
-    // route them into a closed socket and park them until the ask times out.
-    executionController.clearInputCallback();
-    for (const resolve of this.asks.values()) resolve(null);
-    this.asks.clear();
-    this.queue = [];
-    this.socket?.close();
-    this.socket = null;
+  close(exitCode: number): Promise<void> {
+    if (!this.url) return Promise.resolve();
+    if (!this.closing) this.closing = this.shutdown(exitCode);
+    return this.closing;
   }
 
   isEnabled(): boolean {
@@ -116,6 +106,23 @@ export class Remote implements LogDestination {
     });
   }
 
+  private async shutdown(exitCode: number): Promise<void> {
+    this.send('result', { ok: exitCode === 0, exitCode });
+    await this.flush();
+
+    this.url = null;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    // Whoever asks next has nobody to ask — leaving the callback installed would
+    // route them into a closed socket and park them until the ask times out.
+    executionController.clearInputCallback();
+    for (const resolve of this.asks.values()) resolve(null);
+    this.asks.clear();
+    this.queue = [];
+    this.socket?.close();
+    this.socket = null;
+    this.closing = null;
+  }
+
   private connect(): void {
     if (!this.url) return;
 

package/src/utils/aria.ts

@@ -521,7 +521,12 @@ export const diffAriaSnapshots = (previous: string | null, current: string | nul
   const renames = detectRenames(prev, curr, prevTotals, currTotals);
   const added = [...byCount.added, ...renames.added];
   const removed = [...byCount.removed, ...renames.removed];
-  return { text: formatDiff(added, removed, toggled, typed), count: added.length + removed.length + toggled.length + typed.length };
+  return {
+    text: formatDiff(added, removed, toggled, typed),
+    count: added.length + removed.length + toggled.length + typed.length,
+    added: added.length,
+    removed: removed.length,
+  };
 };
 
 export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
@@ -587,6 +592,8 @@ export const LARGE_ARIA_CHANGE_THRESHOLD = 50;
 export interface AriaDiff {
   text: string | null;
   count: number;
+  added: number;
+  removed: number;
 }
 
 type AriaNode = {

package/src/utils/code-extractor.ts

@@ -2,13 +2,17 @@ import { createDebug } from './logger.js';
 
 const debugLog = createDebug('explorbot:code-extractor');
 
+const JS_LANGUAGES = new Set(['', 'js', 'javascript']);
+
 export function extractCodeBlocks(aiResponse: string): string[] {
-  const codeBlockRegex = /```(?:js|javascript)?\s*\n([\s\S]*?)\n```/g;
+  const codeBlockRegex = /```([^\n`]*)\n([\s\S]*?)\n```/g;
   const codeBlocks: string[] = [];
   let match: RegExpExecArray | null = null;
 
   while ((match = codeBlockRegex.exec(aiResponse))) {
-    const code = match[1].trim();
+    const language = match[1].trim().toLowerCase();
+    if (!JS_LANGUAGES.has(language)) continue;
+    const code = match[2].trim();
     if (!code) continue;
     try {
       new Function('I', code);

package/src/utils/markdown-query.ts

@@ -162,6 +162,12 @@ function matchText(text: string, matcher: TextMatcher): boolean {
   return matcher.negated ? !result : result;
 }
 
+function entryKey(line: string): string | null {
+  const separator = line.indexOf(':');
+  if (separator < 1) return null;
+  return line.slice(0, separator).trim().toLowerCase();
+}
+
 function getTokenText(token: Token): string {
   const t = token as any;
   switch (token.type) {
@@ -407,6 +413,39 @@ export class MarkdownQuery {
     return results;
   }
 
+  keyValue(): Record<string, string> {
+    const entries: Record<string, string> = {};
+
+    for (const range of this.matches) {
+      for (const line of getTokenText(range.token).split('\n')) {
+        const key = entryKey(line);
+        if (!key) continue;
+        const value = line.slice(line.indexOf(':') + 1).trim();
+        if (value) entries[key] = value;
+      }
+    }
+
+    return entries;
+  }
+
+  setKeyValue(key: string, value: string | null): string {
+    return this.replaceEach((match) => {
+      const token = match.matches[0].token;
+      const lines = getTokenText(token)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+
+      const index = lines.findIndex((line) => entryKey(line) === key.toLowerCase());
+      if (index < 0 && value) lines.push(`${key}: ${value}`);
+      if (index >= 0 && value) lines[index] = `${key}: ${value}`;
+      if (index >= 0 && !value) lines.splice(index, 1);
+
+      if (token.type !== 'blockquote') return lines.join('\n');
+      return lines.map((line) => `> ${line}`).join('\n');
+    });
+  }
+
   replace(content: string): string {
     return this.replaceEach(() => content);
   }

package/src/utils/pagination.ts

@@ -0,0 +1,36 @@
+export function inspectList(css: string): ListMeasure | null {
+  const element = document.querySelector(css);
+  if (!element) return null;
+  const rect = element.getBoundingClientRect();
+  return {
+    hasPagingControls: !!element.querySelector('a[rel="next"], a[rel="prev"]'),
+    isFeed: element.matches('[role="feed"]') || !!element.querySelector('[role="feed"]'),
+    scrolls: element.scrollHeight > element.clientHeight + 1 || rect.bottom > window.innerHeight,
+    items: element.querySelectorAll(':scope > *').length,
+    scrollTop: element.scrollTop,
+    pageScrollY: window.scrollY,
+  };
+}
+
+export function restoreScroll({ css, scrollTop, pageScrollY }: ScrollPosition): void {
+  const element = document.querySelector(css);
+  if (element) element.scrollTop = scrollTop;
+  window.scrollTo(0, pageScrollY);
+}
+
+export type PaginationStrategy = 'controls' | 'infinite';
+
+export interface ListMeasure {
+  hasPagingControls: boolean;
+  isFeed: boolean;
+  scrolls: boolean;
+  items: number;
+  scrollTop: number;
+  pageScrollY: number;
+}
+
+export interface ScrollPosition {
+  css: string;
+  scrollTop: number;
+  pageScrollY: number;
+}