explorbot 0.2.5 → 0.3.1

package/src/commands/init-command.ts

@@ -8,15 +8,10 @@ import { getCliName } from '../utils/cli-name.ts';
 import { log, tag } from '../utils/logger.js';
 import { relativeToCwd } from '../utils/next-steps.ts';
 
-const DEFAULT_CONFIG_TEMPLATE = `import { createOpenRouter } from '@openrouter/ai-sdk-provider';
-// import { '<your provider here>' } from '<your provider package here>';
-
-// Vercel AI SDK is used to connect to AI providers.
-// Bring your own provider or use OpenRouter (one API key, many providers).
-// https://github.com/testomatio/explorbot/blob/main/docs/providers.md
-const openrouter = createOpenRouter({
-  apiKey: process.env.OPENROUTER_API_KEY,
-});
+function defaultConfigTemplate(): string {
+  return `// 'provider/model-id' uses a bundled provider.
+// It is also possible to import provider as a module from Vercel AI SDK.  
+// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
 
 const config = {
   web: {
@@ -25,12 +20,7 @@ const config = {
   },
 
   ai: {
-    // fast model with tool calling capabilities
-    model: openrouter('openai/gpt-oss-20b:nitro'),
-    // vision model for screenshot analysis
-    visionModel: openrouter('meta-llama/llama-4-scout-17b-16e-instruct'),
-    // agentic model for decision making
-    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+${modelLines('openrouter')}
   },
 
   reporter: {
@@ -45,6 +35,7 @@ const config = {
 
 export default config;
 `;
+}
 
 const DEFAULT_ENV_TEMPLATE = dedent`
 # AI provider API keys
@@ -141,7 +132,7 @@ export function runInitCommand(options: InitCommandOptions): void {
       process.exit(1);
     }
 
-    writeFileSync(outPath, DEFAULT_CONFIG_TEMPLATE, 'utf8');
+    writeFileSync(outPath, defaultConfigTemplate(), 'utf8');
     log(`Created config file: ${relativeToCwd(outPath)}`);
 
     const envPath = resolve(process.cwd(), '.env');
@@ -222,8 +213,7 @@ async function renderInitWizard(mode: 'choose' | 'global'): Promise<'local' | 'g
   });
 }
 
-function globalConfigTemplate(provider: string): string {
-  const { envKey } = PROVIDERS[provider];
+function modelLines(provider: string): string {
   const recommended = ConfigParser.recommendedModels()[provider] || {};
   const roles: Array<[ModelRoleName, string]> = [
     ['model', 'fast model with tool calling capabilities'],
@@ -231,7 +221,11 @@ function globalConfigTemplate(provider: string): string {
     ['agenticModel', 'agentic model for decision making'],
   ];
 
-  const models = roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+  return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+}
+
+function globalConfigTemplate(provider: string): string {
+  const { envKey } = PROVIDERS[provider];
 
   return `// Global Explorbot configuration — used by every directory without its own explorbot.config.js.
 // Models are written as 'provider/model-id' so they resolve without a local node_modules.
@@ -240,7 +234,7 @@ function globalConfigTemplate(provider: string): string {
 // https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
 const config = {
   ai: {
-${models}
+${modelLines(provider)}
   },
 
   reporter: {

package/src/config.ts

@@ -175,8 +175,9 @@ interface AIConfig {
   vision?: boolean;
   visionModel?: any;
   agenticModel?: any;
-  maxAttempts?: number;
+  retryAttempts?: number;
   retryDelay?: number;
+  maxParallelRequests?: number;
   agents?: AgentsConfig;
 }
 
@@ -433,7 +434,7 @@ export class ConfigParser {
   public getOutputDir(): string {
     const config = this.getConfig();
     if (!this.configPath) throw new Error('Config path not found');
-    return path.join(this.getProjectRoot(), config.dirs?.output || 'output');
+    return this.resolveProjectDir(config.dirs?.output || 'output');
   }
 
   public getProjectRoot(): string {
@@ -444,6 +445,7 @@ export class ConfigParser {
   }
 
   public resolveProjectDir(relativeDir: string): string {
+    if (path.isAbsolute(relativeDir)) return relativeDir;
     if (!this.configPath) return relativeDir;
     return path.join(this.getProjectRoot(), relativeDir);
   }

package/src/experience-tracker.ts

@@ -304,6 +304,14 @@ export class ExperienceTracker {
     return this.buildToc(sorted);
   }
 
+  renderExperienceFor(state: ActionResult): string {
+    const successful = this.getSuccessfulExperience(state);
+    if (!successful.length) return '';
+
+    tag('operation').log(`Found ${successful.length} experience ${pluralize(successful.length, 'file')} for: ${state.url}`);
+    return renderExperienceRecipes(successful);
+  }
+
   renderExperienceTocFor(state: ActionResult): string {
     const toc = this.getExperienceTableOfContents(state);
     if (toc.length === 0) return '';
@@ -437,6 +445,11 @@ function indexToLetters(index: number): string {
   return result;
 }
 
+export function renderExperienceRecipes(recipes: string[]): string {
+  if (recipes.length === 0) return '';
+  return `<experience>\nPast successful recipes recorded from prior runs for this page. Prefer these solutions first if they match the goal.\n\n${recipes.join('\n\n')}\n</experience>`;
+}
+
 export function renderExperienceToc(toc: ExperienceTocEntry[]): string {
   if (toc.length === 0) return '';
 

package/src/explorbot.ts

@@ -248,7 +248,7 @@ export class ExplorBot {
       this.agents.tester = this.createAgent((deps) => {
         const researcher = this.agentResearcher();
         const navigator = this.agentNavigator();
-        const tools = createAgentTools({ ...deps, researcher, navigator });
+        const tools = createAgentTools({ ...deps, researcher, navigator, withExperience: false });
         return new Tester(deps, researcher, navigator, tools);
       });
 

package/src/playwright-recorder.ts

@@ -9,7 +9,7 @@ const RECORDABLE: Record<string, Set<string>> = {
   Page: new Set(['goBack', 'goForward', 'reload', 'keyboardPress', 'keyboardType', 'keyboardDown', 'keyboardUp', 'keyboardInsertText', 'mouseClick', 'mouseDblclick', 'mouseMove', 'mouseDown', 'mouseUp', 'mouseWheel']),
 };
 
-const PLAYWRIGHT_INCOMPATIBLE = "Playwright output is not compatible with this Playwright version (playwright-core/lib/utils does not expose asLocator). Use output.framework: 'codeceptjs' instead, or pin Playwright to a version shipping lib/utils/isomorphic/locatorGenerators.js.";
+const PLAYWRIGHT_INCOMPATIBLE = "Playwright output requires playwright-core 1.62 or newer (lib/coreBundle does not expose iso.asLocator). Use output.framework: 'codeceptjs' instead.";
 
 let cachedAsLocator: ((lang: string, selector: string) => string) | null = null;
 let asLocatorLoadAttempted = false;
@@ -20,16 +20,11 @@ function getAsLocator(): (lang: string, selector: string) => string {
   if (asLocatorLoadAttempted) throw new Error(PLAYWRIGHT_INCOMPATIBLE);
 
   asLocatorLoadAttempted = true;
-  try {
-    const mod = nodeRequire('playwright-core/lib/utils');
-    if (typeof (mod as any)?.asLocator === 'function') {
-      cachedAsLocator = (mod as any).asLocator;
-      return cachedAsLocator!;
-    }
-  } catch {
-    // Module not exported or not found
-  }
-  throw new Error(PLAYWRIGHT_INCOMPATIBLE);
+  const asLocator = nodeRequire('playwright-core/lib/coreBundle')?.iso?.asLocator;
+  if (typeof asLocator !== 'function') throw new Error(PLAYWRIGHT_INCOMPATIBLE);
+
+  cachedAsLocator = asLocator;
+  return cachedAsLocator;
 }
 
 export interface TraceCall {

package/src/test-plan.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import figures from 'figures';
+import type { ActionResult } from './action-result.ts';
 import { WebPageState } from './state-manager.ts';
 import { tag } from './utils/logger.ts';
 import { parsePlanFromMarkdown, planToAiContext, savePlanToMarkdown, savePlansToMarkdown } from './utils/test-plan-markdown.ts';
@@ -236,6 +237,7 @@ export class Test extends Task {
   startTime?: number;
   endTime?: number;
   resetCount = 0;
+  appliedExperience: AppliedExperience[] = [];
 
   constructor(scenario: string, priority: 'critical' | 'important' | 'high' | 'normal' | 'low', expectedOutcome: string | string[], startUrl: string, plannedSteps: string[] = []) {
     super(scenario, startUrl);
@@ -257,6 +259,17 @@ export class Test extends Task {
     return [...new Set([this.startUrl, ...this.states.map((s) => s.url)].filter((value): value is string => Boolean(value) && value.trim() !== ''))];
   }
 
+  applyExperience(recipes: AppliedExperience[]): void {
+    for (const recipe of recipes) {
+      if (this.appliedExperience.some((applied) => applied.content === recipe.content)) continue;
+      this.appliedExperience.push(recipe);
+    }
+  }
+
+  getAppliedExperience(state: ActionResult): string[] {
+    return this.appliedExperience.filter((recipe) => state.isRelevantExperienceRecord({ url: recipe.url })).map((recipe) => recipe.content);
+  }
+
   addArtifact(artifact?: string): void {
     if (!artifact) return;
     const timestamp = `${performance.now()}_${this.timestampCounter++}`;
@@ -530,3 +543,8 @@ interface UrlNoteState {
   h2?: string;
   screenshotFile?: string;
 }
+
+interface AppliedExperience {
+  url: string;
+  content: string;
+}

package/src/utils/html-diff.ts

@@ -17,6 +17,7 @@ export interface HtmlDiffResult {
   removed: string[];
   similarity: number;
   summary: string;
+  messages: string[];
 }
 
 interface HtmlNode {
@@ -29,6 +30,11 @@ interface HtmlNode {
 
 const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]']);
 
+const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
+const TEXT_LINE_PREFIX = 'TEXT:';
+const MESSAGE_MAX_LENGTH = 200;
+const MESSAGE_LIMIT = 8;
+
 type DocumentNode = parse5TreeAdapter.Document;
 type ElementNode = parse5TreeAdapter.Element;
 type ParentNode = parse5TreeAdapter.Document | parse5TreeAdapter.Element;
@@ -203,7 +209,9 @@ export async function htmlDiff(originalHtml: string, modifiedHtml: string, htmlC
   const similarity = calculateSimilarity(originalLines, modifiedLines);
   const { added, removed } = findDifferences(originalLines, modifiedLines);
 
-  const parts = await buildDiffParts(originalDocument, modifiedDocument);
+  const originalMap = collectElementMap(originalDocument);
+  const modifiedMap = collectElementMap(modifiedDocument);
+  const parts = await buildDiffParts(originalMap, modifiedMap);
 
   const structuralAdditions = parts.flatMap((p) => p.added.filter((a) => a.startsWith('ELEMENT:')));
   const allAdded = [...added, ...structuralAdditions];
@@ -216,9 +224,69 @@ export async function htmlDiff(originalHtml: string, modifiedHtml: string, htmlC
     removed,
     similarity,
     summary,
+    messages: collectMessages(originalMap, modifiedMap, allAdded),
   };
 }
 
+/**
+ * Text the app announced while the page stayed the same: live region content first, then any other text that appeared.
+ */
+function collectMessages(originalMap: NodeMap, modifiedMap: NodeMap, added: string[]): string[] {
+  const appearedText = added.filter((line) => line.startsWith(TEXT_LINE_PREFIX)).map((line) => line.slice(TEXT_LINE_PREFIX.length));
+
+  return limitMessages([...collectLiveRegionTexts(originalMap, modifiedMap), ...appearedText]);
+}
+
+/**
+ * Text the app announced across a navigation. Only live regions: everything else on a new page is its content, not a message.
+ */
+export function liveRegionMessages(originalHtml: string, modifiedHtml: string): string[] {
+  const originalMap = collectElementMap(parseDocument(originalHtml));
+  const modifiedMap = collectElementMap(parseDocument(modifiedHtml));
+
+  return limitMessages(collectLiveRegionTexts(originalMap, modifiedMap));
+}
+
+function limitMessages(candidates: string[]): string[] {
+  const messages: string[] = [];
+
+  for (const candidate of candidates) {
+    const text = candidate.replace(/\s+/g, ' ').trim().slice(0, MESSAGE_MAX_LENGTH);
+    if (!text) continue;
+    if (messages.some((message) => message.includes(text))) continue;
+    messages.push(text);
+    if (messages.length === MESSAGE_LIMIT) break;
+  }
+
+  return messages;
+}
+
+function collectLiveRegionTexts(originalMap: NodeMap, modifiedMap: NodeMap): string[] {
+  const texts: string[] = [];
+
+  for (const [path, element] of modifiedMap) {
+    if (!isLiveRegion(element)) continue;
+    const text = getTextContent(element).trim();
+    if (!text) continue;
+    const previous = originalMap.get(path);
+    if (previous && getTextContent(previous).trim() === text) continue;
+    texts.push(text);
+  }
+
+  return texts;
+}
+
+function isLiveRegion(element: ElementNode): boolean {
+  if (element.tagName?.toLowerCase() === 'output') return true;
+
+  const attrs = element.attrs ?? [];
+  const role = attrs.find((attr) => attr.name === 'role')?.value.toLowerCase();
+  if (role && LIVE_REGION_ROLES.has(role)) return true;
+
+  const live = attrs.find((attr) => attr.name === 'aria-live')?.value.toLowerCase();
+  return live === 'polite' || live === 'assertive';
+}
+
 /**
  * Parse HTML into a document, wrapping fragments with html/body for consistency.
  * Uses custom sanitization that removes iframes for diff purposes.
@@ -448,10 +516,7 @@ function findStableContainer(topLevelPath: string, originalMap: NodeMap, modifie
   return { path: 'html[1]/body[1]', selector: 'body' };
 }
 
-async function buildDiffParts(originalDocument: DocumentNode, modifiedDocument: DocumentNode): Promise<HtmlDiffPart[]> {
-  const originalMap = collectElementMap(originalDocument);
-  const modifiedMap = collectElementMap(modifiedDocument);
-
+async function buildDiffParts(originalMap: NodeMap, modifiedMap: NodeMap): Promise<HtmlDiffPart[]> {
   const addedPaths: string[] = [];
   const changedPaths: string[] = [];
 
@@ -774,7 +839,7 @@ function flattenHtml(node: HtmlNode): string[] {
   function process(n: HtmlNode): void {
     if (n.type === 'text' && n.content) {
       if (n.content.length >= 5) {
-        lines.push(`TEXT:${n.content}`);
+        lines.push(`${TEXT_LINE_PREFIX}${n.content}`);
       }
       return;
     }
@@ -795,7 +860,7 @@ function flattenHtml(node: HtmlNode): string[] {
       }
 
       if (n.content && n.content.length >= 5) {
-        lines.push(`TEXT:${n.content}`);
+        lines.push(`${TEXT_LINE_PREFIX}${n.content}`);
       }
 
       if (n.children) {

package/src/utils/strings.ts

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import stripAnsi from 'strip-ansi';
 
 export function truncateJson(input: any): string {
   if (!input) return '';
@@ -40,3 +41,38 @@ export function safeFilename(name: string, ext = '', maxBytes = 240): string {
   }
   return truncated + suffix + ext;
 }
+
+export function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 3)}...`;
+}
+
+const MAX_COMPACT_ERROR = 400;
+
+export function compactErrorMessage(error: unknown): string {
+  let text = stripAnsi(String(error));
+  for (const strip of STRIP_STRATEGIES) {
+    text = strip(text);
+  }
+  return truncate(text, MAX_COMPACT_ERROR);
+}
+
+function stripCallLog(text: string): string {
+  const CALL_LOG = 'Call log:';
+  const NOISE = ['attempting', 'retrying', 'waiting'];
+
+  const [headline, ...log] = text.split(CALL_LOG);
+  if (!log.length) return text;
+
+  const lines = new Set<string>();
+  for (const line of log.join(CALL_LOG).split('\n')) {
+    const cleaned = normalizeInlineText(line);
+    if (!cleaned) continue;
+    if (NOISE.some((noise) => cleaned.includes(noise))) continue;
+    lines.add(cleaned);
+  }
+
+  return [headline.trim(), ...lines].join(' ');
+}
+
+const STRIP_STRATEGIES = [stripCallLog];

package/src/utils/url-matcher.ts

@@ -28,6 +28,21 @@ export function hasDynamicUrlSegment(url: string): boolean {
   return url.split('/').some((seg) => seg.length > 0 && isDynamicSegment(seg));
 }
 
+export function isSamePageFamily(urlA: string, urlB: string): boolean {
+  const partsA = new URL(urlA, 'http://localhost').pathname.toLowerCase().split('/').filter(Boolean);
+  const partsB = new URL(urlB, 'http://localhost').pathname.toLowerCase().split('/').filter(Boolean);
+  if (partsA.length !== partsB.length) return false;
+
+  let diffCount = 0;
+  for (let i = 0; i < partsA.length; i++) {
+    if (partsA[i] === partsB[i]) continue;
+    diffCount++;
+    if (diffCount > 1) return false;
+    if (!isDynamicSegment(partsA[i]) || !isDynamicSegment(partsB[i])) return false;
+  }
+  return true;
+}
+
 export function generalizeSegment(segment: string): string {
   if (/^\d+$/.test(segment)) return '\\d+';
   if (/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(segment)) return '[a-f0-9-]+';
@@ -103,6 +118,16 @@ export function matchesNavigationUrl(expected: string, current: string): boolean
   if (!expectedPath.includes('?')) {
     currentPath = currentPath.split('?')[0];
   }
-  const normalize = (value: string) => value.replace(/^\/+|\/+$/g, '').toLowerCase();
-  return normalize(expectedPath) === normalize(currentPath);
+  const normalize = (value: string) => value.replace(/^\/+|\/+$/g, '');
+  const expectedNormalized = normalize(expectedPath);
+  const currentNormalized = normalize(currentPath);
+  const expectedKey = expectedNormalized.toLowerCase();
+  const currentKey = currentNormalized.toLowerCase();
+  if (expectedKey === currentKey) return true;
+  if (!currentKey.startsWith(`${expectedKey}/`)) return false;
+  const recordSegments = currentNormalized
+    .slice(expectedKey.length + 1)
+    .split('/')
+    .filter(Boolean);
+  return recordSegments.length > 0 && recordSegments.every(isDynamicSegment);
 }