explorbot 0.2.2 → 0.2.3

package/dist/boat/prima/src/pw-registry.js

@@ -0,0 +1,66 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const DEFAULT_TITLE = 'default';
+const DEFAULT_BROWSER = 'chromium';
+export function registryDir() {
+    if (process.platform === 'darwin')
+        return path.join(os.homedir(), 'Library', 'Caches', 'ms-playwright', 'b');
+    if (process.platform === 'win32')
+        return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'ms-playwright', 'b');
+    return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'ms-playwright', 'b');
+}
+export function readDescriptors(dir = registryDir()) {
+    const descriptors = [];
+    for (const fileName of listFiles(dir)) {
+        const descriptor = parseDescriptor(path.join(dir, fileName));
+        if (descriptor)
+            descriptors.push(descriptor);
+    }
+    return descriptors;
+}
+export function selectDescriptor(descriptors, opts) {
+    const workspaceDir = path.resolve(opts.workspaceDir);
+    const candidates = descriptors.filter((descriptor) => path.resolve(descriptor.workspaceDir) === workspaceDir);
+    if (!candidates.length)
+        return { candidates };
+    if (opts.title) {
+        const titled = candidates.find((descriptor) => descriptor.title === opts.title);
+        if (titled)
+            return { match: titled, candidates };
+        return { candidates };
+    }
+    const preferred = candidates.find((descriptor) => descriptor.title === DEFAULT_TITLE);
+    if (preferred)
+        return { match: preferred, candidates };
+    if (candidates.length === 1)
+        return { match: candidates[0], candidates };
+    return { candidates };
+}
+function listFiles(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function parseDescriptor(file) {
+    let data;
+    try {
+        data = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!data?.endpoint || !data?.title || !data?.workspaceDir)
+        return null;
+    return {
+        file,
+        title: data.title,
+        endpoint: data.endpoint,
+        workspaceDir: data.workspaceDir,
+        browserName: data.browser?.browserName || DEFAULT_BROWSER,
+        playwrightLib: data.playwrightLib || '',
+    };
+}

package/dist/models.json

@@ -4,6 +4,9 @@
     "visionModel": "google/gemma-4-31b-it:nitro",
     "agenticModel": "google/gemma-4-31b-it:nitro"
   },
+  "poolside": {
+    "model": "poolside/laguna-xs-2.1"
+  },
   "groq": {
     "model": "openai/gpt-oss-20b",
     "visionModel": "qwen/qwen3.6-27b",

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -14,7 +14,8 @@
     }
   },
   "bin": {
-    "explorbot": "./dist/bin/explorbot-cli.js"
+    "explorbot": "./dist/bin/explorbot-cli.js",
+    "prima": "./dist/boat/prima/bin/prima-cli.js"
   },
   "files": [
     "dist/",
@@ -25,6 +26,9 @@
     "boat/doc-collector/src/**/*.ts",
     "boat/doc-collector/bin/**/*.ts",
     "boat/doc-collector/package.json",
+    "boat/prima/src/**/*.ts",
+    "boat/prima/bin/**/*.ts",
+    "boat/prima/package.json",
     "rules/",
     "assets/sample-files/",
     "models.json"

package/dist/src/action.d.ts

@@ -24,7 +24,7 @@ declare class Action {
         includeScreenshot?: boolean;
         codeBlock?: string;
     }): Promise<ActionResult>;
-    execute(code: string): Promise<Action>;
+    execute(code: string, opts?: ExecuteOptions): Promise<Action>;
     captureOnce({ includeScreenshot, codeBlock }?: {
         includeScreenshot?: boolean;
         codeBlock?: string;
@@ -40,7 +40,7 @@ declare class Action {
         id?: string;
     }>>;
     captureBrowserLogs(): Promise<any[]>;
-    executeOnce(code: string): Promise<Action>;
+    executeOnce(code: string, verbatim?: boolean): Promise<Action>;
     attempt(codeBlock: string, originalMessage?: string): Promise<boolean>;
     exitIframe(): Promise<void>;
     getActor(): CodeceptJS.I;
@@ -49,3 +49,6 @@ declare class Action {
 }
 export default Action;
 export type RecoveryRunner = <T>(fn: () => Promise<T>) => Promise<T>;
+export interface ExecuteOptions {
+    verbatim?: boolean;
+}

package/dist/src/action.js

@@ -57,8 +57,8 @@ class Action {
     async capturePageState(opts = {}) {
         return this.recovery(() => this.captureOnce(opts));
     }
-    async execute(code) {
-        return this.recovery(() => this.executeOnce(code));
+    async execute(code, opts = {}) {
+        return this.recovery(() => this.executeOnce(code, opts.verbatim));
     }
     async captureOnce({ includeScreenshot = false, codeBlock } = {}) {
         try {
@@ -251,7 +251,7 @@ class Action {
             return [];
         }
     }
-    async executeOnce(code) {
+    async executeOnce(code, verbatim = false) {
         let error = null;
         setActivity('🔎 Browsing...', 'action');
         let codeString = code.replace(/^\(I\) => /, '').trim();
@@ -265,8 +265,8 @@ class Action {
         const tracer = trace.getTracer('ai');
         const stepSpan = activeSpan ? tracer.startSpan('codeceptjs.step', undefined, trace.setSpan(context.active(), activeSpan)) : null;
         setStepSpanParent(stepSpan);
-        const sanitizedCode = sanitizeCodeBlock(codeString);
-        const isPlaywright = hasPlaywrightCommands(sanitizedCode);
+        const sanitizedCode = verbatim ? codeString : sanitizeCodeBlock(codeString);
+        const isPlaywright = !verbatim && hasPlaywrightCommands(sanitizedCode);
         try {
             debugLog('Executing action:', codeString);
             if (!sanitizedCode) {

package/dist/src/ai/captain/mixin.js

@@ -1,10 +1,9 @@
-import { dirname } from 'node:path';
 import { ConfigParser } from "../../config.js";
 import { createDebug } from '../../utils/logger.js';
 export const debugLog = createDebug('explorbot:captain');
 export function resolveProjectRoot() {
-    const configPath = ConfigParser.getInstance().getConfigPath();
-    if (!configPath)
+    const configParser = ConfigParser.getInstance();
+    if (!configParser.getConfigPath())
         return null;
-    return dirname(configPath);
+    return configParser.getProjectRoot();
 }

package/dist/src/ai/captain/web-mode.js

@@ -25,7 +25,7 @@ export function WithWebMode(Base) {
                     execute: async ({ destination }) => {
                         try {
                             debugLog('navigate', destination);
-                            await ctx.explorBot.agentNavigator().visit(destination);
+                            await ctx.explorBot.visit(destination);
                             const stateManager = ctx.explorBot.stateManager();
                             const state = stateManager.getCurrentState();
                             return { success: true, url: state?.url, title: state?.title };

package/dist/src/ai/navigator.d.ts

@@ -32,6 +32,10 @@ declare class Navigator implements Agent {
     resolveState(message: string, actionResult: ActionResult, opts?: {
         action?: Action;
         expectedUrl?: string;
+        onAttempt?: (attempt: {
+            code: string;
+            error?: string;
+        }) => void;
     }): Promise<boolean>;
     buildExperienceTools(): {
         learnExperience: unknown;

package/dist/src/ai/navigator.js

@@ -8,7 +8,7 @@ import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
 import { RulesLoader } from "../utils/rules-loader.js";
-import { extractStatePath } from '../utils/url-matcher.js';
+import { extractStatePath, matchesNavigationUrl } from '../utils/url-matcher.js';
 import { Researcher } from "./researcher.js";
 import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
@@ -118,7 +118,7 @@ class Navigator {
             return false;
         }
         const currentUrl = this.getComparableCurrentUrl(stateManager, expectedUrl);
-        return normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
+        return matchesNavigationUrl(expectedUrl, currentUrl);
     }
     async visit(url) {
         return this.visitOnce(url);
@@ -167,11 +167,13 @@ class Navigator {
         }
     }
     async resolveState(message, actionResult, opts) {
+        if (!this.provider)
+            throw new Error('AI-assisted recovery is unavailable: no AI model is configured.');
         tag('info').log('AI Navigator resolving state at', actionResult.url);
         debugLog('Resolution message:', message);
         const action = opts?.action ?? this.explorer.action();
         const expectedUrl = opts?.expectedUrl;
-        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
+        const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
         let experience = '';
         if (!actionResult.isInsideIframe) {
             const successful = this.experienceTracker.getSuccessfulExperience(actionResult);
@@ -328,16 +330,19 @@ class Navigator {
                     // Navigation did not reach 'load' state within timeout; continue and verify URL
                 }
             }
+            if (attemptOk)
+                opts?.onAttempt?.({ code: codeBlock });
             if (!attemptOk) {
                 const raw = action.lastError?.message || 'attempt failed';
                 const firstMeaningful = raw.split('\n').find((l) => l.trim() && !l.trim().startsWith('at ')) || raw;
                 const shortErr = firstMeaningful.replace(/\s+/g, ' ').trim().slice(0, 220);
                 batchFailures.push({ code: codeBlock, error: shortErr });
+                opts?.onAttempt?.({ code: codeBlock, error: shortErr });
             }
             if (expectedUrl) {
                 if (page) {
                     try {
-                        await page.waitForURL((url) => normalizeUrl(url.pathname) === normalizeUrl(expectedUrl), { timeout: 5000 });
+                        await page.waitForURL((url) => matchesNavigationUrl(expectedUrl, `${url.pathname}${url.search}${url.hash}`), { timeout: 5000 });
                     }
                     catch {
                         // URL did not transition to expectedUrl within timeout
@@ -345,7 +350,7 @@ class Navigator {
                 }
                 const freshState = await this.explorer.capture();
                 const currentUrl = /^https?:\/\//i.test(expectedUrl) ? freshState.fullUrl || freshState.url || '' : freshState.url || '';
-                const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && normalizeUrl(currentUrl) === normalizeUrl(expectedUrl);
+                const urlMatches = this.isSameExpectedOrigin(expectedUrl, action.stateManager) && matchesNavigationUrl(expectedUrl, currentUrl);
                 const stateChanged = freshState.getStateHash() !== actionResult.getStateHash();
                 resolved = urlMatches && stateChanged;
                 if (!resolved && attemptOk) {
@@ -562,7 +567,7 @@ class Navigator {
             tag('operation').log(`Reusing cached verification: ${cachedVerification ? 'PASS' : 'FAIL'}`);
             return { verified: cachedVerification, successfulCodes: [], assertionSteps: [], totalAttempted: 0 };
         }
-        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
+        const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
         let experience = '';
         if (!actionResult.isInsideIframe) {
             experience = this.experienceTracker.renderExperienceTocFor(actionResult);

package/dist/src/ai/planner.d.ts

@@ -50,6 +50,7 @@ export declare class Planner extends PlannerBase implements Agent {
     provider: Provider;
     stateManager: StateManager;
     experienceTracker: ExperienceTracker;
+    knowledgeTracker: AgentDeps['knowledgeTracker'];
     MIN_TASKS: number;
     MAX_TASKS: number;
     currentPlan: Plan | null;

package/dist/src/ai/planner.js

@@ -41,6 +41,7 @@ export class Planner extends PlannerBase {
     provider;
     stateManager;
     experienceTracker;
+    knowledgeTracker;
     MIN_TASKS = 3;
     MAX_TASKS = 12;
     currentPlan = null;
@@ -56,6 +57,7 @@ export class Planner extends PlannerBase {
         this.researcher = researcher;
         this.stateManager = deps.stateManager;
         this.experienceTracker = deps.stateManager.getExperienceTracker();
+        this.knowledgeTracker = deps.knowledgeTracker;
     }
     setFisherman(fisherman) {
         this.fisherman = fisherman;
@@ -368,6 +370,10 @@ export class Planner extends PlannerBase {
       ${plannerResearch}
       </page_research>
     `);
+        const applicationContext = this.knowledgeTracker.renderApplicationSpec(state);
+        if (applicationContext) {
+            conversation.addUserText(applicationContext);
+        }
         conversation.addUserText(dedent `
       ${this.buildApproach(style)}
 

package/dist/src/ai/researcher.js

@@ -379,7 +379,7 @@ export class Researcher extends ResearcherBase {
         if (!this.actionResult)
             throw new Error('actionResult is not set');
         const html = await this.actionResult.combinedHtml();
-        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(this.actionResult);
+        const knowledge = this.knowledgeTracker.renderRelevantContext(this.actionResult);
         const ariaSnapshot = this.actionResult.getCompactARIA();
         return dedent `
       Analyze this web page and provide a comprehensive research report in markdown format.

package/dist/src/ai/task-agent.js

@@ -49,7 +49,7 @@ export class TaskAgent {
         return this.provider;
     }
     getKnowledge(actionResult) {
-        return this.getKnowledgeTracker().renderRelevantKnowledge(actionResult);
+        return this.getKnowledgeTracker().renderRelevantContext(actionResult);
     }
     getExperience(actionResult) {
         return this.getExperienceTracker().renderExperienceTocFor(actionResult);

package/dist/src/ai/tester.d.ts

@@ -31,6 +31,7 @@ export declare class Tester extends TaskAgent implements Agent {
     seenUiMapUrls: Set<string>;
     lastAnalyzedStateHash: string | null;
     stalledIterations: number;
+    hasSuccessfulAssertion: boolean;
     readonly MAX_STALLED_ITERATIONS = 3;
     constructor(deps: AgentDeps, researcher: Researcher, navigator: Navigator, agentTools?: any);
     getNavigator(): Navigator;

package/dist/src/ai/tester.js

@@ -48,6 +48,7 @@ export class Tester extends TaskAgent {
     seenUiMapUrls = new Set();
     lastAnalyzedStateHash = null;
     stalledIterations = 0;
+    hasSuccessfulAssertion = false;
     MAX_STALLED_ITERATIONS = 3;
     constructor(deps, researcher, navigator, agentTools) {
         super(deps);
@@ -87,6 +88,7 @@ export class Tester extends TaskAgent {
         this.seenUiMapUrls.clear();
         this.lastAnalyzedStateHash = null;
         this.stalledIterations = 0;
+        this.hasSuccessfulAssertion = false;
         this.stateManager.clearHistory();
         this.resetFailureCount();
         this.pilot?.reset();
@@ -266,8 +268,15 @@ export class Tester extends TaskAgent {
                 const allToolNames = result?.toolExecutions?.map((execution) => execution.toolName) || [];
                 const successfulToolNames = result?.toolExecutions?.filter((execution) => execution.wasSuccessful)?.map((execution) => execution.toolName) || [];
                 const actionPerformed = !!allToolNames.find((toolName) => this.ACTION_TOOLS.includes(toolName));
+                const successfulActionPerformed = !!successfulToolNames.find((toolName) => this.ACTION_TOOLS.includes(toolName));
                 assertionPerformed = !!successfulToolNames.find((toolName) => this.ASSERTION_TOOLS.includes(toolName));
                 const wasSuccessful = result?.toolExecutions?.every((execution) => execution.wasSuccessful);
+                if (successfulActionPerformed) {
+                    this.hasSuccessfulAssertion = false;
+                }
+                if (assertionPerformed) {
+                    this.hasSuccessfulAssertion = true;
+                }
                 this.trackToolExecutions(result?.toolExecutions || []);
                 if (this.consecutiveEmptyResults >= 5) {
                     task.addNote('AI model is not responding with actions. Stopped');
@@ -405,6 +414,10 @@ export class Tester extends TaskAgent {
         this.stalledIterations++;
         if (this.stalledIterations < this.MAX_STALLED_ITERATIONS)
             return false;
+        if (this.hasSuccessfulAssertion) {
+            task.addNote('No further browser progress after successful verification; requesting final review');
+            return true;
+        }
         task.addNote('No browser progress after repeated attempts on unchanged page', TestResult.FAILED);
         task.finish(TestResult.FAILED);
         return true;

package/dist/src/application-spec-contract.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export declare const APPLICATION_SPEC_FORMAT = "explorbot-application-spec";
+export declare const APPLICATION_SPEC_VERSION = 1;
+export declare const APPLICATION_SPEC_PAGE_SCHEMA: z.ZodObject<{
+    format: z.ZodLiteral<"explorbot-application-spec">;
+    version: z.ZodLiteral<1>;
+    url: z.ZodString;
+}, z.core.$strip>;

package/dist/src/application-spec-contract.js

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+export const APPLICATION_SPEC_FORMAT = 'explorbot-application-spec';
+export const APPLICATION_SPEC_VERSION = 1;
+export const APPLICATION_SPEC_PAGE_SCHEMA = z.object({
+    format: z.literal(APPLICATION_SPEC_FORMAT),
+    version: z.literal(APPLICATION_SPEC_VERSION),
+    url: z.string().trim().min(1),
+});

package/dist/src/application-spec.d.ts

@@ -0,0 +1,15 @@
+import { ActionResult } from './action-result.js';
+export declare class ApplicationSpec {
+    pages: ApplicationSpecPage[];
+    readonly sourcePath: string;
+    constructor(sourcePath: string);
+    renderFor(state: ActionResult): string;
+    get pageCount(): number;
+    load(): void;
+    resolveSourcePath(sourcePath: string): string;
+}
+interface ApplicationSpecPage {
+    url: string;
+    content: string;
+}
+export {};

package/dist/src/application-spec.js

@@ -0,0 +1,71 @@
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import dedent from 'dedent';
+import { APPLICATION_SPEC_PAGE_SCHEMA } from "./application-spec-contract.js";
+import { ConfigParser } from "./config.js";
+import { tag } from "./utils/logger.js";
+import { loadMarkdownFiles } from "./utils/markdown-files.js";
+export class ApplicationSpec {
+    pages = [];
+    sourcePath;
+    constructor(sourcePath) {
+        this.sourcePath = this.resolveSourcePath(sourcePath);
+        this.load();
+    }
+    renderFor(state) {
+        const relevant = this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
+        if (relevant.length === 0)
+            return '';
+        tag('operation').log(`Found application specification for ${state.url}`);
+        return dedent `
+      <application_spec>
+      This is previously collected application documentation. Treat User Can and observed state transitions as supporting context, not as a replacement for the current page state. Treat User Might as unverified possibilities that must be confirmed before use.
+
+      ${relevant.map((page) => page.content).join('\n\n')}
+      </application_spec>
+    `;
+    }
+    get pageCount() {
+        return this.pages.length;
+    }
+    load() {
+        if (!existsSync(this.sourcePath)) {
+            throw new Error(`Application spec not found: ${this.sourcePath}`);
+        }
+        const isDirectory = statSync(this.sourcePath).isDirectory();
+        if (!isDirectory && path.basename(this.sourcePath).toLowerCase() !== 'index.md') {
+            throw new Error(`Application spec file must be index.md: ${this.sourcePath}`);
+        }
+        const bundlePath = isDirectory ? this.sourcePath : path.dirname(this.sourcePath);
+        const indexPath = path.join(bundlePath, 'index.md');
+        if (!existsSync(indexPath)) {
+            throw new Error(`Application spec index not found: ${indexPath}`);
+        }
+        const pagesPath = path.join(bundlePath, 'pages');
+        if (!existsSync(pagesPath)) {
+            throw new Error(`Application spec pages directory not found: ${pagesPath}`);
+        }
+        for (const file of loadMarkdownFiles(pagesPath, { recursive: true })) {
+            const parsed = APPLICATION_SPEC_PAGE_SCHEMA.safeParse(file.data);
+            if (!parsed.success && parsed.error.issues.some((issue) => issue.path[0] === 'format')) {
+                throw new Error(`Invalid application spec format in ${file.filePath}`);
+            }
+            if (!parsed.success && parsed.error.issues.some((issue) => issue.path[0] === 'version')) {
+                throw new Error(`Unsupported application spec version in ${file.filePath}: ${String(file.data.version)}`);
+            }
+            if (!parsed.success) {
+                throw new Error(`Application spec page URL is missing in ${file.filePath}`);
+            }
+            this.pages.push({ url: parsed.data.url, content: file.content.trim() });
+        }
+        if (this.pages.length === 0) {
+            throw new Error(`Application spec contains no documented pages: ${pagesPath}`);
+        }
+    }
+    resolveSourcePath(sourcePath) {
+        if (path.isAbsolute(sourcePath))
+            return path.resolve(sourcePath);
+        const configParser = ConfigParser.getInstance();
+        return path.resolve(configParser.resolveProjectDir(sourcePath));
+    }
+}

package/dist/src/browser-server.d.ts

@@ -1,10 +1,16 @@
-declare function getEndpointFilePath(): string;
-declare function readEndpoint(): string | null;
-declare function removeEndpointFile(): void;
+declare function getEndpointFilePath(instance?: string): string;
+declare function readEndpoint(instance?: string): string | null;
+declare function removeEndpointFile(instance?: string): void;
+declare function listInstances(): Array<{
+    name: string;
+    endpoint: string;
+}>;
 declare function isServerRunning(wsEndpoint: string): Promise<boolean>;
 declare function launchServer(opts: {
     browser?: string;
     show?: boolean;
-}): Promise<any>;
-declare function getAliveEndpoint(): Promise<string | null>;
-export { readEndpoint, removeEndpointFile, isServerRunning, launchServer, getEndpointFilePath, getAliveEndpoint };
+}, instance?: string): Promise<any>;
+declare function stopServer(instance?: string): Promise<boolean>;
+declare function keepServerRunning(stop: () => unknown): Promise<never>;
+declare function getAliveEndpoint(instance?: string): Promise<string | null>;
+export { readEndpoint, removeEndpointFile, isServerRunning, launchServer, stopServer, getEndpointFilePath, getAliveEndpoint, listInstances, keepServerRunning };

package/dist/src/browser-server.js

@@ -1,35 +1,62 @@
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
-import { chromium, firefox, webkit } from 'playwright-core';
+import { chromium, firefox, webkit } from 'playwright';
 import { ConfigParser } from './config.js';
 import { getCliName } from "./utils/cli-name.js";
 import { log } from './utils/logger.js';
 import { printNextSteps } from "./utils/next-steps.js";
 const ENDPOINT_FILENAME = '.browser-endpoint';
-function getEndpointFilePath() {
+const INSTANCE_NAME_PATTERN = /^[a-z0-9-]+$/;
+const KEEP_ALIVE_INTERVAL = 1 << 30;
+function getEndpointFilePath(instance = 'default') {
+    if (!INSTANCE_NAME_PATTERN.test(instance)) {
+        throw new Error(`Invalid browser instance name: "${instance}". Use lowercase letters, digits and dashes.`);
+    }
     const configParser = ConfigParser.getInstance();
     const outputDir = configParser.getOutputDir();
-    return path.join(outputDir, ENDPOINT_FILENAME);
+    if (instance === 'default')
+        return path.join(outputDir, ENDPOINT_FILENAME);
+    return path.join(outputDir, `${ENDPOINT_FILENAME}-${instance}`);
 }
-function readEndpoint() {
-    const filePath = getEndpointFilePath();
+function readEndpoint(instance = 'default') {
+    const filePath = getEndpointFilePath(instance);
     if (!existsSync(filePath))
         return null;
     return readFileSync(filePath, 'utf8').trim();
 }
-function writeEndpoint(wsEndpoint) {
-    const filePath = getEndpointFilePath();
+function writeEndpoint(wsEndpoint, instance = 'default') {
+    const filePath = getEndpointFilePath(instance);
     const dir = path.dirname(filePath);
     if (!existsSync(dir)) {
         mkdirSync(dir, { recursive: true });
     }
     writeFileSync(filePath, wsEndpoint, 'utf8');
 }
-function removeEndpointFile() {
-    const filePath = getEndpointFilePath();
+function removeEndpointFile(instance = 'default') {
+    const filePath = getEndpointFilePath(instance);
     if (existsSync(filePath))
         unlinkSync(filePath);
 }
+function listInstances() {
+    const dir = path.dirname(getEndpointFilePath());
+    if (!existsSync(dir))
+        return [];
+    const instances = [];
+    for (const fileName of readdirSync(dir)) {
+        if (!fileName.startsWith(ENDPOINT_FILENAME))
+            continue;
+        const suffix = fileName.slice(ENDPOINT_FILENAME.length);
+        if (suffix && !suffix.startsWith('-'))
+            continue;
+        if (suffix === '-')
+            continue;
+        const name = suffix.slice(1) || 'default';
+        if (!INSTANCE_NAME_PATTERN.test(name))
+            continue;
+        instances.push({ name, endpoint: readFileSync(path.join(dir, fileName), 'utf8').trim() });
+    }
+    return instances;
+}
 async function isServerRunning(wsEndpoint) {
     try {
         const browser = await chromium.connect(wsEndpoint, { timeout: 3000 });
@@ -41,7 +68,7 @@ async function isServerRunning(wsEndpoint) {
     }
 }
 const BROWSER_LAUNCHERS = { chromium, firefox, webkit };
-async function launchServer(opts) {
+async function launchServer(opts, instance = 'default') {
     const browserName = (opts.browser || 'chromium');
     const launcher = BROWSER_LAUNCHERS[browserName];
     if (!launcher)
@@ -50,30 +77,58 @@ async function launchServer(opts) {
         headless: !opts.show,
     });
     const wsEndpoint = server.wsEndpoint();
-    writeEndpoint(wsEndpoint);
+    writeEndpoint(wsEndpoint, instance);
     log(`Browser server started: ${browserName} (${opts.show ? 'headed' : 'headless'})`);
     const cli = getCliName();
+    let instanceFlag = '';
+    if (instance !== 'default')
+        instanceFlag = ` --instance ${instance}`;
     const sections = [
         {
             label: 'Browser server',
-            path: getEndpointFilePath(),
+            path: getEndpointFilePath(instance),
             commands: [
                 { label: 'Endpoint', command: wsEndpoint },
-                { label: 'Status', command: `${cli} browser status` },
-                { label: 'Stop', command: `${cli} browser stop` },
+                { label: 'Status', command: `${cli} browser status${instanceFlag}` },
+                { label: 'Stop', command: `${cli} browser stop${instanceFlag}` },
             ],
         },
     ];
     printNextSteps(sections);
     return server;
 }
-async function getAliveEndpoint() {
-    const endpoint = readEndpoint();
+async function stopServer(instance = 'default') {
+    const endpoint = await getAliveEndpoint(instance);
+    if (!endpoint)
+        return false;
+    try {
+        const browser = await chromium.connect(endpoint, { timeout: 3000 });
+        await browser.close();
+    }
+    catch { }
+    removeEndpointFile(instance);
+    return true;
+}
+function keepServerRunning(stop) {
+    console.log('Browser server is running. Press Ctrl+C to stop.');
+    const heartbeat = setInterval(() => { }, KEEP_ALIVE_INTERVAL);
+    const cleanup = async () => {
+        console.log('\nStopping browser server...');
+        clearInterval(heartbeat);
+        await stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+    return new Promise(() => { });
+}
+async function getAliveEndpoint(instance = 'default') {
+    const endpoint = readEndpoint(instance);
     if (!endpoint)
         return null;
     if (await isServerRunning(endpoint))
         return endpoint;
-    removeEndpointFile();
+    removeEndpointFile(instance);
     return null;
 }
-export { readEndpoint, removeEndpointFile, isServerRunning, launchServer, getEndpointFilePath, getAliveEndpoint };
+export { readEndpoint, removeEndpointFile, isServerRunning, launchServer, stopServer, getEndpointFilePath, getAliveEndpoint, listInstances, keepServerRunning };