explorbot 0.5.0 → 0.5.2

package/bin/explorbot-cli.ts

@@ -12,7 +12,7 @@ import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { knowledgeOption, wsOption } from '../src/commands/options/index.js';
+import { decisionModelOption, knowledgeOption, wsOption } from '../src/commands/options/index.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot, type ExplorBotOptions } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
@@ -33,6 +33,7 @@ const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version as stri
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
 wsOption.register(program);
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 
 process.on('uncaughtException', async (error) => {
   tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);

package/boat/prima/README.md

@@ -61,22 +61,49 @@ prima-cli browser stop
 
 Prima needs a model, and takes it from the environment. There is no `init` to run and nothing is written for you.
 
+The setup we recommend runs everything through OpenRouter with one key: GPT-OSS 120B served by Groq as the main model, and TypeSafe's Jev as the [decision model](https://github.com/testomatio/explorbot/blob/main/docs/web-testing/decisions.md), which answers narrow yes/no and pick-one questions so the main model is called less often.
+
 ```bash
-export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b
-export OPENROUTER_API_KEY=your-key
+PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b:nitro
+PRIMA_CLI_DECISION_MODEL=openrouter/typesafe/jev-1.13
+OPENROUTER_API_KEY=your-key
 ```
 
-The provider comes from the model name, so that is the whole setup. Fish uses `set -gx` instead of `export`. Since prima is usually run by a coding agent, the better home is the agent's own config — in `~/.claude/settings.json`, an `env` block reaches every command the agent runs:
+The provider comes from each model name, and `:nitro` asks OpenRouter for its fastest host, which is Groq for this model. Jev is optional: leave `PRIMA_CLI_DECISION_MODEL` unset and prima never calls it, or pass `--decision-model` for a single run.
+
+Prima is usually run by a coding agent, so the best home for these variables is the agent's own config, where they reach every command the agent runs.
+
+Claude Code, in `~/.claude/settings.json`:
 
 ```json
 {
   "env": {
-    "PRIMA_CLI_AI_MODEL": "openrouter/openai/gpt-oss-120b",
+    "PRIMA_CLI_AI_MODEL": "openrouter/openai/gpt-oss-120b:nitro",
+    "PRIMA_CLI_DECISION_MODEL": "openrouter/typesafe/jev-1.13",
     "OPENROUTER_API_KEY": "your-key"
   }
 }
 ```
 
+Codex, in `~/.codex/config.toml`:
+
+```toml
+[shell_environment_policy]
+set = { PRIMA_CLI_AI_MODEL = "openrouter/openai/gpt-oss-120b:nitro", PRIMA_CLI_DECISION_MODEL = "openrouter/typesafe/jev-1.13", OPENROUTER_API_KEY = "your-key" }
+```
+
+`set` is applied after Codex filters the inherited environment, so the key survives even where names containing `KEY` are stripped.
+
+To run prima yourself, or from any agent that inherits your shell, export them in `~/.bashrc` or `~/.zshrc`:
+
+```bash
+export PRIMA_CLI_AI_MODEL=openrouter/openai/gpt-oss-120b:nitro
+export PRIMA_CLI_DECISION_MODEL=openrouter/typesafe/jev-1.13
+export OPENROUTER_API_KEY=your-key
+```
+
+Fish uses `set -gx` in `~/.config/fish/config.fish` instead of `export`.
+
 Screenshot analysis needs its own model — one is never guessed from the main model. Set `PRIMA_CLI_VISION_MODEL`, or pass `--vision-model` for a single run, as `--model` does for the main one. Without it prima still runs, but settles `check` outcomes from the run log rather than from the page as seen.
 
 Every `PRIMA_CLI_*` variable mirrors the `EXPLORBOT_*` one of the same name and wins over it, so prima can be pointed at a different provider, model or URL without disturbing an explorbot setup on the same machine. `PRIMA_CLI_AI_MODEL`, `PRIMA_CLI_URL`, `PRIMA_CLI_VISION_MODEL` and the rest all work this way.

package/boat/prima/bin/prima-cli.ts

@@ -1,7 +1,8 @@
 #!/usr/bin/env bun
-import { knowledgeOption } from '../../../src/commands/options/index.ts';
+import { decisionModelOption, knowledgeOption } from '../../../src/commands/options/index.ts';
 import { createPrimaCommands } from '../src/cli.ts';
 
 const program = createPrimaCommands('prima');
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 program.parse();

package/dist/bin/explorbot-cli.js

@@ -12,7 +12,7 @@ import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { knowledgeOption, wsOption } from '../src/commands/options/index.js';
+import { decisionModelOption, knowledgeOption, wsOption } from '../src/commands/options/index.js';
 import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
@@ -30,6 +30,7 @@ const pkgVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf-8')).version;
 program.name(cli).description('AI-powered web exploration tool').version(pkgVersion, '-V, --version');
 wsOption.register(program);
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 process.on('uncaughtException', async (error) => {
     tag('error').log(`Uncaught exception: ${error instanceof Error ? `${error.message}\n${error.stack}` : String(error)}`);
     await flushTelemetry();

package/dist/boat/prima/bin/prima-cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-import { knowledgeOption } from "../../../src/commands/options/index.js";
+import { decisionModelOption, knowledgeOption } from "../../../src/commands/options/index.js";
 import { createPrimaCommands } from "../src/cli.js";
 const program = createPrimaCommands('prima');
 knowledgeOption.register(program);
+decisionModelOption.register(program);
 program.parse();

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -102,7 +102,7 @@
     "bash-tool": "^1.3.15",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "^4.2.0-beta.3",
+    "codeceptjs": "^4.2.0",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",

package/dist/src/action.d.ts

@@ -48,6 +48,7 @@ declare class Action {
     captureBrowserLogs(): Promise<any[]>;
     executeOnce(code: string, verbatim?: boolean): Promise<Action>;
     attempt(codeBlock: string, originalMessage?: string): Promise<boolean>;
+    attemptExactElementIndex(codeBlock: string, elementIndex: number, originalMessage?: string): Promise<boolean>;
     exitIframe(): Promise<void>;
     getActor(): CodeceptJS.I;
     getActionResult(): ActionResult | null;

package/dist/src/action.js

@@ -461,6 +461,13 @@ class Action {
             return false;
         }
     }
+    async attemptExactElementIndex(codeBlock, elementIndex, originalMessage) {
+        const applyElementIndex = (step) => {
+            step.opts = { ...step.opts, elementIndex };
+        };
+        codeceptjs.event.dispatcher.once(codeceptjs.event.step.started, applyElementIndex);
+        return this.attempt(codeBlock, originalMessage).finally(() => codeceptjs.event.dispatcher.off(codeceptjs.event.step.started, applyElementIndex));
+    }
     async exitIframe() {
         if (!this.playwrightHelper.frame)
             return;

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

@@ -1,3 +1,5 @@
+import { Observability } from "../observability.js";
+import { redactSecrets } from "../utils/secrets.js";
 const REQUEST_TIMEOUT_MS = 15000;
 export class JudgeProvider {
     model;
@@ -19,6 +21,9 @@ export class JudgeProvider {
         if (options)
             q = { type: 'choice', instructions: question, criteria: Object.fromEntries(options.map((option, index) => [String(index), option])) };
         const body = JSON.stringify({ model: this.model, state, questions: { q } });
+        const span = Observability.getSpan();
+        span?.setAttribute('langfuse.observation.input', redactSecrets(body));
+        span?.setAttribute('ai.telemetry.metadata.judgeEndpoint', this.url);
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
         try {

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

@@ -15,13 +15,15 @@ export declare class Judge {
         tool: boolean;
         direct: boolean;
     };
+    threshold: number;
     constructor(provider: JudgeProvider, enabled: {
         tool: boolean;
         direct: boolean;
-    });
+    }, threshold?: number);
     static fromConfig(config: AIConfig['decisionModel']): Judge | null;
     get toolEnabled(): boolean;
     decide(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;
+    pick(question: string, options: string[], state: unknown): Promise<number | null>;
     consult(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;
     request(question: string, options: string[] | boolean | null, state: unknown): Promise<Decision>;
     recordFailure(error: unknown): null;

package/dist/src/ai/judge.js

@@ -5,6 +5,7 @@ import { JudgeProvider } from "./judge-provider.js";
 const debugLog = createDebug('explorbot:judge');
 const APPROVAL_THRESHOLD = 0.7;
 export const UNDECIDED = 'undecided';
+const UNDECIDED_HINT = `Choose "${UNDECIDED}" if you are not sure or no option fits.`;
 export const JUDGE_PAGE_CAP = 12000;
 export class Decision {
     value;
@@ -23,14 +24,19 @@ export class Decision {
 export class Judge {
     provider;
     enabled;
-    constructor(provider, enabled) {
+    threshold;
+    constructor(provider, enabled, threshold = APPROVAL_THRESHOLD) {
         this.provider = provider;
         this.enabled = enabled;
+        this.threshold = threshold;
     }
     static fromConfig(config) {
         if (!config)
             return null;
-        return new Judge(new JudgeProvider(config.provider, config.model), { tool: config.tool !== false, direct: config.direct !== false });
+        const threshold = config.threshold ?? APPROVAL_THRESHOLD;
+        if (!(threshold > 0 && threshold < 1))
+            throw new Error(`decisionModel.threshold must be between 0 and 1, got ${config.threshold}`);
+        return new Judge(new JudgeProvider(config.provider, config.model), { tool: config.tool !== false, direct: config.direct !== false }, threshold);
     }
     get toolEnabled() {
         return this.enabled.tool;
@@ -40,13 +46,23 @@ export class Judge {
             return new Decision(null, 0);
         return this.consult(question, options, state);
     }
+    async pick(question, options, state) {
+        if (new Set(options).size < options.length)
+            return null;
+        const decision = await this.decide(question, [...options, UNDECIDED], state);
+        if (!decision.value)
+            return null;
+        return options.indexOf(decision.value) + 1;
+    }
     async consult(question, options, state) {
         if (Array.isArray(options) && options.length < 2)
             return new Decision(null, 0);
         return Observability.run('judge.decide', { tags: ['judge'] }, async () => {
             setActivity('⚖️ Asking judge...', 'ai');
             const decision = await this.request(question, options, state).finally(() => clearActivity());
-            Observability.getSpan()?.setAttribute('ai.telemetry.metadata.judgeDecision', JSON.stringify({ question, value: decision.value, confidence: decision.confidence }));
+            const span = Observability.getSpan();
+            span?.setAttribute('ai.telemetry.metadata.judgeQuestion', question);
+            span?.setAttribute('ai.telemetry.metadata.judgeDecision', JSON.stringify({ question, value: decision.value, confidence: decision.confidence, threshold: this.threshold, model: this.provider.model }));
             return decision;
         });
     }
@@ -54,10 +70,14 @@ export class Judge {
         let list;
         if (Array.isArray(options))
             list = options;
-        const answer = await this.provider.decide(state, question, list).catch((error) => this.recordFailure(error));
+        let instructions = question;
+        if (list?.includes(UNDECIDED))
+            instructions = `${question} ${UNDECIDED_HINT}`;
+        const answer = await this.provider.decide(state, instructions, list).catch((error) => this.recordFailure(error));
         if (!answer)
             return new Decision(null, 0);
-        if (answer.probability <= APPROVAL_THRESHOLD)
+        Observability.getSpan()?.setAttribute('langfuse.observation.output', JSON.stringify(answer));
+        if (answer.probability <= this.threshold)
             return new Decision(null, answer.probability);
         if (answer.value === UNDECIDED)
             return new Decision(null, answer.probability);
@@ -65,7 +85,10 @@ export class Judge {
     }
     recordFailure(error) {
         debugLog('judge declined: %s', error);
-        Observability.getSpan()?.setAttribute('ai.telemetry.metadata.judgeError', String(error));
+        const span = Observability.getSpan();
+        span?.setAttribute('ai.telemetry.metadata.judgeError', String(error));
+        span?.setAttribute('langfuse.observation.level', 'ERROR');
+        span?.setAttribute('langfuse.observation.status_message', String(error));
         return null;
     }
 }

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

@@ -41,6 +41,7 @@ export declare class Pilot implements Agent {
     buildVerdictSystemPrompt(task: Test): string;
     planTest(task: Test, currentState: ActionResult): Promise<string>;
     reviewNewPage(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
+    periodicAnalyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     analyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
     settleExpectations(task: Test, finalState?: ActionResult): Promise<SettledExpectation[]>;
     settleByJudge(task: Test, expectations: string[]): Promise<Map<string, SettledStatus>>;

package/dist/src/ai/pilot.js

@@ -11,7 +11,7 @@ import { createDebug, tag } from "../utils/logger.js";
 const debugLog = createDebug('explorbot:pilot');
 import { truncateJson } from "../utils/strings.js";
 import { createAskApiTool } from "./fisherman/tools.js";
-import { UNDECIDED } from "./judge.js";
+import { JUDGE_PAGE_CAP, UNDECIDED } from "./judge.js";
 import { capabilityGroundingRule, dataProtectionRules } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 import { withdrawVisionTools } from "./tools.js";
@@ -477,6 +477,22 @@ export class Pilot {
         Tester holds no recipe for this page until you load one — open the <experience> entries whose titles fit a step you are about to instruct.
       `, 'pilot.reviewNewPage', { tools: true, maxToolRoundtrips: 2, task });
     }
+    async periodicAnalyzeProgress(task, currentState, testerConversation) {
+        const toolCalls = testerConversation.getToolExecutions().slice(-this.stepsToReview);
+        const healthy = await this.judge?.decide('The recent actions advance the scenario toward its remaining expected outcomes.', null, {
+            scenario: task.scenario,
+            plannedSteps: task.plannedSteps,
+            expectations: this.formatExpectations(task),
+            runLog: task.notesToString() || 'No steps recorded.',
+            visitedUrls: task.getVisitedUrls({ localOnly: true }),
+            state: this.buildStateContext(currentState),
+            page: currentState.getCompactARIA().slice(0, JUDGE_PAGE_CAP),
+            recentActions: this.formatActions(toolCalls),
+        });
+        if (healthy?.approved)
+            return '';
+        return this.analyzeProgress(task, currentState, testerConversation);
+    }
     async analyzeProgress(task, currentState, testerConversation) {
         tag('substep').log('Pilot analyzing progress...');
         if (!this.conversation) {
@@ -487,9 +503,6 @@ export class Pilot {
         const toolCalls = testerConversation.getToolExecutions().slice(-this.stepsToReview);
         const actionsContext = this.formatActions(toolCalls);
         const stateContext = this.buildStateContext(currentState);
-        const healthy = await this.judge?.decide('The run is moving toward the goal and can continue without a supervisor reviewing it now.', null, { scenario: task.scenario, state: stateContext, recentActions: actionsContext });
-        if (healthy?.approved)
-            return '';
         const hasFailures = toolCalls.length === 0 || toolCalls.some((t) => !t.wasSuccessful);
         const text = await this.sendToPilot(dedent `
         START URL: ${task.startUrl}

package/dist/src/ai/provider.js

@@ -1,9 +1,9 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 import { OpenTelemetry } from '@ai-sdk/otel';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
-import { AsyncLocalStorage } from 'node:async_hooks';
-import dedent from 'dedent';
 import { APICallError, NoObjectGeneratedError, asSchema, extractJsonMiddleware, generateObject, generateText, isStepCount, parsePartialJson, registerTelemetry, tool, wrapLanguageModel } from 'ai';
+import dedent from 'dedent';
 import { z } from 'zod';
 import { clearActivity, setActivity } from "../activity.js";
 import { configuredModels, modelName as getModelName } from '../config.js';
@@ -51,15 +51,16 @@ const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum
 function extractCachedTokens(usage) {
     return usage?.inputTokenDetails?.cacheReadTokens ?? 0;
 }
-function abortAfterIdle(ms, cancel, controller, busy) {
+function abortAfterIdle(ms, state, controller, busy) {
     return new Promise((_, reject) => {
         const tick = () => {
-            if (cancel.cancelled)
+            if (state.cancelled)
                 return;
             if (executionController.isAwaitingInput() || busy.tools > 0) {
                 setTimeout(tick, ms);
                 return;
             }
+            state.timedOut = true;
             controller.abort();
             reject(new Error('AI request timeout'));
         };
@@ -232,14 +233,20 @@ export class Provider {
         });
     }
     async raceWithIdleTimeout(fn, timeoutMs, busy = { tools: 0 }) {
-        const cancel = { cancelled: false };
+        const state = { cancelled: false, timedOut: false };
         const controller = new AbortController();
         const combinedSignal = combinedAbortSignal(controller);
         try {
-            return await Promise.race([fn(combinedSignal), abortAfterIdle(timeoutMs, cancel, controller, busy)]);
+            return await Promise.race([fn(combinedSignal), abortAfterIdle(timeoutMs, state, controller, busy)]);
+        }
+        catch (error) {
+            if (state.timedOut && !executionController.getAbortSignal()?.aborted) {
+                throw new Error('AI request timeout', { cause: error });
+            }
+            throw error;
         }
         finally {
-            cancel.cancelled = true;
+            state.cancelled = true;
         }
     }
     async recoverFromContextLength(error, messages, options, retry) {
@@ -615,7 +622,7 @@ export class Provider {
         if (!this.config.visionModel) {
             throw new Error(`Vision model not configured. Set ai.visionModel in your config; ${getCliName()} recommended-models lists the providers that serve one`);
         }
-        setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');
+        setActivity(`🤖 Processing image with ${getModelName(this.config.visionModel)}`, 'ai');
         const messages = [
             {
                 role: 'user',

package/dist/src/ai/rules.js

@@ -480,6 +480,19 @@ export const actionRule = dedent `
 
   After hovering, use see() or context() to check what appeared.
 
+  ### I.seeInClipboard / I.seeClipboardEquals / I.clearClipboard
+
+  Check what a copy control put into the system clipboard. Run via form(), not click().
+  I.seeInClipboard asserts the clipboard contains the text, I.seeClipboardEquals asserts an exact match,
+  I.clearClipboard empties it — call it before copying so a stale value can't pass the check.
+
+  <example>
+    I.clearClipboard();
+    I.click({ role: 'button', text: 'Copy link' });
+    I.seeInClipboard('/invite/');
+    I.seeClipboardEquals('ABC-123');
+  </example>
+
   [DO NEVER USE OTHER CODECEPTJS COMMANDS THAN PROPOSED HERE]
   [INTERACT ONLY WITH ELEMENTS THAT ARE ON THE PAGE HTML]
   [DO NOT USE WAIT FUNCTIONS]

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

@@ -51,6 +51,7 @@ export declare class Tester extends TaskAgent implements Agent {
         success: boolean;
     }>;
     shouldAnalyzeProgress(iteration: number, currentState: ActionResult): boolean;
+    get isStruggling(): boolean;
     shouldStopForStalledExecution(task: Test, previousState: ActionResult, toolExecutions: any[]): boolean;
     prepareInstructionsForNextStep(task: Test): Promise<string>;
     reinjectContextIfNeeded(iteration: number, currentState: ActionResult): Promise<string>;

package/dist/src/ai/tester.js

@@ -285,7 +285,13 @@ export class Tester extends TaskAgent {
                             nextStep += `\n\n${guidance}`;
                     }
                     else if (this.shouldAnalyzeProgress(iteration, currentState) && this.pilot) {
-                        const guidance = await this.pilot.analyzeProgress(task, currentState, conversation);
+                        let guidance;
+                        if (this.isStruggling) {
+                            guidance = await this.pilot.analyzeProgress(task, currentState, conversation);
+                        }
+                        else {
+                            guidance = await this.pilot.periodicAnalyzeProgress(task, currentState, conversation);
+                        }
                         if (guidance)
                             nextStep += `\n\n${guidance}`;
                         this.consecutiveFailures = 0;
@@ -432,9 +438,7 @@ export class Tester extends TaskAgent {
             this.regionTransitioned = false;
             return true;
         }
-        if (this.consecutiveFailures >= 3)
-            return true;
-        if (this.consecutiveEmptyResults >= 2)
+        if (this.isStruggling)
             return true;
         if (iteration % this.progressCheckInterval !== 0)
             return false;
@@ -442,6 +446,9 @@ export class Tester extends TaskAgent {
             return false;
         return true;
     }
+    get isStruggling() {
+        return this.consecutiveFailures >= 3 || this.consecutiveEmptyResults >= 2;
+    }
     shouldStopForStalledExecution(task, previousState, toolExecutions) {
         if (task.hasFinished)
             return false;

package/dist/src/ai/tools.js

@@ -14,7 +14,7 @@ import { pause } from '../utils/loop.js';
 import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { WebElement } from "../utils/web-element.js";
 import { createJudgeTool } from "./judge-tool.js";
-import { JUDGE_PAGE_CAP, UNDECIDED } from "./judge.js";
+import { JUDGE_PAGE_CAP } from "./judge.js";
 import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 const debugLog = createDebug('explorbot:tools');
@@ -92,13 +92,20 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }, task) {
                 let ambiguityError = null;
                 for (let i = 0; i < commands.length; i++) {
                     const command = transformContainsCommand(commands[i]);
-                    const success = await action.attempt(command, explanation);
+                    let success = await action.attempt(command, explanation);
                     const attempt = { command, success };
                     if (action.lastError)
                         attempt.error = errorText(action.lastError);
                     attempts.push(attempt);
-                    if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound')
+                    if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound') {
                         ambiguityError = action.lastError;
+                        if (judge) {
+                            const labels = (await extractWebElements(ambiguityError))?.map((el) => el.label) || [];
+                            const index = await judge.pick(PICK_ELEMENT_QUESTION, labels, { intent: explanation, task: task.description });
+                            if (index)
+                                success = await action.attemptExactElementIndex(command, index, explanation);
+                        }
+                    }
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
                         if (!hasObservablePageChange(toolResult)) {
@@ -127,7 +134,7 @@ export function createCodeceptJSTools({ explorer, stateManager, judge }, task) {
                     ...toolResult,
                     attempts,
                     suggestion,
-                }, ambiguityError || action.lastError, judge, explanation);
+                }, ambiguityError || action.lastError);
             },
         }),
         hover: tool({
@@ -1148,11 +1155,11 @@ export async function failedToolResult(action, message, data, error, judge, inte
         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)
+        if (!judge || !matched)
+            return result;
+        const index = await judge.pick(PICK_ELEMENT_QUESTION, matched.map((el) => el.label), { intent });
+        if (!index)
             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;
     }
@@ -1170,6 +1177,7 @@ function getMultipleElementsSuggestion() {
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
     A match reported as not visible can never be acted on — pick one that is.
     If none of them is the element you want, narrow the locator with a container or its full unique text.
+    If the matches cannot be told apart, click the one you mean by appearance with visualClick().
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
 }
@@ -1206,6 +1214,7 @@ const MAX_DISAMBIGUATE_ELEMENTS = 10;
 const MAX_DISAMBIGUATE_TEXT = 80;
 const MAX_DISAMBIGUATE_HTML = 300;
 const MULTIPLE_ELEMENTS_PATTERN = 'multiple elements';
+const PICK_ELEMENT_QUESTION = 'Which listed element does the intent name?';
 async function extractWebElements(error) {
     if (!error || error.name !== 'MultipleElementsFound')
         return null;
@@ -1219,7 +1228,7 @@ async function extractWebElements(error) {
             const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
             const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
             const visible = await Promise.resolve(elements[i].isVisible?.()).catch(() => undefined);
-            result.push({ xpath, html, text, visible });
+            result.push({ xpath, html, text, visible, label: `${text || 'no text'} — ${html}` });
         }
         catch (e) {
             debugLog('Failed to get details for element %d: %s', i, e);

package/dist/src/commands/options/decision-model-option.d.ts

@@ -0,0 +1,6 @@
+import { BaseOption } from './base-option.js';
+export declare class DecisionModelOption extends BaseOption {
+    flags: string;
+    description: string;
+    apply(options: Record<string, any>): void;
+}

package/dist/src/commands/options/decision-model-option.js

@@ -0,0 +1,10 @@
+import { BaseOption } from './base-option.js';
+export class DecisionModelOption extends BaseOption {
+    flags = '--decision-model <model>';
+    description = 'Turn on the decision model for this run, as provider/model-id (e.g. openrouter/typesafe/jev-1.13)';
+    apply(options) {
+        if (!options.decisionModel)
+            return;
+        process.env.EXPLORBOT_DECISION_MODEL = options.decisionModel;
+    }
+}

package/dist/src/commands/options/index.d.ts

@@ -1,5 +1,7 @@
+import { DecisionModelOption } from './decision-model-option.js';
 import { KnowledgeOption } from './knowledge-option.js';
 import { WsOption } from './ws-option.js';
 export { BaseOption } from './base-option.js';
+export declare const decisionModelOption: DecisionModelOption;
 export declare const knowledgeOption: KnowledgeOption;
 export declare const wsOption: WsOption;

package/dist/src/commands/options/index.js

@@ -1,5 +1,7 @@
+import { DecisionModelOption } from './decision-model-option.js';
 import { KnowledgeOption } from './knowledge-option.js';
 import { WsOption } from './ws-option.js';
 export { BaseOption } from './base-option.js';
+export const decisionModelOption = new DecisionModelOption();
 export const knowledgeOption = new KnowledgeOption();
 export const wsOption = new WsOption();

package/dist/src/config.d.ts

@@ -162,6 +162,7 @@ interface AIConfig {
         model: string;
         tool?: boolean;
         direct?: boolean;
+        threshold?: number;
     };
     retryAttempts?: number;
     retryDelay?: number;
@@ -270,6 +271,7 @@ export declare class ConfigParser {
     static cleanupAllTestDirectories(): void;
     enterGlobalMode(config: ExplorbotConfig, target: string | null): Promise<ExplorbotConfig>;
     applyEnvSpec(config: ExplorbotConfig): void;
+    applyEnvDecisionModel(config: ExplorbotConfig): void;
     buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig>;
     findConfigFile(): string | null;
     loadConfigModule(configPath: string): Promise<any>;

package/dist/src/config.js

@@ -45,6 +45,7 @@ export const EXPLORBOT_ENV_VARS = [
     { name: 'EXPLORBOT_URL', required: true, description: 'Base URL to test; the API boat reads it as the base endpoint' },
     { name: 'EXPLORBOT_VISION_MODEL', description: 'Screenshot analysis; overrides the provider recommendation' },
     { name: 'EXPLORBOT_AGENTIC_MODEL', description: 'Captain and Pilot decisions; overrides the provider recommendation' },
+    { name: 'EXPLORBOT_DECISION_MODEL', description: 'Turns on the decision model, as provider/model-id (openrouter/typesafe/jev-1.13 or typesafe/jev-latest); overrides ai.decisionModel' },
     { name: 'EXPLORBOT_OUTPUT', description: 'Output root for states, plans, research, and reports. Defaults to the site dir under ~/.explorbot/sites' },
     { name: 'EXPLORBOT_EPHEMERAL', description: 'Keep no state between runs — output goes to a fresh temp directory instead of the site dir' },
     { name: 'EXPLORBOT_KNOWLEDGE', description: 'Inline knowledge text, applied to every page' },
@@ -138,6 +139,7 @@ export class ConfigParser {
             this.runtimeTarget = target;
             this.configPath = sourcePath;
             this.applyEnvSpec(this.config);
+            this.applyEnvDecisionModel(this.config);
             // Restore original directory after successful config load
             if (options?.path && originalCwd !== process.cwd()) {
                 process.chdir(originalCwd);
@@ -300,6 +302,15 @@ export class ConfigParser {
             config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
         config.dirs.spec = spec;
     }
+    applyEnvDecisionModel(config) {
+        const spec = process.env.EXPLORBOT_DECISION_MODEL;
+        if (!spec)
+            return;
+        const separator = spec.indexOf('/');
+        if (separator < 1)
+            throw new Error('EXPLORBOT_DECISION_MODEL must be written as "provider/model-id", e.g. openrouter/typesafe/jev-1.13');
+        config.ai.decisionModel = { ...config.ai.decisionModel, provider: spec.slice(0, separator), model: spec.slice(separator + 1) };
+    }
     async buildEnvConfig(baseUrl, outputRoot) {
         const provider = process.env.EXPLORBOT_AI_PROVIDER;
         const modelSpec = process.env.EXPLORBOT_AI_MODEL;