explorbot 0.4.4 → 0.4.6

package/src/api/spec-reader.ts

@@ -51,7 +51,7 @@ export function extractEndpointDefinition(schema: any, endpoint: string, baseEnd
   }
 
   const basePath = toBasePath(baseEndpoint);
-  const matched = collectMatchingPaths(schema, basePath, (normalized) => matchesEndpoint(normalized, endpoint));
+  const matched = collectEndpointPaths(schema, basePath, endpoint);
 
   if (!Object.keys(matched).length) {
     const available = listNormalizedPaths(schema, basePath);
@@ -61,6 +61,35 @@ export function extractEndpointDefinition(schema: any, endpoint: string, baseEnd
   return safeStringify(matched);
 }
 
+export function resolveEndpoints(schema: any, pattern: string, baseEndpoint?: string): string[] {
+  if (!schema?.paths) {
+    throw new Error('OpenAPI spec has no paths defined');
+  }
+
+  const basePath = toBasePath(baseEndpoint);
+  const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+  const matched = normalized.filter((specPath) => matchesPattern(specPath, pattern));
+
+  if (!matched.length) {
+    throw new Error(`Endpoint "${pattern}" not found in spec. Available: ${listNormalizedPaths(schema, basePath)}`);
+  }
+
+  const roots = matched.map((specPath) => toCollection(specPath, normalized, pattern));
+  const resolved = [...new Set(roots.map((root) => fillParameters(root, pattern)))];
+  const endpoints = resolved.filter((specPath) => !specPath.includes('{'));
+
+  if (!endpoints.length) {
+    throw new Error(`Endpoint "${pattern}" leaves ${listParameters(resolved)} unresolved. Give the value in the endpoint or in the base endpoint.`);
+  }
+
+  const skipped = resolved.filter((specPath) => specPath.includes('{'));
+  if (skipped.length) {
+    tag('warning').log(`Skipped, no value for their parameters: ${skipped.join(', ')}`);
+  }
+
+  return endpoints;
+}
+
 export function searchEndpoints(schema: any, query: string, baseEndpoint?: string): string {
   if (!schema?.paths) return 'No endpoints available';
 
@@ -166,6 +195,82 @@ function stripBasePath(specPath: string, basePath: string): string {
   return `/${specSegments.slice(i).join('/')}`;
 }
 
+function collectEndpointPaths(schema: any, basePath: string, endpoint: string): Record<string, any> {
+  const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+  const roots = resolveEndpoint(normalized, endpoint);
+
+  if (!roots.length) return collectMatchingPaths(schema, basePath, (path) => matchesEndpoint(path, endpoint));
+
+  return collectMatchingPaths(schema, basePath, (path) => roots.some((root) => path === root || path.startsWith(`${root}/`)));
+}
+
+function resolveEndpoint(specPaths: string[], endpoint: string): string[] {
+  const wanted = toSegments(endpoint);
+  if (!wanted.length) return [];
+
+  const matched = specPaths.filter((specPath) => {
+    const segments = toSegments(specPath);
+    if (segments.length !== wanted.length) return false;
+    return segmentsMatch(segments, wanted);
+  });
+
+  const literals = matched.map((specPath) => toSegments(specPath).filter((segment, i) => segment === wanted[i]).length);
+  const best = Math.max(0, ...literals);
+  return matched.filter((_, i) => literals[i] === best);
+}
+
+function matchesPattern(specPath: string, pattern: string): boolean {
+  const wanted = toSegments(pattern);
+  const segments = toSegments(specPath);
+  if (segments.length < wanted.length) return false;
+  return segmentsMatch(segments, wanted);
+}
+
+function segmentsMatch(segments: string[], wanted: string[]): boolean {
+  return wanted.every((want, i) => want === '*' || segments[i] === want || segments[i].startsWith('{'));
+}
+
+function toCollection(specPath: string, specPaths: string[], pattern: string): string {
+  const segments = toSegments(specPath);
+  const filled = toSegments(fillParameters(specPath, pattern));
+
+  let deepest = segments.length;
+  const unfilled = filled.findIndex((segment) => segment.startsWith('{'));
+  if (unfilled >= 0) deepest = unfilled;
+
+  for (let i = Math.max(1, Math.min(toSegments(pattern).length, deepest)); i <= deepest; i++) {
+    const prefix = `/${segments.slice(0, i).join('/')}`;
+    if (specPaths.includes(prefix)) return prefix;
+  }
+
+  return specPath;
+}
+
+function fillParameters(specPath: string, pattern: string): string {
+  const wanted = toSegments(pattern);
+  const segments = toSegments(specPath);
+  for (let i = 0; i < wanted.length && i < segments.length; i++) {
+    if (wanted[i] === '*') continue;
+    if (!segments[i].startsWith('{')) continue;
+    segments[i] = wanted[i];
+  }
+  return `/${segments.join('/')}`;
+}
+
+function listParameters(specPaths: string[]): string {
+  const found = new Set<string>();
+  for (const specPath of specPaths) {
+    for (const segment of toSegments(specPath)) {
+      if (segment.startsWith('{')) found.add(segment);
+    }
+  }
+  return [...found].join(', ');
+}
+
+function toSegments(path: string): string[] {
+  return path.split('/').filter(Boolean);
+}
+
 function matchesEndpoint(specPath: string, endpoint: string): boolean {
   if (specPath === endpoint) return true;
   if (specPath.startsWith(`${endpoint}/`)) return true;

package/src/application-spec.ts

@@ -17,7 +17,7 @@ export class ApplicationSpec {
   }
 
   renderFor(state: ActionResult): string {
-    const relevant = this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
+    const relevant = this.relevantPages(state);
     if (relevant.length === 0) return '';
 
     tag('operation').log(`Found application specification for ${state.url}`);
@@ -30,6 +30,10 @@ export class ApplicationSpec {
     `;
   }
 
+  matchedUrls(state: ActionResult): string[] {
+    return this.relevantPages(state).map((page) => page.url);
+  }
+
   get pageCount(): number {
     return this.pages.length;
   }
@@ -75,12 +79,26 @@ export class ApplicationSpec {
   }
 
   private resolveSourcePath(sourcePath: string): string {
-    if (path.isAbsolute(sourcePath)) return path.resolve(sourcePath);
-    const configParser = ConfigParser.getInstance();
-    return path.resolve(configParser.resolveProjectDir(sourcePath));
+    return resolveSpecSource(sourcePath);
+  }
+
+  private relevantPages(state: ActionResult): ApplicationSpecPage[] {
+    return this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
   }
 }
 
+export function resolveSpecBundlePath(sourcePath: string): string | null {
+  const resolved = resolveSpecSource(sourcePath);
+  if (!existsSync(resolved)) return null;
+  if (statSync(resolved).isDirectory()) return resolved;
+  return path.dirname(resolved);
+}
+
+function resolveSpecSource(sourcePath: string): string {
+  if (path.isAbsolute(sourcePath)) return path.resolve(sourcePath);
+  return path.resolve(ConfigParser.getInstance().resolveProjectDir(sourcePath));
+}
+
 interface ApplicationSpecPage {
   url: string;
   content: string;

package/src/commands/base-command.ts

@@ -15,7 +15,7 @@ export interface Suggestion {
   hint: string;
 }
 
-export abstract class BaseCommand {
+export abstract class BaseCommand<T = ExplorBot> {
   abstract name: string;
   abstract description: string;
   aliases: string[] = [];
@@ -23,9 +23,9 @@ export abstract class BaseCommand {
   tuiEnabled = true;
   suggestions: Suggestion[] = [];
 
-  protected explorBot: ExplorBot;
+  protected explorBot: T;
 
-  constructor(explorBot: ExplorBot) {
+  constructor(explorBot: T) {
     this.explorBot = explorBot;
   }
 

package/src/commands/init-command.ts

@@ -39,7 +39,7 @@ ${moduleExport}
 `;
 }
 
-function envTemplate(provider: string): string {
+export function envTemplate(provider: string): string {
   const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
     if (name === provider) return `${envKey}=`;
     return `# ${envKey}=`;
@@ -253,7 +253,7 @@ async function renderLocalProviderWizard(): Promise<string | null> {
   });
 }
 
-function modelLines(provider: string): string {
+export function modelLines(provider: string, only?: ModelRole[]): string {
   const recommended = ConfigParser.recommendedModels()[provider] || {};
   const roles: Array<[ModelRole, string]> = [
     ['model', 'fast model with tool calling capabilities'],
@@ -261,7 +261,10 @@ function modelLines(provider: string): string {
     ['agenticModel', 'agentic model for decision making'],
   ];
 
-  return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+  let selected = roles;
+  if (only) selected = roles.filter(([role]) => only.includes(role));
+
+  return selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
 }
 
 function globalConfigTemplate(provider: string): string {

package/src/config.ts

@@ -130,6 +130,11 @@ interface RerunnerAgentConfig extends AgentConfig {
 interface PlannerAgentConfig extends AgentConfig {
   styles?: string[];
   stylesDir?: string;
+  docsWeight?: number;
+}
+
+interface ScoutAgentConfig extends AgentConfig {
+  dirs?: string[];
 }
 
 interface ScreencastConfig {
@@ -154,6 +159,7 @@ interface AgentsConfig {
   quartermaster?: AgentConfig;
   historian?: HistorianAgentConfig;
   fisherman?: AgentConfig;
+  scout?: ScoutAgentConfig;
   chief?: AgentConfig;
   curler?: AgentConfig;
   rerunner?: RerunnerAgentConfig;
@@ -293,6 +299,7 @@ export type {
   ResearcherAgentConfig,
   NavigatorAgentConfig,
   PlannerAgentConfig,
+  ScoutAgentConfig,
   RerunnerAgentConfig,
   HealRecipe,
   Hook,

package/src/explorbot.ts

@@ -14,12 +14,15 @@ import { AIProvider } from './ai/provider.ts';
 import { Quartermaster } from './ai/quartermaster.ts';
 import { Rerunner } from './ai/rerunner.ts';
 import { Researcher } from './ai/researcher.ts';
+import { Scout } from './ai/scout.ts';
+import { loadScoutCorpus } from './ai/scout/tools.ts';
 import { SessionAnalyst } from './ai/session-analyst.ts';
 import { Tester } from './ai/tester.ts';
 import { createAgentTools } from './ai/tools.ts';
 import { ApiClient } from './api/api-client.ts';
 import { RequestStore } from './api/request-store.ts';
 import { loadSpec } from './api/spec-reader.ts';
+import { resolveSpecBundlePath } from './application-spec.ts';
 import type { ExplorbotConfig, ReporterConfig } from './config.js';
 import { ConfigParser } from './config.ts';
 import { ExperienceTracker } from './experience-tracker.ts';
@@ -231,6 +234,8 @@ export class ExplorBot {
       this.agents.planner = this.createAgent((deps) => new Planner(deps, this.agentResearcher()));
       const fisherman = this.agentFisherman();
       if (fisherman) this.agents.planner.setFisherman(fisherman);
+      const scout = this.agentScout();
+      if (scout) this.agents.planner.setScout(scout);
     }
     return this.agents.planner;
   }
@@ -367,6 +372,37 @@ export class ExplorBot {
     return this.agents.fisherman;
   }
 
+  agentScout(): Scout | null {
+    const scoutConfig = this.config.ai?.agents?.scout;
+    if (scoutConfig?.enabled !== true) return null;
+
+    const dirs = this.scoutCorpusDirs();
+    if (dirs.length === 0) {
+      tag('warning').log('Scout enabled but no documentation found — set --spec or ai.agents.scout.dirs');
+      return null;
+    }
+
+    return (this.agents.scout ||= this.createAgent(({ ai }) => new Scout(ai, loadScoutCorpus(dirs))));
+  }
+
+  private scoutCorpusDirs(): string[] {
+    const dirs: string[] = [];
+
+    const specPath = this.options.applicationSpec || this.config.dirs?.spec;
+    if (specPath) {
+      const bundle = resolveSpecBundlePath(specPath);
+      const pagesDir = bundle && path.join(bundle, 'pages');
+      if (pagesDir && existsSync(pagesDir)) dirs.push(pagesDir);
+    }
+
+    for (const dir of this.config.ai?.agents?.scout?.dirs || []) {
+      const resolved = this.configParser.resolveProjectDir(dir);
+      if (existsSync(resolved)) dirs.push(resolved);
+    }
+
+    return [...new Set(dirs)];
+  }
+
   getCurrentPlan(): Plan | undefined {
     return this.currentPlan;
   }

package/src/explorer.ts

@@ -263,7 +263,7 @@ class Explorer {
   }
 
   private convertToCodeceptConfig(config: ExplorbotConfig): any {
-    const playwrightConfig = { ...config.playwright };
+    const playwrightConfig = { visibleLocator: true, ...config.playwright };
 
     if (this.options?.show !== undefined) {
       playwrightConfig.show = this.options.show;

package/src/knowledge-tracker.ts

@@ -102,6 +102,10 @@ export class KnowledgeTracker {
     return this.applicationSpec?.renderFor(state) || '';
   }
 
+  applicationSpecUrls(state: ActionResult): string[] {
+    return this.applicationSpec?.matchedUrls(state) || [];
+  }
+
   addKnowledge(urlPattern: string, description: string, opts?: { replace?: boolean }): { filename: string; filePath: string; isNewFile: boolean } {
     const configParser = ConfigParser.getInstance();
     const configPath = configParser.getConfigPath();

package/src/utils/aria-ref.ts

@@ -0,0 +1,61 @@
+import { WebElement } from './web-element.ts';
+
+const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
+const ARIA_REF_PATTERN = /^(f\d+)?e\d+$/i;
+
+const REF_ROLES: Record<string, string> = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
+
+export function ariaRefSelector(ref: string): string {
+  return `aria-ref=${ref}`;
+}
+
+export function isAriaRef(ref: string): boolean {
+  return ARIA_REF_PATTERN.test(ref);
+}
+
+export function ariaRefSnapshot(page: any): Promise<string> {
+  return page.locator('body').ariaSnapshot({ mode: 'ai' });
+}
+
+export function parseAriaRefs(ariaSnapshot: string): AriaRefEntry[] {
+  const entries: AriaRefEntry[] = [];
+  for (const line of ariaSnapshot.split('\n')) {
+    const match = line.match(REF_LINE_PATTERN);
+    if (!match) continue;
+    entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
+  }
+  return entries;
+}
+
+export async function elementFromAriaRef(page: any, ref: string): Promise<WebElement | null> {
+  if (!isAriaRef(ref)) return null;
+  return WebElement.fromPlaywrightLocator(page.locator(ariaRefSelector(ref)));
+}
+
+export async function refIsGone(explorer: any, ref: string): Promise<boolean> {
+  const count = () => Promise.resolve(explorer?.withPage?.((page: any) => page.locator(ariaRefSelector(ref)).count())).catch(() => undefined);
+  if ((await count()) !== 0) return false;
+  await Promise.resolve(explorer?.withPage?.(ariaRefSnapshot)).catch(() => null);
+  return (await count()) === 0;
+}
+
+export async function describeRef(explorer: any, ref: string): Promise<{ role: string; text: string } | null> {
+  return Promise.resolve(
+    explorer?.withPage?.((page: any) =>
+      page.locator(ariaRefSelector(ref)).evaluate((el: any, roles: Record<string, string>) => {
+        const tag = el.tagName.toLowerCase();
+        const role = el.getAttribute('role') || roles[tag];
+        if (!role) return null;
+        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
+        if (!text) return null;
+        return { role, text };
+      }, REF_ROLES)
+    )
+  ).catch(() => null);
+}
+
+export interface AriaRefEntry {
+  role: string;
+  name: string;
+  ref: string;
+}

package/src/utils/aria.ts

@@ -431,9 +431,9 @@ const formatDiffSection = (label: string, items: string[]): string[] => {
   const summary = countBy(items);
   if (summary.size === 0) return [`  ${label}: []`];
 
-  const sorted = Array.from(summary.entries()).sort(([aItem, aCount], [bItem, bCount]) => bCount - aCount || aItem.localeCompare(bItem));
-  const top = sorted.slice(0, TOP_DIFF_ITEMS);
-  const rest = sorted.slice(TOP_DIFF_ITEMS);
+  const ordered = Array.from(summary.entries());
+  const top = ordered.slice(0, TOP_DIFF_ITEMS);
+  const rest = ordered.slice(TOP_DIFF_ITEMS);
 
   const lines = [`  ${label}:`];
   for (const [item, count] of top) {

package/src/utils/html-diff.ts

@@ -37,7 +37,7 @@ const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]'])
 const SHELL_RATIO = 0.8;
 const ROOT_CONTENT_RATIO = 0.8;
 
-const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
+const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log', 'tooltip']);
 const TEXT_LINE_PREFIX = 'TEXT:';
 const MESSAGE_MAX_LENGTH = 200;
 const MESSAGE_LIMIT = 8;
@@ -549,6 +549,8 @@ function semanticSelectorFor(element: ElementNode, allElements: NodeMap): string
   while (current) {
     const selector = buildContainerSelector(current, allElements);
     if (selector) return selector;
+    const classAttr = (current.attrs ?? []).find((a) => a.name === 'class')?.value;
+    if (classAttr && filterContainerClasses(classAttr.split(/\s+/).filter(Boolean)).length > 0) return undefined;
     current = dominantChild(current);
   }
   return undefined;

package/src/utils/web-annotate.ts

@@ -1,27 +1,15 @@
+import { ariaRefSnapshot, parseAriaRefs } from './aria-ref.ts';
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from './html.ts';
 import { createDebug } from './logger.js';
 import { WebElement } from './web-element.ts';
 
 const debugLog = createDebug('explorbot:web-annotate');
 
-const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
-
 const ANNOTATABLE_ROLES = new Set(['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'switch', 'combobox', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'treeitem']);
 
-function parseAriaRefs(ariaSnapshot: string): Array<{ role: string; name: string; ref: string }> {
-  const entries: Array<{ role: string; name: string; ref: string }> = [];
-  for (const line of ariaSnapshot.split('\n')) {
-    const match = line.match(REF_LINE_PATTERN);
-    if (!match) continue;
-    if (!ANNOTATABLE_ROLES.has(match[2])) continue;
-    entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
-  }
-  return entries;
-}
-
 export async function annotatePageElements(page: any): Promise<{ ariaSnapshot: string; elements: WebElement[] }> {
-  const ariaSnapshot: string = await page.locator('body').ariaSnapshot({ mode: 'ai' });
-  const refEntries = parseAriaRefs(ariaSnapshot);
+  const ariaSnapshot: string = await ariaRefSnapshot(page);
+  const refEntries = parseAriaRefs(ariaSnapshot).filter((entry) => ANNOTATABLE_ROLES.has(entry.role));
 
   const byRole = new Map<string, Array<{ name: string; ref: string }>>();
   for (const { role, name, ref } of refEntries) {

package/src/utils/web-element.ts

@@ -125,15 +125,6 @@ export class WebElement {
     return WebElement.fromPlaywrightLocator(page.locator(`[${EXPLORBOT_ATTRS.eidx}="${eidx}"]`));
   }
 
-  static isAriaRef(ref: string): boolean {
-    return /^(f\d+)?e\d+$/i.test(ref);
-  }
-
-  static async fromAriaRef(page: any, ref: string): Promise<WebElement | null> {
-    if (!WebElement.isAriaRef(ref)) return null;
-    return WebElement.fromPlaywrightLocator(page.locator(`aria-ref=${ref}`));
-  }
-
   static async fromEidxList(page: any, eidxList: string[]): Promise<WebElement[]> {
     const validEidxList = eidxList.filter((eidx) => /^e\d+$/i.test(eidx));
     if (validEidxList.length === 0) return [];