explorbot 0.2.2 → 0.2.4

package/src/config.ts

@@ -1,18 +1,22 @@
 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 { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
+import dedent from 'dedent';
 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(),
+import { type SiteRecord, findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from './global-config.js';
+import { getCliName } from './utils/cli-name.js';
+import { log, tag } from './utils/logger.js';
+
+export const PROVIDERS: Record<string, ProviderInfo> = {
+  openai: { envKey: 'OPENAI_API_KEY', load: async () => (await import('@ai-sdk/openai')).createOpenAI() },
+  anthropic: { envKey: 'ANTHROPIC_API_KEY', load: async () => (await import('@ai-sdk/anthropic')).createAnthropic() },
+  google: { envKey: 'GOOGLE_GENERATIVE_AI_API_KEY', load: async () => (await import('@ai-sdk/google')).createGoogleGenerativeAI() },
+  groq: { envKey: 'GROQ_API_KEY', load: async () => (await import('@ai-sdk/groq')).createGroq() },
+  mistral: { envKey: 'MISTRAL_API_KEY', load: async () => (await import('@ai-sdk/mistral')).createMistral() },
+  openrouter: { envKey: 'OPENROUTER_API_KEY', load: async () => (await import('@openrouter/ai-sdk-provider')).createOpenRouter() },
+  sambanova: { envKey: 'SAMBANOVA_API_KEY', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
 };
 
 let cachedOutputRoot: string | null = null;
@@ -194,6 +198,7 @@ interface HtmlConfig {
 interface ActionConfig {
   delay?: number;
   retries?: number;
+  timeout?: number;
 }
 
 interface ReporterConfig {
@@ -227,6 +232,7 @@ interface ExplorbotConfig {
     knowledge: string;
     experience: string;
     output: string;
+    spec?: string;
   };
   experience?: {
     maxReadLines?: number;
@@ -260,7 +266,8 @@ export const EXPLORBOT_ENV_VARS: EnvVar[] = [
   { 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_OUTPUT', description: 'Output root for states, plans, research, and reports. Defaults to the site dir under ~/.explorbot/sites' },
+  { name: 'EXPLORBOT_EPHEMERAL', description: 'Keep no state between runs — output goes to a fresh temp directory instead of the site dir' },
   { 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' },
@@ -299,14 +306,26 @@ export class 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;
+  private runtimeTarget: string | null = null;
+  private site: SiteRecord | null = null;
+  private siteStartPath = '/';
 
   private constructor() {}
 
-  public static loadEnv(filePath: string): void {
+  public static loadEnv(filePath: string, keepExisting = false): void {
     const resolved = resolve(filePath);
     if (!existsSync(resolved)) return;
-    Object.assign(process.env, parseEnv(readFileSync(resolved, 'utf8')));
+
+    const parsed = parseEnv(readFileSync(resolved, 'utf8'));
+    if (!keepExisting) {
+      Object.assign(process.env, parsed);
+      return;
+    }
+
+    for (const [key, value] of Object.entries(parsed)) {
+      if (key in process.env) continue;
+      process.env[key] = value as string;
+    }
   }
 
   public static recommendedModels(): Record<string, Record<string, string>> {
@@ -325,8 +344,10 @@ export class ConfigParser {
     config?: string;
     path?: string;
     baseUrl?: string;
+    from?: string;
   }): Promise<ExplorbotConfig> {
-    if (this.config && !options?.config && !options?.path && this.runtimeBaseUrlOverride === (options?.baseUrl || null)) {
+    const target = options?.baseUrl || options?.from || null;
+    if (this.config && !options?.config && !options?.path && this.runtimeTarget === target) {
       return this.config;
     }
 
@@ -342,6 +363,7 @@ export class ConfigParser {
     }
 
     ConfigParser.loadEnv('.env');
+    ConfigParser.loadEnv(globalEnvPath(), true);
 
     try {
       const resolvedPath = options?.config || this.findConfigFile();
@@ -361,16 +383,25 @@ export class ConfigParser {
       }
 
       if (!resolvedPath) {
-        const outputRoot = resolveOutputRoot();
-        loadedConfig = await this.buildEnvConfig(options?.baseUrl, outputRoot);
+        let envUrl = options?.baseUrl;
+        if (!envUrl && target?.startsWith('http')) envUrl = target;
+
+        const outputRoot = resolveOutputRoot(process.env.EXPLORBOT_URL || envUrl);
+        loadedConfig = await this.buildEnvConfig(envUrl, outputRoot);
         sourcePath = join(outputRoot, 'explorbot.config.js');
 
         log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
       }
 
       this.config = this.resolveConfig(loadedConfig as ExplorbotConfig, options);
-      this.runtimeBaseUrlOverride = options?.baseUrl || null;
+      await resolveConfigModels(this.config.ai);
+      this.runtimeTarget = target;
       this.configPath = sourcePath;
+      this.site = null;
+
+      if (resolvedPath && isGlobalConfigPath(resolvedPath)) {
+        this.enterGlobalMode(this.config, target);
+      }
 
       // Restore original directory after successful config load
       if (options?.path && originalCwd !== process.cwd()) {
@@ -383,6 +414,7 @@ export class ConfigParser {
       if (options?.path && originalCwd !== process.cwd()) {
         process.chdir(originalCwd);
       }
+      if (error instanceof ConfigMissingError) throw error;
       throw new Error(`Failed to load configuration: ${error}`);
     }
   }
@@ -400,21 +432,45 @@ export class ConfigParser {
 
   public getOutputDir(): string {
     const config = this.getConfig();
-    const configPath = this.getConfigPath();
-    if (!configPath) throw new Error('Config path not found');
-    return path.join(path.dirname(configPath), config.dirs?.output || 'output');
+    if (!this.configPath) throw new Error('Config path not found');
+    return path.join(this.getProjectRoot(), config.dirs?.output || 'output');
   }
 
   public getProjectRoot(): string {
+    if (this.site) return this.site.dir;
     const configPath = this.getConfigPath();
     if (configPath) return path.dirname(configPath);
     return process.cwd();
   }
 
   public resolveProjectDir(relativeDir: string): string {
-    const configPath = this.getConfigPath();
-    if (!configPath) return relativeDir;
-    return path.join(path.dirname(configPath), relativeDir);
+    if (!this.configPath) return relativeDir;
+    return path.join(this.getProjectRoot(), relativeDir);
+  }
+
+  public isGlobalMode(): boolean {
+    return !!this.site;
+  }
+
+  public getSite(): SiteRecord | null {
+    return this.site;
+  }
+
+  public resolveTargetPath(target?: string): string {
+    if (!this.site) {
+      const configured = this.config?.playwright?.url || this.config?.web?.url;
+      const targetOrigin = target ? URL.parse(target)?.origin : null;
+      const baseOrigin = configured ? URL.parse(configured)?.origin : null;
+      if (targetOrigin && baseOrigin && targetOrigin !== baseOrigin) {
+        tag('warning').log(`Exploring ${targetOrigin} but base URL is ${baseOrigin}. Relative navigation resolves against the base URL — set web.url to ${targetOrigin} to avoid it.`);
+      }
+      return target || '/';
+    }
+    if (!target) return this.siteStartPath;
+
+    const resolved = resolveSiteTarget(target, this.site.url);
+    if (resolved.baseUrl !== this.site.url) return target;
+    return resolved.path;
   }
 
   public getStatesDir(): string {
@@ -435,7 +491,9 @@ export class ConfigParser {
     if (ConfigParser.instance) {
       ConfigParser.instance.config = null;
       ConfigParser.instance.configPath = null;
-      ConfigParser.instance.runtimeBaseUrlOverride = null;
+      ConfigParser.instance.runtimeTarget = null;
+      ConfigParser.instance.site = null;
+      ConfigParser.instance.siteStartPath = '/';
     }
   }
 
@@ -486,11 +544,22 @@ export class ConfigParser {
     }
   }
 
+  private enterGlobalMode(config: ExplorbotConfig, target: string | null): void {
+    const site = resolveSiteTarget(target || undefined, config.web?.url || config.playwright?.url);
+    this.site = registerSite(site.baseUrl);
+    this.siteStartPath = site.path;
+
+    config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
+    config.playwright = { ...config.playwright, browser: config.playwright?.browser || 'chromium', url: site.baseUrl };
+
+    log(`Global mode: ${site.baseUrl} stored in ${this.site.dir}`);
+  }
+
   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');
+      throw new ConfigMissingError(missingConfigMessage());
     }
     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"');
@@ -524,11 +593,14 @@ export class ConfigParser {
     if (agenticSpec) ai.agenticModel = await resolveModel(agenticSpec, 'agenticModel');
     if (!agenticSpec && recommended.agenticModel) ai.agenticModel = await resolveModel(provider!, 'agenticModel');
 
+    const dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
+    if (process.env.EXPLORBOT_OUTPUT) dirs.output = '.';
+
     return {
       playwright: { browser: 'chromium', url, show: false },
       ai,
-      dirs: { knowledge: 'knowledge', experience: 'experience', output: '.' },
-      experience: { disabled: true },
+      dirs,
+      experience: { disabled: !!process.env.EXPLORBOT_EPHEMERAL },
     };
   }
 
@@ -542,22 +614,24 @@ export class ConfigParser {
       }
     }
 
-    return null;
+    if (envConfigRequested()) return null;
+    return findGlobalConfig();
   }
 
   private async loadConfigModule(configPath: string): Promise<any> {
     const ext = configPath.split('.').pop();
+    const moduleUrl = pathToFileURL(resolve(configPath)).href;
 
     if (ext === 'ts') {
       try {
-        const module = await import(configPath);
+        const module = await import(moduleUrl);
         return module;
       } catch (error) {
         const require = (await import('node:module')).createRequire(import.meta.url);
         return require(configPath);
       }
     } else if (ext === 'js' || ext === 'mjs') {
-      const module = await import(configPath);
+      const module = await import(moduleUrl);
       return module;
     } else {
       const content = readFileSync(configPath, 'utf8');
@@ -664,30 +738,84 @@ export async function resolveModel(spec: string, role: ModelRole = 'model'): Pro
   return createModel(spec, modelId);
 }
 
-export function resolveOutputRoot(): string {
+export class ConfigMissingError extends Error {}
+
+export function envConfigRequested(): boolean {
+  return !!(process.env.EXPLORBOT_AI_PROVIDER || process.env.EXPLORBOT_AI_MODEL);
+}
+
+export function missingConfigMessage(configFile = 'explorbot.config.js'): string {
+  const cli = getCliName();
+  return dedent`
+    No AI configuration found. Set up explorbot in one of these ways:
+
+      Global - configure this machine once, then run from any directory:
+        ${cli} init --global
+
+      Local - create ${configFile} for this project:
+        ${cli} init
+
+      Environment - one-off run, no files written:
+        EXPLORBOT_AI_PROVIDER=openrouter EXPLORBOT_URL=https://your-app.example.com ${cli} ...
+
+    Providers: ${Object.keys(PROVIDERS).join(', ')}
+  `;
+}
+
+export async function resolveConfigModels(ai?: AIConfig): Promise<void> {
+  if (!ai) return;
+
+  const roles: ModelRole[] = ['model', 'visionModel', 'agenticModel'];
+  for (const role of roles) {
+    if (typeof ai[role] === 'string') ai[role] = await resolveModel(ai[role], role);
+  }
+
+  for (const agent of Object.values(ai.agents || {})) {
+    if (typeof agent?.model === 'string') agent.model = await resolveModel(agent.model);
+  }
+}
+
+export function resolveOutputRoot(baseUrl?: string): string {
   if (cachedOutputRoot) return cachedOutputRoot;
 
   const configured = process.env.EXPLORBOT_OUTPUT;
-  if (!configured) {
-    cachedOutputRoot = mkdtempSync(join(tmpdir(), 'explorbot-'));
+  if (configured) {
+    cachedOutputRoot = resolve(configured);
+    mkdirSync(cachedOutputRoot, { recursive: true });
+    return cachedOutputRoot;
+  }
+
+  if (baseUrl) {
+    cachedOutputRoot = resolveStateRoot(baseUrl, !!process.env.EXPLORBOT_EPHEMERAL);
     return cachedOutputRoot;
   }
 
-  cachedOutputRoot = resolve(configured);
-  mkdirSync(cachedOutputRoot, { recursive: true });
+  cachedOutputRoot = mkdtempSync(join(tmpdir(), 'explorbot-'));
   return cachedOutputRoot;
 }
 
+export function resolveStateRoot(baseUrl: string, ephemeral?: boolean): string {
+  const url = URL.parse(baseUrl);
+  if (ephemeral || !url?.host) return mkdtempSync(join(tmpdir(), 'explorbot-'));
+
+  return registerSite(url.origin).dir;
+}
+
 export function materializeKnowledge(outputRoot: string): void {
   const inline = process.env.EXPLORBOT_KNOWLEDGE;
   const knowledgeFile = process.env.EXPLORBOT_KNOWLEDGE_FILE;
+  const knowledgeDir = join(outputRoot, 'knowledge');
+  const globalFile = join(knowledgeDir, 'global.md');
+  const envDir = join(knowledgeDir, 'env');
+
+  if (!inline) rmSync(globalFile, { force: true });
+  rmSync(envDir, { recursive: true, force: true });
   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: '*' }));
+    writeFileSync(globalFile, matter.stringify(inline, { url: '*', endpoint: '*' }));
   }
 
   if (!knowledgeFile) return;
@@ -696,23 +824,29 @@ export function materializeKnowledge(outputRoot: string): void {
   if (!existsSync(source)) {
     throw new Error(`Knowledge file from EXPLORBOT_KNOWLEDGE_FILE not found: ${source}`);
   }
-  copyFileSync(source, join(knowledgeDir, basename(source)));
+  mkdirSync(envDir, { recursive: true });
+  copyFileSync(source, join(envDir, basename(source)));
 }
 
 export async function createModel(provider: string, modelId: string): Promise<any> {
-  const factory = PROVIDERS[provider];
-  if (!factory) {
+  const info = PROVIDERS[provider];
+  if (!info) {
     throw new Error(`Unknown AI provider "${provider}". Supported providers: ${Object.keys(PROVIDERS).join(', ')}`);
   }
-  return (await factory())(modelId);
+  return (await info.load())(modelId);
 }
 
 type ModelRole = 'model' | 'visionModel' | 'agenticModel';
 
+interface ProviderInfo {
+  envKey: string;
+  load: () => Promise<(modelId: string) => any>;
+}
+
 interface EnvVar {
   name: string;
   description: string;
   required?: boolean;
 }
 
-export type { ModelRole, EnvVar };
+export type { ModelRole, EnvVar, ProviderInfo };

package/src/execution-controller.ts

@@ -27,6 +27,14 @@ export class ExecutionController extends EventEmitter {
     this.inputCallback = callback;
   }
 
+  hasInputCallback(): boolean {
+    return !!this.inputCallback;
+  }
+
+  clearInputCallback(): void {
+    this.inputCallback = null;
+  }
+
   startExecution(): void {
     this.interrupted = false;
     this.abortController = new AbortController();

package/src/explorbot.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import type { Browser } from 'playwright';
 import type { AgentDeps } from './ai/agent.ts';
 import { Captain } from './ai/captain.ts';
 import { Driller } from './ai/driller.ts';
@@ -19,7 +20,7 @@ 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 type { ExplorbotConfig } from './config.js';
+import type { ExplorbotConfig, ReporterConfig } from './config.js';
 import { ConfigParser } from './config.ts';
 import { ExperienceTracker } from './experience-tracker.ts';
 import Explorer from './explorer.ts';
@@ -46,6 +47,11 @@ export interface ExplorBotOptions {
   headless?: boolean;
   incognito?: boolean;
   session?: string | boolean;
+  instance?: string;
+  optionalAi?: boolean;
+  reporter?: ReporterConfig;
+  attachedBrowser?: Browser;
+  applicationSpec?: string;
 }
 
 export type UserResolveFunction = (error?: Error, showWelcome?: boolean) => Promise<string | null>;
@@ -61,6 +67,7 @@ export class ExplorBot {
   private planFeature?: string;
   lastPlanError: Error | null = null;
   lastSavedPlanPath: string | null = null;
+  private aiFailure: string | null = null;
   private agents: Record<string, any> = {};
   private sessionPlans: Plan[] = [];
   private lastReportedTestCount = 0;
@@ -88,6 +95,10 @@ export class ExplorBot {
     this.userResolveFn = fn;
   }
 
+  attachBrowser(browser: Browser): void {
+    this.options.attachedBrowser = browser;
+  }
+
   async start(): Promise<void> {
     if (this.explorer) {
       return;
@@ -104,7 +115,7 @@ export class ExplorBot {
         playwrightRecorder: this.playwrightRecorder(),
       });
       await this.explorer.start();
-      if (!this.options.incognito) {
+      if (!this.options.incognito && this.provider) {
         await this.agentExperienceCompactor().autocompact();
       }
     } catch (error) {
@@ -118,22 +129,27 @@ export class ExplorBot {
     if (this.provider) return;
     this.config = await this.configParser.loadConfig(this.options);
     if (this.options.session === true) this.options.session = path.join(this.configParser.getOutputDir(), 'session.json');
+    if (typeof this.options.session === 'string') this.options.session = path.resolve(this.options.path || '.', this.options.session);
+    if (this.options.optionalAi) return this.bootstrapOptionalProvider();
     this.provider = new AIProvider(this.config.ai);
     await this.provider.validateConnection();
   }
 
+  aiFailureReason(): string | null {
+    return this.aiFailure;
+  }
+
   async stop(): Promise<void> {
     this.agents.quartermaster?.stop();
     await this.explorer?.stop();
   }
 
   async visitInitialState(): Promise<void> {
-    const url = this.options.from || '/';
-    await this.visit(url);
+    await this.visit(this.options.from || '/');
   }
 
   async visit(url: string): Promise<void> {
-    return this.agentNavigator().visit(url);
+    return this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
   }
 
   async openTab(): Promise<void> {
@@ -149,7 +165,7 @@ export class ExplorBot {
   }
 
   knowledgeTracker(): KnowledgeTracker {
-    return (this._knowledgeTracker ||= new KnowledgeTracker());
+    return (this._knowledgeTracker ||= new KnowledgeTracker(this.options.applicationSpec));
   }
 
   experienceTracker(): ExperienceTracker {
@@ -161,7 +177,7 @@ export class ExplorBot {
   }
 
   reporter(): Reporter {
-    return (this._reporter ||= new Reporter(this.config.reporter, this.stateManager()));
+    return (this._reporter ||= new Reporter(this.options.reporter || this.config.reporter, this.stateManager()));
   }
 
   requestStore(): RequestStore {
@@ -518,4 +534,15 @@ export class ExplorBot {
   private isHistorianEnabled(): boolean {
     return this.config.ai?.agents?.historian?.enabled !== false;
   }
+
+  private async bootstrapOptionalProvider(): Promise<void> {
+    try {
+      const provider = new AIProvider(this.config.ai);
+      await provider.validateConnection();
+      this.provider = provider;
+    } catch (error) {
+      this.aiFailure = browserErrorMessage(error);
+      tag('debug').log(`AI provider unavailable: ${this.aiFailure}`);
+    }
+  }
 }

package/src/explorer.ts

@@ -6,7 +6,7 @@ import stepsListener from 'codeceptjs/lib/listener/steps';
 import storeListener from 'codeceptjs/lib/listener/store';
 import { createTest } from 'codeceptjs/lib/mocha/test';
 import dedent from 'dedent';
-import type { BrowserContextOptions, Page } from 'playwright';
+import type { Browser, BrowserContextOptions, Page } from 'playwright';
 import { ActionResult } from './action-result.ts';
 import Action from './action.js';
 import type { RequestStore } from './api/request-store.ts';
@@ -103,8 +103,8 @@ class Explorer {
       throw new Error('Playwright helper not available');
     }
     await this.connectOrLaunchBrowser();
-    const hasSession = this.options?.session && existsSync(this.options.session);
-    await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+    const hasSession = !this.options?.attachedBrowser && this.options?.session && existsSync(this.options.session);
+    await this.openContextPage();
     await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
     this.attachXhrCapture();
     if (hasSession) {
@@ -123,10 +123,11 @@ class Explorer {
   async stop(): Promise<void> {
     if (!this.started) return;
     this.started = false;
+    const attached = !!this.options?.attachedBrowser;
 
     await this.stopCaptures();
 
-    if (this.options?.session && this.playwrightHelper?.browserContext) {
+    if (!attached && this.options?.session && this.playwrightHelper?.browserContext) {
       const dir = path.dirname(this.options.session);
       if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
       await this.playwrightHelper.browserContext.storageState({ path: this.options.session });
@@ -141,7 +142,14 @@ class Explorer {
       return;
     }
 
-    tag('info').log('Closing browser context (persistent browser stays running)');
+    if (attached) {
+      tag('info').log('Disconnecting from attached browser (its pages stay open)');
+      await this.playwrightHelper.browser?.close().catch((err: unknown) => {
+        debugLog('Failed to disconnect from attached browser:', err);
+      });
+    }
+
+    if (!attached) tag('info').log('Closing browser context (persistent browser stays running)');
     await this.closeBrowserContext();
     this.playwrightHelper.browser = null;
     this.playwrightHelper.isRunning = false;
@@ -309,8 +317,16 @@ class Explorer {
   }
 
   private async connectOrLaunchBrowser(): Promise<void> {
+    if (this.options?.attachedBrowser) {
+      this.playwrightHelper.browser = this.options.attachedBrowser;
+      this.playwrightHelper.isRunning = true;
+      this.isSharedBrowser = true;
+      tag('success').log('Attached to a browser opened by another tool');
+      return;
+    }
+
     const { getAliveEndpoint } = await import('./browser-server.js');
-    const endpoint = await getAliveEndpoint();
+    const endpoint = await getAliveEndpoint(this.options?.instance);
 
     if (endpoint) {
       const browserName = this.config.playwright.browser || 'chromium';
@@ -326,6 +342,21 @@ class Explorer {
     await this.playwrightHelper._startBrowser();
   }
 
+  private async openContextPage(): Promise<void> {
+    const attached = this.options?.attachedBrowser;
+    if (!attached) {
+      await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+      return;
+    }
+
+    const context = attached.contexts()[0] || (await attached.newContext());
+    const pages = context.pages();
+    const page = pages[pages.length - 1] || (await context.newPage());
+    this.playwrightHelper.browserContext = context;
+    await this.playwrightHelper._setPage(page);
+    debugLog(`Adopted attached browser page: ${page.url()}`);
+  }
+
   private createBrowserContextOptions(): BrowserContextOptions {
     const helperOptions = this.playwrightHelper.options || {};
     const contextOptions: BrowserContextOptions = {
@@ -506,6 +537,10 @@ class Explorer {
   }
 
   private async closeBrowserContext(): Promise<void> {
+    if (this.options?.attachedBrowser) {
+      this.playwrightHelper.browserContext = null;
+      return;
+    }
     if (!this.playwrightHelper.browserContext) return;
     await this.playwrightHelper.browserContext.close().catch((err: unknown) => {
       debugLog('Failed to close browser context:', err);
@@ -529,7 +564,7 @@ class Explorer {
       }
 
       await this.connectOrLaunchBrowser();
-      await this.playwrightHelper._createContextPage(this.createBrowserContextOptions());
+      await this.openContextPage();
       await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
       this.attachXhrCapture();
       this.listenToStateChanged();
@@ -631,6 +666,7 @@ class Explorer {
 
   private async closeOtherTabs(): Promise<void> {
     if (!this.playwrightHelper) return;
+    if (this.options?.attachedBrowser) return;
 
     const context = this.playwrightHelper.page.context();
     const pages = context.pages();
@@ -685,11 +721,11 @@ class Explorer {
     if (this.observedTestPages.has(page)) return;
 
     this.testPageErrorHandler ||= (err: Error) => {
-      this._activeTest?.addNote(`Console error: ${err.message}`, TestResult.FAILED);
+      this._activeTest?.addObservation(`Console error: ${err.message}`);
     };
     this.testConsoleHandler ||= (msg: any) => {
       if (msg.type() !== 'error') return;
-      this._activeTest?.addNote(`Console error: ${msg.text()}`, TestResult.FAILED);
+      this._activeTest?.addObservation(`Console error: ${msg.text()}`);
     };
     this.testDialogHandler ||= (dialog: any) => {
       const dialogType = dialog.type();
@@ -733,6 +769,8 @@ export interface ExplorerOptions {
   headless?: boolean;
   incognito?: boolean;
   session?: string;
+  instance?: string;
+  attachedBrowser?: Browser;
 }
 
 export interface ExplorerDeps {