explorbot 0.4.9 → 0.5.0

package/src/ai/planner.ts

@@ -301,13 +301,14 @@ export class Planner extends PlannerBase implements Agent {
         .replaceEach((section) => {
           const heading = section.query('heading').text().trim();
           const withoutHeadings = mdq(section.text()).query('heading').replace('');
-          const body = mdq(withoutHeadings).query('hr').replace('').trim();
+          const body = mdq(withoutHeadings).query('hr').replace('').toString().trim();
           if (body && !seenTitles.has(heading)) {
             seenTitles.add(heading);
             return section.text();
           }
           return '';
-        });
+        })
+        .toString();
     }
 
     const trimmedTitles = new Set<string>();
@@ -319,10 +320,11 @@ export class Planner extends PlannerBase implements Agent {
           if (trimmedTitles.has(heading)) return section.text();
           const count = section.query('blockquote').count();
           if (count <= 10) return section.text();
-          const kept = mdq(section.text()).query('blockquote[10:]').replace('');
+          const kept = mdq(section.text()).query('blockquote[10:]').replace('').toString();
           trimmedTitles.add(heading);
           return `${kept.trimEnd()}\n> ... and ${count - 10} more discoveries\n`;
-        });
+        })
+        .toString();
     }
 
     return result.trim() || null;
@@ -404,7 +406,7 @@ export class Planner extends PlannerBase implements Agent {
     if (this.scout && this.docsWeight > 0) {
       docsPromise = this.scout.collectDocs({ url: state.url, title: state.title, feature, excludeUrls: this.knowledgeTracker.applicationSpecUrls(state) });
     }
-    let plannerResearch = mdq(research).query('code').replace('');
+    let plannerResearch = mdq(research).query('code').replace('').toString();
     plannerResearch = mdq(plannerResearch)
       .query('table')
       .replaceEach((table) => {
@@ -415,7 +417,8 @@ export class Planner extends PlannerBase implements Agent {
           Type: r.Type || '',
         }));
         return jsonToTable(elementWithType, ['Element', 'Type']);
-      });
+      })
+      .toString();
 
     const hasFocusedOverlay = hasFocusedSection(plannerResearch);
     const focusNote = hasFocusedOverlay ? "IMPORTANT: One section is marked as **Focused** — this is the user's current focus area. Concentrate testing on the Focused section FIRST — test all interactions inside it before planning tests for the rest of the page." : '';

package/src/ai/provider.ts

@@ -3,7 +3,7 @@ import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import dedent from 'dedent';
-import { APICallError, generateObject, generateText, isStepCount, registerTelemetry, tool } from 'ai';
+import { APICallError, NoObjectGeneratedError, asSchema, extractJsonMiddleware, generateObject, generateText, isStepCount, parsePartialJson, registerTelemetry, tool, wrapLanguageModel } from 'ai';
 import type { ModelMessage } from 'ai';
 import { z } from 'zod';
 import { clearActivity, setActivity } from '../activity.ts';
@@ -60,11 +60,11 @@ function extractCachedTokens(usage: any): number {
   return usage?.inputTokenDetails?.cacheReadTokens ?? 0;
 }
 
-function abortAfterIdle(ms: number, cancel: { cancelled: boolean }, controller: AbortController): Promise<never> {
+function abortAfterIdle(ms: number, cancel: { cancelled: boolean }, controller: AbortController, busy: { tools: number }): Promise<never> {
   return new Promise((_, reject) => {
     const tick = () => {
       if (cancel.cancelled) return;
-      if (executionController.isAwaitingInput()) {
+      if (executionController.isAwaitingInput() || busy.tools > 0) {
         setTimeout(tick, ms);
         return;
       }
@@ -87,7 +87,7 @@ export class Provider {
   private otelSdk: NodeSDK | null = null;
   private defaultRetryOptions: RetryOptions = {
     maxAttempts: 3,
-    baseDelay: 10,
+    baseDelay: 1000,
     maxDelay: 10000,
     retryCondition: (error: Error) => {
       return (
@@ -251,12 +251,12 @@ export class Provider {
     });
   }
 
-  private async raceWithIdleTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, timeoutMs: number): Promise<T> {
+  private async raceWithIdleTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, timeoutMs: number, busy: { tools: number } = { tools: 0 }): Promise<T> {
     const cancel = { cancelled: false };
     const controller = new AbortController();
     const combinedSignal = combinedAbortSignal(controller);
     try {
-      return await Promise.race([fn(combinedSignal), abortAfterIdle(timeoutMs, cancel, controller)]);
+      return await Promise.race([fn(combinedSignal), abortAfterIdle(timeoutMs, cancel, controller, busy)]);
     } finally {
       cancel.cancelled = true;
     }
@@ -269,6 +269,24 @@ export class Provider {
     return retry(reduced.messages, { ...options, _contextRetryLevel: reduced.nextLevel });
   }
 
+  private async recoverWithPlainJson(messages: ModelMessage[], schema: any, model: any, options: any): Promise<any> {
+    const target = asSchema(schema);
+    tag('warning').log(`${getModelName(model)} returned no structured output, asking for plain JSON instead`);
+    const instruction = dedent`
+      Respond with a single JSON object that matches this JSON Schema, and nothing else:
+      ${JSON.stringify(await target.jsonSchema)}
+    `;
+    const response = await this.chat([...messages, { role: 'user', content: instruction }], wrapLanguageModel({ model, middleware: extractJsonMiddleware() }), options);
+
+    const parsed = await parsePartialJson(response.text);
+    if (parsed.state !== 'successful-parse') throw new AiError('No object generated: plain JSON fallback returned no parsable JSON');
+    const validated = await target.validate?.(parsed.value);
+    if (validated && !validated.success) throw new AiError(`No object generated: plain JSON fallback did not match the schema: ${validated.error.message}`);
+
+    responseLog(parsed.value);
+    return { ...response, object: validated?.value ?? parsed.value };
+  }
+
   private initLangfuse() {
     const { enabled, publicKey, secretKey, baseUrl } = this.config.langfuse || {};
 
@@ -411,6 +429,8 @@ export class Provider {
 
   async generateWithTools(messages: ModelMessage[], model: any, tools: any, options: any = {}): Promise<any> {
     const modelName = getModelName(model);
+    const busy = { tools: 0 };
+    tools = withIdleExemption(tools, busy);
     setActivity(`🤖 Asking ${modelName} with dynamic tools`, 'ai');
     promptLog(`Using model: ${modelName}`);
 
@@ -437,7 +457,7 @@ export class Provider {
           const onStepEnd = (step: any) => {
             stepMessages.push(...(step.response?.messages || []));
           };
-          const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages: attemptMessages, ...config, abortSignal: signal, onStepEnd }), config.timeout || 30000).catch((error) => {
+          const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages: attemptMessages, ...config, abortSignal: signal, onStepEnd }), config.timeout || 30000, busy).catch((error) => {
             if (stepMessages.length > 0) {
               tag('warning').log(`Keeping ${stepMessages.length} messages from tool steps that already ran before the failure`);
               executedStepMessages.push(...stepMessages);
@@ -527,6 +547,7 @@ export class Provider {
       if (Provider.isContextLengthError(error)) {
         return this.recoverFromContextLength(error, messages, options, (m, o) => this.generateObject(m, schema, model, o));
       }
+      if (NoObjectGeneratedError.isInstance(error)) return this.recoverWithPlainJson(messages, schema, modelToUse, options);
       throw new AiError(error.message || error.toString());
     }
   }
@@ -769,6 +790,29 @@ function repairHarmonyChannel({ toolCall, tools }: ToolCallRepairOptions): any |
   return { ...toolCall, toolName: NARRATION_TOOL, input };
 }
 
+function withIdleExemption(tools: any, busy: { tools: number }): any {
+  if (!tools) return tools;
+  const wrapped: any = {};
+  for (const [name, definition] of Object.entries<any>(tools)) {
+    if (typeof definition?.execute !== 'function') {
+      wrapped[name] = definition;
+      continue;
+    }
+    wrapped[name] = {
+      ...definition,
+      execute: async (...args: any[]) => {
+        busy.tools++;
+        try {
+          return await definition.execute(...args);
+        } finally {
+          busy.tools--;
+        }
+      },
+    };
+  }
+  return wrapped;
+}
+
 export { AiError, Provider as AIProvider };
 
 type ToolCallRepairOptions = { toolCall: any; tools: any };

package/src/ai/rerunner.ts

@@ -18,6 +18,7 @@ import { formatHeadings } from '../utils/context-formatter.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
+import { isInternalStep } from '../utils/step-analyzer.ts';
 import type { Agent, AgentDeps } from './agent.ts';
 import { toolExecutionLabel } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
@@ -85,6 +86,7 @@ export class Rerunner extends TaskAgent implements Agent {
 
     const onStepStarted = (step: any) => {
       if (!step.toCode) return;
+      if (isInternalStep(step)) return;
       const code = highlight(step.toCode(), { language: 'javascript' });
       console.log(chalk.dim(`    ${code}`));
     };
@@ -92,12 +94,14 @@ export class Rerunner extends TaskAgent implements Agent {
     const onStepPassed = (step: any) => {
       const task = this.getCurrentTask(testMap);
       if (!task || !step.toCode) return;
+      if (isInternalStep(step)) return;
       task.addStep(step.toCode(), step.duration, 'passed');
     };
 
     const onStepFailed = (step: any, error: any) => {
       const task = this.getCurrentTask(testMap);
       if (!task || !step.toCode) return;
+      if (isInternalStep(step)) return;
       task.addStep(step.toCode(), step.duration, 'failed', error?.message);
       console.log(chalk.red(`    ${figureSet.cross} ${step.toCode()} — ${error?.message || 'failed'}`));
     };

package/src/ai/researcher/deep-analysis.ts

@@ -126,7 +126,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       let updated: string;
       if (extQuery.count() > 0) {
         const existing = extQuery.text().trimEnd();
-        updated = extQuery.replace(`${existing}\n\n${sectionMarkdown}\n`);
+        updated = extQuery.replace(`${existing}\n\n${sectionMarkdown}\n`).toString();
       } else {
         updated = `${cached.trimEnd()}\n\n# Extended Research\n\n${sectionMarkdown}\n`;
       }
@@ -539,7 +539,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       if (heading.count() === 0) heading = mdq(sectionMarkdown).query('h2[0]');
       if (heading.count() === 0) return sectionMarkdown;
 
-      return heading.replace(`${heading.text().trimEnd()}\n\n> Container: '${containerCss}'\n\n`);
+      return heading.replace(`${heading.text().trimEnd()}\n\n> Container: '${containerCss}'\n\n`).toString();
     }
 
     private _deduplicateExpandedSections(sections: string[]): string[] {

package/src/ai/researcher/locators.ts

@@ -304,9 +304,9 @@ export function WithLocators<T extends Constructor>(Base: T) {
       if (sectionQuery.count() === 0) sectionQuery = mdq(result.text).query(`section3(~"${escaped}")`);
 
       if (newCss) {
-        result.text = sectionQuery.query('blockquote[0]').setKeyValue('Container', `'${newCss}'`);
+        result.text = sectionQuery.query('blockquote[0]').setKeyValue('Container', `'${newCss}'`).toString();
       } else {
-        result.text = sectionQuery.query('blockquote[0]').replace('');
+        result.text = sectionQuery.query('blockquote[0]').replace('').toString();
         result.text = result.text.replace(`${FOCUSED_MARKER}\n`, '');
       }
 

package/src/ai/researcher/pagination.ts

@@ -58,7 +58,7 @@ export function WithPagination<T extends Constructor>(Base: T) {
       let sectionQuery = mdq(result.text).query(`section2(~"${escaped}")`);
       if (sectionQuery.count() === 0) sectionQuery = mdq(result.text).query(`section3(~"${escaped}")`);
       if (sectionQuery.count() === 0) return;
-      result.text = sectionQuery.query('blockquote[0]').setKeyValue('Pagination', strategy);
+      result.text = sectionQuery.query('blockquote[0]').setKeyValue('Pagination', strategy).toString();
     }
   };
 }

package/src/ai/researcher/research-result.ts

@@ -52,9 +52,9 @@ export class ResearchResult {
     const escaped = section.name.replace(/"/g, '\\"');
     let sectionQuery = mdq(this.text).query(`section2(~"${escaped}")`);
     if (sectionQuery.count() === 0) sectionQuery = mdq(this.text).query(`section3(~"${escaped}")`);
-    const updated = sectionQuery.query('table').replace(`${newTable.trimEnd()}\n`);
+    const updated = sectionQuery.query('table').replace(`${newTable.trimEnd()}\n`).toString();
     if (updated === this.text) return;
-    section.rawMarkdown = mdq(section.rawMarkdown).query('table').replace(`${newTable.trimEnd()}\n`);
+    section.rawMarkdown = mdq(section.rawMarkdown).query('table').replace(`${newTable.trimEnd()}\n`).toString();
     this.text = updated;
   }
 

package/src/ai/researcher.ts

@@ -313,7 +313,7 @@ export class Researcher extends ResearcherBase implements Agent {
         researchFile = saveResearch(researchState, result.text, combinedHtml);
       }
 
-      const summaryText = mdq(result.text).query('section2(/^summary/)').query('paragraph[0]').text().trim();
+      const summaryText = mdq(result.text).query('section2(/^summary/i)').query('paragraph[0]').text().trim();
       const summaryLine = summaryText.split('\n')[0]?.trim().slice(0, 200);
       if (summaryLine) this.experienceTracker.updateSummary(this.actionResult!, summaryLine);
 

package/src/ai/task-agent.ts

@@ -8,6 +8,7 @@ import type { StateManager } from '../state-manager.ts';
 import { HooksRunner } from '../utils/hooks-runner.ts';
 import type { AgentDeps, ToolDeps } from './agent.ts';
 import { Historian } from './historian.js';
+import type { Judge } from './judge.ts';
 import type { Navigator } from './navigator.js';
 import type { Provider } from './provider.js';
 import { Quartermaster } from './quartermaster.js';
@@ -29,6 +30,7 @@ export abstract class TaskAgent {
   config!: ExplorbotConfig;
   stateManager!: StateManager;
   knowledgeTracker!: KnowledgeTracker;
+  protected judge?: Judge;
   protected hooksRunner!: HooksRunner;
   protected consecutiveFailures = 0;
   protected consecutiveEmptyResults = 0;
@@ -45,6 +47,7 @@ export abstract class TaskAgent {
     this.config = deps.config;
     this.stateManager = deps.stateManager;
     this.knowledgeTracker = deps.knowledgeTracker;
+    this.judge = deps.judge;
     this.hooksRunner = new HooksRunner(deps.explorer, deps.config);
   }
 
@@ -59,7 +62,7 @@ export abstract class TaskAgent {
   protected abstract getNavigator(): Navigator;
 
   protected get toolDeps(): ToolDeps {
-    return { explorer: this.explorer, stateManager: this.stateManager, ai: this.provider };
+    return { explorer: this.explorer, stateManager: this.stateManager, ai: this.provider, judge: this.judge };
   }
 
   protected getExperienceTracker(): ExperienceTracker {

package/src/ai/tester.ts

@@ -136,8 +136,8 @@ export class Tester extends TaskAgent implements Agent {
     let initialState = ActionResult.fromState(state);
     const currentUrl = state.fullUrl || state.url;
     let startOnCurrentPage = opts.startOnCurrentPage;
-    if (isErrorPage(initialState) && !startOnCurrentPage && task.startUrl && normalizeUrl(currentUrl) !== normalizeUrl(task.startUrl)) {
-      debugLog(`Recovering from error page at ${currentUrl} by navigating to ${task.startUrl}`);
+    if (!startOnCurrentPage && task.startUrl && normalizeUrl(currentUrl) !== normalizeUrl(task.startUrl)) {
+      debugLog(`Opening test start URL ${task.startUrl} before building context (was at ${currentUrl})`);
       try {
         await this.explorer.visit(task.startUrl);
         state = this.stateManager.getCurrentState();
@@ -145,7 +145,7 @@ export class Tester extends TaskAgent implements Agent {
         initialState = ActionResult.fromState(state);
         startOnCurrentPage = true;
       } catch (error) {
-        debugLog(`Could not recover from error page: ${compactErrorMessage(error)}`);
+        debugLog(`Could not open test start URL: ${compactErrorMessage(error)}`);
       }
     }
     if (isErrorPage(initialState)) {
@@ -159,14 +159,6 @@ export class Tester extends TaskAgent implements Agent {
     conversation.markLastMessageCacheable();
     this.currentConversation = conversation;
 
-    const scenarioBlock = this.buildScenarioBlock(task, initialState);
-    conversation.addUserText(scenarioBlock);
-    conversation.markLastMessageCacheable();
-    conversation.protectPrefix(conversation.messages.length);
-
-    const pageContext = await this.reinjectContextIfNeeded(1, initialState);
-    if (pageContext) conversation.addUserText(pageContext);
-
     return await Observability.run(
       `test: ${task.scenario}`,
       {
@@ -185,16 +177,15 @@ export class Tester extends TaskAgent implements Agent {
   private async runTestSession(task: Test, initialState: ActionResult, conversation: Conversation, handlers: TestSessionHandlers, opts: TestOptions): Promise<{ success: boolean }> {
     const { offFailedRequest } = handlers;
 
+    let plan = '';
     if (this.pilot) {
       try {
-        const plan = await this.pilot.planTest(task, initialState);
+        await this.researcher.research(initialState).catch(this.skipResearch);
+        plan = await this.pilot.planTest(task, initialState);
         if (task.hasFinished) {
           offFailedRequest?.();
           return { success: task.isSuccessful };
         }
-        if (plan) {
-          conversation.addUserText(`Pilot's test plan:\n${plan}\n\nFollow this plan while executing the test.`);
-        }
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         tag('error').log(`Pilot planning failed: ${message}`);
@@ -216,7 +207,7 @@ export class Tester extends TaskAgent implements Agent {
 
     if (opts.startOnCurrentPage) debugLog(`Starting on the page already open at ${task.startUrl}`);
 
-    if (!opts.startOnCurrentPage) {
+    if (!opts.startOnCurrentPage || task.preparedData.length > 0) {
       debugLog(`Navigating to ${task.startUrl}`);
       try {
         await this.explorer.visit(task.startUrl!);
@@ -242,6 +233,15 @@ export class Tester extends TaskAgent implements Agent {
     const currentUrl = startState?.url || task.startUrl || '';
     await this.hooksRunner.runBeforeHook('tester', currentUrl);
 
+    const testerState = this.getCurrentState();
+    conversation.addUserText(this.buildScenarioBlock(task, testerState));
+    conversation.markLastMessageCacheable();
+    conversation.protectPrefix(conversation.messages.length);
+
+    const pageContext = await this.reinjectContextIfNeeded(1, testerState);
+    if (pageContext) conversation.addUserText(pageContext);
+    if (plan) conversation.addUserText(`Pilot's test plan:\n${plan}\n\nFollow this plan while executing the test.`);
+
     const offStateChange = this.stateManager.onStateChange((event: StateTransition) => {
       if (task.hasFinished) return;
       if (event.toState?.url === event.fromState?.url) return;
@@ -912,6 +912,9 @@ export class Tester extends TaskAgent implements Agent {
   }
 
   private buildDeletionScope(task: Test): string {
+    if (task.preparedData.length > 0) {
+      return `When deleting items, ONLY delete the data prepared for this test: ${task.preparedData.join('; ')}.`;
+    }
     const deletableItems = this.getDeletableSessionNames(task);
     if (deletableItems.length > 0) {
       return `When deleting items, ONLY delete items whose title contains one of these session names: ${deletableItems.join(', ')}. These were created by previous tests.`;

package/src/ai/tools.ts

@@ -15,6 +15,8 @@ import { pause } from '../utils/loop.js';
 import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
+import { createJudgeTool } from './judge-tool.ts';
+import { JUDGE_PAGE_CAP, type Judge, UNDECIDED } from './judge.ts';
 import { Navigator } from './navigator.ts';
 import { Researcher } from './researcher.ts';
 import { sectionContextRule } from './rules.ts';
@@ -31,7 +33,7 @@ interface AgentToolDeps extends ToolDeps {
 
 export const ASSERTION_TOOLS = ['verify'] as const;
 
-export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task: Task) {
+export function createCodeceptJSTools({ explorer, stateManager, judge }: ToolDeps, task: Task) {
   return {
     click: tool({
       description: dedent`
@@ -156,7 +158,9 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
             attempts,
             suggestion,
           },
-          ambiguityError || action.lastError
+          ambiguityError || action.lastError,
+          judge,
+          explanation
         );
       },
     }),
@@ -232,7 +236,9 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
             attempts,
             suggestion: 'Use xpathCheck() to locate the row/card/tree node, or visualClick() if the hover target is only visually identifiable.',
           },
-          action.lastError
+          action.lastError,
+          judge,
+          explanation
         );
       },
     }),
@@ -375,7 +381,7 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
         - Performing multiple form actions in a single batch
         - Complex interactions requiring sequential commands
         - Reaching items further down a list (I.scrollTo)
-        - Reloading the page to prove a change outlived it (I.reloadPage)
+        - Reloading the page to prove a change outlived it (I.refreshPage)
 
         Example - filling a form with context (PREFERRED):
         I.fillField('Username', 'John', '.login-form')
@@ -437,7 +443,9 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
                 attempts: action.executedSteps,
                 suggestion: formSuggestion,
               },
-              action.lastError
+              action.lastError,
+              judge,
+              explanation
             );
           }
 
@@ -587,7 +595,7 @@ export function createLearnExperienceTool({ getExperienceTracker, getState }: {
   });
 }
 
-export function createAgentTools({ explorer, stateManager, ai, researcher, navigator, supervisor, withExperience }: AgentToolDeps): any {
+export function createAgentTools({ explorer, stateManager, ai, judge, researcher, navigator, supervisor, withExperience }: AgentToolDeps): any {
   const tools: Record<string, any> = {
     see: tool({
       description: dedent`
@@ -724,6 +732,13 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
           }
 
           if (result.inexpressible) {
+            if (result.judged?.approved) {
+              return failedToolResult('verify', `No assertion could express this claim, but the page appears to confirm it: ${assertion}`, {
+                inexpressible: true,
+                suggestion: 'This is a judgement about the page, not an assertion that ran in the browser — a hint, not proof. Restate the claim in terms of what is visible or of a control state to get a real assertion.',
+              });
+            }
+
             return failedToolResult('verify', `No assertion could express this claim: ${assertion}`, {
               inexpressible: true,
               suggestion: 'This is not evidence the page is wrong — the claim could not be turned into an assertion. Restate it in terms of what is visible or of a control state, or check it with see().',
@@ -1143,6 +1158,20 @@ export function createAgentTools({ explorer, stateManager, ai, researcher, navig
     });
   }
 
+  const buildJudgeState = async () => {
+    const activeTest = explorer.activeTest;
+    const state = stateManager.getCurrentState();
+    const result = state ? ActionResult.fromState(state) : null;
+    return {
+      task: activeTest?.scenario || '',
+      page: cap(result?.getCompactARIA(), JUDGE_PAGE_CAP),
+      recentActions: Object.values(activeTest?.steps || {})
+        .slice(-JUDGE_RECENT_ACTIONS_LIMIT)
+        .map((step) => step.text),
+    };
+  };
+  Object.assign(tools, createJudgeTool({ explorer, stateManager, ai, judge }, buildJudgeState));
+
   withdrawVisionTools(tools);
 
   return tools;
@@ -1158,6 +1187,7 @@ const NAVIGATED_SUGGESTION = 'The action left the page. Elements are never compa
 const ARIA_OUTPUT_CAP = 4000;
 const HTML_OUTPUT_CAP = 6000;
 const ANALYSIS_OUTPUT_CAP = 2000;
+const JUDGE_RECENT_ACTIONS_LIMIT = 8;
 
 function cap(text: string | undefined | null, max: number): string {
   if (!text) return '';
@@ -1267,7 +1297,7 @@ function hasObservablePageChange(data?: Record<string, any>): boolean {
   return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
 
-export async function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null) {
+export async function failedToolResult(action: string, message: string, data?: Record<string, any>, error?: Error | null, judge?: Judge, intent?: string) {
   const result: Record<string, any> = { success: false, action, message, ...data };
   if (data?.pageDiff) {
     result.suggestion = data.suggestion ? `${data.suggestion} ${PAGE_DIFF_SUGGESTION}` : PAGE_DIFF_SUGGESTION;
@@ -1279,6 +1309,11 @@ export async function failedToolResult(action: string, message: string, data?: R
     result.suggestion = getMultipleElementsSuggestion();
     result.multipleElementsDetected = true;
     result.elements = formatElementList(matched);
+    const labels = (matched || []).map((element) => `${element.text || 'no text'} — ${element.html}`);
+    const pick = await judge?.decide('Which listed element does the intent name?', [...labels, UNDECIDED], { intent });
+    if (!pick?.value) return result;
+    const index = labels.indexOf(pick.value) + 1;
+    result.suggestion = `Element ${index} is the one meant. Repeat the action with step.opts({ elementIndex: ${index} }) as the last argument.`;
     return result;
   }
 

package/src/api/request-result.ts

@@ -199,7 +199,8 @@ export class RequestResult {
     if (Array.isArray(data)) return {};
 
     const id = data.id ?? data._id ?? data.uuid;
-    const title = data.name ?? data.title ?? data.label;
+    const attributes = data.attributes || {};
+    const title = data.name ?? data.title ?? data.label ?? attributes.name ?? attributes.title ?? attributes.label;
 
     const result: { id?: string | number; title?: string } = {};
     if (id !== undefined) result.id = id;

package/src/api/xhr-capture.ts

@@ -1,3 +1,4 @@
+import { isSameHostFamily } from '../utils/url-matcher.js';
 import { RequestResult, generateRequestId } from './request-result.ts';
 import type { RequestStore } from './request-store.ts';
 
@@ -39,7 +40,7 @@ export class XhrCapture {
 
     const method = request.method();
     const url = request.url();
-    if (!url.startsWith(this.baseOrigin)) return;
+    if (!isSameHostFamily(url, this.baseOrigin)) return;
 
     const status = response.status();
 

package/src/command-handler.ts

@@ -31,6 +31,7 @@ export interface CommandAutocomplete {
   replaceTo: number;
   visible: boolean;
   argumentHint?: string;
+  completesArgument?: boolean;
 }
 
 function parseCommand(input: string): ParsedCommand | null {
@@ -266,6 +267,31 @@ export class CommandHandler implements InputManager {
     const parsed = parseCommand(query);
     const exactCommand = parsed ? this.findCommand(parsed.name) : undefined;
     const hasArguments = commandEnd !== -1 && input.slice(commandEnd + 1).trim().length > 0;
+    const argumentHint = !insideCommand && exactCommand && !hasArguments && exactCommand.options.length > 0 ? exactCommand.options.map((option) => option.flags).join(' ') : undefined;
+
+    if (!insideCommand && exactCommand) {
+      const argumentQuery = input.slice(commandEnd + 1).trim();
+      const argumentEntries = exactCommand
+        .completeArguments()
+        .filter((completion) => completion.value !== argumentQuery)
+        .map((completion) => ({
+          aliases: [],
+          canonical: completion.value,
+          description: '',
+          value: completion.display || completion.value,
+        }));
+      const argumentSuggestions = this.rankSuggestions(argumentQuery, argumentEntries);
+
+      return {
+        suggestions: argumentSuggestions,
+        replaceFrom: commandEnd + 1,
+        replaceTo: input.length,
+        visible: argumentSuggestions.length > 0,
+        argumentHint,
+        completesArgument: true,
+      };
+    }
+
     const commandEntries = this.getSlashCommandEntries();
     let suggestions: CommandAutocompleteSuggestion[] = [];
     if (insideCommand) {
@@ -280,10 +306,9 @@ export class CommandHandler implements InputManager {
         suggestions = this.rankSuggestions(query, commandEntries);
       }
     }
-    const argumentHint = !insideCommand && exactCommand && !hasArguments && exactCommand.options.length > 0 ? exactCommand.options.map((option) => option.flags).join(' ') : undefined;
 
     return {
-      suggestions,
+      suggestions: suggestions.map((suggestion) => ({ ...suggestion, value: `${suggestion.value} ` })),
       replaceFrom: 0,
       replaceTo,
       visible: insideCommand && suggestions.length > 0,
@@ -378,7 +403,7 @@ export class CommandHandler implements InputManager {
   private rankSuggestions(query: string, entries: AutocompleteEntry[]): CommandAutocompleteSuggestion[] {
     if (!query) {
       return entries.slice(0, 20).map((entry) => ({
-        value: entry.value,
+        value: entry.canonical,
         display: entry.value,
         description: entry.description,
         argumentHint: entry.argumentHint,

package/src/commands/base-command.ts

@@ -35,6 +35,10 @@ export abstract class BaseCommand<T = ExplorBot> {
     return this.name === commandName || this.aliases.includes(commandName);
   }
 
+  completeArguments(): ArgumentCompletion[] {
+    return [];
+  }
+
   printSuggestions(): void {
     if (this.suggestions.length === 0) return;
     const prefix = isInteractive() ? '/' : `${getCliName()} `;
@@ -63,3 +67,8 @@ export abstract class BaseCommand<T = ExplorBot> {
     return { opts: cmd.opts(), args: cmd.args };
   }
 }
+
+export interface ArgumentCompletion {
+  value: string;
+  display?: string;
+}