explorbot 0.1.32-beta.1 → 0.2.1

package/dist/src/commands/compact-command.js

@@ -1,8 +1,8 @@
 import { basename } from 'node:path';
 import chalk from 'chalk';
+import { COMPACT_MAX_LENGTH } from '../ai/experience-compactor.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
-const COMPACT_THRESHOLD = 5000;
 export class CompactCommand extends BaseCommand {
     name = 'compact';
     description = 'Compact stored experience files; optionally filtered by filename or URL substring';
@@ -16,7 +16,7 @@ export class CompactCommand extends BaseCommand {
         const target = remaining[0];
         const dryRun = !!opts.dryRun;
         const merge = opts.merge !== false;
-        const tracker = this.explorBot.getExperienceTracker();
+        const tracker = this.explorBot.experienceTracker();
         const files = this.resolveTarget(tracker, target);
         if (files === null) {
             tag('info').log('No experience files found.');
@@ -51,7 +51,7 @@ export class CompactCommand extends BaseCommand {
     buildDryRunSuggestions(compactor, files, target) {
         const wouldTouch = files.filter((f) => {
             const stripped = compactor.stripNonUsefulEntries(f.content);
-            return stripped !== f.content || stripped.length >= COMPACT_THRESHOLD || compactor.isRecent(f);
+            return stripped !== f.content || stripped.length >= COMPACT_MAX_LENGTH || compactor.isRecent(f);
         });
         if (wouldTouch.length === 0)
             return [];
@@ -62,7 +62,7 @@ export class CompactCommand extends BaseCommand {
     async runFullSweep(compactor, merge) {
         if (!merge) {
             tag('info').log('Compacting all experience files (merge skipped)…');
-            const compacted = await compactor.compactFiles(this.explorBot.getExperienceTracker().getAllExperience());
+            const compacted = await compactor.compactFiles(this.explorBot.experienceTracker().getAllExperience());
             return { merged: 0, compacted };
         }
         tag('info').log('Merging experience files with similar URLs, then compacting all…');
@@ -101,7 +101,7 @@ export class CompactCommand extends BaseCommand {
             const charsRemoved = chars - strippedChars;
             const willStrip = stripped !== file.content;
             const willReview = compactor.isRecent(file);
-            const willAi = strippedChars >= COMPACT_THRESHOLD;
+            const willAi = strippedChars >= COMPACT_MAX_LENGTH;
             if (willStrip)
                 wouldStrip++;
             if (willReview)
@@ -131,7 +131,7 @@ export class CompactCommand extends BaseCommand {
         lines.push(`  ${chalk.dim('Files matched:')}      ${chalk.bold(String(files.length))}`);
         lines.push(`  ${chalk.dim('Would strip:')}        ${chalk.bold(String(wouldStrip))} ${chalk.dim('(remove legacy / FAILED / Visual click, rename to FLOW/ACTION)')}`);
         lines.push(`  ${chalk.dim('Would ai-review:')}    ${chalk.bold(String(wouldAiReview))} ${chalk.dim('(recent files ≤30d — quality/reusability check)')}`);
-        lines.push(`  ${chalk.dim('Would ai-compact:')}   ${chalk.bold(String(wouldAiCompact))} ${chalk.dim(`(over ${COMPACT_THRESHOLD} chars after strip)`)}`);
+        lines.push(`  ${chalk.dim('Would ai-compact:')}   ${chalk.bold(String(wouldAiCompact))} ${chalk.dim(`(over ${COMPACT_MAX_LENGTH} chars after strip)`)}`);
         lines.push(`  ${chalk.dim('Total chars:')}        ${chalk.bold(String(totalChars))}`);
         tag('info').log(lines.join('\n'));
     }

package/dist/src/commands/context-aria-command.js

@@ -4,7 +4,7 @@ export class ContextAriaCommand extends BaseCommand {
     name = 'context:aria';
     description = 'Print full ARIA snapshot for current page';
     async execute(_args) {
-        const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to snapshot');
         }

package/dist/src/commands/context-command.js

@@ -1,8 +1,10 @@
 import { Researcher } from '../ai/researcher.js';
+import { visuallyAnnotateContainers } from '../ai/researcher/coordinates.js';
 import { outputPath } from '../config.js';
 import { formatContextSummary } from '../utils/context-formatter.js';
 import { tag } from '../utils/logger.js';
 import { extractValidContainers } from '../utils/research-parser.js';
+import { annotatePageElements } from '../utils/web-annotate.js';
 import { BaseCommand } from './base-command.js';
 export class ContextCommand extends BaseCommand {
     name = 'context';
@@ -22,21 +24,21 @@ export class ContextCommand extends BaseCommand {
     ];
     async execute(args) {
         const explorer = this.explorBot.getExplorer();
-        const state = explorer.getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to show context for');
         }
         const { opts } = this.parseArgs(args);
         const isVisual = !!(opts.visual || opts.screenshot);
-        await explorer.annotateElements();
+        await explorer.withPage(annotatePageElements);
         if (isVisual) {
             const cachedResearch = Researcher.getCachedResearch(state);
             const containers = cachedResearch ? extractValidContainers(cachedResearch) : [];
-            await explorer.visuallyAnnotateElements({ containers });
+            await explorer.withPage((page) => visuallyAnnotateContainers(page, containers));
         }
-        const actionResult = await explorer.createAction().capturePageState({ includeScreenshot: isVisual });
-        const experienceTracker = explorer.getStateManager().getExperienceTracker();
-        const knowledgeTracker = this.explorBot.getKnowledgeTracker();
+        const actionResult = await explorer.capture({ screenshot: isVisual });
+        const experienceTracker = this.explorBot.experienceTracker();
+        const knowledgeTracker = this.explorBot.knowledgeTracker();
         let mode = 'compact';
         if (opts.full) {
             mode = 'full';

package/dist/src/commands/context-data-command.js

@@ -6,14 +6,14 @@ export class ContextDataCommand extends BaseCommand {
     description = 'Extract structured data from current page';
     async execute(_args) {
         const explorer = this.explorBot.getExplorer();
-        const state = explorer.getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to extract data from');
         }
         const actionResult = ActionResult.fromState(state);
         if (!actionResult.html || actionResult.html.trim().length < 100) {
             tag('info').log('Capturing fresh page content...');
-            const freshResult = await explorer.createAction().capturePageState();
+            const freshResult = await explorer.capture();
             const table = await this.explorBot.agentResearcher().extractData(freshResult);
             tag('multiline').log(table);
             return;

package/dist/src/commands/context-experience-command.js

@@ -8,12 +8,12 @@ export class ContextExperienceCommand extends BaseCommand {
     description = 'Print all matching experience for current page';
     async execute(_args) {
         const explorer = this.explorBot.getExplorer();
-        const state = explorer.getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page');
         }
         const actionResult = ActionResult.fromState(state);
-        const experienceTracker = explorer.getStateManager().getExperienceTracker();
+        const experienceTracker = this.explorBot.experienceTracker();
         const experience = experienceTracker.getRelevantExperience(actionResult);
         if (experience.length === 0) {
             tag('info').log(`No experience found for: ${actionResult.url}`);

package/dist/src/commands/context-html-command.js

@@ -6,7 +6,7 @@ export class ContextHtmlCommand extends BaseCommand {
     description = 'Print combined HTML snapshot for current page';
     async execute(_args) {
         const explorer = this.explorBot.getExplorer();
-        const manager = explorer.getStateManager();
+        const manager = this.explorBot.stateManager();
         const state = manager.getCurrentState();
         if (!state) {
             throw new Error('No active page to snapshot');
@@ -14,7 +14,7 @@ export class ContextHtmlCommand extends BaseCommand {
         let actionResult = ActionResult.fromState(state);
         if (!actionResult.html || actionResult.html.trim().length < 100) {
             tag('info').log('Capturing fresh page content...');
-            actionResult = await explorer.createAction().capturePageState();
+            actionResult = await explorer.capture();
         }
         const html = await actionResult.combinedHtml();
         if (!html) {

package/dist/src/commands/context-knowledge-command.js

@@ -8,12 +8,12 @@ export class ContextKnowledgeCommand extends BaseCommand {
     description = 'Print all matching knowledge for current page';
     async execute(_args) {
         const explorer = this.explorBot.getExplorer();
-        const state = explorer.getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page');
         }
         const actionResult = ActionResult.fromState(state);
-        const knowledgeTracker = this.explorBot.getKnowledgeTracker();
+        const knowledgeTracker = this.explorBot.knowledgeTracker();
         const knowledge = knowledgeTracker.getRelevantKnowledge(actionResult);
         if (knowledge.length === 0) {
             tag('info').log(`No knowledge found for: ${actionResult.url}`);

package/dist/src/commands/drill-command.js

@@ -10,7 +10,7 @@ export class DrillCommand extends BaseCommand {
     async execute(args) {
         const knowledgePath = this.parseKnowledgeArg(args);
         const maxComponents = this.parseMaxArg(args);
-        const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to drill');
         }

package/dist/src/commands/experience-command.js

@@ -16,7 +16,7 @@ export class ExperienceCommand extends BaseCommand {
             return;
         }
         const recency = opts.recent ? 'recent' : opts.old ? 'old' : undefined;
-        const tracker = this.explorBot.getExperienceTracker();
+        const tracker = this.explorBot.experienceTracker();
         const [first, second] = remaining;
         const combinedRef = first?.match(/^([A-Z]+)[.\-]?(\d+)$/i);
         if (combinedRef) {

package/dist/src/commands/explore-command.js

@@ -4,6 +4,7 @@ import { outputPath } from '../config.js';
 import { normalizeUrl } from '../state-manager.js';
 import { Stats } from '../stats.js';
 import { TestResult } from '../test-plan.js';
+import { browserErrorMessage } from "../utils/browser-errors.js";
 import { getCliName } from "../utils/cli-name.js";
 import { ErrorPageError, getStateErrorPageError } from "../utils/error-page.js";
 import { tag } from '../utils/logger.js';
@@ -34,7 +35,7 @@ export class ExploreCommand extends BaseCommand {
     oldTestRefs = new Set();
     priorityFilter;
     getCurrentPageUrl() {
-        const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         return state?.fullUrl || state?.url;
     }
     async execute(args) {
@@ -53,7 +54,7 @@ export class ExploreCommand extends BaseCommand {
         Stats.mode ??= 'explore';
         Stats.focus ??= feature;
         const mainUrl = this.getCurrentPageUrl();
-        const error = getStateErrorPageError(this.explorBot.getExplorer().getStateManager().getCurrentState());
+        const error = getStateErrorPageError(this.explorBot.stateManager().getCurrentState());
         if (error) {
             tag('warning').log(error.message);
             return;
@@ -72,7 +73,7 @@ export class ExploreCommand extends BaseCommand {
             return;
         }
         if (mainUrl)
-            await this.explorBot.visit(mainUrl);
+            await this.explorBot.visit(mainUrl).catch((err) => tag('warning').log(`Could not return to ${mainUrl}: ${browserErrorMessage(err)}`));
         const savedPath = this.explorBot.savePlans(this.completedPlans);
         this.printResults();
         await this.explorBot.printSessionAnalysis();

package/dist/src/commands/freesail-command.js

@@ -31,7 +31,7 @@ export class FreesailCommand extends BaseCommand {
         await loop(async (ctx) => {
             if (maxTests != null && testsRun >= maxTests)
                 ctx.stop();
-            const stateManager = this.explorBot.getExplorer().getStateManager();
+            const stateManager = this.explorBot.stateManager();
             const state = stateManager.getCurrentState();
             if (state && !Researcher.getCachedResearch(state)) {
                 await this.explorBot.agentResearcher().research(state, { deep: true, screenshot: true });
@@ -63,7 +63,7 @@ export class FreesailCommand extends BaseCommand {
                 return;
             }
             tag('info').log(`Navigating to: ${suggestion.target} - ${suggestion.reason}`);
-            await this.explorBot.openFreshTab();
+            await this.explorBot.openTab();
             await this.explorBot.visit(suggestion.target);
             this.explorBot.clearPlan();
         }, { maxAttempts: Number.POSITIVE_INFINITY });

package/dist/src/commands/knows-command.js

@@ -17,7 +17,7 @@ export class KnowsCommand extends BaseCommand {
     description = 'List all knowledge URLs or show matching knowledge for a URL';
     async execute(args, limit = 0) {
         const url = args.trim();
-        const tracker = this.explorBot.getKnowledgeTracker();
+        const tracker = this.explorBot.knowledgeTracker();
         if (!url) {
             const allKnowledge = tracker.listAllKnowledge();
             if (allKnowledge.length === 0) {

package/dist/src/commands/learn-command.js

@@ -10,10 +10,12 @@ export class LearnCommand extends BaseCommand {
         const note = args.trim();
         if (!note) {
             const AddKnowledge = (await import('../components/AddKnowledge.js')).default;
-            const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+            const explorer = this.explorBot.getExplorer();
+            const state = this.explorBot.stateManager().getCurrentState();
             const initialUrl = state?.url || '';
             const { unmount } = render(React.createElement(AddKnowledge, {
                 initialUrl,
+                knowledgeTracker: this.explorBot.knowledgeTracker(),
                 onComplete: () => unmount(),
                 onCancel: () => unmount(),
             }), {
@@ -23,12 +25,12 @@ export class LearnCommand extends BaseCommand {
             return;
         }
         const explorer = this.explorBot.getExplorer();
-        const state = explorer.getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to attach knowledge');
         }
         const targetUrl = state.url || state.fullUrl || '/';
-        explorer.getKnowledgeTracker().addKnowledge(targetUrl, note);
+        this.explorBot.knowledgeTracker().addKnowledge(targetUrl, note);
         tag('success').log('Knowledge saved for current page');
     }
 }

package/dist/src/commands/path-command.js

@@ -7,7 +7,7 @@ export class PathCommand extends BaseCommand {
     async execute(args) {
         const { opts } = this.parseArgs(args);
         const showLinks = !!opts.links;
-        const stateManager = this.explorBot.getExplorer().getStateManager();
+        const stateManager = this.explorBot.stateManager();
         const history = stateManager.getStateHistory();
         if (history.length === 0) {
             tag('multiline').log('No navigation history yet.');

package/dist/src/commands/research-command.js

@@ -23,7 +23,7 @@ export class ResearchCommand extends BaseCommand {
         if (target) {
             await this.explorBot.agentNavigator().visit(target);
         }
-        const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+        const state = this.explorBot.stateManager().getCurrentState();
         if (!state) {
             throw new Error('No active page to research');
         }

package/dist/src/commands/test-command.js

@@ -48,7 +48,7 @@ export class TestCommand extends BaseCommand {
                 toExecute.push(...matching);
             }
             else {
-                const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+                const state = this.explorBot.stateManager().getCurrentState();
                 if (!state) {
                     throw new Error('No page loaded. Please navigate to a page first.');
                 }

package/dist/src/components/AddKnowledge.d.ts

@@ -1,6 +1,8 @@
 import React from 'react';
+import type { KnowledgeTracker } from '../knowledge-tracker.js';
 interface AddKnowledgeProps {
     initialUrl?: string;
+    knowledgeTracker: KnowledgeTracker;
     onComplete?: () => void;
     onCancel?: () => void;
 }

package/dist/src/components/AddKnowledge.js

@@ -1,8 +1,7 @@
 import { Box, Text, useInput } from 'ink';
 import React, { useEffect, useState } from 'react';
-import { KnowledgeTracker } from '../knowledge-tracker.js';
 import InputReadline from './InputReadline.js';
-const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
+const AddKnowledge = ({ initialUrl = '', knowledgeTracker, onComplete, onCancel }) => {
     const [urlPattern, setUrlPattern] = useState(initialUrl);
     const [description, setDescription] = useState('');
     const [activeField, setActiveField] = useState(initialUrl ? 'description' : 'url');
@@ -11,18 +10,16 @@ const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
     const isStandalone = !onComplete;
     useEffect(() => {
         try {
-            const knowledgeTracker = new KnowledgeTracker();
             const urls = knowledgeTracker.getExistingUrls();
             setSuggestedUrls(urls);
         }
         catch (error) {
             console.error('Failed to load suggestions:', error);
         }
-    }, []);
+    }, [knowledgeTracker]);
     useEffect(() => {
         if (urlPattern.trim()) {
             try {
-                const knowledgeTracker = new KnowledgeTracker();
                 const knowledge = knowledgeTracker.getKnowledgeForUrl(urlPattern);
                 setExistingKnowledge(knowledge);
             }
@@ -34,13 +31,12 @@ const AddKnowledge = ({ initialUrl = '', onComplete, onCancel }) => {
         else {
             setExistingKnowledge([]);
         }
-    }, [urlPattern]);
+    }, [urlPattern, knowledgeTracker]);
     const handleSave = () => {
         if (!urlPattern.trim() || !description.trim()) {
             return;
         }
         try {
-            const knowledgeTracker = new KnowledgeTracker();
             const result = knowledgeTracker.addKnowledge(urlPattern.trim(), description.trim());
             const action = result.isNewFile ? 'Created' : 'Updated';
             console.log(`\nKnowledge ${action} in: ${result.filename}`);

package/dist/src/components/App.js

@@ -47,7 +47,7 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
                 userInputPromiseRef.current = { resolve, reject };
             });
         });
-        const manager = explorBot.getExplorer().getStateManager();
+        const manager = explorBot.stateManager();
         unsubscribe = manager.onStateChange((transition) => {
             if (mounted) {
                 setLastTransition(transition);
@@ -111,7 +111,7 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
                 return;
             setChecklistData({
                 config: explorBot.getConfig(),
-                knowledgeTracker: explorBot.getKnowledgeTracker(),
+                knowledgeTracker: explorBot.knowledgeTracker(),
             });
             setShowWelcome(true);
             setShowInput(true);
@@ -283,7 +283,7 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
         React.createElement(Box, { height: 3, flexDirection: "row", justifyContent: "space-between", alignItems: "center", paddingX: 1 },
             React.createElement(ActivityPane, { isInputVisible: showInput }),
             showSessionTimer && React.createElement(SessionTimer, { startedAt: sessionStartedAtRef.current })),
-        showWelcome && React.createElement(WelcomeCommands, { hasKnowledge: explorBot.getKnowledgeTracker().listAllKnowledge().length > 0 }),
+        showWelcome && React.createElement(WelcomeCommands, { hasKnowledge: explorBot.knowledgeTracker().listAllKnowledge().length > 0 }),
         showInput && React.createElement(Box, { height: 1 }),
         interruptPrompt && showInput && (React.createElement(Box, { paddingX: 1 },
             React.createElement(Text, { color: "yellow" }, interruptPrompt))),

package/dist/src/config.d.ts

@@ -1,3 +1,4 @@
+export declare const PROVIDERS: Record<string, () => Promise<(modelId: string) => any>>;
 interface PlaywrightConfig {
     browser: 'chromium' | 'firefox' | 'webkit';
     url: string;
@@ -204,6 +205,7 @@ interface ExplorbotConfig {
     };
     experience?: {
         maxReadLines?: number;
+        disabled?: boolean;
     };
     reporter?: ReporterConfig;
     api?: ApiConfig;
@@ -213,14 +215,17 @@ interface ExplorbotConfig {
 }
 type RuleEntry = string | Record<string, string>;
 export declare const EXPLORBOT_CONFIG_PATHS: string[];
+export declare const EXPLORBOT_ENV_VARS: EnvVar[];
 export type { ExplorbotConfig, PlaywrightConfig, AIConfig, HtmlConfig, ActionConfig, AgentConfig, AgentsConfig, HistorianAgentConfig, ResearcherAgentConfig, NavigatorAgentConfig, PlannerAgentConfig, RerunnerAgentConfig, HealRecipe, Hook, HookConfig, HooksConfig, PlaywrightHook, CodeceptJSHook, HookPatternMap, RuleEntry, ReporterConfig, ApiConfig, WebConfig, ApiHookFn, };
 export declare class ConfigParser {
     static instance: ConfigParser;
+    static recommended: Record<string, Record<string, string>> | null;
     config: ExplorbotConfig | null;
     configPath: string | null;
     runtimeBaseUrlOverride: string | null;
     constructor();
     static loadEnv(filePath: string): void;
+    static recommendedModels(): Record<string, Record<string, string>>;
     static getInstance(): ConfigParser;
     loadConfig(options?: {
         config?: string;
@@ -230,6 +235,8 @@ export declare class ConfigParser {
     getConfig(): ExplorbotConfig;
     getConfigPath(): string | null;
     getOutputDir(): string;
+    getProjectRoot(): string;
+    resolveProjectDir(relativeDir: string): string;
     getStatesDir(): string;
     getPlansDir(): string;
     getTestsDir(): string;
@@ -237,6 +244,7 @@ export declare class ConfigParser {
     static setupTestConfig(): void;
     static getTestDirectories(): string[];
     static cleanupAllTestDirectories(): void;
+    buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig>;
     findConfigFile(): string | null;
     loadConfigModule(configPath: string): Promise<any>;
     resolveConfig(config: ExplorbotConfig, options?: {
@@ -249,3 +257,14 @@ export declare class ConfigParser {
     ensureDirectory(path: string): void;
 }
 export declare function outputPath(...segments: string[]): string;
+export declare function resolveModel(spec: string, role?: ModelRole): Promise<any>;
+export declare function resolveOutputRoot(): string;
+export declare function materializeKnowledge(outputRoot: string): void;
+export declare function createModel(provider: string, modelId: string): Promise<any>;
+type ModelRole = 'model' | 'visionModel' | 'agenticModel';
+interface EnvVar {
+    name: string;
+    description: string;
+    required?: boolean;
+}
+export type { ModelRole, EnvVar };