explorbot 0.4.6 → 0.4.7

package/dist/src/ai/researcher/sections.js

@@ -63,7 +63,7 @@ export function WithSections(Base) {
         }
         async _researchSingleSection(name, description, ariaSnapshot, focusCss) {
             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';
             let focusHint = '';

package/dist/src/ai/researcher.js

@@ -18,6 +18,7 @@ import { WithCoordinates } from "./researcher/coordinates.js";
 import { WithDeepAnalysis } from "./researcher/deep-analysis.js";
 import { detectFocusedSection, hasFocusedSection, markSectionAsFocused, pickDefaultFocusedSection } from "./researcher/focus.js";
 import { WithLocators } from "./researcher/locators.js";
+import { WithPagination } from "./researcher/pagination.js";
 import { extractValidContainers, formatResearchSummary, parseResearchSections } from "./researcher/parser.js";
 import { ResearchResult } from "./researcher/research-result.js";
 import { WithSections } from "./researcher/sections.js";
@@ -33,7 +34,7 @@ export const POSSIBLE_SECTIONS = {
     menu: 'page menu (toolbar, context actions, filters, dropdowns)',
     navigation: 'main navigation (top bar, sidebar, breadcrumbs)',
 };
-const ResearcherBase = WithSections(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent))));
+const ResearcherBase = WithSections(WithPagination(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent)))));
 export class Researcher extends ResearcherBase {
     ACTION_TOOLS = ['click'];
     emoji = '🔍';
@@ -230,6 +231,9 @@ export class Researcher extends ResearcherBase {
                 await this.backfillCoordinates(result);
                 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);
@@ -366,7 +370,7 @@ export class Researcher extends ResearcherBase {
 
       ${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:
@@ -439,6 +443,7 @@ export class Researcher extends ResearcherBase {
       - 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/dist/src/ai/rules.js

@@ -332,6 +332,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/dist/src/ai/scout.js

@@ -47,12 +47,18 @@ export class Scout {
                 maxToolRoundtrips: MAX_TOOL_ROUNDTRIPS,
                 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/dist/src/ai/tools.js

@@ -311,6 +311,7 @@ export function createCodeceptJSTools({ explorer, stateManager }, 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)
 
         Example - filling a form with context (PREFERRED):
         I.fillField('Username', 'John', '.login-form')
@@ -365,10 +366,10 @@ export function createCodeceptJSTools({ explorer, stateManager }, 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);
@@ -1080,7 +1081,13 @@ export function successToolResult(action, data, source) {
     return result;
 }
 export function isMajorPageChange(pageDiff) {
-    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) {
     return (pageDiff.requests ?? []).some((request) => request.status >= 400);

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

@@ -3,5 +3,12 @@ import { BaseOption } from './base-option.js';
 export declare class WsOption extends BaseOption {
     flags: string;
     description: string;
+    /**
+     * 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.
+     */
+    register(command: Command): void;
     apply(options: Record<string, any>, command: Command): void;
 }

package/dist/src/commands/options/ws-option.js

@@ -3,6 +3,20 @@ import { BaseOption } from './base-option.js';
 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.
+     */
+    register(command) {
+        super.register(command);
+        command.hook('postAction', async () => {
+            if (!remote.isAttached())
+                return;
+            await remote.close(0);
+        });
+    }
     apply(options, command) {
         const url = options.ws || process.env.EXPLORBOT_WS_URL;
         if (!url)

package/dist/src/config.d.ts

@@ -287,6 +287,7 @@ export declare function modelName(model: unknown): string;
 export declare function modelProvider(model: unknown): string;
 export declare function configuredModels(ai?: AIConfig): Record<string, ConfiguredModel>;
 export declare function resolveConfigModels(ai?: AIConfig): Promise<void>;
+export declare function resolveLangfuse(ai?: AIConfig): void;
 export declare function resolveOutputRoot(baseUrl?: string): string;
 export declare function resolveStateRoot(baseUrl: string, ephemeral?: boolean): string;
 export declare function materializeKnowledge(outputRoot: string): void;

package/dist/src/config.js

@@ -377,17 +377,7 @@ export class ConfigParser {
             config.playwright = config.playwright || { browser: 'chromium', url: '' };
             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;
     }
     validateConfig(config) {
@@ -540,6 +530,19 @@ export async function resolveConfigModels(ai) {
             agent.model = await resolveModel(agent.model);
     }
 }
+export function resolveLangfuse(ai) {
+    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) {
     if (cachedOutputRoot)
         return cachedOutputRoot;

package/dist/src/remote.d.ts

@@ -18,6 +18,7 @@ export declare class Remote implements LogDestination {
     asks: Map<string, (value: string | null) => void>;
     askCounter: number;
     lastActivity: string | null;
+    closing: Promise<void> | null;
     attach(url: string, command: string): void;
     isAttached(): boolean;
     send(type: string, data?: Record<string, unknown>): void;
@@ -30,6 +31,7 @@ export declare class Remote implements LogDestination {
      * back out of flattened text.
      */
     write(entry: TaggedLogEntry): void;
+    shutdown(exitCode: number): Promise<void>;
     connect(): void;
     reconnect(): void;
     flush(): Promise<void>;

package/dist/src/remote.js

@@ -26,6 +26,7 @@ export class Remote {
     asks = new Map();
     askCounter = 0;
     lastActivity = null;
+    closing = null;
     attach(url, command) {
         if (this.url)
             return;
@@ -68,23 +69,12 @@ export class Remote {
             });
         });
     }
-    async close(exitCode) {
+    close(exitCode) {
         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;
+            return Promise.resolve();
+        if (!this.closing)
+            this.closing = this.shutdown(exitCode);
+        return this.closing;
     }
     isEnabled() {
         return this.isAttached();
@@ -112,6 +102,23 @@ export class Remote {
             error: this.errorOf(entry.originalArgs),
         });
     }
+    async shutdown(exitCode) {
+        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;
+    }
     connect() {
         if (!this.url)
             return;

package/dist/src/utils/aria.d.ts

@@ -16,4 +16,6 @@ export declare const LARGE_ARIA_CHANGE_THRESHOLD = 50;
 export interface AriaDiff {
     text: string | null;
     count: number;
+    added: number;
+    removed: number;
 }

package/dist/src/utils/aria.js

@@ -511,7 +511,12 @@ export const diffAriaSnapshots = (previous, current) => {
     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) => {
     let tree = parseSnapshot(snapshot);

package/dist/src/utils/markdown-query.d.ts

@@ -29,6 +29,8 @@ export declare class MarkdownQuery {
     text(): string;
     get(): string;
     toJson(): Record<string, string>[];
+    keyValue(): Record<string, string>;
+    setKeyValue(key: string, value: string | null): string;
     replace(content: string): string;
     replaceEach(replacer: (match: MarkdownQuery, index: number) => string): string;
     count(): number;

package/dist/src/utils/markdown-query.js

@@ -129,6 +129,12 @@ function matchText(text, matcher) {
     }
     return matcher.negated ? !result : result;
 }
+function entryKey(line) {
+    const separator = line.indexOf(':');
+    if (separator < 1)
+        return null;
+    return line.slice(0, separator).trim().toLowerCase();
+}
 function getTokenText(token) {
     const t = token;
     switch (token.type) {
@@ -340,6 +346,39 @@ export class MarkdownQuery {
         }
         return results;
     }
+    keyValue() {
+        const entries = {};
+        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, value) {
+        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) {
         return this.replaceEach(() => content);
     }

package/dist/src/utils/pagination.d.ts

@@ -0,0 +1,16 @@
+export declare function inspectList(css: string): ListMeasure | null;
+export declare function restoreScroll({ css, scrollTop, pageScrollY }: ScrollPosition): void;
+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;
+}

package/dist/src/utils/pagination.js

@@ -0,0 +1,20 @@
+export function inspectList(css) {
+    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 }) {
+    const element = document.querySelector(css);
+    if (element)
+        element.scrollTop = scrollTop;
+    window.scrollTo(0, pageScrollY);
+}