explorbot 0.1.11 → 0.1.13

package/src/commands/explore-command.ts

@@ -1,5 +1,6 @@
 import figureSet from 'figures';
 import { getStyles } from '../ai/planner/styles.js';
+import { outputPath } from '../config.js';
 import { Stats } from '../stats.js';
 import type { Plan } from '../test-plan.js';
 import { getCliName } from '../utils/cli-name.ts';
@@ -7,6 +8,7 @@ import { ErrorPageError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { jsonToTable } from '../utils/markdown-parser.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
+import { safeFilename } from '../utils/strings.ts';
 import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class ExploreCommand extends BaseCommand {
@@ -71,6 +73,7 @@ export class ExploreCommand extends BaseCommand {
     if (mainUrl) await this.explorBot.visit(mainUrl);
     const savedPath = this.explorBot.savePlans(this.completedPlans);
     this.printResults();
+    await this.explorBot.printSessionAnalysis();
     this.printNextSteps(savedPath);
   }
 
@@ -152,11 +155,27 @@ export class ExploreCommand extends BaseCommand {
     }
 
     const savedFiles = this.explorBot.agentHistorian().getSavedFiles();
-    if (savedFiles.length > 0) {
-      const commands = savedFiles.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}` }));
+    const screencasts = savedFiles.filter((f) => f.endsWith('.webm'));
+    const testFiles = savedFiles.filter((f) => !f.endsWith('.webm'));
+
+    if (testFiles.length > 0) {
+      const commands = testFiles.map((f) => ({ label: '', command: `${cli} rerun ${relativeToCwd(f)}` }));
       commands.push({ label: 'List tests', command: `${cli} runs` });
       sections.push({
-        label: `Generated tests (${savedFiles.length})`,
+        label: `Generated tests (${testFiles.length})`,
+        commands,
+      });
+    }
+
+    if (screencasts.length > 0) {
+      const commands = screencasts.map((f) => ({ label: '', command: relativeToCwd(f) }));
+      const screencastDir = relativeToCwd(outputPath('screencasts'));
+      const planSlugs = [...new Set(this.completedPlans.map((p) => safeFilename(p.title)).filter(Boolean))];
+      for (const slug of planSlugs) {
+        commands.push({ label: 'Browse plan', command: `ls ${screencastDir}/${slug}-*` });
+      }
+      sections.push({
+        label: `Screencasts (${screencasts.length})`,
         commands,
       });
     }

package/src/components/AddRule.tsx

@@ -5,7 +5,7 @@ import React, { useEffect, useState } from 'react';
 import { AddRuleCommand } from '../commands/add-rule-command.js';
 import InputReadline from './InputReadline.js';
 
-const KNOWN_AGENTS = ['researcher', 'tester', 'planner', 'pilot', 'captain', 'bosun', 'navigator'];
+const KNOWN_AGENTS = ['researcher', 'tester', 'planner', 'pilot', 'captain', 'driller', 'navigator'];
 
 interface AddRuleProps {
   initialAgent?: string;

package/src/config.ts

@@ -107,8 +107,14 @@ interface PlannerAgentConfig extends AgentConfig {
   stylesDir?: string;
 }
 
+interface ScreencastConfig {
+  size?: { width: number; height: number };
+  quality?: number;
+}
+
 interface HistorianAgentConfig extends AgentConfig {
   framework?: 'codeceptjs' | 'playwright';
+  screencast?: boolean | ScreencastConfig;
 }
 
 interface AgentsConfig {
@@ -117,6 +123,7 @@ interface AgentsConfig {
   researcher?: ResearcherAgentConfig;
   planner?: PlannerAgentConfig;
   pilot?: PilotAgentConfig;
+  driller?: AgentConfig;
   'experience-compactor'?: AgentConfig;
   captain?: AgentConfig;
   quartermaster?: AgentConfig;
@@ -125,6 +132,7 @@ interface AgentsConfig {
   chief?: AgentConfig;
   curler?: AgentConfig;
   rerunner?: RerunnerAgentConfig;
+  analyst?: AgentConfig;
 }
 
 interface AIConfig {
@@ -173,6 +181,8 @@ interface ActionConfig {
 interface ReporterConfig {
   enabled?: boolean;
   html?: boolean;
+  markdown?: boolean;
+  runGroup?: string | null;
 }
 
 type ApiHookFn = (ctx: { headers: Record<string, string>; baseEndpoint: string }) => Promise<Record<string, string> | undefined> | Record<string, string> | undefined;

package/src/explorbot.ts

@@ -1,8 +1,8 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { ActionResult } from './action-result.ts';
-import { Bosun } from './ai/bosun.ts';
 import { Captain } from './ai/captain.ts';
+import { Driller } from './ai/driller.ts';
 import { ExperienceCompactor } from './ai/experience-compactor.ts';
 import { Fisherman } from './ai/fisherman.ts';
 import { Historian } from './ai/historian.ts';
@@ -13,6 +13,7 @@ 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 { 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';
@@ -25,8 +26,9 @@ import Explorer from './explorer.ts';
 import { KnowledgeTracker } from './knowledge-tracker.ts';
 import { WebPageState } from './state-manager.ts';
 import type { Suite } from './suite.ts';
-import { Plan } from './test-plan.ts';
+import { Plan, type Test } from './test-plan.ts';
 import { setVerboseMode, tag } from './utils/logger.ts';
+import { relativeToCwd } from './utils/next-steps.ts';
 import { sanitizeFilename } from './utils/strings.ts';
 
 export interface ExplorBotOptions {
@@ -55,6 +57,8 @@ export class ExplorBot {
   lastPlanError: Error | null = null;
   lastSavedPlanPath: string | null = null;
   private agents: Record<string, any> = {};
+  private sessionPlans: Plan[] = [];
+  private lastReportedTestCount = 0;
 
   constructor(options: ExplorBotOptions = {}) {
     this.options = options;
@@ -262,7 +266,10 @@ export class ExplorBot {
     return (this.agents.historian ||= this.createAgent(({ ai, explorer, config }) => {
       const experienceTracker = explorer.getStateManager().getExperienceTracker();
       const reporter = explorer.getReporter();
-      return new Historian(ai, experienceTracker, reporter, explorer.getStateManager(), config, explorer.getPlaywrightRecorder());
+      return new Historian(ai, experienceTracker, reporter, explorer.getStateManager(), config, {
+        recorder: explorer.getPlaywrightRecorder(),
+        helper: explorer.playwrightHelper,
+      });
     }));
   }
 
@@ -281,15 +288,17 @@ export class ExplorBot {
     return this.agents.rerunner;
   }
 
-  agentBosun(): Bosun {
-    return (this.agents.bosun ||= this.createAgent(({ ai, explorer }) => {
-      const researcher = this.agentResearcher();
+  agentDriller(): Driller {
+    return (this.agents.driller ||= this.createAgent(({ ai, explorer }) => {
       const navigator = this.agentNavigator();
-      const tools = createAgentTools({ explorer, researcher, navigator });
-      return new Bosun(explorer, ai, researcher, navigator, tools);
+      return new Driller(explorer, ai, navigator);
     }));
   }
 
+  agentSessionAnalyst(): SessionAnalyst {
+    return (this.agents.sessionAnalyst ||= this.createAgent(({ ai }) => new SessionAnalyst(ai)));
+  }
+
   agentFisherman(): Fisherman | null {
     const fishermanConfig = this.config.ai?.agents?.fisherman;
     const hasApiConfig = !!this.config.api;
@@ -362,7 +371,7 @@ export class ExplorBot {
     }
     this.lastPlanError = null;
     try {
-      this.currentPlan = await planner.plan(feature, opts.style, opts.extend, opts.completedPlans);
+      this.setCurrentPlan(await planner.plan(feature, opts.style, opts.extend, opts.completedPlans));
     } catch (err) {
       this.lastPlanError = err instanceof Error ? err : new Error(String(err));
       tag('warning').log(`Planning failed: ${this.lastPlanError.message}`);
@@ -433,11 +442,50 @@ export class ExplorBot {
       throw new Error(`Plan file not found: ${planPath}`);
     }
 
-    this.currentPlan = Plan.fromMarkdown(planPath);
-    return this.currentPlan;
+    this.setCurrentPlan(Plan.fromMarkdown(planPath));
+    return this.currentPlan!;
   }
 
   setCurrentPlan(plan?: Plan): void {
     this.currentPlan = plan;
+    if (plan && !this.sessionPlans.includes(plan)) {
+      this.sessionPlans.push(plan);
+    }
+  }
+
+  getSessionTests(): Test[] {
+    return this.sessionPlans.flatMap((p) => p.tests.filter((t) => t.startTime != null));
+  }
+
+  async printSessionAnalysis(): Promise<void> {
+    const analystConfig = this.config.ai?.agents?.analyst;
+    if (analystConfig?.enabled === false) return;
+
+    const tests = this.getSessionTests();
+    if (tests.length === 0) return;
+    if (tests.length === this.lastReportedTestCount) return;
+
+    try {
+      const markdown = await this.agentSessionAnalyst().analyze(tests);
+      if (!markdown) {
+        this.lastReportedTestCount = tests.length;
+        return;
+      }
+
+      tag('multiline').log(markdown);
+
+      const filePath = this.agentSessionAnalyst().writeReport(markdown);
+      tag('info').log(`Session report saved: ${relativeToCwd(filePath)}`);
+
+      const reporter = this.explorer?.getReporter();
+      if (reporter?.isEnabled()) {
+        await reporter.setRunDescription(markdown);
+      }
+
+      this.lastReportedTestCount = tests.length;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      tag('warning').log(`Session analysis failed: ${message}`);
+    }
   }
 }

package/src/explorer.ts

@@ -19,8 +19,9 @@ import { PlaywrightRecorder } from './playwright-recorder.ts';
 import { Reporter } from './reporter.ts';
 import { StateManager } from './state-manager.js';
 import { Test } from './test-plan.ts';
+import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from './utils/html.ts';
 import { createDebug, log, tag } from './utils/logger.js';
-import { WebElement, extractElementData } from './utils/web-element.ts';
+import { WebElement } from './utils/web-element.ts';
 
 declare global {
   namespace NodeJS {
@@ -337,11 +338,11 @@ class Explorer {
   async getEidxInContainer(containerCss: string | null): Promise<string[]> {
     const page = this.playwrightHelper.page;
     try {
-      const selector = containerCss ? `${containerCss} [data-explorbot-eidx]` : '[data-explorbot-eidx]';
+      const selector = containerCss ? `${containerCss} [${ELEMENT_EXTRACTION_CONFIG.attrs.eidx}]` : `[${ELEMENT_EXTRACTION_CONFIG.attrs.eidx}]`;
       const elements = await page.locator(selector).all();
       const result: string[] = [];
       for (const el of elements) {
-        const attr = await el.getAttribute('data-explorbot-eidx');
+        const attr = await el.getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx);
         if (attr) result.push(attr);
       }
       return result;
@@ -359,7 +360,7 @@ class Explorer {
       const page = this.playwrightHelper.page;
       const base = container ? page.locator(container) : page;
       const el = locator.startsWith('//') ? base.locator(`xpath=${locator}`) : base.locator(locator);
-      return await el.first().getAttribute('data-explorbot-eidx');
+      return await el.first().getAttribute(ELEMENT_EXTRACTION_CONFIG.attrs.eidx);
     } catch (error) {
       if (this.isFatalBrowserError(error)) {
         tag('warning').log(`getEidxByLocator: ${error instanceof Error ? error.message : error}`);
@@ -714,6 +715,7 @@ function toCodeceptjsTest(test: Test): any {
   codeceptjsTest.fullTitle = () => `${parent.title} ${test.scenario}`;
   codeceptjsTest.state = 'pending';
   codeceptjsTest.notes = test.getPrintableNotes();
+  codeceptjsTest._explorbotTest = test;
   return codeceptjsTest;
 }
 
@@ -733,7 +735,7 @@ function parseAriaRefs(ariaSnapshot: string): Array<{ role: string; name: string
 }
 
 export async function annotatePageElements(page: any): Promise<{ ariaSnapshot: string; elements: WebElement[] }> {
-  const ariaSnapshot: string = await page.locator('body').ariaSnapshot({ forAI: true });
+  const ariaSnapshot: string = await page.locator('body').ariaSnapshot({ mode: 'ai' });
   const refEntries = parseAriaRefs(ariaSnapshot);
 
   const byRole = new Map<string, Array<{ name: string; ref: string }>>();
@@ -750,20 +752,20 @@ export async function annotatePageElements(page: any): Promise<{ ariaSnapshot: s
   for (const [role, entries] of byRole) {
     try {
       const rawList = await page.getByRole(role).evaluateAll(
-        (domElements: Element[], [data, extractFnStr]: [Array<{ name: string; ref: string }>, string]) => {
+        (domElements: Element[], [data, extractFnStr, config]: [Array<{ name: string; ref: string }>, string, typeof ELEMENT_EXTRACTION_CONFIG]) => {
           const extract = new Function(`return ${extractFnStr}`)() as (el: Element) => any;
           const results: any[] = [];
           let ariaIdx = 0;
           for (const el of domElements) {
             if (ariaIdx >= data.length) break;
-            el.setAttribute('data-explorbot-eidx', data[ariaIdx].ref);
-            const elData = extract(el);
+            el.setAttribute(config.attrs.eidx, data[ariaIdx].ref);
+            const elData = extract(el, config);
             if (elData) results.push(elData);
             ariaIdx++;
           }
           return results;
         },
-        [entries, extractElementData.toString()]
+        [entries, getElementDataExtractorSource(), ELEMENT_EXTRACTION_CONFIG]
       );
       for (const raw of rawList) {
         elements.push(WebElement.fromRawData(raw, role));

package/src/reporter.ts

@@ -33,8 +33,21 @@ export class Reporter {
       this.configureHtmlPipe();
     }
 
-    const pipe = process.env.TESTOMATIO && config?.html ? 'both' : process.env.TESTOMATIO ? 'testomatio' : 'html';
-    debugLog('Reporter initialized', { enabled: this.reporterEnabled, pipe });
+    if (this.reporterEnabled && config?.markdown) {
+      this.configureMarkdownPipe();
+    }
+
+    if (this.reporterEnabled) {
+      this.configureRunGroup(config?.runGroup);
+    }
+
+    debugLog('Reporter initialized', {
+      enabled: this.reporterEnabled,
+      testomatio: Boolean(process.env.TESTOMATIO),
+      html: Boolean(process.env.TESTOMATIO_HTML_REPORT_SAVE),
+      markdown: Boolean(process.env.TESTOMATIO_MARKDOWN_REPORT_SAVE),
+      runGroup: process.env.TESTOMATIO_RUNGROUP_TITLE || null,
+    });
   }
 
   private buildTitle(): string {
@@ -56,7 +69,31 @@ export class Reporter {
   private configureHtmlPipe(): void {
     process.env.TESTOMATIO_HTML_REPORT_SAVE = '1';
     process.env.TESTOMATIO_HTML_REPORT_FOLDER = outputPath('reports');
-    debugLog('HTML report pipe configured', { folder: process.env.TESTOMATIO_HTML_REPORT_FOLDER });
+    process.env.TESTOMATIO_HTML_FILENAME = `${Stats.sessionLabel()}.html`;
+    debugLog('HTML report pipe configured', {
+      folder: process.env.TESTOMATIO_HTML_REPORT_FOLDER,
+      filename: process.env.TESTOMATIO_HTML_FILENAME,
+    });
+  }
+
+  private configureMarkdownPipe(): void {
+    process.env.TESTOMATIO_MARKDOWN_REPORT_SAVE = '1';
+    process.env.TESTOMATIO_MARKDOWN_REPORT_FOLDER = outputPath('reports');
+    process.env.TESTOMATIO_MARKDOWN_FILENAME = `${Stats.sessionLabel()}-tests.md`;
+    debugLog('Markdown report pipe configured', {
+      folder: process.env.TESTOMATIO_MARKDOWN_REPORT_FOLDER,
+      filename: process.env.TESTOMATIO_MARKDOWN_FILENAME,
+    });
+  }
+
+  private configureRunGroup(runGroup: string | null | undefined): void {
+    if (process.env.TESTOMATIO_RUNGROUP_TITLE) return;
+    if (runGroup === null) return;
+    if (runGroup) {
+      process.env.TESTOMATIO_RUNGROUP_TITLE = runGroup;
+      return;
+    }
+    process.env.TESTOMATIO_RUNGROUP_TITLE = `Explorbot ${new Date().toISOString().slice(0, 10)}`;
   }
 
   async startRun(): Promise<void> {
@@ -104,6 +141,7 @@ export class Reporter {
     const noteEntries = Object.entries(test.notes)
       .map(([timestampKey, note]) => ({
         startTime: note.startTime,
+        endTime: note.endTime,
         message: note.message,
         status: note.status,
         screenshot: note.screenshot,
@@ -135,7 +173,7 @@ export class Reporter {
       const step: Step = {
         category: 'user',
         title: noteEntry.message,
-        duration: 0,
+        duration: Math.max(0, Math.round(noteEntry.endTime - noteEntry.startTime)),
         status: noteEntry.status || 'none',
         steps: noteSteps.length > 0 ? noteSteps : undefined,
       };
@@ -182,6 +220,7 @@ export class Reporter {
       }
 
       const steps = this.combineStepsAndNotes(test, screenshotFile);
+      const durationMs = test.getDurationMs();
 
       const testData = {
         rid: test.id,
@@ -197,6 +236,7 @@ export class Reporter {
         files: Object.values(test.artifacts) || [],
         message: test.summary || this.extractLastNoteMessage(test) || '',
         meta,
+        time: durationMs != null ? Math.round(durationMs) : 0,
       };
 
       debugLog(testData);
@@ -226,6 +266,30 @@ export class Reporter {
     return this.isRunStarted;
   }
 
+  async setRunDescription(text: string): Promise<void> {
+    if (!this.isRunStarted) return;
+    if (!process.env.TESTOMATIO) return;
+    const runId = this.client.runId;
+    if (!runId) return;
+
+    const baseUrl = process.env.TESTOMATIO_URL || 'https://app.testomat.io';
+    const url = `${baseUrl}/api/reporter/${runId}`;
+    try {
+      const response = await fetch(url, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ api_key: process.env.TESTOMATIO, description: text }),
+      });
+      if (!response.ok) {
+        debugLog('Run description update failed:', response.status, response.statusText);
+        return;
+      }
+      debugLog('Run description updated');
+    } catch (error) {
+      debugLog('Failed to update run description:', error);
+    }
+  }
+
   private extractLastNoteMessage(test: Test): string {
     const notes = Object.values(test.notes);
     if (notes.length === 0) return '';

package/src/state-manager.ts

@@ -142,8 +142,8 @@ export class StateManager {
 
   /**
    * Extract state path from full URL
-   * Removes domain, port, protocol, and query params
-   * Keeps path and hash: /path/to/page#section
+   * Removes domain, port, protocol
+   * Keeps path, query, and hash: /path/to/page?tab=users#section
    */
   /**
    * Update current state from ActionResult and record transition if state changed
@@ -549,7 +549,8 @@ export class StateManager {
 export function normalizeUrl(url: string): string {
   try {
     const parsed = new URL(url, 'http://localhost');
-    return parsed.pathname.replace(/^\/+|\/+$/g, '');
+    const path = parsed.pathname.replace(/^\/+|\/+$/g, '');
+    return `${path}${parsed.search}${parsed.hash}`;
   } catch {
     return url.replace(/^\/+|\/+$/g, '');
   }

package/src/stats.ts

@@ -1,3 +1,5 @@
+import { uniqExplorationName } from './utils/unique-names.ts';
+
 interface TokenUsage {
   input: number;
   output: number;
@@ -8,6 +10,7 @@ export type ExplorbotMode = 'explore' | 'test' | 'freesail' | 'tui';
 
 export class Stats {
   static startTime = Date.now();
+  static sessionName = uniqExplorationName();
   static researches = 0;
   static tests = 0;
   static plans = 0;
@@ -54,4 +57,8 @@ export class Stats {
     const totalTokens = Object.values(Stats.models).reduce((sum, m) => sum + m.total, 0);
     return totalTokens > 0;
   }
+
+  static sessionLabel(): string {
+    return `${Stats.mode || 'session'}-${Stats.sessionName}`;
+  }
 }