explorbot 0.5.4 → 0.5.5

package/boat/prima/README.md

@@ -17,25 +17,20 @@ npm install -g prima-cli      # or install it
 
 Prima also ships inside [explorbot](https://www.npmjs.com/package/explorbot), so `npx explorbot prima <command>` runs the same tool if you already have it.
 
-Requires Node.js 24+. Playwright browsers come from `npx playwright install chromium`.
+Requires Node.js 22.13+. Playwright browsers come from `npx playwright install chromium`.
 
 ## Session
 
-Prima needs a browser to drive. Either attach to a `playwright-cli` session:
+Prima drives a browser opened by `playwright-cli` and never launches one itself:
 
 ```bash
 playwright-cli open https://app.example.com
+prima-cli browser
 prima-cli check "the settings page saves a changed theme"
 playwright-cli close
 ```
 
-Or let prima own the browser:
-
-```bash
-prima-cli browser start --url https://app.example.com
-prima-cli do "open the account menu" "choose the settings entry"
-prima-cli browser stop
-```
+`browser` checks that a `playwright-cli` session is open and fails with the command to open one when it is not.
 
 ## Commands
 
@@ -50,7 +45,7 @@ prima-cli browser stop
 | `pw <fn>` | Run a Playwright function expression against the open page |
 | `status <hash>` | Show the artifacts and page detail recorded for an earlier command |
 | `report` | Turn every command of a session into one html and markdown report |
-| `browser start\|stop\|status\|list` | Manage the browsers prima drives |
+| `browser` | Check that a playwright-cli session is open, and fail with the command to open one when it is not |
 | `config` | Show models, config file and paths used by this run |
 
 `check` takes an outcome rather than a click path. It runs on the page you are already on and never reloads it, so an open dialog survives the check. Each `--expected` outcome comes back as PASSED, FAILED, CONTRADICTION or not verified — settled against a screenshot of the whole page, because what a user can see is the proof.

package/boat/prima/package.json

@@ -15,6 +15,6 @@
     "directory": "boat/prima"
   },
   "engines": {
-    "node": ">=24.0.0"
+    "node": ">=22.13.0"
   }
 }

package/boat/prima/src/cli.ts

@@ -1,5 +1,4 @@
 import { Command } from 'commander';
-import { keepServerRunning } from '../../../src/browser-server.ts';
 import { RecommendedModelsCommand } from '../../../src/commands/recommended-models-command.ts';
 import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
 import { isVerboseMode, setQuietMode } from '../../../src/utils/logger.ts';
@@ -22,8 +21,6 @@ function buildOptions(subcommand: any): PrimaOptions {
     noVision: options.vision === false,
     url: options.url,
     baseUrl: options.baseUrl,
-    show: options.show,
-    headless: options.headless,
     endpoint: options.endpoint,
     pwSession: options.pwSession,
   };
@@ -89,18 +86,6 @@ async function runPrima(options: any, command: string, run: (prima: Prima) => Pr
   process.exit(envelope.ok ? 0 : 1);
 }
 
-async function runBrowser(options: any, run: (prima: Prima) => Promise<boolean>): Promise<void> {
-  let ok = false;
-  try {
-    ok = await run(primaFor(options));
-  } catch (error) {
-    console.error(browserErrorMessage(error));
-    process.exit(1);
-  }
-
-  process.exit(ok ? 0 : 1);
-}
-
 export function createPrimaCommands(name = 'prima'): Command {
   const cmd = new Command(name);
   cmd.description('Drives a web app through described behaviour, not locators');
@@ -179,41 +164,14 @@ export function createPrimaCommands(name = 'prima'): Command {
       process.exit(0);
     });
 
-  const browser = cmd.command('browser').description('Manage the browsers prima drives');
-
-  addBrowserOptions(browser.command('start').description('Start a prima-owned browser and hold it open until Ctrl+C'))
-    .option('-s, --show', 'Launch the browser in a visible window')
-    .option('--headless', 'Launch the browser without a window')
-    .action(async (options) => {
-      await runBrowser(options, async (prima) => {
-        await prima.browserStart();
-        console.log(await prima.browserStatus());
-        return keepServerRunning(() => prima.browserStop());
-      });
-    });
-
-  addBrowserOptions(browser.command('stop').description('Stop the browser of this instance'))
-    .option('--all', 'Stop every running instance')
-    .action(async (options) => {
-      await runBrowser(options, async (prima) => {
-        const stopped = await prima.browserStop(options.all);
-        console.log(await prima.browserStatus());
-        return stopped;
-      });
-    });
-
-  addBrowserOptions(browser.command('status').description('Report the browser of this instance')).action(async (options) => {
-    await runBrowser(options, async (prima) => {
-      console.log(await prima.browserStatus());
-      return true;
-    });
-  });
-
-  addBrowserOptions(browser.command('list').description('List every browser instance that is running')).action(async (options) => {
-    await runBrowser(options, async (prima) => {
-      console.log(await prima.browserList());
-      return true;
-    });
+  addBrowserOptions(cmd.command('browser').description('Check that a playwright-cli session is open for prima to drive')).action(async (options) => {
+    try {
+      console.log(await primaFor(options).browserCheck());
+    } catch (error) {
+      console.error(browserErrorMessage(error));
+      process.exit(1);
+    }
+    process.exit(0);
   });
 
   return cmd;

package/boat/prima/src/prima.ts

@@ -12,7 +12,7 @@ import { JUDGE_PAGE_CAP, UNDECIDED } from '../../../src/ai/judge.ts';
 import { getPreviousResearch } from '../../../src/ai/researcher/cache.ts';
 import { actionRule, locatorRule } from '../../../src/ai/rules.ts';
 import { createAgentTools, createCodeceptJSTools, createRefTools } from '../../../src/ai/tools.ts';
-import { getAliveEndpoint, launchServer, listInstances, stopServer } from '../../../src/browser-server.ts';
+import { getAliveEndpoint, listInstances } from '../../../src/browser-server.ts';
 import { ConfigCommand } from '../../../src/commands/config-command.ts';
 import { ConfigMissingError, ConfigParser, EXPLORBOT_ENV_VARS, type ExplorbotConfig, outputPath } from '../../../src/config.ts';
 import { ExplorBot } from '../../../src/explorbot.ts';
@@ -73,7 +73,6 @@ export class Prima {
   private artifactsDir?: string;
   private hash?: string;
   private sessionUrl?: string;
-  private server: { close: () => Promise<void> } | null = null;
   private attached: string | null = null;
   private session: SessionRun | null = null;
 
@@ -503,25 +502,12 @@ export class Prima {
     return envelope;
   }
 
-  async browserStart(): Promise<void> {
-    const config = await this.loadConfig();
-    let show = config.playwright.show || false;
-    if (this.options.show) show = true;
-    if (this.options.headless) show = false;
-    this.server = await this.launchOwnServer({ browser: config.playwright.browser, show }, this.instanceName());
-  }
-
-  async browserStop(all = false): Promise<boolean> {
+  async browserCheck(): Promise<string> {
     await this.loadConfig();
-    if (this.attached) return false;
-
-    if (!all) return this.stopInstance(this.instanceName());
-
-    let stopped = false;
-    for (const instance of listInstances()) {
-      if (await this.stopInstance(instance.name)) stopped = true;
-    }
-    return stopped;
+    const { match, candidates, browser } = await this.discover();
+    await browser?.close().catch(() => {});
+    if (!match) throw this.missingSessionError(candidates);
+    return `browser: ${this.attachmentLabel(match)} at ${match.endpoint}`;
   }
 
   async config(json?: boolean): Promise<string> {
@@ -572,37 +558,6 @@ export class Prima {
     ].join('\n');
   }
 
-  async browserStatus(): Promise<string> {
-    await this.loadConfig();
-    const info = await this.instanceInfo();
-    const endpoint = await getAliveEndpoint(info.name);
-    const others = info.others.map((other) => other.name).join(', ') || 'none';
-    const lines = [`instance: ${info.name} (${info.tabs} ${pluralize(info.tabs, 'tab')}) | other instances: ${others}`];
-    if (!endpoint) lines.push('browser: not running');
-    if (endpoint) lines.push(`browser: running at ${endpoint}`);
-    return lines.join('\n');
-  }
-
-  async browserList(): Promise<string> {
-    await this.loadConfig();
-
-    const lines: string[] = [];
-    for (const instance of listInstances()) {
-      const endpoint = await getAliveEndpoint(instance.name);
-      if (!endpoint) continue;
-      lines.push(`prima --instance ${instance.name}  ${endpoint}`);
-    }
-
-    const discovery = await this.discover();
-    await discovery.browser?.close().catch(() => {});
-    for (const descriptor of discovery.candidates) {
-      lines.push(`playwright-cli --pw-session ${descriptor.title}  ${descriptor.endpoint}`);
-    }
-
-    if (!lines.length) return 'no browser instances running';
-    return lines.join('\n');
-  }
-
   async instanceInfo(): Promise<InstanceInfo> {
     const name = this.instanceName();
     const others = listInstances()
@@ -666,22 +621,27 @@ export class Prima {
     const { match, candidates, browser } = discovered || (await this.discover());
     if (match && (await this.attachToEndpoint(match, browser))) return;
 
-    if (!match && candidates.length) {
+    if (!match && candidates.length) throw this.missingSessionError(candidates);
+
+    if (await this.connectOwnInstance()) return;
+
+    throw this.missingSessionError(candidates);
+  }
+
+  private missingSessionError(candidates: PwServerDescriptor[]): Error {
+    if (candidates.length) {
       const titles = candidates.map((candidate) => candidate.title).join(', ');
-      throw new Error(dedent`
+      return new Error(dedent`
         Several playwright-cli sessions are open: ${titles}
         Pick one with --pw-session <title>.
       `);
     }
 
-    if (await this.connectOwnInstance()) return;
-
-    throw new Error(dedent`
-      No browser to drive for instance "${this.instanceName()}".
-      Open one first:
-        playwright-cli open <url>   prima attaches to this workspace session by default
-        prima browser start         starts a prima-owned browser instead
-      Prima never launches a browser implicitly.
+    return new Error(dedent`
+      No playwright-cli session is open for prima to drive.
+      Start one first:
+        playwright-cli open ${this.options.url || '<url>'}
+      Prima attaches to this workspace session by default and never launches a browser itself.
     `);
   }
 
@@ -751,20 +711,6 @@ export class Prima {
     return true;
   }
 
-  private async launchOwnServer(opts: { browser?: string; show?: boolean }, instance: string): Promise<{ close: () => Promise<void> }> {
-    return launchServer(opts, instance);
-  }
-
-  private async stopInstance(instance: string): Promise<boolean> {
-    if (instance === this.instanceName()) {
-      const server = this.server;
-      this.server = null;
-      await server?.close();
-    }
-
-    return stopServer(instance);
-  }
-
   private isUrlTarget(target: string): boolean {
     const value = target.trim();
     if (value.startsWith('/')) return true;
@@ -1229,8 +1175,6 @@ export interface PrimaOptions {
   noVision?: boolean;
   url?: string;
   baseUrl?: string;
-  show?: boolean;
-  headless?: boolean;
   endpoint?: string;
   pwSession?: string;
 }

package/dist/boat/prima/src/cli.js

@@ -1,5 +1,4 @@
 import { Command } from 'commander';
-import { keepServerRunning } from "../../../src/browser-server.js";
 import { RecommendedModelsCommand } from "../../../src/commands/recommended-models-command.js";
 import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { isVerboseMode, setQuietMode } from "../../../src/utils/logger.js";
@@ -20,8 +19,6 @@ function buildOptions(subcommand) {
         noVision: options.vision === false,
         url: options.url,
         baseUrl: options.baseUrl,
-        show: options.show,
-        headless: options.headless,
         endpoint: options.endpoint,
         pwSession: options.pwSession,
     };
@@ -87,17 +84,6 @@ async function runPrima(options, command, run, opts = {}) {
     await prima.stop().catch(() => { });
     process.exit(envelope.ok ? 0 : 1);
 }
-async function runBrowser(options, run) {
-    let ok = false;
-    try {
-        ok = await run(primaFor(options));
-    }
-    catch (error) {
-        console.error(browserErrorMessage(error));
-        process.exit(1);
-    }
-    process.exit(ok ? 0 : 1);
-}
 export function createPrimaCommands(name = 'prima') {
     const cmd = new Command(name);
     cmd.description('Drives a web app through described behaviour, not locators');
@@ -163,37 +149,15 @@ export function createPrimaCommands(name = 'prima') {
             .catch((error) => browserErrorMessage(error)));
         process.exit(0);
     });
-    const browser = cmd.command('browser').description('Manage the browsers prima drives');
-    addBrowserOptions(browser.command('start').description('Start a prima-owned browser and hold it open until Ctrl+C'))
-        .option('-s, --show', 'Launch the browser in a visible window')
-        .option('--headless', 'Launch the browser without a window')
-        .action(async (options) => {
-        await runBrowser(options, async (prima) => {
-            await prima.browserStart();
-            console.log(await prima.browserStatus());
-            return keepServerRunning(() => prima.browserStop());
-        });
-    });
-    addBrowserOptions(browser.command('stop').description('Stop the browser of this instance'))
-        .option('--all', 'Stop every running instance')
-        .action(async (options) => {
-        await runBrowser(options, async (prima) => {
-            const stopped = await prima.browserStop(options.all);
-            console.log(await prima.browserStatus());
-            return stopped;
-        });
-    });
-    addBrowserOptions(browser.command('status').description('Report the browser of this instance')).action(async (options) => {
-        await runBrowser(options, async (prima) => {
-            console.log(await prima.browserStatus());
-            return true;
-        });
-    });
-    addBrowserOptions(browser.command('list').description('List every browser instance that is running')).action(async (options) => {
-        await runBrowser(options, async (prima) => {
-            console.log(await prima.browserList());
-            return true;
-        });
+    addBrowserOptions(cmd.command('browser').description('Check that a playwright-cli session is open for prima to drive')).action(async (options) => {
+        try {
+            console.log(await primaFor(options).browserCheck());
+        }
+        catch (error) {
+            console.error(browserErrorMessage(error));
+            process.exit(1);
+        }
+        process.exit(0);
     });
     return cmd;
 }

package/dist/boat/prima/src/prima.js

@@ -11,7 +11,7 @@ import { JUDGE_PAGE_CAP, UNDECIDED } from "../../../src/ai/judge.js";
 import { getPreviousResearch } from "../../../src/ai/researcher/cache.js";
 import { actionRule, locatorRule } from "../../../src/ai/rules.js";
 import { createAgentTools, createCodeceptJSTools, createRefTools } from "../../../src/ai/tools.js";
-import { getAliveEndpoint, launchServer, listInstances, stopServer } from "../../../src/browser-server.js";
+import { getAliveEndpoint, listInstances } from "../../../src/browser-server.js";
 import { ConfigCommand } from "../../../src/commands/config-command.js";
 import { ConfigMissingError, ConfigParser, EXPLORBOT_ENV_VARS, outputPath } from "../../../src/config.js";
 import { ExplorBot } from "../../../src/explorbot.js";
@@ -67,7 +67,6 @@ export class Prima {
     artifactsDir;
     hash;
     sessionUrl;
-    server = null;
     attached = null;
     session = null;
     constructor(options = {}) {
@@ -460,27 +459,13 @@ export class Prima {
             envelope.page.redirectedFrom = target;
         return envelope;
     }
-    async browserStart() {
-        const config = await this.loadConfig();
-        let show = config.playwright.show || false;
-        if (this.options.show)
-            show = true;
-        if (this.options.headless)
-            show = false;
-        this.server = await this.launchOwnServer({ browser: config.playwright.browser, show }, this.instanceName());
-    }
-    async browserStop(all = false) {
+    async browserCheck() {
         await this.loadConfig();
-        if (this.attached)
-            return false;
-        if (!all)
-            return this.stopInstance(this.instanceName());
-        let stopped = false;
-        for (const instance of listInstances()) {
-            if (await this.stopInstance(instance.name))
-                stopped = true;
-        }
-        return stopped;
+        const { match, candidates, browser } = await this.discover();
+        await browser?.close().catch(() => { });
+        if (!match)
+            throw this.missingSessionError(candidates);
+        return `browser: ${this.attachmentLabel(match)} at ${match.endpoint}`;
     }
     async config(json) {
         const [site] = listSites();
@@ -529,36 +514,6 @@ export class Prima {
             `upload:   TESTOMATIO=<apiKey> npx @testomatio/reporter replay ${file}`,
         ].join('\n');
     }
-    async browserStatus() {
-        await this.loadConfig();
-        const info = await this.instanceInfo();
-        const endpoint = await getAliveEndpoint(info.name);
-        const others = info.others.map((other) => other.name).join(', ') || 'none';
-        const lines = [`instance: ${info.name} (${info.tabs} ${pluralize(info.tabs, 'tab')}) | other instances: ${others}`];
-        if (!endpoint)
-            lines.push('browser: not running');
-        if (endpoint)
-            lines.push(`browser: running at ${endpoint}`);
-        return lines.join('\n');
-    }
-    async browserList() {
-        await this.loadConfig();
-        const lines = [];
-        for (const instance of listInstances()) {
-            const endpoint = await getAliveEndpoint(instance.name);
-            if (!endpoint)
-                continue;
-            lines.push(`prima --instance ${instance.name}  ${endpoint}`);
-        }
-        const discovery = await this.discover();
-        await discovery.browser?.close().catch(() => { });
-        for (const descriptor of discovery.candidates) {
-            lines.push(`playwright-cli --pw-session ${descriptor.title}  ${descriptor.endpoint}`);
-        }
-        if (!lines.length)
-            return 'no browser instances running';
-        return lines.join('\n');
-    }
     async instanceInfo() {
         const name = this.instanceName();
         const others = listInstances()
@@ -621,21 +576,25 @@ export class Prima {
         const { match, candidates, browser } = discovered || (await this.discover());
         if (match && (await this.attachToEndpoint(match, browser)))
             return;
-        if (!match && candidates.length) {
+        if (!match && candidates.length)
+            throw this.missingSessionError(candidates);
+        if (await this.connectOwnInstance())
+            return;
+        throw this.missingSessionError(candidates);
+    }
+    missingSessionError(candidates) {
+        if (candidates.length) {
             const titles = candidates.map((candidate) => candidate.title).join(', ');
-            throw new Error(dedent `
+            return new Error(dedent `
         Several playwright-cli sessions are open: ${titles}
         Pick one with --pw-session <title>.
       `);
         }
-        if (await this.connectOwnInstance())
-            return;
-        throw new Error(dedent `
-      No browser to drive for instance "${this.instanceName()}".
-      Open one first:
-        playwright-cli open <url>   prima attaches to this workspace session by default
-        prima browser start         starts a prima-owned browser instead
-      Prima never launches a browser implicitly.
+        return new Error(dedent `
+      No playwright-cli session is open for prima to drive.
+      Start one first:
+        playwright-cli open ${this.options.url || '<url>'}
+      Prima attaches to this workspace session by default and never launches a browser itself.
     `);
     }
     async discover(descriptors = readDescriptors()) {
@@ -703,17 +662,6 @@ export class Prima {
         this.session = { key: this.instanceName(), endpoint, title: `prima instance "${this.instanceName()}"` };
         return true;
     }
-    async launchOwnServer(opts, instance) {
-        return launchServer(opts, instance);
-    }
-    async stopInstance(instance) {
-        if (instance === this.instanceName()) {
-            const server = this.server;
-            this.server = null;
-            await server?.close();
-        }
-        return stopServer(instance);
-    }
     isUrlTarget(target) {
         const value = target.trim();
         if (value.startsWith('/'))

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/dist/src/ai/navigator.js

@@ -7,6 +7,7 @@ import { normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from "../utils/browser-errors.js";
 import { getCliName } from "../utils/cli-name.js";
 import { extractCodeBlocks } from '../utils/code-extractor.js';
+import { isLoginPage } from "../utils/error-page.js";
 import { HooksRunner } from "../utils/hooks-runner.js";
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
@@ -15,7 +16,7 @@ import { normalizeInlineText } from "../utils/strings.js";
 import { extractStatePath, isSameHostFamily, matchesNavigationUrl } from '../utils/url-matcher.js';
 import { JUDGE_PAGE_CAP, UNDECIDED } from "./judge.js";
 import { Researcher } from "./researcher.js";
-import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
+import { actionRule, credentialsRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
 import { createLearnExperienceTool } from "./tools.js";
 const debugLog = createDebug('explorbot:navigator');
@@ -46,7 +47,7 @@ class Navigator {
     NEVER use executeScript, executeAsyncScript, or any JS evaluation to change the URL, bypass redirects, or fake the page state.
     If the target URL redirects to an authentication/login page, DO NOT try to force the original URL. Instead:
       1. Look for credentials in the provided knowledge/hint context and perform a real login through the form.
-      2. If no credentials are available, ask the user for credentials or ask the user to log in manually.
+      2. If no credentials are available, stop and name the credentials that are missing. Never guess them.
     A redirect to /login, /sign_in, /auth, or similar is a signal that authentication is required — treat it as such, never as an obstacle to bypass.
   </constraints>
   `;
@@ -344,6 +345,9 @@ class Navigator {
         if (!experience && !actionResult.isInsideIframe) {
             experience = this.experienceTracker.renderExperienceFor(actionResult);
         }
+        let credentials = '';
+        if (isLoginPage(actionResult))
+            credentials = credentialsRule;
         return dedent `
       <message>
         ${message}
@@ -369,6 +373,8 @@ class Navigator {
 
       ${unexpectedPopupRule}
 
+      ${credentials}
+
       ${RulesLoader.loadRules('navigator', ['multiple-locator', 'output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.MAX_ATTEMPTS))}
 
       ${experience}

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

@@ -3,6 +3,7 @@ export declare const locatorRule: string;
 export declare const drillLocatorRule: string;
 export declare const fileUploadRule: string;
 export declare const formRequirementsRule: string;
+export declare const credentialsRule: string;
 export declare const protectionRule: string;
 export declare const dataProtectionRules: string;
 export declare const capabilityGroundingRule: string;

package/dist/src/ai/rules.js

@@ -138,6 +138,13 @@ export const formRequirementsRule = dedent `
   Before filling a form that persists data (create/update), read each control's requirements (required, type/format, length, placeholder/aria-describedby hints) from <page_aria> and page HTML — call context() if not visible — and enter values that satisfy them. Search/filter/sort forms that only change the view do not need this.
   </form_requirements>
 `;
+export const credentialsRule = dedent `
+  <credentials>
+  Sign in to an existing account only with credentials present in the provided context (message, knowledge, experience).
+  Never invent, guess, or try default, common, or placeholder credentials for an existing account.
+  If the required credentials are not provided, call stop() and name what is missing — do not submit the form.
+  </credentials>
+`;
 // in rage mode we do not protect from irreversible actions
 export const protectionRule = dedent `
   <important>

package/dist/src/utils/error-page.d.ts

@@ -3,6 +3,7 @@ import type { WebPageState } from '../state-manager.js';
 export type PageCondition = 'ok' | 'loading' | 'error';
 export declare function detectPageCondition(actionResult: ActionResult): PageCondition;
 export declare function isErrorPage(actionResult: ActionResult): boolean;
+export declare function isLoginPage(actionResult: ActionResult): boolean;
 export declare function getStateErrorPageError(state: WebPageState | null | undefined): ErrorPageError | null;
 export declare class ErrorPageError extends Error {
     readonly url: string;

package/dist/src/utils/error-page.js

@@ -1,8 +1,11 @@
 import { ActionResult } from '../action-result.js';
 import { isBodyEmpty } from './html.js';
+import { extractStatePath } from './url-matcher.js';
 const HTTP_ERRORS = ['400 Bad Request', '401 Unauthorized', '403 Forbidden', '404 Not Found', '405 Method Not Allowed', '408 Request Timeout', '500 Internal Server Error', '502 Bad Gateway', '503 Service Unavailable', '504 Gateway Timeout'];
 const SMALL_PAGE_THRESHOLD = 500;
 const LOADING_WORD = /\bloading\b/i;
+const PASSWORD_INPUT = /<input\b[^>]*\btype\s*=\s*["']?password\b/i;
+const AUTH_PATH = /\b(log[-_]?in|sign[-_]?in|auth)\b/i;
 export function detectPageCondition(actionResult) {
     if (actionResult.httpStatus && actionResult.httpStatus >= 400)
         return 'error';
@@ -32,6 +35,11 @@ export function detectPageCondition(actionResult) {
 export function isErrorPage(actionResult) {
     return detectPageCondition(actionResult) === 'error';
 }
+export function isLoginPage(actionResult) {
+    if (PASSWORD_INPUT.test(actionResult.html || ''))
+        return true;
+    return AUTH_PATH.test(extractStatePath(actionResult.url || '').split('?')[0]);
+}
 export function getStateErrorPageError(state) {
     if (!state)
         return null;

package/dist/src/utils/mdq/query.d.ts

@@ -57,6 +57,8 @@ export declare class MarkdownQuery {
     sectionsOf(candidates: MatchedRange[], segment: QuerySegment): MatchedRange[];
     itemsOf(candidates: MatchedRange[]): MatchedRange[];
     expandSections(matches: MatchedRange[]): MatchedRange[];
+    evaluate(candidates: MatchedRange[], expression: QueryExpression): MatchedRange[];
+    union(results: MatchedRange[][]): MatchedRange[];
     narrow(matches: MatchedRange[], segment: QuerySegment): MatchedRange[];
     filterByText(matches: MatchedRange[], segment: QuerySegment): MatchedRange[];
     matchText(text: string, matcher: TextMatcher): boolean;
@@ -77,7 +79,7 @@ export declare class MdqOperationError extends MdqError {
     constructor(message: string);
 }
 export declare function mdq(source: Markdown): MarkdownQuery;
-export declare function parseQuery(input: string): QuerySegment[];
+export declare function parseQuery(input: string): QueryExpression;
 export declare function buildTokenIndex(source: string): MatchedRange[];
 export type Markdown = string | MarkdownQuery;
 export type Matcher = string | RegExp | ((text: string) => boolean);
@@ -92,6 +94,7 @@ export interface TextMatcher {
     flags?: string;
     predicate?: (text: string) => boolean;
 }
+export type QueryExpression = QuerySegment[][][];
 export interface QuerySegment {
     selector: SelectorType;
     textMatch?: TextMatcher;

package/dist/src/utils/mdq/query.js

@@ -9,10 +9,13 @@ export class MarkdownQuery {
         this.matches = matches || buildTokenIndex(source);
     }
     query(selector, matcher) {
-        const segments = parseQuery(selector);
-        if (matcher !== undefined && segments.length > 0)
-            segments[segments.length - 1].textMatch = this.valueMatcher(matcher);
-        return new MarkdownQuery(this.source, this.run(this.expandSections(this.matches), segments));
+        const expression = parseQuery(selector);
+        for (const chain of expression.flat()) {
+            const last = chain.at(-1);
+            if (matcher !== undefined && last)
+                last.textMatch = this.valueMatcher(matcher);
+        }
+        return new MarkdownQuery(this.source, this.evaluate(this.expandSections(this.matches), expression));
     }
     section(matcher, options) {
         return this.query(`section${options?.depth || ''}`, matcher);
@@ -299,6 +302,27 @@ export class MarkdownQuery {
         }
         return expanded;
     }
+    evaluate(candidates, expression) {
+        const results = [];
+        for (const operands of expression) {
+            const matched = operands.map((chain) => this.run(candidates, chain));
+            if (matched.some((ranges) => ranges.length === 0))
+                continue;
+            results.push(...matched);
+        }
+        return this.union(results);
+    }
+    union(results) {
+        if (results.length === 1)
+            return results[0];
+        const unique = new Map();
+        for (const range of results.flat()) {
+            const key = `${range.start}:${range.length}:${Boolean(range.innerTokens)}`;
+            if (!unique.has(key))
+                unique.set(key, range);
+        }
+        return [...unique.values()].sort((a, b) => a.start - b.start || b.length - a.length);
+    }
     narrow(matches, segment) {
         if (segment.index !== null) {
             let index = segment.index;
@@ -390,10 +414,24 @@ export function mdq(source) {
     return new MarkdownQuery(String(source));
 }
 export function parseQuery(input) {
-    const segments = [];
+    const expression = [[[]]];
+    let chain = expression[0][0];
     SEGMENT.lastIndex = 0;
     while (SEGMENT.lastIndex < input.length) {
         const at = SEGMENT.lastIndex;
+        OPERATOR.lastIndex = at;
+        const operator = OPERATOR.exec(input);
+        if (operator) {
+            if (chain.length === 0)
+                throw new MdqSelectorError(`Empty selector before ${operator[1]}`, at);
+            chain = [];
+            if (operator[1] === '||')
+                expression.push([chain]);
+            if (operator[1] === '&&')
+                expression[expression.length - 1].push(chain);
+            SEGMENT.lastIndex = OPERATOR.lastIndex;
+            continue;
+        }
         const match = SEGMENT.exec(input);
         if (!match)
             throw new MdqSelectorError(`Unexpected character "${input[at]}" in selector`, at);
@@ -424,9 +462,11 @@ export function parseQuery(input) {
             if (to)
                 segment.slice.to = Number.parseInt(to, 10);
         }
-        segments.push(segment);
+        chain.push(segment);
     }
-    return segments;
+    if (expression.flat().length > 1 && chain.length === 0)
+        throw new MdqSelectorError('Empty selector after operator', input.length);
+    return expression;
 }
 export function buildTokenIndex(source) {
     const { body, offset } = MarkdownEditor.splitFrontmatter(source);
@@ -449,3 +489,4 @@ export function buildTokenIndex(source) {
 const SELECTOR_NAMES = new Set(['section', 'heading', 'paragraph', 'table', 'list', 'item', 'code', 'blockquote', 'hr', 'html', 'comment']);
 const TOKEN_ALIASES = { item: 'list_item' };
 const SEGMENT = /(\s*\.?)([A-Za-z]\w*)(?:\((!?)(~?)(?:"((?:[^"\\]|\\.)*)"|\/((?:[^/\\]|\\.)*)\/([a-z]*))\))?((?:\[[^\]]*\])*)\s*/y;
+const OPERATOR = /\s*(&&|\|\|)\s*/y;

package/docs/reference/commands.md

@@ -733,16 +733,16 @@ html: /home/you/.explorbot/sites/app.example.com/output/prima/2026-08-04T10-04-2
 
 ### Browsers and sessions
 
-Prima never launches a browser implicitly. Open one first:
+Prima never launches a browser. Open a playwright-cli session first, and check prima sees it:
 
 ```bash
 playwright-cli open https://app.example.com   # the session prima attaches to by default
-npx explorbot prima browser start             # a prima-owned browser instead
+npx explorbot prima browser                   # prints the session, or fails with the command to open one
 ```
 
-By default prima attaches to the playwright-cli browser of the current workspace and works on the tabs it already has open — driving the same session from both tools is the intended usage. Stopping prima disconnects from an attached browser; it never closes it. `prima browser list` shows both kinds of browser, and the `### Instance` block names the one you are on.
+By default prima attaches to the playwright-cli browser of the current workspace and works on the tabs it already has open — driving the same session from both tools is the intended usage. Stopping prima disconnects from an attached browser; it never closes it. The `### Instance` block names the browser you are on.
 
-Prima reaches every browser over a Playwright browser-server endpoint — a playwright-cli session, an `--endpoint`, or a `prima browser start` instance — and that client needs the Node build, which is what `npx explorbot prima` and the published `prima` bin run on. Driving a browser by running the CLI from source under Bun does not connect.
+Prima reaches every browser over a Playwright browser-server endpoint — a playwright-cli session, an `--endpoint`, or an `explorbot browser start` instance — and that client needs the Node build, which is what `npx explorbot prima` and the published `prima` bin run on. Driving a browser by running the CLI from source under Bun does not connect.
 
 Every command takes these:
 
@@ -769,8 +769,6 @@ A few commands add their own:
 | `research` | `--data` | Include data extraction in the map |
 | `research` | `--deep` | Expand hidden elements for a deeper map |
 | `research` | `--fresh` | Ignore the cached map and research the page again |
-| `browser start` | `-s, --show` / `--headless` | Launch the browser with or without a window |
-| `browser stop` | `--all` | Stop every running instance |
 
 Prima carries no logging flags of its own. `DEBUG` in front of a command prints everything the run does — config and browser attachment, every step as it executes, and the debug stream of the agents behind it:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",

package/src/ai/navigator.ts

@@ -13,6 +13,7 @@ import { type StateManager, normalizeUrl } from '../state-manager.js';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
+import { isLoginPage } from '../utils/error-page.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import { createDebug, pluralize, tag } from '../utils/logger.js';
 import { loop, pause } from '../utils/loop.js';
@@ -24,7 +25,7 @@ import type { Conversation } from './conversation.js';
 import { type Decision, JUDGE_PAGE_CAP, type Judge, UNDECIDED } from './judge.ts';
 import type { Provider } from './provider.js';
 import { Researcher } from './researcher.ts';
-import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
+import { actionRule, credentialsRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
 import { createLearnExperienceTool } from './tools.ts';
 
@@ -59,7 +60,7 @@ class Navigator implements Agent {
     NEVER use executeScript, executeAsyncScript, or any JS evaluation to change the URL, bypass redirects, or fake the page state.
     If the target URL redirects to an authentication/login page, DO NOT try to force the original URL. Instead:
       1. Look for credentials in the provided knowledge/hint context and perform a real login through the form.
-      2. If no credentials are available, ask the user for credentials or ask the user to log in manually.
+      2. If no credentials are available, stop and name the credentials that are missing. Never guess them.
     A redirect to /login, /sign_in, /auth, or similar is a signal that authentication is required — treat it as such, never as an obstacle to bypass.
   </constraints>
   `;
@@ -381,6 +382,9 @@ class Navigator implements Agent {
       experience = this.experienceTracker.renderExperienceFor(actionResult);
     }
 
+    let credentials = '';
+    if (isLoginPage(actionResult)) credentials = credentialsRule;
+
     return dedent`
       <message>
         ${message}
@@ -406,6 +410,8 @@ class Navigator implements Agent {
 
       ${unexpectedPopupRule}
 
+      ${credentials}
+
       ${RulesLoader.loadRules('navigator', ['multiple-locator', 'output'], actionResult.url || '').replace('{{maxAttempts}}', String(this.MAX_ATTEMPTS))}
 
       ${experience}

package/src/ai/rules.ts

@@ -147,6 +147,14 @@ export const formRequirementsRule = dedent`
   </form_requirements>
 `;
 
+export const credentialsRule = dedent`
+  <credentials>
+  Sign in to an existing account only with credentials present in the provided context (message, knowledge, experience).
+  Never invent, guess, or try default, common, or placeholder credentials for an existing account.
+  If the required credentials are not provided, call stop() and name what is missing — do not submit the form.
+  </credentials>
+`;
+
 // in rage mode we do not protect from irreversible actions
 export const protectionRule = dedent`
   <important>

package/src/utils/error-page.ts

@@ -1,11 +1,14 @@
 import { ActionResult } from '../action-result.js';
 import type { WebPageState } from '../state-manager.js';
 import { isBodyEmpty } from './html.js';
+import { extractStatePath } from './url-matcher.js';
 
 const HTTP_ERRORS = ['400 Bad Request', '401 Unauthorized', '403 Forbidden', '404 Not Found', '405 Method Not Allowed', '408 Request Timeout', '500 Internal Server Error', '502 Bad Gateway', '503 Service Unavailable', '504 Gateway Timeout'];
 
 const SMALL_PAGE_THRESHOLD = 500;
 const LOADING_WORD = /\bloading\b/i;
+const PASSWORD_INPUT = /<input\b[^>]*\btype\s*=\s*["']?password\b/i;
+const AUTH_PATH = /\b(log[-_]?in|sign[-_]?in|auth)\b/i;
 
 export type PageCondition = 'ok' | 'loading' | 'error';
 
@@ -40,6 +43,11 @@ export function isErrorPage(actionResult: ActionResult): boolean {
   return detectPageCondition(actionResult) === 'error';
 }
 
+export function isLoginPage(actionResult: ActionResult): boolean {
+  if (PASSWORD_INPUT.test(actionResult.html || '')) return true;
+  return AUTH_PATH.test(extractStatePath(actionResult.url || '').split('?')[0]);
+}
+
 export function getStateErrorPageError(state: WebPageState | null | undefined): ErrorPageError | null {
   if (!state) return null;
   const actionResult = ActionResult.fromState(state);

package/src/utils/mdq/query.ts

@@ -13,9 +13,12 @@ export class MarkdownQuery {
   }
 
   query(selector: string, matcher?: Matcher): MarkdownQuery {
-    const segments = parseQuery(selector);
-    if (matcher !== undefined && segments.length > 0) segments[segments.length - 1].textMatch = this.valueMatcher(matcher);
-    return new MarkdownQuery(this.source, this.run(this.expandSections(this.matches), segments));
+    const expression = parseQuery(selector);
+    for (const chain of expression.flat()) {
+      const last = chain.at(-1);
+      if (matcher !== undefined && last) last.textMatch = this.valueMatcher(matcher);
+    }
+    return new MarkdownQuery(this.source, this.evaluate(this.expandSections(this.matches), expression));
   }
 
   section(matcher?: Matcher, options?: SelectorOptions): MarkdownQuery {
@@ -364,6 +367,27 @@ export class MarkdownQuery {
     return expanded;
   }
 
+  private evaluate(candidates: MatchedRange[], expression: QueryExpression): MatchedRange[] {
+    const results: MatchedRange[][] = [];
+    for (const operands of expression) {
+      const matched = operands.map((chain) => this.run(candidates, chain));
+      if (matched.some((ranges) => ranges.length === 0)) continue;
+      results.push(...matched);
+    }
+    return this.union(results);
+  }
+
+  private union(results: MatchedRange[][]): MatchedRange[] {
+    if (results.length === 1) return results[0];
+
+    const unique = new Map<string, MatchedRange>();
+    for (const range of results.flat()) {
+      const key = `${range.start}:${range.length}:${Boolean(range.innerTokens)}`;
+      if (!unique.has(key)) unique.set(key, range);
+    }
+    return [...unique.values()].sort((a, b) => a.start - b.start || b.length - a.length);
+  }
+
   private narrow(matches: MatchedRange[], segment: QuerySegment): MatchedRange[] {
     if (segment.index !== null) {
       let index = segment.index;
@@ -449,12 +473,24 @@ export function mdq(source: Markdown): MarkdownQuery {
   return new MarkdownQuery(String(source));
 }
 
-export function parseQuery(input: string): QuerySegment[] {
-  const segments: QuerySegment[] = [];
+export function parseQuery(input: string): QueryExpression {
+  const expression: QueryExpression = [[[]]];
+  let chain = expression[0][0];
   SEGMENT.lastIndex = 0;
 
   while (SEGMENT.lastIndex < input.length) {
     const at = SEGMENT.lastIndex;
+    OPERATOR.lastIndex = at;
+    const operator = OPERATOR.exec(input);
+    if (operator) {
+      if (chain.length === 0) throw new MdqSelectorError(`Empty selector before ${operator[1]}`, at);
+      chain = [];
+      if (operator[1] === '||') expression.push([chain]);
+      if (operator[1] === '&&') expression[expression.length - 1].push(chain);
+      SEGMENT.lastIndex = OPERATOR.lastIndex;
+      continue;
+    }
+
     const match = SEGMENT.exec(input);
     if (!match) throw new MdqSelectorError(`Unexpected character "${input[at]}" in selector`, at);
 
@@ -484,10 +520,11 @@ export function parseQuery(input: string): QuerySegment[] {
       if (to) segment.slice.to = Number.parseInt(to, 10);
     }
 
-    segments.push(segment);
+    chain.push(segment);
   }
 
-  return segments;
+  if (expression.flat().length > 1 && chain.length === 0) throw new MdqSelectorError('Empty selector after operator', input.length);
+  return expression;
 }
 
 export function buildTokenIndex(source: string): MatchedRange[] {
@@ -516,6 +553,8 @@ const TOKEN_ALIASES: Record<string, string> = { item: 'list_item' };
 
 const SEGMENT = /(\s*\.?)([A-Za-z]\w*)(?:\((!?)(~?)(?:"((?:[^"\\]|\\.)*)"|\/((?:[^/\\]|\\.)*)\/([a-z]*))\))?((?:\[[^\]]*\])*)\s*/y;
 
+const OPERATOR = /\s*(&&|\|\|)\s*/y;
+
 export type Markdown = string | MarkdownQuery;
 
 export type Matcher = string | RegExp | ((text: string) => boolean);
@@ -534,6 +573,8 @@ export interface TextMatcher {
   predicate?: (text: string) => boolean;
 }
 
+export type QueryExpression = QuerySegment[][][];
+
 export interface QuerySegment {
   selector: SelectorType;
   textMatch?: TextMatcher;