explorbot 0.2.5 → 0.3.0

package/dist/src/ai/provider.js

@@ -327,7 +327,7 @@ export class Provider {
         const stopConditions = [isStepCount(maxRoundtrips)];
         if (extraStop)
             stopConditions.push(extraStop);
-        const config = this.buildGenerateConfig({ tools, maxOutputTokens: 16384, toolChoice: 'auto' }, { stopWhen: stopConditions, model }, options);
+        const config = this.buildGenerateConfig({ tools, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
         try {
             const response = await withRetry(async () => {
                 const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000));
@@ -562,4 +562,19 @@ export class Provider {
         return this.config.visionModel !== undefined;
     }
 }
+function repairToolCall(options) {
+    if (options.toolCall.toolName.includes('<|channel|>'))
+        return repairChannelMarker(options);
+    return null;
+}
+function repairChannelMarker({ toolCall, tools }) {
+    const markerIndex = toolCall.toolName.indexOf('<|channel|>');
+    if (markerIndex <= 0)
+        return null;
+    const toolName = toolCall.toolName.slice(0, markerIndex);
+    if (!tools[toolName])
+        return null;
+    tag('warning').log(`Repaired tool name '${toolCall.toolName}' → '${toolName}'`);
+    return { ...toolCall, toolName };
+}
 export { AiError, Provider as AIProvider };

package/dist/src/ai/researcher/cache.d.ts

@@ -3,6 +3,11 @@ export declare function reportResearch(hash: string, text: string): void;
 export declare function clearResearchCache(): void;
 export declare function getCachedResearch(hash: string): string;
 export declare function getPreviousResearch(hash: string): string;
-export declare function saveResearch(hash: string, text: string, combinedHtml?: string): string;
-export declare function findSimilarResearch(combinedHtml: string): Promise<string | null>;
-export declare function findSimilarStateHash(combinedHtml: string): Promise<string | null>;
+export declare function saveResearch(state: ResearchState, text: string, combinedHtml?: string): string;
+export declare function findSimilarResearch(combinedHtml: string, url?: string): Promise<string | null>;
+export declare function findSimilarStateHash(combinedHtml: string, url?: string): Promise<string | null>;
+type ResearchState = {
+    hash: string;
+    url?: string;
+};
+export {};

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

@@ -55,7 +55,8 @@ export function getPreviousResearch(hash) {
         return '';
     return readFileSync(researchFile, 'utf8');
 }
-export function saveResearch(hash, text, combinedHtml) {
+export function saveResearch(state, text, combinedHtml) {
+    const { hash, url } = state;
     const researchDir = outputPath('research');
     const researchFile = join(researchDir, `${hash}.md`);
     if (!existsSync(researchDir))
@@ -70,12 +71,15 @@ export function saveResearch(hash, text, combinedHtml) {
             mkdirSync(statesDir, { recursive: true });
         const fingerprint = computeHtmlFingerprint(combinedHtml);
         const fingerprintFile = join(statesDir, `${hash}.fingerprint`);
-        writeFileSync(fingerprintFile, fingerprint.join('\n'));
+        const record = { entries: fingerprint };
+        if (url)
+            record.url = url;
+        writeFileSync(fingerprintFile, JSON.stringify(record));
         debugLog(`Fingerprint saved to ${fingerprintFile}`);
     }
     return researchFile;
 }
-function findSimilarMatch(combinedHtml) {
+function findSimilarMatch(combinedHtml, url) {
     const statesDir = getStatesDir();
     if (!existsSync(statesDir))
         return Promise.resolve(null);
@@ -93,23 +97,24 @@ function findSimilarMatch(combinedHtml) {
                 return;
             }
             debugLog(`Similar fingerprint found: ${matchHash} (${similarity}% similar)`);
-            resolve({ hash: matchHash, similarity });
+            resolve({ hash: matchHash, similarity, url: data.url });
         });
         worker.postMessage({
             html: combinedHtml,
             statesDir,
             maxAgeMs: FINGERPRINT_MAX_AGE_MS,
             threshold: SIMILARITY_THRESHOLD,
+            url,
         });
     });
 }
-export async function findSimilarResearch(combinedHtml) {
-    const match = await findSimilarMatch(combinedHtml);
+export async function findSimilarResearch(combinedHtml, url) {
+    const match = await findSimilarMatch(combinedHtml, url);
     if (!match)
         return null;
     return getCachedResearch(match.hash) || null;
 }
-export async function findSimilarStateHash(combinedHtml) {
-    const match = await findSimilarMatch(combinedHtml);
+export async function findSimilarStateHash(combinedHtml, url) {
+    const match = await findSimilarMatch(combinedHtml, url);
     return match?.hash || null;
 }

package/dist/src/ai/researcher/deep-analysis.js

@@ -96,7 +96,7 @@ export function WithDeepAnalysis(Base) {
             else {
                 updated = `${cached.trimEnd()}\n\n# Extended Research\n\n${sectionMarkdown}\n`;
             }
-            saveResearch(pageStateHash, updated);
+            saveResearch({ hash: pageStateHash }, updated);
             tag('substep').log(`Overlay research appended: ${focusArea.name}`);
             return sectionMarkdown;
         }

package/dist/src/ai/researcher/fingerprint-worker.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from "../../utils/html-diff.js";
+import { isSamePageFamily } from "../../utils/url-matcher.js";
 function diceSimilarity(a, b) {
     let intersection = 0;
     for (const item of a) {
@@ -14,7 +15,7 @@ function diceSimilarity(a, b) {
     return Math.round(((2 * intersection) / total) * 100);
 }
 parentPort.on('message', (data) => {
-    const { html, statesDir, maxAgeMs, threshold } = data;
+    const { html, statesDir, maxAgeMs, threshold, url } = data;
     if (!existsSync(statesDir)) {
         parentPort.postMessage({ matchHash: null, similarity: 0 });
         return;
@@ -28,19 +29,35 @@ parentPort.on('message', (data) => {
     const files = readdirSync(statesDir).filter((f) => f.endsWith('.fingerprint'));
     let bestHash = null;
     let bestSimilarity = 0;
+    let bestUrl;
     for (const file of files) {
         const filePath = join(statesDir, file);
         const mtime = statSync(filePath).mtimeMs;
         if (now - mtime > maxAgeMs)
             continue;
-        const lines = readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
-        const storedFingerprint = new Set(lines);
+        const record = readFingerprint(filePath);
+        if (url && record.url && !isSamePageFamily(url, record.url))
+            continue;
+        const storedFingerprint = new Set(record.entries);
         const similarity = diceSimilarity(currentFingerprint, storedFingerprint);
         if (similarity > bestSimilarity) {
             bestSimilarity = similarity;
             bestHash = file.replace('.fingerprint', '');
+            bestUrl = record.url;
         }
     }
     const matched = bestSimilarity >= threshold;
-    parentPort.postMessage({ matchHash: matched ? bestHash : null, similarity: bestSimilarity });
+    parentPort.postMessage({ matchHash: matched ? bestHash : null, similarity: bestSimilarity, url: matched ? bestUrl : undefined });
 });
+function readFingerprint(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    try {
+        const record = JSON.parse(content);
+        if (Array.isArray(record.entries))
+            return record;
+    }
+    catch {
+        return { entries: content.split('\n').filter(Boolean) };
+    }
+    return { entries: content.split('\n').filter(Boolean) };
+}

package/dist/src/ai/researcher.js

@@ -72,6 +72,7 @@ export class Researcher extends ResearcherBase {
         let retriesLeft = opts._retriesLeft ?? maxRetries;
         this.actionResult = ActionResult.fromState(state);
         const stateHash = state.hash || this.actionResult.getStateHash();
+        const researchState = { ...state, hash: stateHash };
         if (!force && stateHash) {
             const cached = getCachedResearch(stateHash);
             if (cached) {
@@ -105,11 +106,11 @@ export class Researcher extends ResearcherBase {
             debugLog('Researching web page:', this.actionResult.url);
             const combinedHtml = await this.actionResult.combinedHtml();
             if (!deep && !force) {
-                const similar = await findSimilarResearch(combinedHtml);
+                const similar = await findSimilarResearch(combinedHtml, state.url);
                 if (similar) {
                     tag('operation').log('Similar research found, reusing cached result');
                     if (stateHash)
-                        saveResearch(stateHash, similar, combinedHtml);
+                        saveResearch(researchState, similar, combinedHtml);
                     tag('multiline').log(formatResearchSummary(similar));
                     tag('success').log('Research complete (reused)');
                     await this.hooksRunner.runAfterHook('researcher', state.url);
@@ -238,7 +239,7 @@ export class Researcher extends ResearcherBase {
             result.cleanup();
             let researchFile = null;
             if (stateHash) {
-                researchFile = saveResearch(stateHash, result.text, combinedHtml);
+                researchFile = saveResearch(researchState, result.text, combinedHtml);
             }
             const summaryText = mdq(result.text).query('section2(/^summary/)').query('paragraph[0]').text().trim();
             const summaryLine = summaryText.split('\n')[0]?.trim().slice(0, 200);

package/dist/src/ai/rules.js

@@ -2,10 +2,6 @@ import dedent from 'dedent';
 export const recommendedCodeceptCommands = ['I.click', 'I.type', 'I.fillField', 'I.see', 'I.seeElement'];
 const locatorPriorityRule = dedent `
   <locator_priority>
-  When the page context shows the element a ref, such as [ref=e14], there is no locator to select: click it with clickRef
-  and that ref. A ref names one exact element, so it never matches the wrong one and never has to be narrowed. Everything
-  below is for elements the context gives no ref for.
-
   Use the following priority when selecting locators:
 
   1. ARIA locators (first choice) - target browser's accessibility tree, most reliable
@@ -76,7 +72,7 @@ const locatorStrategyRule = dedent `
 
   NEVER include \`eidx\` attribute in any locator (ARIA, CSS, XPath). It is an internal annotation.
 
-  If <aria> section is not present or element is not found there, fall back to CSS/XPath locators from <html> section.
+  If the element is not found in the ARIA snapshot, fall back to CSS/XPath locators from page HTML.
 
   Stick to semantic attributes like role, aria-*, id, class, name, data-id, etc.
   Avoid IDs that follow framework auto-generation patterns (these change on every page load):

package/dist/src/ai/tester.d.ts

@@ -11,6 +11,7 @@ import { Researcher } from './researcher.js';
 import { TaskAgent } from './task-agent.js';
 export declare class Tester extends TaskAgent implements Agent {
     readonly ACTION_TOOLS: string[];
+    readonly DELEGATED_ACTION_TOOLS: string[];
     readonly SPECIAL_CONTEXT_ACTION_TOOLS: string[];
     emoji: string;
     requestStore: RequestStore;
@@ -49,7 +50,6 @@ export declare class Tester extends TaskAgent implements Agent {
     shouldStopForStalledExecution(task: Test, previousState: ActionResult, toolExecutions: any[]): boolean;
     prepareInstructionsForNextStep(task: Test): Promise<string>;
     reinjectContextIfNeeded(iteration: number, currentState: ActionResult): Promise<string>;
-    interactiveAriaWithRefs(state: ActionResult): Promise<string>;
     finishTest(task: Test): void;
     abortStartedTestOnErrorPage(task: Test, actionResult: ActionResult): Promise<{
         success: boolean;

package/dist/src/ai/tester.js

@@ -8,10 +8,11 @@ import { clearActivity, setActivity } from "../activity.js";
 import { Observability } from "../observability.js";
 import { Stats } from "../stats.js";
 import { TestResult } from "../test-plan.js";
-import { compactAriaSnapshot, detectFocusArea } from "../utils/aria.js";
+import { detectFocusArea } from "../utils/aria.js";
 import { ErrorPageError, isErrorPage } from "../utils/error-page.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop } from "../utils/loop.js";
+import { compactErrorMessage } from "../utils/strings.js";
 import { actionRule, capabilityGroundingRule, dataProtectionRules, focusedElementRule, formRequirementsRule, locatorRule, multipleTabsRule, sectionContextRule } from "./rules.js";
 import { TaskAgent } from "./task-agent.js";
 import { createCodeceptJSTools, createIframeTools, withdrawVisionTools } from "./tools.js";
@@ -28,6 +29,7 @@ const SAMPLE_FILES = {
 };
 export class Tester extends TaskAgent {
     ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
+    DELEGATED_ACTION_TOOLS = ['interact'];
     SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
     emoji = '🧪';
     requestStore;
@@ -232,8 +234,6 @@ export class Tester extends TaskAgent {
           `);
                 }
                 conversation.cleanupTag('page_aria', '...cleaned aria snapshot...', 1);
-                conversation.cleanupTag('page_html', '...cleaned HTML snapshot...', 1);
-                conversation.cleanupTag('experience', '...cleaned experience...', 1);
                 conversation.cleanupTag('applied_experience', '...cleaned past experience...', 1);
                 conversation.cleanupTag('page_ui_map', '...cleaned UI map...', 1);
                 conversation.cleanupTag('page_ui_map_overlay', '...cleaned UI overlay...', 1);
@@ -359,8 +359,6 @@ export class Tester extends TaskAgent {
             this.stalledIterations = 0;
             tag('info').log(`Pilot extending test (${extensions}/${this.MAX_EXTENSIONS})`);
             conversation.cleanupTag('page_aria', '...trimmed...', 1);
-            conversation.cleanupTag('page_html', '...trimmed...', 0);
-            conversation.cleanupTag('experience', '...trimmed...', 0);
             conversation.cleanupTag('page_ui_map', '...trimmed...', 0);
             conversation.cleanupTag('page_ui_map_overlay', '...trimmed...', 0);
             conversation.compactToolResults(1);
@@ -398,7 +396,7 @@ export class Tester extends TaskAgent {
             return false;
         const currentState = this.getCurrentState();
         const stateChanged = previousState.url !== currentState.url || previousState.hash !== currentState.hash;
-        const actionTools = [...this.ACTION_TOOLS, ...this.SPECIAL_CONTEXT_ACTION_TOOLS];
+        const actionTools = [...this.ACTION_TOOLS, ...this.DELEGATED_ACTION_TOOLS, ...this.SPECIAL_CONTEXT_ACTION_TOOLS];
         const hasSuccessfulAction = toolExecutions.some((execution) => execution.wasSuccessful && actionTools.includes(execution.toolName));
         const hasSuccessfulAssertion = toolExecutions.some((execution) => execution.wasSuccessful && this.ASSERTION_TOOLS.includes(execution.toolName));
         if (stateChanged || hasSuccessfulAction || hasSuccessfulAssertion) {
@@ -422,6 +420,7 @@ export class Tester extends TaskAgent {
   
       <rules>
       Use tools ${this.ACTION_TOOLS.join(', ')} to interact with the page.
+      Fall back to interact() when those fail, when the step needs a sequence of actions, or when your context is not enough to locate the element.
       Use tool names exactly as listed in this prompt. Do not invent combined tool names, aliases, or names with channel markers such as "commentary".
       Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
       Do not do unsuccesful clicks again.
@@ -532,13 +531,13 @@ export class Tester extends TaskAgent {
         </page>
 
         <page_aria>
-        ${await this.interactiveAriaWithRefs(currentState)}
+        ${currentState.getInteractiveARIA()}
         </page_aria>
         ${uiMapSection}
 
         Use <page_ui_map> to understand the page structure and its main elements.
-        However, <page_ui_map> is not always up to date, use <page_aria> and <page_html> to understand the ACTUAL state of the page
-        Do not interact with elements that are not listed in <page_aria> and <page_html>
+        However, <page_ui_map> is not always up to date, use <page_aria> to understand the ACTUAL state of the page
+        Do not interact with elements that are not listed in <page_aria> or in HTML returned by tools
         Refer to information on page sections in <page_ui_map> and use container CSS locators to interact with elements inside sections
       `;
             return context;
@@ -567,16 +566,10 @@ export class Tester extends TaskAgent {
       </page>
 
       <page_aria>
-      ${await this.interactiveAriaWithRefs(currentState)}
+      ${currentState.getInteractiveARIA()}
       </page_aria>
     `;
     }
-    async interactiveAriaWithRefs(state) {
-        const withRefs = await Promise.resolve(this.explorer?.withPage?.((page) => page.locator('body').ariaSnapshot({ mode: 'ai' }))).catch(() => null);
-        if (!withRefs)
-            return state.getInteractiveARIA();
-        return compactAriaSnapshot(withRefs, false);
-    }
     finishTest(task) {
         if (!task.result) {
             if (task.hasAchievedAll())
@@ -646,7 +639,7 @@ export class Tester extends TaskAgent {
 
     <rules>
     - Refer to UI Map from <page_ui_map> to understand the page structure and its main elements
-    - Use only elements that exist in the provided ARIA tree or HTML, <page_aria> and <page_html>
+    - Use only elements that exist in <page_aria> or in HTML returned by tools
     - Use tool input schemas exactly as documented. Do not invent parameter names or add fields not listed by the tool schema.
     - Use click() for buttons, links, and clickable elements ONLY - do NOT include I.fillField() or I.type() commands in click() tool
     - click() commands array is for FALLBACK LOCATORS of the SAME element, NOT for clicking different elements in sequence. If you need to click two different elements, make two separate click() calls.
@@ -669,7 +662,8 @@ export class Tester extends TaskAgent {
     - Check for error messages to understand if there are issues
     - Verify if data was correctly saved and changes are reflected on the page
     - By default, you receive accessibility tree data which shows interactive elements and page structure
-    - Understand current context by following <page_html>, <page_aria>, and <page_ui_map>
+    - Full page HTML is never injected automatically. When ARIA is not enough, delegate to the tools that read it: verify() to assert, interact() to act
+    - Understand current context by following <page_aria> and <page_ui_map>
     - Before submitting form, check all inputs were filled in correctly using see() tool
     - When you interact with form with inputs, ensure that you click corresponding button to save its data
     - Follow <locator_priority> rules when selecting locators for all tools
@@ -720,7 +714,6 @@ export class Tester extends TaskAgent {
     }
     buildScenarioBlock(task, actionResult) {
         const knowledge = this.getKnowledge(actionResult);
-        const experience = this.getExperience(actionResult);
         return dedent `
       <task>
       SCENARIO GOAL: ${task.scenario}
@@ -749,8 +742,6 @@ export class Tester extends TaskAgent {
       ${this.buildAvailableFiles()}
 
       ${knowledge}
-
-      ${experience}
     `;
     }
     getDeletableSessionNames(task) {
@@ -860,7 +851,7 @@ export class Tester extends TaskAgent {
                         explanation,
                     };
                     if (resetAction.lastError) {
-                        result.error = resetAction.lastError.toString();
+                        result.error = compactErrorMessage(resetAction.lastError);
                     }
                     return result;
                 },

package/dist/src/ai/tools.d.ts

@@ -1,5 +1,5 @@
 import { ActionResult, type PageDiff } from '../action-result.js';
-import type { ExperienceTracker } from '../experience-tracker.js';
+import { type ExperienceTracker } from '../experience-tracker.js';
 import { type Task } from '../test-plan.js';
 import type { ToolDeps } from './agent.js';
 import { Navigator } from './navigator.js';
@@ -16,10 +16,6 @@ export declare function createCodeceptJSTools({ explorer, stateManager, ai }: To
         commands: any;
         explanation: any;
     }, Record<string, any>, import("@ai-sdk/provider-utils").Context>>;
-    clickRef: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
-        ref: any;
-        element: any;
-    }, Record<string, any>, import("@ai-sdk/provider-utils").Context>>;
     hover: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
         commands: any;
         explanation: any;
@@ -34,6 +30,12 @@ export declare function createCodeceptJSTools({ explorer, stateManager, ai }: To
         explanation: any;
     }, Record<string, any>, import("@ai-sdk/provider-utils").Context>>;
 };
+export declare function createRefTools({ explorer, stateManager }: ToolDeps, task: Task): {
+    clickRef: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
+        ref: any;
+        element: any;
+    }, Record<string, any>, import("@ai-sdk/provider-utils").Context>>;
+};
 export declare function createIframeTools({ explorer, stateManager }: ToolDeps): {
     exitIframe: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
         reason?: string;
@@ -59,6 +61,7 @@ export declare function successToolResult(action: string, data?: Record<string,
     assertionSteps?: any[];
 }): Record<string, any>;
 export declare function isMajorPageChange(pageDiff: PageDiff): boolean;
+export declare function hasFailedRequest(pageDiff: PageDiff): boolean;
 export declare function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null): Promise<Record<string, any>>;
 export declare function withdrawVisionTools(tools: Record<string, any>): void;
 export declare function clickFailureSuggestion(attempts: Array<{