explorbot 0.2.2 → 0.2.4

package/dist/src/config.js

@@ -9,17 +9,21 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 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';
+import { 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 = {
-    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(),
+    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 = null;
 const config = {
@@ -38,7 +42,8 @@ export const EXPLORBOT_ENV_VARS = [
     { 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' },
@@ -49,13 +54,24 @@ export class ConfigParser {
     static recommended = null;
     config = null;
     configPath = null;
-    runtimeBaseUrlOverride = null;
+    runtimeTarget = null;
+    site = null;
+    siteStartPath = '/';
     constructor() { }
-    static loadEnv(filePath) {
+    static loadEnv(filePath, keepExisting = false) {
         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;
+        }
     }
     static recommendedModels() {
         ConfigParser.recommended ||= JSON.parse(readFileSync(new URL('../models.json', import.meta.url), 'utf8'));
@@ -68,7 +84,8 @@ export class ConfigParser {
         return ConfigParser.instance;
     }
     async loadConfig(options) {
-        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;
         }
         // Store the initial working directory for reference
@@ -81,6 +98,7 @@ export class ConfigParser {
             process.chdir(resolvedWorkingPath);
         }
         ConfigParser.loadEnv('.env');
+        ConfigParser.loadEnv(globalEnvPath(), true);
         try {
             const resolvedPath = options?.config || this.findConfigFile();
             let loadedConfig = null;
@@ -94,14 +112,22 @@ export class ConfigParser {
                 log(`Configuration loaded from: ${resolvedPath}`);
             }
             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, 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()) {
                 process.chdir(originalCwd);
@@ -113,6 +139,8 @@ 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}`);
         }
     }
@@ -127,22 +155,45 @@ export class ConfigParser {
     }
     getOutputDir() {
         const config = this.getConfig();
-        const configPath = this.getConfigPath();
-        if (!configPath)
+        if (!this.configPath)
             throw new Error('Config path not found');
-        return path.join(path.dirname(configPath), config.dirs?.output || 'output');
+        return path.join(this.getProjectRoot(), config.dirs?.output || 'output');
     }
     getProjectRoot() {
+        if (this.site)
+            return this.site.dir;
         const configPath = this.getConfigPath();
         if (configPath)
             return path.dirname(configPath);
         return process.cwd();
     }
     resolveProjectDir(relativeDir) {
-        const configPath = this.getConfigPath();
-        if (!configPath)
+        if (!this.configPath)
             return relativeDir;
-        return path.join(path.dirname(configPath), relativeDir);
+        return path.join(this.getProjectRoot(), relativeDir);
+    }
+    isGlobalMode() {
+        return !!this.site;
+    }
+    getSite() {
+        return this.site;
+    }
+    resolveTargetPath(target) {
+        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;
     }
     getStatesDir() {
         return outputPath('states');
@@ -159,7 +210,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 = '/';
         }
     }
     // For testing purposes only - sets up minimal default config
@@ -206,11 +259,19 @@ export class ConfigParser {
             // Ignore cleanup errors
         }
     }
+    enterGlobalMode(config, target) {
+        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}`);
+    }
     async buildEnvConfig(baseUrl, outputRoot) {
         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"');
@@ -244,11 +305,14 @@ export class ConfigParser {
             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 },
         };
     }
     findConfigFile() {
@@ -259,13 +323,16 @@ export class ConfigParser {
                 return fullPath;
             }
         }
-        return null;
+        if (envConfigRequested())
+            return null;
+        return findGlobalConfig();
     }
     async loadConfigModule(configPath) {
         const ext = configPath.split('.').pop();
+        const moduleUrl = pathToFileURL(resolve(configPath)).href;
         if (ext === 'ts') {
             try {
-                const module = await import(__rewriteRelativeImportExtension(configPath));
+                const module = await import(__rewriteRelativeImportExtension(moduleUrl));
                 return module;
             }
             catch (error) {
@@ -274,7 +341,7 @@ export class ConfigParser {
             }
         }
         else if (ext === 'js' || ext === 'mjs') {
-            const module = await import(__rewriteRelativeImportExtension(configPath));
+            const module = await import(__rewriteRelativeImportExtension(moduleUrl));
             return module;
         }
         else {
@@ -365,27 +432,77 @@ export async function resolveModel(spec, role = 'model') {
     }
     return createModel(spec, modelId);
 }
-export function resolveOutputRoot() {
+export class ConfigMissingError extends Error {
+}
+export function envConfigRequested() {
+    return !!(process.env.EXPLORBOT_AI_PROVIDER || process.env.EXPLORBOT_AI_MODEL);
+}
+export function missingConfigMessage(configFile = 'explorbot.config.js') {
+    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) {
+    if (!ai)
+        return;
+    const roles = ['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) {
     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, ephemeral) {
+    const url = URL.parse(baseUrl);
+    if (ephemeral || !url?.host)
+        return mkdtempSync(join(tmpdir(), 'explorbot-'));
+    return registerSite(url.origin).dir;
+}
 export function materializeKnowledge(outputRoot) {
     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;
@@ -393,12 +510,13 @@ export function materializeKnowledge(outputRoot) {
     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, modelId) {
-    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);
 }

package/dist/src/execution-controller.d.ts

@@ -10,6 +10,8 @@ export declare class ExecutionController extends EventEmitter {
     constructor();
     static getInstance(): ExecutionController;
     setInputCallback(callback: InputCallback): void;
+    hasInputCallback(): boolean;
+    clearInputCallback(): void;
     startExecution(): void;
     getAbortSignal(): AbortSignal | undefined;
     interrupt(): void;

package/dist/src/execution-controller.js

@@ -20,6 +20,12 @@ export class ExecutionController extends EventEmitter {
     setInputCallback(callback) {
         this.inputCallback = callback;
     }
+    hasInputCallback() {
+        return !!this.inputCallback;
+    }
+    clearInputCallback() {
+        this.inputCallback = null;
+    }
     startExecution() {
         this.interrupted = false;
         this.abortController = new AbortController();

package/dist/src/explorbot.d.ts

@@ -1,3 +1,4 @@
+import type { Browser } from 'playwright';
 import type { AgentDeps } from './ai/agent.js';
 import { Captain } from './ai/captain.js';
 import { Driller } from './ai/driller.js';
@@ -14,7 +15,7 @@ import { Researcher } from './ai/researcher.js';
 import { SessionAnalyst } from './ai/session-analyst.js';
 import { Tester } from './ai/tester.js';
 import { RequestStore } from './api/request-store.js';
-import type { ExplorbotConfig } from './config.js';
+import type { ExplorbotConfig, ReporterConfig } from './config.js';
 import { ConfigParser } from './config.js';
 import { ExperienceTracker } from './experience-tracker.js';
 import Explorer from './explorer.js';
@@ -34,6 +35,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>;
 export declare class ExplorBot {
@@ -47,6 +53,7 @@ export declare class ExplorBot {
     planFeature?: string;
     lastPlanError: Error | null;
     lastSavedPlanPath: string | null;
+    aiFailure: string | null;
     agents: Record<string, any>;
     sessionPlans: Plan[];
     lastReportedTestCount: number;
@@ -59,8 +66,10 @@ export declare class ExplorBot {
     constructor(options?: ExplorBotOptions);
     get isExploring(): boolean;
     setUserResolve(fn: UserResolveFunction): void;
+    attachBrowser(browser: Browser): void;
     start(): Promise<void>;
     startProviderOnly(): Promise<void>;
+    aiFailureReason(): string | null;
     stop(): Promise<void>;
     visitInitialState(): Promise<void>;
     visit(url: string): Promise<void>;
@@ -112,4 +121,5 @@ export declare class ExplorBot {
     getSessionTests(): Test[];
     printSessionAnalysis(): Promise<void>;
     isHistorianEnabled(): boolean;
+    bootstrapOptionalProvider(): Promise<void>;
 }

package/dist/src/explorbot.js

@@ -43,6 +43,7 @@ export class ExplorBot {
     planFeature;
     lastPlanError = null;
     lastSavedPlanPath = null;
+    aiFailure = null;
     agents = {};
     sessionPlans = [];
     lastReportedTestCount = 0;
@@ -66,6 +67,9 @@ export class ExplorBot {
     setUserResolve(fn) {
         this.userResolveFn = fn;
     }
+    attachBrowser(browser) {
+        this.options.attachedBrowser = browser;
+    }
     async start() {
         if (this.explorer) {
             return;
@@ -81,7 +85,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();
             }
         }
@@ -97,19 +101,25 @@ export class ExplorBot {
         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() {
+        return this.aiFailure;
+    }
     async stop() {
         this.agents.quartermaster?.stop();
         await this.explorer?.stop();
     }
     async visitInitialState() {
-        const url = this.options.from || '/';
-        await this.visit(url);
+        await this.visit(this.options.from || '/');
     }
     async visit(url) {
-        return this.agentNavigator().visit(url);
+        return this.agentNavigator().visit(this.configParser.resolveTargetPath(url));
     }
     async openTab() {
         await this.explorer.openTab();
@@ -121,7 +131,7 @@ export class ExplorBot {
         return this.explorer;
     }
     knowledgeTracker() {
-        return (this._knowledgeTracker ||= new KnowledgeTracker());
+        return (this._knowledgeTracker ||= new KnowledgeTracker(this.options.applicationSpec));
     }
     experienceTracker() {
         return (this._experienceTracker ||= new ExperienceTracker(this.knowledgeTracker()));
@@ -130,7 +140,7 @@ export class ExplorBot {
         return (this._stateManager ||= new StateManager(this.experienceTracker(), this.knowledgeTracker()));
     }
     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() {
         return (this._requestStore ||= new RequestStore(this.configParser.getOutputDir()));
@@ -451,4 +461,15 @@ export class ExplorBot {
     isHistorianEnabled() {
         return this.config.ai?.agents?.historian?.enabled !== false;
     }
+    async bootstrapOptionalProvider() {
+        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/dist/src/explorer.d.ts

@@ -1,4 +1,4 @@
-import type { BrowserContextOptions, Page } from 'playwright';
+import type { Browser, BrowserContextOptions, Page } from 'playwright';
 import { ActionResult } from './action-result.js';
 import Action from './action.js';
 import type { RequestStore } from './api/request-store.js';
@@ -56,6 +56,7 @@ declare class Explorer {
     initializeContainer(): void;
     convertToCodeceptConfig(config: ExplorbotConfig): any;
     connectOrLaunchBrowser(): Promise<void>;
+    openContextPage(): Promise<void>;
     createBrowserContextOptions(): BrowserContextOptions;
     attachXhrCapture(): void;
     runWithRecovery<T>(label: string, operation: () => Promise<T>): Promise<T>;
@@ -81,6 +82,8 @@ export interface ExplorerOptions {
     headless?: boolean;
     incognito?: boolean;
     session?: string;
+    instance?: string;
+    attachedBrowser?: Browser;
 }
 export interface ExplorerDeps {
     stateManager: StateManager;

package/dist/src/explorer.js

@@ -10,7 +10,6 @@ import { ActionResult } from "./action-result.js";
 import Action from './action.js';
 import { XhrCapture } from "./api/xhr-capture.js";
 import { ConfigParser } from './config.js';
-import { TestResult } from "./test-plan.js";
 import { BrowserRecoveryError, browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from "./utils/browser-errors.js";
 import { createDebug, log, tag } from './utils/logger.js';
 import { sleep, waitForPageReadiness } from "./utils/page-readiness.js";
@@ -74,8 +73,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) {
@@ -91,8 +90,9 @@ class Explorer {
         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 });
@@ -105,7 +105,14 @@ class Explorer {
             await Promise.all([this.reporter.finishRun(), this.playwrightHelper._stopBrowser(), codeceptjs.recorder.stop()]);
             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) => {
+                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;
@@ -247,8 +254,15 @@ class Explorer {
         return codeceptConfig;
     }
     async connectOrLaunchBrowser() {
+        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';
             this.playwrightHelper.options[browserName] ||= {};
@@ -261,6 +275,19 @@ class Explorer {
         }
         await this.playwrightHelper._startBrowser();
     }
+    async openContextPage() {
+        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()}`);
+    }
     createBrowserContextOptions() {
         const helperOptions = this.playwrightHelper.options || {};
         const contextOptions = {
@@ -427,6 +454,10 @@ class Explorer {
         await this.playwrightRecorder.stop();
     }
     async closeBrowserContext() {
+        if (this.options?.attachedBrowser) {
+            this.playwrightHelper.browserContext = null;
+            return;
+        }
         if (!this.playwrightHelper.browserContext)
             return;
         await this.playwrightHelper.browserContext.close().catch((err) => {
@@ -447,7 +478,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();
@@ -542,6 +573,8 @@ class Explorer {
     async closeOtherTabs() {
         if (!this.playwrightHelper)
             return;
+        if (this.options?.attachedBrowser)
+            return;
         const context = this.playwrightHelper.page.context();
         const pages = context.pages();
         if (pages.length <= 1)
@@ -590,12 +623,12 @@ class Explorer {
         if (this.observedTestPages.has(page))
             return;
         this.testPageErrorHandler ||= (err) => {
-            this._activeTest?.addNote(`Console error: ${err.message}`, TestResult.FAILED);
+            this._activeTest?.addObservation(`Console error: ${err.message}`);
         };
         this.testConsoleHandler ||= (msg) => {
             if (msg.type() !== 'error')
                 return;
-            this._activeTest?.addNote(`Console error: ${msg.text()}`, TestResult.FAILED);
+            this._activeTest?.addObservation(`Console error: ${msg.text()}`);
         };
         this.testDialogHandler ||= (dialog) => {
             const dialogType = dialog.type();