explorbot 0.4.10 → 0.5.0

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/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/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;
+}

package/src/commands/explore-command.ts

@@ -10,7 +10,7 @@ import { ErrorPageError, getStateErrorPageError } from '../utils/error-page.ts';
 import { tag } from '../utils/logger.js';
 import { type NextStepSection, printNextSteps, relativeToCwd } from '../utils/next-steps.ts';
 import { safeFilename } from '../utils/strings.ts';
-import { BaseCommand, type Suggestion } from './base-command.js';
+import { type ArgumentCompletion, BaseCommand, type Suggestion } from './base-command.js';
 
 const MAX_SUB_PAGE_ATTEMPTS = 30;
 const PRIORITY_ORDER: Record<string, number> = { critical: 0, important: 1, high: 2, normal: 3, low: 4 };
@@ -19,7 +19,7 @@ export const DEADLINE_TEST_ALLOWANCE_MS = 5 * 60_000;
 
 export class ExploreCommand extends BaseCommand {
   name = 'explore';
-  description = 'Start web exploration';
+  description = 'Start web exploration on the current page, or on the URL given as the first argument';
   options = [
     { flags: '--max-tests <number>', description: 'Maximum number of tests to run' },
     { flags: '--max-duration <minutes>', description: 'Wall-clock budget in minutes; wraps up the session before the limit is hit' },
@@ -61,6 +61,12 @@ export class ExploreCommand extends BaseCommand {
       this.hardDeadlineAt = Date.now() + this.maxDurationMinutes * 60_000 - DEADLINE_RESERVE_MS;
     }
 
+    const [target] = remaining;
+    if (target?.startsWith('/') || target?.startsWith('http://') || target?.startsWith('https://')) {
+      remaining.shift();
+      await this.explorBot.visit(target);
+    }
+
     const feature = (opts.focus as string) || remaining.join(' ') || undefined;
     const cfg = this.parseConfigure(opts.configure as string | undefined);
     if (cfg.priorities) this.priorityFilter = new Set(cfg.priorities);
@@ -97,6 +103,13 @@ export class ExploreCommand extends BaseCommand {
     }
   }
 
+  completeArguments(): ArgumentCompletion[] {
+    return this.explorBot
+      .stateManager()
+      .getKnownUrls()
+      .map((url) => ({ value: url }));
+  }
+
   private originLabel(test: Test): string {
     return this.oldTestRefs.has(test) ? 'OLD' : 'NEW';
   }

package/src/commands/freesail-command.ts

@@ -1,5 +1,6 @@
 import { Planner } from '../ai/planner.js';
 import { Researcher } from '../ai/researcher.js';
+import { normalizeUrl } from '../state-manager.js';
 import { Stats } from '../stats.js';
 import { tag } from '../utils/logger.js';
 import { loop } from '../utils/loop.js';
@@ -67,12 +68,18 @@ export class FreesailCommand extends BaseCommand {
         const suggestion = await navigator.freeSail({ strategy, scope, visitedUrls });
         if (!suggestion) {
           tag('info').log('No navigation suggestion available');
-          return;
+          ctx.stop();
         }
 
         if (scope && !suggestion.target.startsWith(scope)) {
           tag('warning').log(`Suggestion ${suggestion.target} is outside scope ${scope}, skipping`);
-          return;
+          ctx.stop();
+        }
+
+        const currentUrl = stateManager.getCurrentState()?.url;
+        if (currentUrl && normalizeUrl(suggestion.target) === normalizeUrl(currentUrl)) {
+          tag('info').log(`No new navigation target available after ${currentUrl}; stopping exploration`);
+          ctx.stop();
         }
 
         tag('info').log(`Navigating to: ${suggestion.target} - ${suggestion.reason}`);

package/src/commands/init-command.ts

@@ -163,7 +163,7 @@ export function runInitCommand(options: InitCommandOptions): void {
     log('2. Set AI models config file');
     log('3. Set web application URL in the config file');
     log('4. Add initial knowledge (how to authorize to the application, etc.)');
-    tag('substep').log(chalk.yellow(`${getCliName()} learn * 'to authorize use these credentials: admin@example.com / secret123'`));
+    tag('substep').log(chalk.yellow(`${getCliName()} learn '*' 'to authorize use these credentials: admin@example.com / secret123'`));
     tag('substep').log('You can use ${env.LOGIN} and ${env.PASSWORD} to reference environment variables.');
 
     log('5. Launch application on a relative URL');

package/src/commands/navigate-command.ts

@@ -1,5 +1,5 @@
 import { tag } from '../utils/logger.js';
-import { BaseCommand, type Suggestion } from './base-command.js';
+import { type ArgumentCompletion, BaseCommand, type Suggestion } from './base-command.js';
 
 export class NavigateCommand extends BaseCommand {
   name = 'navigate';
@@ -18,4 +18,11 @@ export class NavigateCommand extends BaseCommand {
     await this.explorBot.visit(destination);
     tag('success').log(`Navigation requested: ${destination}`);
   }
+
+  completeArguments(): ArgumentCompletion[] {
+    return this.explorBot
+      .stateManager()
+      .getKnownUrls()
+      .map((url) => ({ value: url }));
+  }
 }

package/src/commands/plan-load-command.ts

@@ -1,5 +1,6 @@
+import { Plan } from '../test-plan.js';
 import { tag } from '../utils/logger.js';
-import { BaseCommand, type Suggestion } from './base-command.js';
+import { type ArgumentCompletion, BaseCommand, type Suggestion } from './base-command.js';
 
 export class PlanLoadCommand extends BaseCommand {
   name = 'plan:load';
@@ -18,4 +19,8 @@ export class PlanLoadCommand extends BaseCommand {
     const plan = this.explorBot.loadPlan(filename);
     tag('success').log(`Plan loaded: ${plan.title} with ${plan.tests.length} tests`);
   }
+
+  completeArguments(): ArgumentCompletion[] {
+    return Plan.listFiles(this.explorBot.getPlansDir()).map((file) => ({ value: file.name, display: file.label }));
+  }
 }