explorbot 0.2.2 → 0.2.4

package/dist/src/ai/tools.js

@@ -2,8 +2,9 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
+import { Stats } from "../stats.js";
 import { TestResult } from '../test-plan.js';
-import { LARGE_ARIA_CHANGE_THRESHOLD, extractFocusedElement } from "../utils/aria.js";
+import { LARGE_ARIA_CHANGE_THRESHOLD } from "../utils/aria.js";
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { pause } from '../utils/loop.js';
@@ -18,6 +19,10 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
             description: dedent `
         Click an element by trying multiple CodeceptJS commands in order until one succeeds.
 
+        Use this only for elements the page context gives you no ref for. When the element shows a ref such as [ref=e14],
+        call clickRef with that ref instead — composing a locator for an element that already has a ref is wasted work,
+        and a locator can match several elements where a ref cannot.
+
         Follow <locator_priority> from system prompt for locator selection.
 
         I.click(locator) - click element matching locator
@@ -36,14 +41,13 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 commands: z.array(z.string()).describe(dedent `
           FALLBACK LOCATORS for ONE element. All commands must click the SAME element.
           Never mix different elements — use separate click() calls instead.
+          REQUIRED: include at least one command WITHOUT a container — a wrong or stale container always fails.
           Order by reliability:
-          1. I.click(text, container) - PREFERRED when container is known - e.g. I.click("Save", ".modal")
+          1. I.click(text, container) - when the container is verified - e.g. I.click("Save", ".modal")
           2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
           5. I.clickXY(x, y) - coordinates fallback
-          IMPORTANT: Always include at least one command WITHOUT a container as fallback,
-          in case the element moved to a different section (e.g. I.click("Save") without container).
         `),
                 explanation: z.string().describe('Why you are clicking this element'),
             }),
@@ -106,14 +110,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 }
                 const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, commands[0]);
                 await commitNote(activeNote, TestResult.FAILED, toolResult, action);
-                let suggestion = "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
-                const lastError = attempts[attempts.length - 1]?.error || '';
-                if (lastError.includes('was not found') || lastError.includes('not found by text')) {
-                    suggestion = 'Element was not found in the DOM. Use xpathCheck() to locate it, context() to refresh snapshot, or visualClick() to click by visual appearance.';
-                }
-                else if (lastError.includes('Timeout') || lastError.includes('intercept')) {
-                    suggestion = 'Element exists but could not be clicked (possibly covered by overlay or not interactable). Try closing overlapping panels first, or use visualClick().';
-                }
+                const suggestion = clickFailureSuggestion(attempts);
                 return failedToolResult('click', 'All click commands failed', {
                     ...toolResult,
                     attempts,
@@ -121,6 +118,38 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 }, action.lastError);
             },
         }),
+        clickRef: tool({
+            description: dedent `
+        Click an element by the ref the page context gave it, e.g. [ref=e14].
+
+        Prefer this over click() whenever the element you want carries a ref. A ref names one exact element, so it
+        cannot match several by mistake and never needs disambiguating — it is the fastest way to click.
+        Only pass a ref that appears in the page context you were given. Never invent or guess one.
+        If it reports the ref is gone, the page has been rebuilt: get fresh context and use the new ref.
+      `,
+            inputSchema: z.object({
+                ref: z.string().describe('The ref exactly as it appears in the page context, e.g. "e14"'),
+                element: z.string().describe('Role and name of the element you are clicking, for the record'),
+            }),
+            execute: async ({ ref, element }) => {
+                const activeNote = task.startNote(`Click ${element}`);
+                const previousState = ActionResult.fromState(stateManager.getCurrentState());
+                const action = explorer.action();
+                const named = await describeRef(explorer, ref);
+                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+                if (!(await action.attempt(run, `Click ${element}`))) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
+                        suggestion: 'The ref may belong to an older version of the page. Get fresh context and use the ref it gives, or fall back to click() with a locator.',
+                    });
+                }
+                // a ref belongs to this session only, so the run is reported as the locator a later test can replay
+                const code = named ? `I.click(${JSON.stringify(named)})` : run;
+                const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, code);
+                await commitNote(activeNote, TestResult.PASSED, toolResult, action);
+                return successToolResult('clickRef', { ...toolResult, code }, action);
+            },
+        }),
         hover: tool({
             description: dedent `
         Move the mouse cursor to an element to reveal hover-only controls.
@@ -245,15 +274,11 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     }
                     const focusFreeKeys = new Set(['Escape', 'Esc', 'Tab', 'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12']);
                     const needsFocus = !focusFreeKeys.has(keyToUse) && !modifier;
-                    if (needsFocus) {
-                        const currentAriaState = stateManager.getCurrentState()?.ariaSnapshot;
-                        const focused = extractFocusedElement(currentAriaState ?? null);
-                        if (!focused) {
-                            activeNote.commit(TestResult.FAILED);
-                            return failedToolResult('pressKey', `No element is focused. Key '${keyToUse}' requires a focused element.`, {
-                                suggestion: 'Click the target element first, then press the key.',
-                            });
-                        }
+                    if (needsFocus && !(await hasFocusedElement(explorer))) {
+                        activeNote.commit(TestResult.FAILED);
+                        return failedToolResult('pressKey', `No element is focused. Key '${keyToUse}' requires a focused element.`, {
+                            suggestion: 'Click the target element first, then press the key.',
+                        });
                     }
                     const previousState = ActionResult.fromState(stateManager.getCurrentState());
                     const action = explorer.action();
@@ -296,6 +321,8 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
         Execute raw CodeceptJS code block with multiple commands.
         USE THIS TOOL for typing text into fields: I.fillField, I.type
 
+        Do not put a click on a ref-bearing element in here — clickRef with its ref is cheaper and cannot mis-target.
+
         Follow <actions> from system prompt for available commands.
         Follow <locator_priority> from system prompt for locator selection.
 
@@ -456,25 +483,25 @@ export function createLearnExperienceTool({ getExperienceTracker, getState }) {
     });
 }
 export function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }) {
-    let visionDisabled = false;
     const tools = {
         see: tool({
             description: dedent `
-        Check the page contents based on current page state and screenshot.
-        This tool will trigger visual research to check the page contents on request.
-        Use it to verify the actions were performed correctly and the page is in the expected state.
+        Answer a question about the page from a screenshot, for things its structure cannot express:
+        layout and position, what an image or canvas depicts, colour, and whether something is covered or cut off.
+        This runs a second model and is the slowest tool here, so reach for it only when the question is genuinely visual.
+        Do NOT use it to confirm an action landed — every action already reports what changed on the page.
         Input schema has exactly one field: request. Do not pass text, reason, assertion, or other fields.
 
         <example>
-        request: "Check current state of the Login form"
-        result: "Login form is visible with username and password fields, username is filled with 'testuser' and password is empty' 
+        request: "Is the save button covered by anything, and does the chart show any plotted data?"
+        result: "The save button is partly behind a cookie banner at the bottom. The chart area is empty apart from its axes."
         </example>
       `,
             inputSchema: z.object({
                 request: z.string().describe('LLM-friendly description of the page contents to look for. 1-3 sentences. No more than 100 words.'),
             }),
             execute: async ({ request }) => {
-                if (visionDisabled) {
+                if (Stats.visionDisabled) {
                     return failedToolResult('see', 'Vision tools are disabled for this session. Use context() to get fresh ARIA snapshot and analyze page state from ARIA data.');
                 }
                 try {
@@ -495,8 +522,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                 catch (error) {
                     throwIfFatalBrowserError(error);
                     const errorMessage = errorText(error);
-                    visionDisabled = true;
-                    tag('warning').log('⚠️ Vision model is not available. Visual checks are disabled for this session.');
+                    disableVision();
                     return failedToolResult('see', `See tool failed: ${errorMessage}`, {
                         suggestion: 'Vision is now disabled. Use context() to get fresh ARIA snapshot and analyze page state from ARIA data.',
                     });
@@ -576,6 +602,12 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                             code: result.successfulCodes.join('\n'),
                         }, { assertionSteps: result.assertionSteps });
                     }
+                    if (result.inexpressible) {
+                        return failedToolResult('verify', `No assertion could express this claim: ${assertion}`, {
+                            inexpressible: true,
+                            suggestion: 'This is not evidence the page is wrong — the claim could not be turned into an assertion. Restate it in terms of what is visible or of a control state, or check it with see().',
+                        });
+                    }
                     return failedToolResult('verify', `Verification failed: ${assertion}`, {
                         suggestion: 'The assertion could not be verified. Check if the condition is actually present on the page or try a different assertion.',
                     });
@@ -696,7 +728,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                 context: z.string().describe('What you already tried and why it failed - helps with accurate identification'),
             }),
             execute: async ({ element, context }) => {
-                if (visionDisabled) {
+                if (Stats.visionDisabled) {
                     return failedToolResult('visualClick', 'Vision tools are disabled for this session. Use xpathCheck() to find the element, then click() with the discovered locator.');
                 }
                 try {
@@ -741,8 +773,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
                 catch (error) {
                     throwIfFatalBrowserError(error);
                     const errorMessage = errorText(error);
-                    visionDisabled = true;
-                    tag('warning').log('⚠️ Vision model is not available. Visual clicks are disabled for this session.');
+                    disableVision();
                     return failedToolResult('visualClick', `visualClick tool failed: ${errorMessage}`, {
                         suggestion: 'Vision is now disabled. Use xpathCheck() to find the element, then click() with the discovered locator.',
                     });
@@ -875,6 +906,11 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
             },
         }),
     };
+    const disableVision = () => {
+        Stats.visionDisabled = true;
+        withdrawVisionTools(tools);
+        tag('warning').log('⚠️ Vision model is not available. Visual tools are disabled for this session.');
+    };
     if (withExperience !== false) {
         tools.learnExperience = createLearnExperienceTool({
             getExperienceTracker: () => stateManager.getExperienceTracker(),
@@ -921,6 +957,7 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
             },
         });
     }
+    withdrawVisionTools(tools);
     return tools;
 }
 const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';
@@ -964,13 +1001,27 @@ function errorText(error) {
         return error.toString();
     return 'Unknown error occurred';
 }
-async function commitNote(activeNote, result, toolResult, action) {
+export async function commitNote(activeNote, result, toolResult, action) {
     if (toolResult?.pageDiff?.ariaChanges || toolResult?.pageDiff?.urlChanged) {
         activeNote.screenshot = await action.saveScreenshot();
     }
     activeNote.commit(result);
 }
-function successToolResult(action, data, source) {
+async function describeRef(explorer, ref) {
+    return Promise.resolve(explorer?.withPage?.((page) => page.locator(`aria-ref=${ref}`).evaluate((el) => {
+        const tag = el.tagName.toLowerCase();
+        const roles = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
+        const role = el.getAttribute('role') || roles[tag] || tag;
+        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
+        if (!text)
+            return null;
+        return { role, text };
+    }))).catch(() => null);
+}
+async function hasFocusedElement(explorer) {
+    return explorer.withPage((page) => page.evaluate(() => !!document.activeElement && document.activeElement !== document.body)).catch(() => true);
+}
+export function successToolResult(action, data, source) {
     const result = { success: true, action, ...data };
     if (source?.playwrightGroupId) {
         result.playwrightGroupId = source.playwrightGroupId;
@@ -1008,7 +1059,7 @@ function hasObservablePageChange(data) {
         return true;
     return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
-async function failedToolResult(action, message, data, error) {
+export async function failedToolResult(action, message, data, error) {
     const result = { success: false, action, message, ...data };
     if (data?.pageDiff) {
         result.suggestion = data.suggestion ? `${data.suggestion} ${PAGE_DIFF_SUGGESTION}` : PAGE_DIFF_SUGGESTION;
@@ -1040,6 +1091,32 @@ function getMultipleElementsSuggestion() {
     6. Use visualClick() to click the right element by visual appearance
   `;
 }
+export function withdrawVisionTools(tools) {
+    if (!Stats.visionDisabled)
+        return;
+    Reflect.deleteProperty(tools, 'see');
+    Reflect.deleteProperty(tools, 'visualClick');
+}
+export function clickFailureSuggestion(attempts) {
+    const errors = attempts.map((a) => a.error || '');
+    if (errors.some((e) => e.includes('not enabled'))) {
+        return 'Element exists but is DISABLED — clicking it again cannot work. A precondition is unmet: a required field is empty, nothing is selected, or a dialog is blocking. Satisfy it, then retry.';
+    }
+    if (errors.some((e) => e.includes('intercepts pointer events'))) {
+        return 'Element exists but another element covers it. Close the overlapping panel or dialog, then retry.';
+    }
+    if (errors.some((e) => e.includes('is not visible'))) {
+        return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
+    }
+    const notFound = errors.filter((e) => e.includes('was not found'));
+    if (notFound.length && notFound.every((e) => e.includes('was not found inside element'))) {
+        return 'Element was not found inside that container — the container is wrong or stale, and the element may exist elsewhere on the page. Retry the same locator WITHOUT a container, or verify the container with xpathCheck().';
+    }
+    if (notFound.length) {
+        return 'Element was not found in the DOM. Use xpathCheck() to locate it, context() to refresh snapshot, or visualClick() to click by visual appearance.';
+    }
+    return "Try xpathCheck() to find the element's actual position, see() for visual analysis, or visualClick() to click by visual appearance.";
+}
 const MAX_DISAMBIGUATE_ELEMENTS = 10;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
 async function extractWebElements(error) {

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 };

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

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, rmSync, statSync, unlinkSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { ConfigParser, outputPath } from '../config.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
@@ -13,12 +13,7 @@ export const CLEAN_TARGETS = {
 };
 function getExperienceDir() {
     const configParser = ConfigParser.getInstance();
-    const config = configParser.getConfig();
-    const configPath = configParser.getConfigPath();
-    if (configPath) {
-        return join(dirname(configPath), config.dirs?.experience || 'experience');
-    }
-    return config.dirs?.experience || 'experience';
+    return configParser.resolveProjectDir(configParser.getConfig().dirs?.experience || 'experience');
 }
 function cleanDirectoryContents(dirPath) {
     if (!existsSync(dirPath))

package/dist/src/commands/init-command.d.ts

@@ -1,7 +1,12 @@
+export declare function runInit(options: InitCommandOptions): Promise<void>;
+export declare function writeGlobalConfig(provider: string, apiKey?: string): void;
 export declare function runInitCommand(options: InitCommandOptions): void;
 type InitCommandOptions = {
     configPath?: string;
     force?: boolean;
     path?: string;
+    global?: boolean;
+    provider?: string;
+    apiKey?: string;
 };
 export {};