explorbot 0.2.0 → 0.2.1

package/src/commands/context-experience-command.ts

@@ -10,14 +10,14 @@ export class ContextExperienceCommand extends BaseCommand {
 
   async execute(_args: string): Promise<void> {
     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) {

package/src/commands/context-html-command.ts

@@ -8,7 +8,7 @@ export class ContextHtmlCommand extends BaseCommand {
 
   async execute(_args: string): Promise<void> {
     const explorer = this.explorBot.getExplorer();
-    const manager = explorer.getStateManager();
+    const manager = this.explorBot.stateManager();
     const state = manager.getCurrentState();
 
     if (!state) {
@@ -19,7 +19,7 @@ export class ContextHtmlCommand extends BaseCommand {
 
     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();

package/src/commands/context-knowledge-command.ts

@@ -10,7 +10,7 @@ export class ContextKnowledgeCommand extends BaseCommand {
 
   async execute(_args: string): Promise<void> {
     const explorer = this.explorBot.getExplorer();
-    const state = explorer.getStateManager().getCurrentState();
+    const state = this.explorBot.stateManager().getCurrentState();
 
     if (!state) {
       throw new Error('No active page');

package/src/commands/drill-command.ts

@@ -13,7 +13,7 @@ export class DrillCommand extends BaseCommand {
     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/src/commands/explore-command.ts

@@ -4,6 +4,7 @@ import { outputPath } from '../config.js';
 import { normalizeUrl } from '../state-manager.js';
 import { Stats } from '../stats.js';
 import { type Plan, type Test, TestResult } from '../test-plan.js';
+import { browserErrorMessage } from '../utils/browser-errors.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { ErrorPageError, getStateErrorPageError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
@@ -38,7 +39,7 @@ export class ExploreCommand extends BaseCommand {
   private priorityFilter?: Set<string>;
 
   private getCurrentPageUrl(): string | undefined {
-    const state = this.explorBot.getExplorer().getStateManager().getCurrentState();
+    const state = this.explorBot.stateManager().getCurrentState();
     return state?.fullUrl || state?.url;
   }
 
@@ -56,7 +57,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;
@@ -74,7 +75,7 @@ export class ExploreCommand extends BaseCommand {
       this.printResults();
       return;
     }
-    if (mainUrl) await this.explorBot.visit(mainUrl);
+    if (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/src/commands/freesail-command.ts

@@ -35,7 +35,7 @@ export class FreesailCommand extends BaseCommand {
       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)) {
@@ -70,7 +70,7 @@ export class FreesailCommand extends BaseCommand {
         }
 
         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();
       },

package/src/commands/learn-command.ts

@@ -14,13 +14,13 @@ export class LearnCommand extends BaseCommand {
     if (!note) {
       const AddKnowledge = (await import('../components/AddKnowledge.js')).default;
       const explorer = this.explorBot.getExplorer();
-      const state = explorer.getStateManager().getCurrentState();
+      const state = this.explorBot.stateManager().getCurrentState();
       const initialUrl = state?.url || '';
 
       const { unmount } = render(
         React.createElement(AddKnowledge, {
           initialUrl,
-          knowledgeTracker: explorer.getKnowledgeTracker(),
+          knowledgeTracker: this.explorBot.knowledgeTracker(),
           onComplete: () => unmount(),
           onCancel: () => unmount(),
         }),
@@ -33,14 +33,14 @@ export class LearnCommand extends BaseCommand {
     }
 
     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/src/commands/path-command.ts

@@ -16,7 +16,7 @@ export class PathCommand extends BaseCommand {
   async execute(args: string): Promise<void> {
     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) {

package/src/commands/research-command.ts

@@ -27,7 +27,7 @@ export class ResearchCommand extends BaseCommand {
       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/src/commands/test-command.ts

@@ -48,7 +48,7 @@ export class TestCommand extends BaseCommand {
       if (matching.length > 0) {
         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/src/components/App.tsx

@@ -68,7 +68,7 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
       });
     });
 
-    const manager = explorBot.getExplorer().getStateManager();
+    const manager = explorBot.stateManager();
 
     unsubscribe = manager.onStateChange((transition: StateTransition) => {
       if (mounted) {

package/src/config.ts

@@ -1,8 +1,22 @@
-import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
-import path, { dirname, join, resolve } from 'node:path';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path, { basename, dirname, join, resolve } from 'node:path';
 import { parseEnv } from 'node:util';
+import matter from 'gray-matter';
 import { log } from './utils/logger.js';
 
+export const PROVIDERS: Record<string, () => Promise<(modelId: string) => any>> = {
+  openai: async () => (await import('@ai-sdk/openai')).createOpenAI(),
+  anthropic: async () => (await import('@ai-sdk/anthropic')).createAnthropic(),
+  google: async () => (await import('@ai-sdk/google')).createGoogleGenerativeAI(),
+  groq: async () => (await import('@ai-sdk/groq')).createGroq(),
+  mistral: async () => (await import('@ai-sdk/mistral')).createMistral(),
+  openrouter: async () => (await import('@openrouter/ai-sdk-provider')).createOpenRouter(),
+  sambanova: async () => (await import('sambanova-ai-provider')).createSambaNova(),
+};
+
+let cachedOutputRoot: string | null = null;
+
 interface PlaywrightConfig {
   browser: 'chromium' | 'firefox' | 'webkit';
   url: string;
@@ -216,6 +230,7 @@ interface ExplorbotConfig {
   };
   experience?: {
     maxReadLines?: number;
+    disabled?: boolean;
   };
   reporter?: ReporterConfig;
   api?: ApiConfig;
@@ -239,6 +254,19 @@ type RuleEntry = string | Record<string, string>;
 
 export const EXPLORBOT_CONFIG_PATHS = ['explorbot.config.js', 'explorbot.config.mjs', 'explorbot.config.ts'];
 
+export const EXPLORBOT_ENV_VARS: EnvVar[] = [
+  { name: 'EXPLORBOT_AI_PROVIDER', required: true, description: 'Provider name; fills every model role from its recommended models. Turns on config-free mode' },
+  { name: 'EXPLORBOT_AI_MODEL', description: 'Pins the main model — a model id for the provider, or a standalone provider/model-id' },
+  { name: 'EXPLORBOT_URL', required: true, description: 'Base URL to test; the API boat reads it as the base endpoint' },
+  { name: 'EXPLORBOT_VISION_MODEL', description: 'Screenshot analysis; overrides the provider recommendation' },
+  { name: 'EXPLORBOT_AGENTIC_MODEL', description: 'Captain and Pilot decisions; overrides the provider recommendation' },
+  { name: 'EXPLORBOT_OUTPUT', description: 'Output root for states, plans, research, and reports. Defaults to a fresh temp directory' },
+  { name: 'EXPLORBOT_KNOWLEDGE', description: 'Inline knowledge text, applied to every page' },
+  { name: 'EXPLORBOT_KNOWLEDGE_FILE', description: 'Path to a knowledge markdown file' },
+  { name: 'EXPLORBOT_API_SPEC', description: 'OpenAPI spec path for the API boat' },
+  { name: 'EXPLORBOT_NO_BANNER', description: 'Suppress the startup banner, for machine-readable output' },
+];
+
 export type {
   ExplorbotConfig,
   PlaywrightConfig,
@@ -268,6 +296,7 @@ export type {
 
 export class ConfigParser {
   private static instance: ConfigParser;
+  private static recommended: Record<string, Record<string, string>> | null = null;
   private config: ExplorbotConfig | null = null;
   private configPath: string | null = null;
   private runtimeBaseUrlOverride: string | null = null;
@@ -280,6 +309,11 @@ export class ConfigParser {
     Object.assign(process.env, parseEnv(readFileSync(resolved, 'utf8')));
   }
 
+  public static recommendedModels(): Record<string, Record<string, string>> {
+    ConfigParser.recommended ||= JSON.parse(readFileSync(new URL('../models.json', import.meta.url), 'utf8'));
+    return ConfigParser.recommended!;
+  }
+
   public static getInstance(): ConfigParser {
     if (!ConfigParser.instance) {
       ConfigParser.instance = new ConfigParser();
@@ -312,22 +346,31 @@ export class ConfigParser {
     try {
       const resolvedPath = options?.config || this.findConfigFile();
 
-      if (!resolvedPath) {
-        throw new Error('No configuration file found. Please create explorbot.config.js or explorbot.config.ts');
+      let loadedConfig: ExplorbotConfig | null = null;
+      let sourcePath = resolvedPath;
+
+      if (resolvedPath) {
+        const configModule = await this.loadConfigModule(resolvedPath);
+        loadedConfig = configModule.default || configModule;
+
+        if (!loadedConfig) {
+          throw new Error('Configuration file is empty or invalid');
+        }
+
+        log(`Configuration loaded from: ${resolvedPath}`);
       }
 
-      const configModule = await this.loadConfigModule(resolvedPath);
-      const loadedConfig = configModule.default || configModule;
+      if (!resolvedPath) {
+        const outputRoot = resolveOutputRoot();
+        loadedConfig = await this.buildEnvConfig(options?.baseUrl, outputRoot);
+        sourcePath = join(outputRoot, 'explorbot.config.js');
 
-      if (!loadedConfig) {
-        throw new Error('Configuration file is empty or invalid');
+        log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
       }
 
       this.config = this.resolveConfig(loadedConfig as ExplorbotConfig, options);
       this.runtimeBaseUrlOverride = options?.baseUrl || null;
-      this.configPath = resolvedPath;
-
-      log(`Configuration loaded from: ${resolvedPath}`);
+      this.configPath = sourcePath;
 
       // Restore original directory after successful config load
       if (options?.path && originalCwd !== process.cwd()) {
@@ -388,6 +431,7 @@ export class ConfigParser {
 
   // For testing purposes only
   public static resetForTesting(): void {
+    cachedOutputRoot = null;
     if (ConfigParser.instance) {
       ConfigParser.instance.config = null;
       ConfigParser.instance.configPath = null;
@@ -442,6 +486,52 @@ export class ConfigParser {
     }
   }
 
+  private async buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig> {
+    const provider = process.env.EXPLORBOT_AI_PROVIDER;
+    const modelSpec = process.env.EXPLORBOT_AI_MODEL;
+    if (!provider && !modelSpec) {
+      throw new Error('No configuration file found. Please create explorbot.config.js or set EXPLORBOT_URL and EXPLORBOT_AI_PROVIDER environment variables');
+    }
+    if (modelSpec && !provider && !modelSpec.includes('/')) {
+      throw new Error('EXPLORBOT_AI_MODEL needs a provider — set EXPLORBOT_AI_PROVIDER, or write it as "provider/model-id"');
+    }
+
+    const url = process.env.EXPLORBOT_URL || baseUrl;
+    if (!url) {
+      throw new Error('No URL to explore. Set EXPLORBOT_URL or pass a URL to the command');
+    }
+
+    materializeKnowledge(outputRoot);
+
+    let model: any;
+    if (provider && modelSpec) model = await createModel(provider, modelSpec);
+    if (provider && !modelSpec) model = await resolveModel(provider, 'model');
+    if (!provider) model = await resolveModel(modelSpec!, 'model');
+
+    const ai: AIConfig = {
+      model,
+      agents: { historian: { enabled: false } },
+    };
+
+    let recommended: Record<string, string> = {};
+    if (provider) recommended = ConfigParser.recommendedModels()[provider] || {};
+
+    const visionSpec = process.env.EXPLORBOT_VISION_MODEL;
+    if (visionSpec) ai.visionModel = await resolveModel(visionSpec, 'visionModel');
+    if (!visionSpec && recommended.visionModel) ai.visionModel = await resolveModel(provider!, 'visionModel');
+
+    const agenticSpec = process.env.EXPLORBOT_AGENTIC_MODEL;
+    if (agenticSpec) ai.agenticModel = await resolveModel(agenticSpec, 'agenticModel');
+    if (!agenticSpec && recommended.agenticModel) ai.agenticModel = await resolveModel(provider!, 'agenticModel');
+
+    return {
+      playwright: { browser: 'chromium', url, show: false },
+      ai,
+      dirs: { knowledge: 'knowledge', experience: 'experience', output: '.' },
+      experience: { disabled: true },
+    };
+  }
+
   private findConfigFile(): string | null {
     const possiblePaths = [...EXPLORBOT_CONFIG_PATHS, 'config/explorbot.config.js', 'config/explorbot.config.mjs', 'config/explorbot.config.ts', 'src/config/explorbot.config.js', 'src/config/explorbot.config.mjs', 'src/config/explorbot.config.ts'];
 
@@ -554,3 +644,75 @@ export class ConfigParser {
 export function outputPath(...segments: string[]): string {
   return path.join(ConfigParser.getInstance().getOutputDir(), ...segments);
 }
+
+export async function resolveModel(spec: string, role: ModelRole = 'model'): Promise<any> {
+  const separator = spec.indexOf('/');
+  if (separator > 0) {
+    return createModel(spec.slice(0, separator), spec.slice(separator + 1));
+  }
+
+  const recommended = ConfigParser.recommendedModels()[spec];
+  if (!recommended) {
+    throw new Error(`No recommended models for "${spec}". Write it as "provider/model-id", or use a provider with recommendations: ${Object.keys(ConfigParser.recommendedModels()).join(', ')}`);
+  }
+
+  const modelId = recommended[role];
+  if (!modelId) {
+    throw new Error(`Provider "${spec}" has no recommended ${role}. Set it explicitly as "provider/model-id".`);
+  }
+
+  return createModel(spec, modelId);
+}
+
+export function resolveOutputRoot(): string {
+  if (cachedOutputRoot) return cachedOutputRoot;
+
+  const configured = process.env.EXPLORBOT_OUTPUT;
+  if (!configured) {
+    cachedOutputRoot = mkdtempSync(join(tmpdir(), 'explorbot-'));
+    return cachedOutputRoot;
+  }
+
+  cachedOutputRoot = resolve(configured);
+  mkdirSync(cachedOutputRoot, { recursive: true });
+  return cachedOutputRoot;
+}
+
+export function materializeKnowledge(outputRoot: string): void {
+  const inline = process.env.EXPLORBOT_KNOWLEDGE;
+  const knowledgeFile = process.env.EXPLORBOT_KNOWLEDGE_FILE;
+  if (!inline && !knowledgeFile) return;
+
+  const knowledgeDir = join(outputRoot, 'knowledge');
+  mkdirSync(knowledgeDir, { recursive: true });
+
+  if (inline) {
+    writeFileSync(join(knowledgeDir, 'global.md'), matter.stringify(inline, { url: '*', endpoint: '*' }));
+  }
+
+  if (!knowledgeFile) return;
+
+  const source = resolve(knowledgeFile);
+  if (!existsSync(source)) {
+    throw new Error(`Knowledge file from EXPLORBOT_KNOWLEDGE_FILE not found: ${source}`);
+  }
+  copyFileSync(source, join(knowledgeDir, basename(source)));
+}
+
+export async function createModel(provider: string, modelId: string): Promise<any> {
+  const factory = PROVIDERS[provider];
+  if (!factory) {
+    throw new Error(`Unknown AI provider "${provider}". Supported providers: ${Object.keys(PROVIDERS).join(', ')}`);
+  }
+  return (await factory())(modelId);
+}
+
+type ModelRole = 'model' | 'visionModel' | 'agenticModel';
+
+interface EnvVar {
+  name: string;
+  description: string;
+  required?: boolean;
+}
+
+export type { ModelRole, EnvVar };

package/src/experience-tracker.ts

@@ -42,7 +42,7 @@ export class ExperienceTracker {
   constructor(knowledgeTracker: KnowledgeTracker, options: { disabled?: boolean } = {}) {
     const configParser = ConfigParser.getInstance();
     const config = configParser.getConfig();
-    this.disabled = options.disabled ?? false;
+    this.disabled = options.disabled ?? config.experience?.disabled ?? false;
     this.knowledgeTracker = knowledgeTracker;
 
     // Resolve experience directory relative to the config file location (project root)