explorbot 0.5.2 → 0.5.4

package/bin/explorbot-cli.ts

@@ -56,6 +56,7 @@ interface CLIOptions {
   debug?: boolean;
   config?: string;
   path?: string;
+  baseUrl?: string;
   show?: boolean;
   headless?: boolean;
   incognito?: boolean;
@@ -66,6 +67,7 @@ interface CLIOptions {
 function buildExplorBotOptions(from: string | undefined, options: CLIOptions): ExplorBotOptions {
   return {
     from,
+    baseUrl: options.baseUrl,
     verbose: options.verbose || options.debug,
     config: options.config,
     path: options.path,
@@ -83,6 +85,7 @@ function addCommonOptions(cmd: Command): Command {
     .option('--debug', 'Enable debug logging (same as --verbose)')
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
+    .option('--base-url <url>', 'Run against this URL: its path scopes relative paths (plans, commands, saved tests on rerun), its query params ride along with every page load')
     .option('-s, --show', 'Show browser window')
     .option('--headless', 'Run browser in headless mode')
     .option('--incognito', 'Run without recording experiences')

package/boat/doc-collector/src/config.ts

@@ -171,6 +171,7 @@ interface DocbotConfig {
     minCanActions?: number;
     minInteractiveElements?: number;
     interactive?: boolean;
+    research?: 'light' | 'full';
   };
 }
 

package/boat/doc-collector/src/docbot.ts

@@ -118,9 +118,11 @@ class DocBot {
           }
         }
 
+        const light = this.useLightResearch();
         const research = await this.explorBot.agentResearcher().research(state, {
-          screenshot: this.shouldUseScreenshots(),
+          screenshot: !light && this.shouldUseScreenshots(),
           force: true,
+          light,
         });
         const pagePath = this.getPageFilePath(state.url);
         const captureState = this.shouldUseScreenshots()
@@ -221,6 +223,13 @@ class DocBot {
     return true;
   }
 
+  private useLightResearch(): boolean {
+    const research = this.config.docs?.research;
+    if (research === 'light') return true;
+    if (research === 'full') return false;
+    return this.config.docs?.interactive !== true;
+  }
+
   private shouldCollapseTemplates(override?: boolean): boolean {
     if (override === false) {
       return false;

package/boat/prima/src/envelope.ts

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import type { SettledExpectation } from '../../../src/test-plan.ts';
 
 export const STATUS_FILE = 'status.json';
 
@@ -26,16 +27,16 @@ export interface EnvelopeData {
   ok: boolean;
   command: string;
   used?: string[];
-  page: { url: string; previousUrl?: string; title: string; state: string; visits: number };
+  page: { url: string; previousUrl?: string; redirectedFrom?: string; title: string; state: string; visits: number };
   changes?: string | null;
   steps?: Array<{ label: string; ok: boolean; unconfirmed?: boolean; proof: string }>;
-  expectations?: Array<{ text: string; status: 'passed' | 'failed' | 'unverified' | 'contradiction'; evidence?: string }>;
+  expectations?: SettledExpectation[];
   warning?: string;
   stepFiles?: string;
   value?: string;
   answer?: string;
   research?: string;
-  assertions?: Array<{ code: string; passed: boolean; proof: string[] }>;
+  assertions?: Array<{ code: string; passed: boolean; proof: string[]; error?: string }>;
   failure?: { error: string; compactAria?: string };
   instance: InstanceInfo;
   status?: string;
@@ -88,12 +89,13 @@ function renderResult(data: EnvelopeData): string {
 }
 
 function renderPage(data: EnvelopeData): string {
-  const { url, previousUrl, title, state, visits } = data.page;
+  const { url, previousUrl, redirectedFrom, title, state, visits } = data.page;
   const urlLabel = `url: ${url}`;
   const stateLabel = `state: ${state}`;
   const width = Math.max(urlLabel.length, stateLabel.length) + 3;
   let changedMarker = '';
   if (previousUrl && previousUrl !== url) changedMarker = `(changed: ${previousUrl} → ${url})`;
+  if (redirectedFrom) changedMarker = `(redirected: ${redirectedFrom} → ${url})`;
   const lines = [align(urlLabel, changedMarker, width), `title: ${title}`, align(stateLabel, `(visit #${visits})`, width)];
   return section('Page', lines.join('\n'));
 }
@@ -129,7 +131,8 @@ function renderExpectations(data: EnvelopeData): string | null {
   const lines: string[] = [];
   data.expectations.forEach((expectation, index) => {
     lines.push(`${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
-    if (expectation.status !== 'contradiction' && expectation.status !== 'failed') return;
+    if (expectation.resolution) lines.push(`      resolved: ${expectation.resolution}`);
+    if (!expectation.contradicted && !expectation.failed && !expectation.resolution) return;
     for (const line of (expectation.evidence || '').split('\n').filter(Boolean)) lines.push(`      ${line}`);
   });
   return section('Expected outcomes', lines.join('\n'));
@@ -153,7 +156,10 @@ function renderOutcome(data: EnvelopeData): string | null {
       .map((line) => line.trim())
       .filter((line) => line && !line.startsWith('//'))
       .join(' ');
-    return `${code}  => ${assertion.passed ? 'PASSED' : 'FAILED'}`;
+    if (assertion.passed) return `${code}  => PASSED`;
+    const reason = assertion.error?.split('\n').find(Boolean);
+    if (!reason) return `${code}  => FAILED`;
+    return `${code}  => FAILED\n      ${reason}`;
   });
 
   const proof = data.assertions.flatMap((assertion) => assertion.proof);

package/boat/prima/src/help.ts

@@ -27,8 +27,10 @@ export const checkHelp = dedent`
               ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
               "not verified" means never checked, not false.
   Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
-  CONTRADICTION means screenshot and log disagree; judge the html, aria and
-  screenshot under ### Artifacts yourself.
+  When screenshot and log disagree, the page structure breaks the tie: the outcome
+  becomes PASSED or FAILED with a "resolved:" line naming the side that was wrong.
+  CONTRADICTION remains when it cannot be broken, or when the page holds something
+  it does not display; judge the html, aria and screenshot under ### Artifacts yourself.
   ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
   reported as such rather than as an app failure.
   Side issues found on the way go under ### Answer, not as step failures.

package/boat/prima/src/prima.ts

@@ -239,6 +239,10 @@ export class Prima {
 
     if (aiError) return this.failureEnvelope(command, aiError, previousState);
 
+    if (trace.length && ledger.some((entry) => entry.status === 'open')) {
+      await this.judgeUnreportedInstructions(ledger, trace);
+    }
+
     if (trace.length && ledger.some((entry) => entry.status === 'open')) {
       await this.settleLedger(conversation, provider, ledger, trace);
     }
@@ -310,6 +314,32 @@ export class Prima {
     return true;
   }
 
+  private async judgeUnreportedInstructions(ledger: LedgerEntry[], trace: Array<{ label: string; ok: boolean; proof: string }>): Promise<void> {
+    const judge = this.bot.judge?.();
+    if (!judge) return;
+
+    const current = this.bot.stateManager().getCurrentState();
+    let page = '';
+    if (current) page = ((await this.refAriaSnapshot(ActionResult.fromState(current))) || '').slice(0, JUDGE_PAGE_CAP);
+    const actions = trace
+      .map((step) => {
+        if (step.ok) return `ok ${step.label}`;
+        return `FAIL ${step.label}`;
+      })
+      .join('\n');
+    const state = { actions, finalUrl: current?.url || '', finalPage: page };
+
+    const open = ledger.filter((entry) => entry.status === 'open');
+    const decisions = await Promise.all(open.map((entry) => judge.decide(`The actions that ran and the final page show this instruction was carried out: ${entry.text}`, null, state)));
+
+    open.forEach((entry, index) => {
+      if (decisions[index].rejected) return;
+      entry.status = 'done';
+      entry.proof = 'judged from the actions that ran and the final page';
+      trace.push({ label: `done: ${entry.text}`, ok: true, proof: entry.proof });
+    });
+  }
+
   private async settleLedger(conversation: any, provider: any, ledger: LedgerEntry[], trace: Array<{ label: string; ok: boolean; proof: string }>): Promise<void> {
     conversation.addUserText(dedent`
       The run is over and these instructions were never reported:
@@ -376,8 +406,8 @@ export class Prima {
       envelope.warning = 'These outcomes were settled from the run log alone — no screenshot backed them. Set ai.visionModel, or check anything visual with prima ask.';
     }
 
-    const unreached = envelope.expectations.filter((expectation) => expectation.status === 'failed');
-    const contradicted = envelope.expectations.filter((expectation) => expectation.status === 'contradiction');
+    const unreached = envelope.expectations.filter((expectation) => expectation.failed);
+    const contradicted = envelope.expectations.filter((expectation) => expectation.contradicted);
     envelope.ok = !unreached.length && !contradicted.length;
 
     const problems = [...unreached.map((expectation) => `not reached: ${expectation.text}`), ...contradicted.map((expectation) => `the picture and the run disagree about: ${expectation.text}`)];
@@ -455,9 +485,10 @@ export class Prima {
     }
 
     let navigationError: unknown = null;
+    let arrived = true;
 
     try {
-      await this.bot.agentNavigator().visit(target);
+      arrived = await this.bot.agentNavigator().visit(target, { recover: !isUrl });
     } catch (error) {
       navigationError = error;
     }
@@ -467,7 +498,9 @@ export class Prima {
     const used: string[] = [];
     if (isUrl) used.push(code);
     const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
-    return this.successEnvelope(command, used, result, previousState);
+    const envelope = await this.successEnvelope(command, used, result, previousState);
+    if (!arrived) envelope.page.redirectedFrom = target;
+    return envelope;
   }
 
   async browserStart(): Promise<void> {

package/boat/prima/src/session-log.ts

@@ -4,7 +4,7 @@ import { outputPath } from '../../../src/config.ts';
 import { safeFilename } from '../../../src/utils/strings.ts';
 import { type EnvelopeData, renderEnvelope } from './envelope.ts';
 
-const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped' };
+const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped', contradiction: 'failed' };
 
 export function sessionsDir(): string {
   return outputPath('prima', 'sessions');
@@ -74,7 +74,7 @@ function commandSteps(envelope: EnvelopeData): any[] {
 
   for (const expectation of envelope.expectations || []) {
     const entry: any = { 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';
+    if (expectation.failed) entry.error = 'the run did not reach this outcome';
     steps.push(entry);
   }
 
@@ -82,7 +82,7 @@ function commandSteps(envelope: EnvelopeData): any[] {
     const entry: any = { 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';
+      entry.error = assertion.error || 'the assertion did not hold on the page';
     }
     steps.push(entry);
   }

package/dist/bin/explorbot-cli.js

@@ -46,6 +46,7 @@ if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima') && !prin
 function buildExplorBotOptions(from, options) {
     return {
         from,
+        baseUrl: options.baseUrl,
         verbose: options.verbose || options.debug,
         config: options.config,
         path: options.path,
@@ -62,6 +63,7 @@ function addCommonOptions(cmd) {
         .option('--debug', 'Enable debug logging (same as --verbose)')
         .option('-c, --config <path>', 'Path to configuration file')
         .option('-p, --path <path>', 'Working directory path')
+        .option('--base-url <url>', 'Run against this URL: its path scopes relative paths (plans, commands, saved tests on rerun), its query params ride along with every page load')
         .option('-s, --show', 'Show browser window')
         .option('--headless', 'Run browser in headless mode')
         .option('--incognito', 'Run without recording experiences')

package/dist/boat/doc-collector/src/docbot.js

@@ -103,9 +103,11 @@ class DocBot {
                         continue;
                     }
                 }
+                const light = this.useLightResearch();
                 const research = await this.explorBot.agentResearcher().research(state, {
-                    screenshot: this.shouldUseScreenshots(),
+                    screenshot: !light && this.shouldUseScreenshots(),
                     force: true,
+                    light,
                 });
                 const pagePath = this.getPageFilePath(state.url);
                 const captureState = this.shouldUseScreenshots()
@@ -197,6 +199,14 @@ class DocBot {
         }
         return true;
     }
+    useLightResearch() {
+        const research = this.config.docs?.research;
+        if (research === 'light')
+            return true;
+        if (research === 'full')
+            return false;
+        return this.config.docs?.interactive !== true;
+    }
     shouldCollapseTemplates(override) {
         if (override === false) {
             return false;

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

@@ -52,13 +52,15 @@ function renderResult(data) {
     return section('Result', lines.join('\n'));
 }
 function renderPage(data) {
-    const { url, previousUrl, title, state, visits } = data.page;
+    const { url, previousUrl, redirectedFrom, title, state, visits } = data.page;
     const urlLabel = `url: ${url}`;
     const stateLabel = `state: ${state}`;
     const width = Math.max(urlLabel.length, stateLabel.length) + 3;
     let changedMarker = '';
     if (previousUrl && previousUrl !== url)
         changedMarker = `(changed: ${previousUrl} → ${url})`;
+    if (redirectedFrom)
+        changedMarker = `(redirected: ${redirectedFrom} → ${url})`;
     const lines = [align(urlLabel, changedMarker, width), `title: ${title}`, align(stateLabel, `(visit #${visits})`, width)];
     return section('Page', lines.join('\n'));
 }
@@ -96,7 +98,9 @@ function renderExpectations(data) {
     const lines = [];
     data.expectations.forEach((expectation, index) => {
         lines.push(`${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
-        if (expectation.status !== 'contradiction' && expectation.status !== 'failed')
+        if (expectation.resolution)
+            lines.push(`      resolved: ${expectation.resolution}`);
+        if (!expectation.contradicted && !expectation.failed && !expectation.resolution)
             return;
         for (const line of (expectation.evidence || '').split('\n').filter(Boolean))
             lines.push(`      ${line}`);
@@ -123,7 +127,12 @@ function renderOutcome(data) {
             .map((line) => line.trim())
             .filter((line) => line && !line.startsWith('//'))
             .join(' ');
-        return `${code}  => ${assertion.passed ? 'PASSED' : 'FAILED'}`;
+        if (assertion.passed)
+            return `${code}  => PASSED`;
+        const reason = assertion.error?.split('\n').find(Boolean);
+        if (!reason)
+            return `${code}  => FAILED`;
+        return `${code}  => FAILED\n      ${reason}`;
     });
     const proof = data.assertions.flatMap((assertion) => assertion.proof);
     if (proof.length)

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

@@ -25,8 +25,10 @@ export const checkHelp = dedent `
               ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
               "not verified" means never checked, not false.
   Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
-  CONTRADICTION means screenshot and log disagree; judge the html, aria and
-  screenshot under ### Artifacts yourself.
+  When screenshot and log disagree, the page structure breaks the tie: the outcome
+  becomes PASSED or FAILED with a "resolved:" line naming the side that was wrong.
+  CONTRADICTION remains when it cannot be broken, or when the page holds something
+  it does not display; judge the html, aria and screenshot under ### Artifacts yourself.
   ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
   reported as such rather than as an app failure.
   Side issues found on the way go under ### Answer, not as step failures.

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

@@ -220,6 +220,9 @@ export class Prima {
         }
         if (aiError)
             return this.failureEnvelope(command, aiError, previousState);
+        if (trace.length && ledger.some((entry) => entry.status === 'open')) {
+            await this.judgeUnreportedInstructions(ledger, trace);
+        }
         if (trace.length && ledger.some((entry) => entry.status === 'open')) {
             await this.settleLedger(conversation, provider, ledger, trace);
         }
@@ -283,6 +286,32 @@ export class Prima {
         }
         return true;
     }
+    async judgeUnreportedInstructions(ledger, trace) {
+        const judge = this.bot.judge?.();
+        if (!judge)
+            return;
+        const current = this.bot.stateManager().getCurrentState();
+        let page = '';
+        if (current)
+            page = ((await this.refAriaSnapshot(ActionResult.fromState(current))) || '').slice(0, JUDGE_PAGE_CAP);
+        const actions = trace
+            .map((step) => {
+            if (step.ok)
+                return `ok ${step.label}`;
+            return `FAIL ${step.label}`;
+        })
+            .join('\n');
+        const state = { actions, finalUrl: current?.url || '', finalPage: page };
+        const open = ledger.filter((entry) => entry.status === 'open');
+        const decisions = await Promise.all(open.map((entry) => judge.decide(`The actions that ran and the final page show this instruction was carried out: ${entry.text}`, null, state)));
+        open.forEach((entry, index) => {
+            if (decisions[index].rejected)
+                return;
+            entry.status = 'done';
+            entry.proof = 'judged from the actions that ran and the final page';
+            trace.push({ label: `done: ${entry.text}`, ok: true, proof: entry.proof });
+        });
+    }
     async settleLedger(conversation, provider, ledger, trace) {
         conversation.addUserText(dedent `
       The run is over and these instructions were never reported:
@@ -343,8 +372,8 @@ export class Prima {
         if (!result.screenshot || !this.visionEnabled()) {
             envelope.warning = 'These outcomes were settled from the run log alone — no screenshot backed them. Set ai.visionModel, or check anything visual with prima ask.';
         }
-        const unreached = envelope.expectations.filter((expectation) => expectation.status === 'failed');
-        const contradicted = envelope.expectations.filter((expectation) => expectation.status === 'contradiction');
+        const unreached = envelope.expectations.filter((expectation) => expectation.failed);
+        const contradicted = envelope.expectations.filter((expectation) => expectation.contradicted);
         envelope.ok = !unreached.length && !contradicted.length;
         const problems = [...unreached.map((expectation) => `not reached: ${expectation.text}`), ...contradicted.map((expectation) => `the picture and the run disagree about: ${expectation.text}`)];
         if (problems.length)
@@ -413,8 +442,9 @@ export class Prima {
                 return judged;
         }
         let navigationError = null;
+        let arrived = true;
         try {
-            await this.bot.agentNavigator().visit(target);
+            arrived = await this.bot.agentNavigator().visit(target, { recover: !isUrl });
         }
         catch (error) {
             navigationError = error;
@@ -425,7 +455,10 @@ export class Prima {
         if (isUrl)
             used.push(code);
         const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
-        return this.successEnvelope(command, used, result, previousState);
+        const envelope = await this.successEnvelope(command, used, result, previousState);
+        if (!arrived)
+            envelope.page.redirectedFrom = target;
+        return envelope;
     }
     async browserStart() {
         const config = await this.loadConfig();

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

@@ -3,7 +3,7 @@ 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' };
+const EXPECTATION_STATUS = { passed: 'passed', failed: 'failed', unverified: 'skipped', contradiction: 'failed' };
 export function sessionsDir() {
     return outputPath('prima', 'sessions');
 }
@@ -64,7 +64,7 @@ function commandSteps(envelope) {
     }
     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')
+        if (expectation.failed)
             entry.error = 'the run did not reach this outcome';
         steps.push(entry);
     }
@@ -72,7 +72,7 @@ function commandSteps(envelope) {
         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';
+            entry.error = assertion.error || 'the assertion did not hold on the page';
         }
         steps.push(entry);
     }

package/dist/package.json

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

package/dist/rules/navigator/output.md

@@ -1,11 +1,11 @@
 <rules>
-Do not invent locators, focus only on locators from HTML PAGE.
+Do not invent locators, focus only on locators from the <page> context.
 Provide up to {{maxAttempts}} various code suggestions to achieve the result.
 If there was already successful solution in <experience> use it as a first solution.
 
 If no successful solution was found in <experience> propose codeblocks for each area that can help to achieve the result.
 Do not stick only to the first found element as it might be hidden or not availble on the page.
-If you think HTML contains several areas that can help to achieve the result, propose codeblocks for each such area.
+If you think the page contains several areas that can help to achieve the result, propose codeblocks for each such area.
 Use exact locators that can pick the elements from each areas.
 Detect such duplicated areas by looking for duplicate IDs, data-ids, forms, etc.
 
@@ -24,7 +24,7 @@ Your response must start explanation of what you are going to do to achive the r
 It is important to explain intention before proposing code.
 Response must also valid CodeceptJS code in code blocks.
 Propose codeblock from successful solutions in <experience> first if they exist.
-Use only locators from HTML PAGE that was passed in <page> context.
+Use only locators from the <page> context.
 </output>
 
 

package/dist/src/action.js

@@ -105,6 +105,7 @@ class Action {
             if (includeScreenshot) {
                 const filename = safeFilename(`${stateHash}_${timestamp}`, '.png');
                 const screenshotPath = join(statesDir, filename);
+                await page?.screencast?.hideOverlays().catch(() => { });
                 screenshotFile = await page
                     ?.screenshot({ path: screenshotPath, fullPage: true })
                     .then(() => {
@@ -115,6 +116,7 @@ class Action {
                     debugLog('Screenshot failed, continuing without it:', err);
                     return undefined;
                 });
+                await page?.screencast?.showOverlays().catch(() => { });
             }
             // Save HTML to file
             const htmlFile = safeFilename(`${stateHash}_${timestamp}`, '.html');
@@ -546,6 +548,10 @@ export const attachStepLogger = (target, assertionsTarget) => {
         if (batchFailed)
             return;
         const executed = { command: step.toCode(), success: !error };
+        if (Object.keys(step.opts || {}).length) {
+            const args = [step.humanizeArgs(), `step.opts(${JSON.stringify(step.opts)})`].filter(Boolean).join(', ');
+            executed.command = `${step.prefix}${step.actor}.${step.title}(${args})${step.suffix}`;
+        }
         if (error) {
             executed.error = errorToString(error);
             batchFailed = true;

package/dist/src/ai/driller.js

@@ -6,6 +6,7 @@ import { setActivity } from "../activity.js";
 import { Observability } from "../observability.js";
 import { Plan, Test, TestResult } from "../test-plan.js";
 import { collectInteractiveNodes } from "../utils/aria.js";
+import { splitTopLevel } from "../utils/code-extractor.js";
 import { EXPLORBOT_ATTRS, HTML_COMPOSITE_AREA_HINTS, HTML_COMPOSITE_TARGET_ROLES, HTML_EXTRACTION_LIMITS, HTML_FORM_CONTROL_ROLES, HTML_FORM_CONTROL_TAGS, HTML_INTERACTIVE_ROLES, HTML_SELECTORS, getComponentScopeHtmlExtractorSource, inferHtmlRole } from "../utils/html.js";
 import { createDebug, tag } from "../utils/logger.js";
 import { loop, pause } from "../utils/loop.js";
@@ -933,34 +934,7 @@ function countTopLevelArgCount(line) {
     const end = line.lastIndexOf(')');
     if (start === -1 || end === -1 || end <= start + 1)
         return 0;
-    const body = line.slice(start + 1, end);
-    let count = 1;
-    let depth = 0;
-    let quote = '';
-    for (let i = 0; i < body.length; i++) {
-        const char = body[i];
-        const escaped = body[i - 1] === '\\';
-        if (quote) {
-            if (char === quote && !escaped)
-                quote = '';
-            continue;
-        }
-        if (char === '"' || char === "'" || char === '`') {
-            quote = char;
-            continue;
-        }
-        if (char === '(' || char === '[' || char === '{') {
-            depth++;
-            continue;
-        }
-        if (char === ')' || char === ']' || char === '}') {
-            depth = Math.max(0, depth - 1);
-            continue;
-        }
-        if (char === ',' && depth === 0)
-            count++;
-    }
-    return count;
+    return splitTopLevel(line.slice(start + 1, end), ',').length;
 }
 function buildClassSelector(tag, classes) {
     const safeClasses = classes.filter((cls) => /^[a-z0-9_-]+$/i.test(cls)).slice(0, 5);

package/dist/src/ai/historian/codeceptjs.js

@@ -6,6 +6,7 @@ import { tag } from "../../utils/logger.js";
 import { relativeToCwd } from "../../utils/next-steps.js";
 import { CODECEPT_TOOLS, isNonReusableCode, stripComments } from "../../utils/step-analyzer.js";
 import { safeFilename } from "../../utils/strings.js";
+import { ensureCodeceptResolvable } from "../../utils/test-files.js";
 import { ASSERTION_TOOLS } from "../tools.js";
 import { escapeString, getExecutionLabel } from "./utils.js";
 export function WithCodeceptJS(Base) {
@@ -79,6 +80,7 @@ export function WithCodeceptJS(Base) {
             }
             const testsDir = ConfigParser.getInstance().getTestsDir();
             mkdirSync(testsDir, { recursive: true });
+            ensureCodeceptResolvable(testsDir);
             const filePath = join(testsDir, safeFilename(plan.title, '.js'));
             writeFileSync(filePath, lines.join('\n'));
             this.savedFiles.add(filePath);

package/dist/src/ai/judge-tool.js

@@ -9,7 +9,11 @@ export function createJudgeTool(deps, buildState) {
     return {
         judge: tool({
             description: dedent `
-        Settle one judgement about the current page instead of guessing. Phrase it literally and concretely.
+        Fast yes/no or pick-one decision about the current page, answered from <page_aria> and your recent steps.
+        No screenshot, no HTML, produces no test code.
+        Use for in-flow judgements you would otherwise guess: did the last action already take effect, which of several similar elements the scenario means, is this the expected page or dialog.
+        Not for final assertions (use verify/finish) and not for anything page_aria does not show, such as styling or visual state (use see).
+        Phrase the question literally and concretely.
       `,
             inputSchema: z.object({
                 question: z.string().describe('The statement to confirm, or the question the options answer'),

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

@@ -35,8 +35,10 @@ declare class Navigator implements Agent {
     }, 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>;
+    visit(url: string, opts?: {
+        recover?: boolean;
+    }): Promise<boolean>;
+    visitOnce(url: string, recover: boolean): Promise<boolean>;
     navigationError(url: string, fallback: string): Error;
     failureReason(stopReason: string | null, knowledge: string, url: string): string | null;
     resolveState(message: string, actionResult: ActionResult, opts?: {
@@ -98,5 +100,6 @@ export type AssertionResult = {
     code: string;
     passed: boolean;
     proof: string[];
+    error?: string;
 };
 export { Navigator };