explorbot 0.2.2 → 0.2.4

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

@@ -0,0 +1,30 @@
+const FUNCTION_SHAPE = /^(async\s+)?(function\b|\()/;
+export function isFunctionExpression(expr) {
+    const trimmed = expr.trim();
+    if (!trimmed)
+        return { valid: false, error: 'empty expression; pass a function like ({ page }) => ...' };
+    if (!FUNCTION_SHAPE.test(trimmed))
+        return { valid: false, error: 'expression must be a function like ({ page }) => ... destructuring the playwright objects it needs' };
+    try {
+        new Function(`return (${trimmed})`);
+    }
+    catch (e) {
+        return { valid: false, error: `not a valid function expression: ${e.message}` };
+    }
+    return { valid: true };
+}
+export function toCodeceptWrapper(expr) {
+    return `return I.usePlaywrightTo('pw', async (playwright) => (${expr.trim()})(playwright))`;
+}
+export function takePwValue(held) {
+    if (held === undefined || held === null)
+        return undefined;
+    if (typeof held === 'string')
+        return held;
+    try {
+        return JSON.stringify(held, null, 2);
+    }
+    catch {
+        return String(held);
+    }
+}

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

@@ -0,0 +1,65 @@
+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 candidates = descriptors;
+    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)
+        return null;
+    return {
+        file,
+        title: data.title,
+        endpoint: data.endpoint,
+        workspaceDir: data.workspaceDir || '',
+        browserName: data.browser?.browserName || DEFAULT_BROWSER,
+        playwrightLib: data.playwrightLib || '',
+    };
+}

package/dist/boat/prima/src/session-log.js

@@ -0,0 +1,108 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { outputPath } from "../../../src/config.js";
+import { safeFilename } from "../../../src/utils/strings.js";
+import { renderEnvelope } from "./envelope.js";
+const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped' };
+export function sessionsDir() {
+    return outputPath('prima', 'sessions');
+}
+export function sessionFile(key) {
+    return path.join(sessionsDir(), `${safeFilename(key)}.jsonl`);
+}
+export function latestSessionFile() {
+    const dir = sessionsDir();
+    if (!existsSync(dir))
+        return null;
+    const files = readdirSync(dir)
+        .filter((name) => name.endsWith('.jsonl'))
+        .map((name) => path.join(dir, name))
+        .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+    return files[0] || null;
+}
+export function recordCommand(file, session, envelope, durationMs) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    if (recordedEndpoint(file) !== session.endpoint)
+        writeFileSync(file, jsonLine({ action: 'createRun', endpoint: session.endpoint, params: { title: session.title } }), 'utf-8');
+    appendFileSync(file, jsonLine({ action: 'addTest', testId: commandTest(envelope, durationMs) }), 'utf-8');
+}
+export function readSession(file) {
+    const entries = readEntries(file);
+    const run = entries.find((entry) => entry.action === 'createRun');
+    const tests = entries.filter((entry) => entry.action === 'addTest').map((entry) => entry.testId);
+    return { title: run?.params?.title || 'prima session', tests };
+}
+function commandTest(envelope, durationMs) {
+    let status = 'failed';
+    if (envelope.ok)
+        status = 'passed';
+    const test = {
+        rid: envelope.status,
+        title: envelope.command,
+        suite_title: 'Prima session',
+        status,
+        file: '<prima>',
+        description: [`page: ${envelope.page.url}`, envelope.stepFiles && `artifacts: ${envelope.stepFiles}`].filter(Boolean).join('\n'),
+        code: (envelope.used || []).join('\n'),
+        steps: commandSteps(envelope),
+        logs: renderEnvelope(envelope),
+        time: Math.round(durationMs),
+    };
+    if (envelope.failure)
+        test.error = { message: envelope.failure.error };
+    return test;
+}
+function commandSteps(envelope) {
+    const steps = [];
+    for (const step of envelope.steps || []) {
+        const entry = { category: 'user', title: step.label, status: 'passed', duration: 0, log: step.proof };
+        if (!step.ok) {
+            entry.status = 'failed';
+            entry.error = step.proof;
+        }
+        steps.push(entry);
+    }
+    for (const expectation of envelope.expectations || []) {
+        const entry = { category: 'user', title: `expected: ${expectation.text}`, status: EXPECTATION_STATUS[expectation.status], duration: 0 };
+        if (expectation.status === 'failed')
+            entry.error = 'the run did not reach this outcome';
+        steps.push(entry);
+    }
+    for (const assertion of envelope.assertions || []) {
+        const entry = { category: 'user', title: assertion.code, status: 'passed', duration: 0, log: assertion.proof.join('\n') };
+        if (!assertion.passed) {
+            entry.status = 'failed';
+            entry.error = 'the assertion did not hold on the page';
+        }
+        steps.push(entry);
+    }
+    return steps;
+}
+function recordedEndpoint(file) {
+    const [first] = readEntries(file);
+    return first?.endpoint || null;
+}
+function readEntries(file) {
+    if (!existsSync(file))
+        return [];
+    const entries = [];
+    for (const line of readFileSync(file, 'utf-8').split('\n')) {
+        if (!line.trim())
+            continue;
+        const entry = parseLine(line);
+        if (entry)
+            entries.push(entry);
+    }
+    return entries;
+}
+function parseLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+function jsonLine(entry) {
+    return `${JSON.stringify(entry)}\n`;
+}

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.4",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -14,10 +14,12 @@
     }
   },
   "bin": {
-    "explorbot": "./dist/bin/explorbot-cli.js"
+    "explorbot": "./dist/bin/explorbot-cli.js",
+    "prima": "./dist/boat/prima/bin/prima-cli.js"
   },
   "files": [
     "dist/",
+    "docs/",
     "src/**/*.ts",
     "src/**/*.tsx",
     "bin/**/*.ts",
@@ -25,6 +27,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"
@@ -115,7 +120,7 @@
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.60",
+    "playwright": "^1.62",
     "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",

package/dist/rules/navigator/verification-actions.md

@@ -105,9 +105,29 @@ Checks that page source does NOT contain expected text.
   I.dontSeeInSource('error-class');
 </example>
 
+### Asserting the state of a control
+
+State means disabled, checked, readonly, required, selected, expanded. A presence assertion says
+nothing about it, so assert it with an attribute selector:
+
+<example>
+  I.seeElement('button[aria-label="Submit"][disabled]');
+  I.dontSeeElement('button[aria-label="Submit"][disabled]');
+  I.seeElement('input[name="accept"][checked]');
+  I.seeElement('button[aria-label="Details"][aria-expanded="true"]');
+</example>
+
+Use I.seeElement for the state you expect and I.dontSeeElement for the state you expect to be
+absent — that pair expresses both directions.
+
+I.seeAttributesOnElements(<locator>, { disabled: true }) also exists, but only takes a state that
+must be PRESENT and does not resolve reliably against a role/text locator. Prefer the selector form above.
+
 <verification_rules>
 Be strict in assertions to avoid false positives.
 Prefer I.seeElement() with ARIA locators - most reliable.
+For a claim about a control's state, assert it with an attribute selector — presence of the element is not evidence of its state.
+If no assertion above can express the claim, say so instead of proposing an assertion that checks something weaker.
 I.see() and I.dontSee() MUST include context parameter.
 For input field values, ALWAYS use I.seeInField() — never check value via CSS attribute selectors or I.seeInSource.
 Prefer text locators (label, name, placeholder) for form fields: I.seeInField('Search', 'value') over I.seeInField('input[name="search"]', 'value').

package/dist/src/action-result.d.ts

@@ -24,6 +24,7 @@ interface ActionResultData extends WebPageState {
     }>;
     ariaSnapshot?: string | null;
     ariaSnapshotFile?: string;
+    focusedElement?: FocusedElement | null;
     iframeURL?: string;
     links?: Link[];
 }
@@ -69,6 +70,7 @@ export declare class ActionResult implements ActionResultData {
     snapshotCache: TTLCache<string>;
     readonly logFile: string | undefined;
     readonly ariaSnapshotFile: string | undefined;
+    readonly focusedElement: FocusedElement | null;
     _ariaSnapshot: string | null | undefined;
     _lastExtractedHtml: string | undefined;
     notes: string[];
@@ -128,4 +130,9 @@ export declare class Diff {
     get htmlDiff(): HtmlDiffResult | null;
     calculate(): Promise<void>;
 }
+export interface FocusedElement {
+    role: string;
+    name: string;
+    value?: string;
+}
 export {};

package/dist/src/action-result.js

@@ -30,6 +30,7 @@ export class ActionResult {
     snapshotCache = new TTLCache();
     logFile = undefined;
     ariaSnapshotFile = undefined;
+    focusedElement = null;
     _ariaSnapshot = undefined;
     _lastExtractedHtml = undefined;
     notes = [];
@@ -61,6 +62,9 @@ export class ActionResult {
         if (data.ariaSnapshotFile !== undefined) {
             this.ariaSnapshotFile = data.ariaSnapshotFile;
         }
+        if (data.focusedElement !== undefined) {
+            this.focusedElement = data.focusedElement;
+        }
         // Store HTML in a private property if provided
         if (data.html !== undefined) {
             this._html = data.html;

package/dist/src/action.d.ts

@@ -15,6 +15,7 @@ declare class Action {
         name: string;
         args: any[];
     }>;
+    lastValue: unknown;
     recorder?: PlaywrightRecorder;
     recovery: RecoveryRunner;
     mainDocumentStatus: number | undefined;
@@ -24,7 +25,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,12 +41,16 @@ 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;
     getActionResult(): ActionResult | null;
+    restorePageTimeout(): void;
     waitForPageReadiness(page: any): Promise<void>;
 }
 export default Action;
 export type RecoveryRunner = <T>(fn: () => Promise<T>) => Promise<T>;
+export interface ExecuteOptions {
+    verbatim?: boolean;
+}

package/dist/src/action.js

@@ -15,6 +15,8 @@ import { safeFilename } from "./utils/strings.js";
 import { codeceptJSSandbox, hasPlaywrightCommands, playwrightSandbox, sanitizeCodeBlock } from "./utils/web-sandbox.js";
 const debugLog = createDebug('explorbot:action');
 const CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS = 3;
+const DEFAULT_ACTION_TIMEOUT = 3000;
+const DEFAULT_PAGE_TIMEOUT = 3000;
 class Action {
     actor;
     stateManager;
@@ -26,6 +28,7 @@ class Action {
     playwrightHelper;
     playwrightGroupId = null;
     assertionSteps = [];
+    lastValue;
     recorder;
     recovery;
     mainDocumentStatus = undefined;
@@ -57,8 +60,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 {
@@ -120,9 +123,11 @@ class Action {
             const iframeSnapshots = await this.captureIframeSnapshots(html);
             let ariaSnapshot = null;
             let ariaSnapshotFile = undefined;
+            let focusedElement = null;
             try {
                 const page = this.playwrightHelper.page;
                 ariaSnapshot = await page.locator('body').ariaSnapshot();
+                focusedElement = await page.evaluate(readFocusedElement);
             }
             catch (err) {
                 debugLog('ARIA snapshot failed:', err instanceof Error ? `${err.message}\n${err.stack}` : err);
@@ -145,6 +150,7 @@ class Action {
                 iframeSnapshots,
                 ariaSnapshot,
                 ariaSnapshotFile,
+                focusedElement,
                 iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
             });
             this.stateManager.updateState(result, codeBlock);
@@ -251,7 +257,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,23 +271,26 @@ 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) {
                 throw new Error('No valid I.* or page.* commands found in code block');
             }
+            this.playwrightHelper?.page?.setDefaultTimeout(this.config.action?.timeout ?? DEFAULT_ACTION_TIMEOUT);
             if (isPlaywright) {
                 const page = this.playwrightHelper.page;
                 await playwrightSandbox(page, sanitizedCode);
                 await sleep(this.config.action?.delay || 500);
             }
             else {
-                codeceptJSSandbox(this.actor, sanitizedCode);
+                const returned = codeceptJSSandbox(this.actor, sanitizedCode);
                 await recorder.add(() => sleep(this.config.action?.delay || 500));
                 await recorder.promise();
+                this.lastValue = await returned;
             }
+            this.restorePageTimeout();
             if (executedSteps.length > 0) {
                 codeString = executedSteps.join('\n');
             }
@@ -300,6 +309,7 @@ class Action {
             throw err;
         }
         finally {
+            this.restorePageTimeout();
             detachMainDocumentResponse();
             if (groupId)
                 await this.recorder.endAction();
@@ -346,6 +356,9 @@ class Action {
     getActionResult() {
         return this.actionResult;
     }
+    restorePageTimeout() {
+        this.playwrightHelper?.page?.setDefaultTimeout(this.config.playwright.timeout ?? DEFAULT_PAGE_TIMEOUT);
+    }
     async waitForPageReadiness(page) {
         await waitForPageReadiness(page, {
             timeout: this.config.playwright.waitForTimeout,
@@ -408,3 +421,25 @@ const detachStepLogger = (listener) => {
     codeceptjs.event.dispatcher.off(codeceptjs.event.step.passed, listener);
     codeceptjs.event.dispatcher.off(codeceptjs.event.step.failed, listener);
 };
+const readFocusedElement = () => {
+    const el = document.activeElement;
+    if (!el || el === document.body)
+        return null;
+    const tag = el.tagName.toLowerCase();
+    const textish = new Set(['text', 'search', 'email', 'password', 'url', 'tel', 'number']);
+    let role = el.getAttribute('role') || tag;
+    if (tag === 'textarea' || el.isContentEditable)
+        role = 'textbox';
+    if (tag === 'input' && textish.has(el.type))
+        role = 'textbox';
+    if (tag === 'select')
+        role = 'combobox';
+    if (tag === 'a')
+        role = 'link';
+    const label = el.getAttribute('aria-label') || el.getAttribute('placeholder') || el.labels?.[0]?.textContent || el.textContent || '';
+    const focused = { role, name: label.trim().slice(0, 80) };
+    const value = el.value ?? el.textContent;
+    if (typeof value === 'string' && value)
+        focused.value = value.slice(0, 200);
+    return focused;
+};

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

@@ -16,7 +16,7 @@ export function WithWebMode(Base) {
                 navigator: ctx.explorBot.agentNavigator(),
             });
             const { see, context, visualClick, learnExperience } = agentTools;
-            return {
+            const tools = {
                 navigate: tool({
                     description: 'Navigate to a URL or page description using AI-powered navigation.',
                     inputSchema: z.object({
@@ -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 };
@@ -114,11 +114,14 @@ export function WithWebMode(Base) {
                     },
                 }),
                 ...codeceptTools,
-                see,
                 context,
-                visualClick,
                 learnExperience,
             };
+            if (see)
+                tools.see = see;
+            if (visualClick)
+                tools.visualClick = visualClick;
+            return tools;
         }
         webModePrompt() {
             return dedent `

package/dist/src/ai/captain.js

@@ -15,6 +15,7 @@ import { WithWebMode } from "./captain/web-mode.js";
 import { toolExecutionLabel } from './conversation.js';
 import { Researcher } from "./researcher.js";
 import { TaskAgent } from "./task-agent.js";
+import { withdrawVisionTools } from "./tools.js";
 const MAX_STEPS = 15;
 const CaptainBase = WithTestMode(WithWebMode(WithIdleMode(TaskAgent)));
 export class Captain extends CaptainBase {
@@ -389,6 +390,7 @@ export class Captain extends CaptainBase {
                 stop();
                 return;
             }
+            withdrawVisionTools(tools);
             const currentState = stateManager.getCurrentState();
             if (!currentState && this.getMode() !== 'idle') {
                 stop();

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;
@@ -46,6 +50,8 @@ declare class Navigator implements Agent {
     } | null>;
     verifyState(message: string, actionResult: ActionResult): Promise<{
         verified: boolean;
+        inexpressible: boolean;
+        results: AssertionResult[];
         successfulCodes: string[];
         assertionSteps: Array<{
             name: string;
@@ -55,4 +61,9 @@ declare class Navigator implements Agent {
     }>;
     checkAlreadyVerified(aiResponse: string, actionResult: ActionResult): boolean;
 }
+export type AssertionResult = {
+    code: string;
+    passed: boolean;
+    proof: string[];
+};
 export { Navigator };