explorbot 0.2.3 → 0.2.5

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

@@ -14,5 +14,17 @@ export function isFunctionExpression(expr) {
     return { valid: true };
 }
 export function toCodeceptWrapper(expr) {
-    return `I.usePlaywrightTo('pw', async (playwright) => (${expr.trim()})(playwright))`;
+    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

@@ -19,9 +19,8 @@ export function readDescriptors(dir = registryDir()) {
     }
     return descriptors;
 }
-export function selectDescriptor(descriptors, opts) {
-    const workspaceDir = path.resolve(opts.workspaceDir);
-    const candidates = descriptors.filter((descriptor) => path.resolve(descriptor.workspaceDir) === workspaceDir);
+export function selectDescriptor(descriptors, opts = {}) {
+    const candidates = descriptors;
     if (!candidates.length)
         return { candidates };
     if (opts.title) {
@@ -53,13 +52,13 @@ function parseDescriptor(file) {
     catch {
         return null;
     }
-    if (!data?.endpoint || !data?.title || !data?.workspaceDir)
+    if (!data?.endpoint || !data?.title)
         return null;
     return {
         file,
         title: data.title,
         endpoint: data.endpoint,
-        workspaceDir: data.workspaceDir,
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -19,6 +19,7 @@
   },
   "files": [
     "dist/",
+    "docs/",
     "src/**/*.ts",
     "src/**/*.tsx",
     "bin/**/*.ts",
@@ -119,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;
@@ -45,6 +46,7 @@ declare class Action {
     exitIframe(): Promise<void>;
     getActor(): CodeceptJS.I;
     getActionResult(): ActionResult | null;
+    restorePageTimeout(): void;
     waitForPageReadiness(page: any): Promise<void>;
 }
 export default Action;

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;
@@ -47,6 +50,7 @@ class Action {
             await this.actor.saveScreenshot(filename);
             if (currentState)
                 currentState.screenshotFile = filename;
+            tag('data').log('screenshot', { path: outputPath('states', filename) });
             return filename;
         }
         catch (err) {
@@ -94,7 +98,10 @@ class Action {
                 const screenshotPath = join(statesDir, filename);
                 screenshotFile = await page
                     ?.screenshot({ path: screenshotPath, fullPage: true })
-                    .then(() => filename)
+                    .then(() => {
+                    tag('data').log('screenshot', { path: screenshotPath });
+                    return filename;
+                })
                     .catch((err) => {
                     debugLog('Screenshot failed, continuing without it:', err);
                     return undefined;
@@ -120,9 +127,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 +154,7 @@ class Action {
                 iframeSnapshots,
                 ariaSnapshot,
                 ariaSnapshotFile,
+                focusedElement,
                 iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
             });
             this.stateManager.updateState(result, codeBlock);
@@ -272,16 +282,19 @@ class Action {
             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 +313,7 @@ class Action {
             throw err;
         }
         finally {
+            this.restorePageTimeout();
             detachMainDocumentResponse();
             if (groupId)
                 await this.recorder.endAction();
@@ -346,6 +360,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 +425,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/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({
@@ -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

@@ -15,6 +15,7 @@ declare class Navigator implements Agent {
     experienceTracker: ExperienceTracker;
     hooksRunner: HooksRunner;
     MAX_ATTEMPTS: number;
+    lastFailureReason: string | null;
     systemPrompt: string;
     freeSailSystemPrompt: string;
     explorer: Explorer;
@@ -25,10 +26,16 @@ declare class Navigator implements Agent {
     get verifyTimeout(): number;
     getBaseOrigin(): string | null;
     getComparableCurrentUrl(stateManager: any, expectedUrl: string): string;
+    comparableUrl(state: {
+        url?: string;
+        fullUrl?: string;
+    }, expectedUrl: string): string;
     isSameExpectedOrigin(expectedUrl: string, stateManager: any): boolean;
     isOnExpectedPage(expectedUrl: string, stateManager: any): boolean;
     visit(url: string): Promise<void>;
     visitOnce(url: string): Promise<void>;
+    navigationError(url: string, fallback: string): Error;
+    failureReason(stopReason: string | null, knowledge: string, url: string): string | null;
     resolveState(message: string, actionResult: ActionResult, opts?: {
         action?: Action;
         expectedUrl?: string;
@@ -37,6 +44,20 @@ declare class Navigator implements Agent {
             error?: string;
         }) => void;
     }): Promise<boolean>;
+    buildResolutionPrompt(message: string, actionResult: ActionResult): Promise<string>;
+    buildRetryFeedback(failures: BatchFailure[], includeHtml: boolean, actionResult: ActionResult): Promise<string>;
+    executeAttempt(action: Action, codeBlock: string, message: string): Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    verifyNavigation(action: Action, expectedUrl: string): Promise<{
+        freshState: ActionResult;
+        urlMatches: boolean;
+    }>;
+    ariaDiff(freshState: ActionResult, previous: ActionResult): Promise<string | null>;
+    saveFlow(message: string, expectedUrl: string | undefined, actionResult: ActionResult, progressBlocks: string[]): void;
+    rescueDelayedRedirect(action: Action, expectedUrl: string): Promise<boolean>;
+    askUserToResolve(action: Action, message: string, expectedUrl: string | undefined, stopReason: string | null): Promise<boolean>;
     buildExperienceTools(): {
         learnExperience: unknown;
     } | undefined;
@@ -50,6 +71,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;
@@ -59,4 +82,15 @@ declare class Navigator implements Agent {
     }>;
     checkAlreadyVerified(aiResponse: string, actionResult: ActionResult): boolean;
 }
+type BatchFailure = {
+    code: string;
+    error: string;
+    ariaChanges?: string | null;
+    urlAfter?: string;
+};
+export type AssertionResult = {
+    code: string;
+    passed: boolean;
+    proof: string[];
+};
 export { Navigator };