explorbot 0.2.4 → 0.3.0

package/src/commands/config-command.ts

@@ -0,0 +1,146 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import { type AIConfig, ConfigParser, EXPLORBOT_ENV_VARS, type ReporterConfig, configuredModels } from '../config.js';
+import { listSites } from '../global-config.js';
+import { Reporter } from '../reporter.js';
+import { getCliName } from '../utils/cli-name.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+export class ConfigCommand extends BaseCommand {
+  name = 'config';
+  description = 'Show models, config file and paths used by this run';
+
+  async execute(): Promise<void> {
+    const parser = ConfigParser.getInstance();
+    tag('info').log(ConfigCommand.render(this.explorBot.getConfig(), { configPath: parser.getConfigPath(), root: parser.getProjectRoot() }));
+  }
+
+  static async summary(options: { config?: string; path?: string; url?: string; json?: boolean } = {}): Promise<string> {
+    const parser = ConfigParser.getInstance();
+    const [site] = listSites();
+    const load = (baseUrl?: string) => parser.loadConfig({ config: options.config, path: options.path, baseUrl });
+
+    const config = await load(options.url).catch((error) => {
+      if (!site) throw error;
+      return load(site.url);
+    });
+
+    return ConfigCommand.render(config, { configPath: parser.getConfigPath(), root: parser.getProjectRoot(), json: options.json });
+  }
+
+  static data(config: SummarizedConfig, options: ConfigSummaryOptions = {}): ConfigData {
+    let configPath = '';
+    if (options.configPath && existsSync(options.configPath)) configPath = options.configPath;
+
+    const dirs: Record<string, string> = {};
+    if (options.root) {
+      for (const [name, dir] of Object.entries({ output: 'output', ...config.dirs })) {
+        dirs[name] = path.join(options.root, dir);
+      }
+    }
+
+    const env: Record<string, string> = {};
+    for (const variable of EXPLORBOT_ENV_VARS) {
+      const value = process.env[variable.name];
+      if (value) env[variable.name] = value;
+    }
+
+    const models: Record<string, string> = {};
+    const providers: Record<string, string> = {};
+    for (const [role, model] of Object.entries(configuredModels(config.ai))) {
+      models[role] = model.name;
+      if (model.provider) providers[role] = model.provider;
+    }
+
+    return {
+      config: configPath,
+      url: config.playwright?.url || config.web?.url || config.api?.baseEndpoint || '',
+      browser: config.playwright?.browser || '',
+      headless: !config.playwright?.show,
+      dirs,
+      models,
+      providers,
+      integrations: {
+        langfuse: !!config.ai?.langfuse?.enabled,
+        testomatio: Reporter.resolveEnabled(config.reporter),
+      },
+      env,
+    };
+  }
+
+  static render(config: SummarizedConfig, options: ConfigSummaryOptions = {}): string {
+    const data = ConfigCommand.data(config, options);
+    if (options.json) return JSON.stringify(data, null, 2);
+
+    const lines: string[] = [];
+    const section = (title: string, entries: [string, string][]) => {
+      if (!entries.length) return;
+      const width = Math.max(...entries.map(([label]) => label.length));
+      lines.push(chalk.bold(title));
+      for (const [label, value] of entries) lines.push(`  ${chalk.dim(label.padEnd(width))}  ${value}`);
+      lines.push('');
+    };
+
+    const general: [string, string][] = [['config', data.config || 'EXPLORBOT_* environment variables']];
+    if (data.url) general.push(['url', data.url]);
+    if (data.browser) {
+      let window = 'visible';
+      if (data.headless) window = 'headless';
+      general.push(['browser', `${data.browser}, ${window}`]);
+    }
+    for (const [name, dir] of Object.entries(data.dirs)) general.push([name, dir]);
+    section('Config', general);
+
+    const providerWidth = Math.max(0, ...Object.values(data.providers).map((provider) => provider.length));
+    const models: [string, string][] = Object.entries(data.models).map(([role, model]) => {
+      if (!providerWidth) return [role, model];
+      return [role, `${chalk.dim((data.providers[role] || '').padEnd(providerWidth))}  ${model}`];
+    });
+    if (!models.length) models.push(['model', chalk.red(`not configured — run ${getCliName()} init`)]);
+    section('Models', models);
+
+    const integrations: [string, string][] = [];
+    if (data.integrations.langfuse) integrations.push(['langfuse', 'traces sent']);
+    if (data.integrations.testomatio) integrations.push(['testomatio', 'runs reported']);
+    section('Integrations', integrations);
+
+    const env: [string, string][] = Object.entries(data.env).map(([name, value]) => {
+      let shown = value;
+      if (shown.length > 60) shown = `${shown.slice(0, 57)}...`;
+      return [name, shown];
+    });
+    section('Environment', env);
+
+    lines.push(chalk.dim(`Every EXPLORBOT_* variable: ${getCliName()} --help`));
+    return lines.join('\n');
+  }
+}
+
+interface ConfigSummaryOptions {
+  configPath?: string | null;
+  root?: string;
+  json?: boolean;
+}
+
+export interface ConfigData {
+  config: string;
+  url: string;
+  browser: string;
+  headless: boolean;
+  dirs: Record<string, string>;
+  models: Record<string, string>;
+  providers: Record<string, string>;
+  integrations: { langfuse: boolean; testomatio: boolean };
+  env: Record<string, string>;
+}
+
+interface SummarizedConfig {
+  ai?: AIConfig;
+  playwright?: { url?: string; browser?: string; show?: boolean };
+  web?: { url?: string };
+  api?: { baseEndpoint?: string };
+  dirs?: Record<string, string>;
+  reporter?: ReporterConfig;
+}

package/src/commands/index.ts

@@ -3,6 +3,7 @@ import { AddRuleCommand } from './add-rule-command.js';
 import type { BaseCommand } from './base-command.js';
 import { CleanCommand } from './clean-command.js';
 import { CompactCommand } from './compact-command.js';
+import { ConfigCommand } from './config-command.js';
 import { ContextAriaCommand } from './context-aria-command.js';
 import { ContextCommand } from './context-command.js';
 import { ContextDataCommand } from './context-data-command.js';
@@ -70,6 +71,7 @@ const commandClasses: CommandClass[] = [
   RunsCommand,
   RerunCommand,
   StatusCommand,
+  ConfigCommand,
   DebugCommand,
   ExitCommand,
 ];

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

@@ -433,7 +433,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 +444,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);
   }
@@ -514,6 +515,7 @@ export class ConfigParser {
         model: { modelId: 'test-model', provider: 'test' },
         config: {},
         vision: false,
+        langfuse: { enabled: false },
       },
       dirs: {
         knowledge: join(testBaseDir, 'knowledge'),
@@ -650,6 +652,18 @@ export class ConfigParser {
       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,
+      };
+    }
+
     return config;
   }
 
@@ -762,6 +776,32 @@ export function missingConfigMessage(configFile = 'explorbot.config.js'): string
   `;
 }
 
+export function modelName(model: unknown): string {
+  if (typeof model === 'string') return model;
+  return (model as any)?.modelId || (model as any)?.model || 'unknown';
+}
+
+export function modelProvider(model: unknown): string {
+  const provider = (model as any)?.provider;
+  if (typeof provider === 'string') return provider.split('.')[0];
+  if (typeof model === 'string') return model.split('/')[0];
+  return '';
+}
+
+export function configuredModels(ai?: AIConfig): Record<string, ConfiguredModel> {
+  if (!ai?.model) return {};
+
+  const describe = (model: unknown): ConfiguredModel => ({ name: modelName(model), provider: modelProvider(model) });
+
+  const models: Record<string, ConfiguredModel> = { model: describe(ai.model) };
+  if (ai.agenticModel) models.agenticModel = describe(ai.agenticModel);
+  if (ai.visionModel) models.visionModel = describe(ai.visionModel);
+  for (const [agent, agentConfig] of Object.entries(ai.agents || {})) {
+    if (agentConfig?.model) models[agent] = describe(agentConfig.model);
+  }
+  return models;
+}
+
 export async function resolveConfigModels(ai?: AIConfig): Promise<void> {
   if (!ai) return;
 
@@ -838,6 +878,11 @@ export async function createModel(provider: string, modelId: string): Promise<an
 
 type ModelRole = 'model' | 'visionModel' | 'agenticModel';
 
+interface ConfiguredModel {
+  name: string;
+  provider: string;
+}
+
 interface ProviderInfo {
   envKey: string;
   load: () => Promise<(modelId: string) => any>;
@@ -849,4 +894,4 @@ interface EnvVar {
   required?: boolean;
 }
 
-export type { ModelRole, EnvVar, ProviderInfo };
+export type { ModelRole, EnvVar, ProviderInfo, ConfiguredModel };

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);
       });
 
@@ -487,9 +487,11 @@ export class ExplorBot {
 
   setCurrentPlan(plan?: Plan): void {
     this.currentPlan = plan;
-    if (plan && !this.sessionPlans.includes(plan)) {
+    if (!plan) return;
+    if (!this.sessionPlans.includes(plan)) {
       this.sessionPlans.push(plan);
     }
+    plan.notifyChange();
   }
 
   getSessionTests(): Test[] {

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/remote.ts

@@ -16,8 +16,9 @@ const FLUSH_TIMEOUT_MS = 3000;
  * process and a CI bot are the same case.
  *
  * It **is** a LogDestination — that is the whole integration on the logger's
- * side — and it answers asks by installing itself as the execution
- * controller's input callback. Nothing else in explorbot knows it exists.
+ * side, messages and `data` alike — and it answers asks by installing itself
+ * as the execution controller's input callback. Nothing else in explorbot
+ * knows it exists.
  */
 export class Remote implements LogDestination {
   private url: string | null = null;
@@ -110,6 +111,11 @@ export class Remote implements LogDestination {
    */
   write(entry: TaggedLogEntry): void {
     if (entry.type === 'html') return;
+    if (entry.type === 'data') {
+      const [kind, payload] = entry.originalArgs || [];
+      this.send(String(kind), payload);
+      return;
+    }
     let content = stripAnsi(entry.content ?? '');
     if (content.length > CONTENT_CAP) content = `${content.slice(0, CONTENT_CAP)}… (${content.length} chars)`;
     this.send('log', {

package/src/state-manager.ts

@@ -1,8 +1,8 @@
-import { type FocusedElement, ActionResult } from './action-result.js';
+import { ActionResult, type FocusedElement } from './action-result.js';
 import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
 import { detectFocusArea } from './utils/aria.js';
-import { createDebug } from './utils/logger.js';
+import { createDebug, tag } from './utils/logger.js';
 import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 
@@ -117,6 +117,9 @@ export class StateManager {
    * Emit state change event to all listeners
    */
   private emitStateChange(event: StateTransition): void {
+    const state = event.toState;
+    tag('data').log('state', { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 });
+
     this.stateChangeListeners.forEach((listener) => {
       try {
         listener(event);

package/src/test-plan.ts

@@ -1,6 +1,8 @@
 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';
 import { uniqSessionName } from './utils/unique-names.ts';
 
@@ -235,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);
@@ -256,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++}`;
@@ -317,6 +331,7 @@ export class Test extends Task {
     this.startTime = performance.now();
     this.addNote(`Test started. Session name: ${this.sessionName}`);
     this.plan?.notifyChange();
+    this.reportStatus();
   }
 
   finish(result: TestResultType = TestResult.FAILED): void {
@@ -324,6 +339,7 @@ export class Test extends Task {
     this.result = result;
     this.endTime = performance.now();
     this.plan?.notifyChange();
+    this.reportStatus();
   }
 
   getDurationMs(): number | null {
@@ -336,6 +352,18 @@ export class Test extends Task {
     return this.expected.filter((e) => !achieved.includes(e));
   }
 
+  private reportStatus(): void {
+    tag('data').log('test', {
+      scenario: this.scenario,
+      status: this.status,
+      result: this.result,
+      priority: this.priority,
+      sessionName: this.sessionName,
+      url: this.startUrl,
+      plan: this.plan?.title,
+    });
+  }
+
   override getLog(): Array<{ type: 'step' | 'note' | 'artifact'; content: string; timestamp: number }> {
     const merged: Record<string, { type: 'step' | 'note' | 'artifact'; content: string }> = {};
 
@@ -407,6 +435,11 @@ export class Plan {
     for (const listener of this.changeListeners) {
       listener(this.tests);
     }
+    tag('data').log('plan', {
+      title: this.title,
+      url: this.url,
+      tests: this.tests.map((test) => ({ scenario: test.scenario, status: test.status, result: test.result, priority: test.priority })),
+    });
   }
 
   getAllTests(): Test[] {
@@ -510,3 +543,8 @@ interface UrlNoteState {
   h2?: string;
   screenshotFile?: string;
 }
+
+interface AppliedExperience {
+  url: string;
+  content: string;
+}