explorbot 0.3.0 → 0.3.1

package/dist/package.json

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

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

@@ -7,6 +7,7 @@ export interface ToolExecution {
 }
 export declare function toToolExecution(toolName: string, input: any, rawOutput: any): ToolExecution;
 export declare function toolExecutionLabel(input: Record<string, any> | undefined): string;
+export declare const NARRATION_TOOL = "commentary";
 export declare class Conversation {
     messages: ModelMessage[];
     model: any;

package/dist/src/ai/conversation.js

@@ -7,6 +7,7 @@ export function toToolExecution(toolName, input, rawOutput) {
 export function toolExecutionLabel(input) {
     return input?.explanation || input?.assertion || input?.reason || input?.request || '';
 }
+export const NARRATION_TOOL = 'commentary';
 const AUTO_COMPACT_ARIA_CHANGES_CUTOFF = 500;
 const AUTO_COMPACT_TARGETED_HTML_CUTOFF = 500;
 export class Conversation {
@@ -203,6 +204,8 @@ export class Conversation {
             for (const part of message.content) {
                 if (part.type !== 'tool-result')
                     continue;
+                if (part.toolName === NARRATION_TOOL)
+                    continue;
                 executions.push(toToolExecution(part.toolName, toolCalls.get(part.toolCallId) || {}, part.output));
             }
         }

package/dist/src/ai/fisherman.js

@@ -158,7 +158,7 @@ export class Fisherman {
 
       AVAILABLE TOOLS:
       ${toolNames.join(', ')}.
-      Use tool names exactly as listed. Do not invent aliases, combined names, or names with channel markers such as "commentary".
+      Use tool names exactly as listed. Do not invent aliases or combined names.
       Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
 
       WORKFLOW:

package/dist/src/ai/pilot.js

@@ -13,7 +13,8 @@ import { truncateJson } from "../utils/strings.js";
 import { capabilityGroundingRule, dataProtectionRules } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 import { withdrawVisionTools } from "./tools.js";
-const CHECK_TOOLS = ['verify', 'see', 'research', 'context'];
+const CHECK_TOOLS = ['verify', 'see', 'research'];
+const EVIDENCE_TOOLS = ['verify', 'see'];
 const META_TOOLS = ['record', 'reset', 'stop', 'finish'];
 const PILOT_MESSAGE_LIMIT = 2;
 const PILOT_MESSAGE_MAX_LENGTH = 160;
@@ -280,6 +281,10 @@ export class Pilot {
       overrides the others — weigh them together. Tester's record() notes are the LEAST reliable; always
       cross-check against actual actions and state. Visual screenshot analysis is strong for UI state
       (active tabs, visible counts, colors).
+      Judge every check by WHAT IT ESTABLISHES, never by the fact that it ran. A check that executed
+      successfully is failure evidence when its content negates the scenario goal — the goal's object
+      absent, the action not performed, the interaction impossible. "The check passed" and "the goal was
+      met" are different claims.
       If the final page clearly shows an equivalent success state in a different UI form, do not fail only
       because one narrow assertion targeted a specific badge, count, toast, or wording that the product
       represents differently.
@@ -499,7 +504,7 @@ export class Pilot {
     async settleExpectations(task, finalState) {
         let image = null;
         if (finalState?.screenshot && this.provider.hasVision())
-            image = `data:image/png;base64,${finalState.screenshot.toString('base64')}`;
+            image = finalState.screenshot;
         const decided = (text) => {
             if (task.hasAchievedAny() && !task.getRemainingExpectations().includes(text))
                 return 'passed';
@@ -897,20 +902,20 @@ export class Pilot {
     hasSuccessfulCheckEvidence(currentState, testerConversation) {
         if (Object.values(currentState.verifications ?? {}).some(Boolean))
             return true;
-        return testerConversation.getToolExecutions().some((t) => CHECK_TOOLS.includes(t.toolName) && t.wasSuccessful);
+        return testerConversation.getToolExecutions().some((t) => EVIDENCE_TOOLS.includes(t.toolName) && t.wasSuccessful);
     }
     formatSuccessfulAssertions(currentState, testerConversation) {
         const lines = [];
         for (const [assertion, passed] of Object.entries(currentState.verifications ?? {})) {
             if (passed)
-                lines.push(`PASS state verification: ${assertion}`);
+                lines.push(`state verification (passed): ${assertion}`);
         }
         for (const exec of testerConversation.getToolExecutions()) {
-            if (!CHECK_TOOLS.includes(exec.toolName) || !exec.wasSuccessful)
+            if (!EVIDENCE_TOOLS.includes(exec.toolName) || !exec.wasSuccessful)
                 continue;
             const description = exec.input?.assertion || exec.input?.request || truncateJson(exec.input);
             const result = exec.output?.message || exec.output?.analysis || exec.output?.result;
-            lines.push(`PASS ${exec.toolName}: ${description}${result ? ` -> ${result}` : ''}`);
+            lines.push(`CHECK ${exec.toolName} (executed successfully): ${description}${result ? ` -> ${result}` : ''}`);
         }
         return [...new Set(lines)].join('\n');
     }
@@ -1028,7 +1033,7 @@ export class Pilot {
 
       Tester tools: click, pressKey, form, see, verify, interact, context, research, xpathCheck,
       visualClick, back, getVisitedStates, reset, stop, finish, record.
-      Use tool names exactly as listed. Do not invent combined names, aliases, or names with channel markers such as "commentary".
+      Use tool names exactly as listed. Do not invent combined names or aliases.
 
       ${capabilityGroundingRule}
 

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

@@ -13,6 +13,8 @@ export declare class Provider {
     otelSdk: NodeSDK | null;
     defaultRetryOptions: RetryOptions;
     lastConversation: Conversation | null;
+    activeModelCalls: number;
+    modelCallWaiters: (() => void)[];
     constructor(config: AIConfig);
     validateConnection(): Promise<void>;
     getModelForAgent(agentName?: string): any;
@@ -23,6 +25,7 @@ export declare class Provider {
     getProviderOptionsForAgent(agentName: string): Record<string, any> | undefined;
     getReasoningForAgent(agentName?: string): string | undefined;
     getRetryOptions(options?: any): RetryOptions;
+    withModelRequestSlot<T>(fn: () => Promise<T>): Promise<T>;
     mergeProviderOptions(config: Record<string, any>, agentName?: string): Record<string, any>;
     finalizeConfig(config: Record<string, any>, options: any, telemetry: any): void;
     buildGenerateConfig(defaults: Record<string, any>, overrides: Record<string, any>, options: any): Record<string, any>;

package/dist/src/ai/provider.js

@@ -1,7 +1,9 @@
 import { OpenTelemetry } from '@ai-sdk/otel';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
-import { generateObject, generateText, isStepCount, registerTelemetry } from 'ai';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { generateObject, generateText, isStepCount, registerTelemetry, tool } from 'ai';
+import { z } from 'zod';
 import { clearActivity, setActivity } from "../activity.js";
 import { configuredModels, modelName as getModelName } from '../config.js';
 import { executionController } from "../execution-controller.js";
@@ -10,7 +12,7 @@ import { Stats } from "../stats.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { withRetry } from '../utils/retry.js';
 import { RulesLoader } from "../utils/rules-loader.js";
-import { Conversation, toToolExecution } from './conversation.js';
+import { Conversation, NARRATION_TOOL, toToolExecution } from './conversation.js';
 const debugLog = createDebug('explorbot:provider');
 const promptLog = createDebug('explorbot:provider:out');
 const responseLog = createDebug('explorbot:provider:in');
@@ -18,6 +20,16 @@ class AiError extends Error {
 }
 export class ContextLengthError extends Error {
 }
+const DEFAULT_PARALLEL_REQUESTS = 4;
+const modelSlotContext = new AsyncLocalStorage();
+const HARMONY_CHANNELS = ['commentary', 'analysis', 'final'];
+function createHarmonyChannelFallbackTool() {
+    return tool({
+        description: 'Internal compatibility fallback for model channel output. Do not call directly.',
+        inputSchema: z.record(z.string(), z.any()),
+        execute: async () => ({ message: 'Noted. Continue with your next action.' }),
+    });
+}
 let telemetryRegistered = false;
 const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
 function extractCachedTokens(usage) {
@@ -73,6 +85,8 @@ export class Provider {
         },
     };
     lastConversation = null;
+    activeModelCalls = 0;
+    modelCallWaiters = [];
     constructor(config) {
         if (!config?.model) {
             throw new AiError('AI model is not configured. Set ai.model in your config file.');
@@ -140,9 +154,31 @@ export class Provider {
     getRetryOptions(options = {}) {
         return {
             ...this.defaultRetryOptions,
-            maxAttempts: options.maxRetries || this.defaultRetryOptions.maxAttempts,
+            maxAttempts: options.maxRetries || this.config.retryAttempts || this.defaultRetryOptions.maxAttempts,
+            baseDelay: this.config.retryDelay || this.defaultRetryOptions.baseDelay,
         };
     }
+    async withModelRequestSlot(fn) {
+        if (modelSlotContext.getStore())
+            return fn();
+        const limit = Math.max(1, this.config.maxParallelRequests ?? DEFAULT_PARALLEL_REQUESTS);
+        if (this.activeModelCalls >= limit || this.modelCallWaiters.length > 0) {
+            await new Promise((resolve) => this.modelCallWaiters.push(resolve));
+        }
+        else {
+            this.activeModelCalls++;
+        }
+        try {
+            return await modelSlotContext.run(true, fn);
+        }
+        finally {
+            const next = this.modelCallWaiters.shift();
+            if (next)
+                next();
+            else
+                this.activeModelCalls--;
+        }
+    }
     mergeProviderOptions(config, agentName) {
         if (!agentName)
             return config;
@@ -269,7 +305,7 @@ export class Provider {
         const toolCalls = response.toolCalls || [];
         const toolResults = response.toolResults || [];
         const resultsById = new Map(toolResults.map((r) => [r.toolCallId, r]));
-        const toolExecutions = toolCalls.map((call) => toToolExecution(call.toolName || '', call.input, resultsById.get(call.toolCallId)?.output));
+        const toolExecutions = toolCalls.filter((call) => call.toolName !== NARRATION_TOOL).map((call) => toToolExecution(call.toolName || '', call.input, resultsById.get(call.toolCallId)?.output));
         return { conversation, response, toolExecutions };
     }
     async chat(messages, model, options = {}) {
@@ -279,7 +315,7 @@ export class Provider {
         const config = this.buildGenerateConfig({ maxOutputTokens: 16384 }, { model, abortSignal: executionController.getAbortSignal() }, options);
         promptLog(messages[messages.length - 1].content);
         try {
-            const response = await withRetry(async () => {
+            const response = await this.withModelRequestSlot(() => withRetry(async () => {
                 const result = await generateText({ messages, ...config });
                 this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
                 if (!result.text) {
@@ -293,7 +329,7 @@ export class Provider {
                     debugLog('finishReason=length, response may be truncated');
                 }
                 return result;
-            }, this.getRetryOptions(options));
+            }, this.getRetryOptions(options)));
             clearActivity();
             responseLog(response.text);
             return response;
@@ -318,7 +354,8 @@ export class Provider {
         const modelName = getModelName(model);
         setActivity(`🤖 Asking ${modelName} with dynamic tools`, 'ai');
         promptLog(`Using model: ${modelName}`);
-        const toolNames = Object.keys(tools || {});
+        const toolsWithCommentary = tools?.commentary ? tools : { ...tools, commentary: createHarmonyChannelFallbackTool() };
+        const toolNames = Object.keys(toolsWithCommentary || {});
         tag('debug').log(`Tools enabled: [${toolNames.join(', ')}]`);
         promptLog('Available tools:', toolNames);
         promptLog(messages[messages.length - 1].content);
@@ -327,9 +364,9 @@ export class Provider {
         const stopConditions = [isStepCount(maxRoundtrips)];
         if (extraStop)
             stopConditions.push(extraStop);
-        const config = this.buildGenerateConfig({ tools, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
+        const config = this.buildGenerateConfig({ tools: toolsWithCommentary, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
         try {
-            const response = await withRetry(async () => {
+            const response = await this.withModelRequestSlot(() => withRetry(async () => {
                 const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000));
                 this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
                 const hasToolCall = (result.toolCalls?.length || 0) > 0;
@@ -337,7 +374,7 @@ export class Provider {
                     throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
                 }
                 return result;
-            }, this.getRetryOptions(options));
+            }, this.getRetryOptions(options)));
             clearActivity();
             // Log tool usage summary
             if (response.toolCalls && response.toolCalls.length > 0) {
@@ -376,9 +413,9 @@ export class Provider {
         const config = this.buildGenerateConfig({ schema }, { model: modelToUse }, options);
         try {
             promptLog(messages[messages.length - 1].content);
-            const response = await withRetry(async () => {
+            const response = await this.withModelRequestSlot(() => withRetry(async () => {
                 return (await this.raceWithIdleTimeout((signal) => generateObject({ messages, ...config, abortSignal: signal }), config.timeout || 30000));
-            }, this.getRetryOptions(options));
+            }, this.getRetryOptions(options)));
             clearActivity();
             responseLog(response.object);
             this.recordUsage(options.agentName || 'unknown', modelName, response.usage);
@@ -512,7 +549,6 @@ export class Provider {
             throw new Error('Vision model not configured. Please set ai.visionModel in your config.');
         }
         setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');
-        const imageData = `data:image/png;base64,${image.toString()}`;
         const messages = [
             {
                 role: 'user',
@@ -524,7 +560,7 @@ export class Provider {
                     {
                         type: 'file',
                         mediaType: 'image/png',
-                        data: imageData,
+                        data: image,
                     },
                 ],
             },
@@ -540,12 +576,12 @@ export class Provider {
             config.telemetry = telemetry;
         try {
             promptLog(`Processing image with prompt: ${prompt}`);
-            const response = await withRetry(async () => {
+            const response = await this.withModelRequestSlot(() => withRetry(async () => {
                 return await generateText({
                     messages,
                     ...config,
                 });
-            }, this.getRetryOptions());
+            }, this.getRetryOptions()));
             clearActivity();
             responseLog(response.text);
             this.recordUsage('vision', getModelName(this.config.visionModel), response.usage);
@@ -559,13 +595,13 @@ export class Provider {
         }
     }
     hasVision() {
-        return this.config.visionModel !== undefined;
+        return this.config.visionModel !== undefined && !Stats.visionDisabled;
     }
 }
 function repairToolCall(options) {
     if (options.toolCall.toolName.includes('<|channel|>'))
         return repairChannelMarker(options);
-    return null;
+    return repairHarmonyChannel(options);
 }
 function repairChannelMarker({ toolCall, tools }) {
     const markerIndex = toolCall.toolName.indexOf('<|channel|>');
@@ -577,4 +613,16 @@ function repairChannelMarker({ toolCall, tools }) {
     tag('warning').log(`Repaired tool name '${toolCall.toolName}' → '${toolName}'`);
     return { ...toolCall, toolName };
 }
+function repairHarmonyChannel({ toolCall, tools }) {
+    if (!HARMONY_CHANNELS.includes(toolCall.toolName))
+        return null;
+    if (!tools.commentary)
+        return null;
+    let input = toolCall.input;
+    if (typeof input !== 'string' || !input.trim().startsWith('{')) {
+        input = JSON.stringify({ content: typeof input === 'string' ? input : JSON.stringify(input ?? null) });
+    }
+    tag('warning').log(`Repaired tool name '${toolCall.toolName}' → 'commentary'`);
+    return { ...toolCall, toolName: NARRATION_TOOL, input };
+}
 export { AiError, Provider as AIProvider };

package/dist/src/ai/tester.js

@@ -6,6 +6,7 @@ import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { clearActivity, setActivity } from "../activity.js";
 import { Observability } from "../observability.js";
+import { normalizeUrl } from "../state-manager.js";
 import { Stats } from "../stats.js";
 import { TestResult } from "../test-plan.js";
 import { detectFocusArea } from "../utils/aria.js";
@@ -78,7 +79,7 @@ export class Tester extends TaskAgent {
     }
     async test(task, opts = {}) {
         Stats.tests++;
-        const state = this.stateManager.getCurrentState();
+        let state = this.stateManager.getCurrentState();
         if (!state)
             throw new Error('No state found');
         setActivity(`🧪 Testing: ${task.scenario}`, 'action');
@@ -97,7 +98,23 @@ export class Tester extends TaskAgent {
         const offFailedRequest = requestStore.onFailedRequest((r) => {
             task.addObservation(`Network error: ${r.method} ${r.path} → ${r.status}`);
         });
-        const initialState = ActionResult.fromState(state);
+        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}`);
+            try {
+                await this.explorer.visit(task.startUrl);
+                state = this.stateManager.getCurrentState();
+                if (!state)
+                    throw new Error('No state found after navigating to test start URL');
+                initialState = ActionResult.fromState(state);
+                startOnCurrentPage = true;
+            }
+            catch (error) {
+                debugLog(`Could not recover from error page: ${compactErrorMessage(error)}`);
+            }
+        }
         if (isErrorPage(initialState)) {
             task.start();
             this.testRun = await this.explorer.beginTest(task);
@@ -122,7 +139,7 @@ export class Tester extends TaskAgent {
                 startUrl: task.startUrl,
                 expected: task.expected,
             },
-        }, async () => this.runTestSession(task, initialState, conversation, { offFailedRequest }, opts));
+        }, async () => this.runTestSession(task, initialState, conversation, { offFailedRequest }, { ...opts, startOnCurrentPage }));
     }
     async runTestSession(task, initialState, conversation, handlers, opts) {
         const { offFailedRequest } = handlers;
@@ -421,7 +438,7 @@ export class Tester extends TaskAgent {
       <rules>
       Use tools ${this.ACTION_TOOLS.join(', ')} to interact with the page.
       Fall back to interact() when those fail, when the step needs a sequence of actions, or when your context is not enough to locate the element.
-      Use tool names exactly as listed in this prompt. Do not invent combined tool names, aliases, or names with channel markers such as "commentary".
+      Use tool names exactly as listed in this prompt. Do not invent combined tool names or aliases.
       Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
       Do not do unsuccesful clicks again.
       Do not run same tool calls with same parameters again.

package/dist/src/commands/explore-command.js

@@ -59,25 +59,30 @@ export class ExploreCommand extends BaseCommand {
             tag('warning').log(error.message);
             return;
         }
-        if (cfg.enabled) {
-            await this.runReuseMode(mainUrl, feature, cfg);
-        }
-        else {
-            await this.runFreshMode(mainUrl, feature, cfg.styles);
-        }
-        const mainPlan = this.completedPlans[0];
-        if (mainPlan)
-            this.explorBot.setCurrentPlan(mainPlan);
-        if (this.dryRun) {
+        try {
+            if (cfg.enabled) {
+                await this.runReuseMode(mainUrl, feature, cfg);
+            }
+            else {
+                await this.runFreshMode(mainUrl, feature, cfg.styles);
+            }
+            const mainPlan = this.completedPlans[0];
+            if (mainPlan)
+                this.explorBot.setCurrentPlan(mainPlan);
+            if (this.dryRun) {
+                this.printResults();
+                return;
+            }
+            if (mainUrl)
+                await this.explorBot.visit(mainUrl).catch((err) => tag('warning').log(`Could not return to ${mainUrl}: ${browserErrorMessage(err)}`));
+            const savedPath = this.explorBot.savePlans(this.completedPlans);
             this.printResults();
-            return;
+            this.printNextSteps(savedPath);
+        }
+        finally {
+            if (!this.dryRun)
+                await this.explorBot.printSessionAnalysis();
         }
-        if (mainUrl)
-            await this.explorBot.visit(mainUrl).catch((err) => tag('warning').log(`Could not return to ${mainUrl}: ${browserErrorMessage(err)}`));
-        const savedPath = this.explorBot.savePlans(this.completedPlans);
-        this.printResults();
-        await this.explorBot.printSessionAnalysis();
-        this.printNextSteps(savedPath);
     }
     originLabel(test) {
         return this.oldTestRefs.has(test) ? 'OLD' : 'NEW';

package/dist/src/config.d.ts

@@ -151,8 +151,9 @@ interface AIConfig {
     vision?: boolean;
     visionModel?: any;
     agenticModel?: any;
-    maxAttempts?: number;
+    retryAttempts?: number;
     retryDelay?: number;
+    maxParallelRequests?: number;
     agents?: AgentsConfig;
 }
 interface HtmlConfig {

package/package.json

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

package/src/ai/conversation.ts

@@ -17,6 +17,8 @@ export function toolExecutionLabel(input: Record<string, any> | undefined): stri
   return input?.explanation || input?.assertion || input?.reason || input?.request || '';
 }
 
+export const NARRATION_TOOL = 'commentary';
+
 const AUTO_COMPACT_ARIA_CHANGES_CUTOFF = 500;
 const AUTO_COMPACT_TARGETED_HTML_CUTOFF = 500;
 
@@ -227,6 +229,7 @@ export class Conversation {
       if (!Array.isArray(message.content)) continue;
       for (const part of message.content) {
         if (part.type !== 'tool-result') continue;
+        if (part.toolName === NARRATION_TOOL) continue;
         executions.push(toToolExecution(part.toolName, toolCalls.get(part.toolCallId) || {}, part.output));
       }
     }

package/src/ai/fisherman.ts

@@ -196,7 +196,7 @@ export class Fisherman implements Agent {
 
       AVAILABLE TOOLS:
       ${toolNames.join(', ')}.
-      Use tool names exactly as listed. Do not invent aliases, combined names, or names with channel markers such as "commentary".
+      Use tool names exactly as listed. Do not invent aliases or combined names.
       Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
 
       WORKFLOW:

package/src/ai/pilot.ts

@@ -25,7 +25,8 @@ import { capabilityGroundingRule, dataProtectionRules } from './rules.ts';
 import { isInteractive } from './task-agent.ts';
 import { withdrawVisionTools } from './tools.ts';
 
-const CHECK_TOOLS = ['verify', 'see', 'research', 'context'];
+const CHECK_TOOLS = ['verify', 'see', 'research'];
+const EVIDENCE_TOOLS = ['verify', 'see'];
 const META_TOOLS = ['record', 'reset', 'stop', 'finish'];
 const PILOT_MESSAGE_LIMIT = 2;
 const PILOT_MESSAGE_MAX_LENGTH = 160;
@@ -326,6 +327,10 @@ export class Pilot implements Agent {
       overrides the others — weigh them together. Tester's record() notes are the LEAST reliable; always
       cross-check against actual actions and state. Visual screenshot analysis is strong for UI state
       (active tabs, visible counts, colors).
+      Judge every check by WHAT IT ESTABLISHES, never by the fact that it ran. A check that executed
+      successfully is failure evidence when its content negates the scenario goal — the goal's object
+      absent, the action not performed, the interaction impossible. "The check passed" and "the goal was
+      met" are different claims.
       If the final page clearly shows an equivalent success state in a different UI form, do not fail only
       because one narrow assertion targeted a specific badge, count, toast, or wording that the product
       represents differently.
@@ -574,8 +579,8 @@ export class Pilot implements Agent {
   }
 
   async settleExpectations(task: Test, finalState?: ActionResult): Promise<SettledExpectation[]> {
-    let image: string | null = null;
-    if (finalState?.screenshot && this.provider.hasVision()) image = `data:image/png;base64,${finalState.screenshot.toString('base64')}`;
+    let image: Buffer | null = null;
+    if (finalState?.screenshot && this.provider.hasVision()) image = finalState.screenshot;
 
     const decided = (text: string): 'passed' | 'failed' => {
       if (task.hasAchievedAny() && !task.getRemainingExpectations().includes(text)) return 'passed';
@@ -995,20 +1000,20 @@ export class Pilot implements Agent {
 
   private hasSuccessfulCheckEvidence(currentState: ActionResult, testerConversation: Conversation): boolean {
     if (Object.values(currentState.verifications ?? {}).some(Boolean)) return true;
-    return testerConversation.getToolExecutions().some((t) => CHECK_TOOLS.includes(t.toolName) && t.wasSuccessful);
+    return testerConversation.getToolExecutions().some((t) => EVIDENCE_TOOLS.includes(t.toolName) && t.wasSuccessful);
   }
 
   private formatSuccessfulAssertions(currentState: ActionResult, testerConversation: Conversation): string {
     const lines: string[] = [];
     for (const [assertion, passed] of Object.entries(currentState.verifications ?? {})) {
-      if (passed) lines.push(`PASS state verification: ${assertion}`);
+      if (passed) lines.push(`state verification (passed): ${assertion}`);
     }
 
     for (const exec of testerConversation.getToolExecutions()) {
-      if (!CHECK_TOOLS.includes(exec.toolName) || !exec.wasSuccessful) continue;
+      if (!EVIDENCE_TOOLS.includes(exec.toolName) || !exec.wasSuccessful) continue;
       const description = exec.input?.assertion || exec.input?.request || truncateJson(exec.input);
       const result = exec.output?.message || exec.output?.analysis || exec.output?.result;
-      lines.push(`PASS ${exec.toolName}: ${description}${result ? ` -> ${result}` : ''}`);
+      lines.push(`CHECK ${exec.toolName} (executed successfully): ${description}${result ? ` -> ${result}` : ''}`);
     }
 
     return [...new Set(lines)].join('\n');
@@ -1137,7 +1142,7 @@ export class Pilot implements Agent {
 
       Tester tools: click, pressKey, form, see, verify, interact, context, research, xpathCheck,
       visualClick, back, getVisitedStates, reset, stop, finish, record.
-      Use tool names exactly as listed. Do not invent combined names, aliases, or names with channel markers such as "commentary".
+      Use tool names exactly as listed. Do not invent combined names or aliases.
 
       ${capabilityGroundingRule}
 

package/src/ai/provider.ts

@@ -1,8 +1,10 @@
 import { OpenTelemetry } from '@ai-sdk/otel';
 import { LangfuseSpanProcessor } from '@langfuse/otel';
 import { NodeSDK } from '@opentelemetry/sdk-node';
-import { generateObject, generateText, isStepCount, registerTelemetry } from 'ai';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { generateObject, generateText, isStepCount, registerTelemetry, tool } from 'ai';
 import type { ModelMessage } from 'ai';
+import { z } from 'zod';
 import { clearActivity, setActivity } from '../activity.ts';
 import { type AIConfig, configuredModels, modelName as getModelName } from '../config.js';
 import { executionController } from '../execution-controller.ts';
@@ -11,7 +13,7 @@ import { Stats } from '../stats.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { type RetryOptions, withRetry } from '../utils/retry.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
-import { Conversation, toToolExecution } from './conversation.js';
+import { Conversation, NARRATION_TOOL, toToolExecution } from './conversation.js';
 
 const debugLog = createDebug('explorbot:provider');
 const promptLog = createDebug('explorbot:provider:out');
@@ -20,6 +22,20 @@ const responseLog = createDebug('explorbot:provider:in');
 class AiError extends Error {}
 export class ContextLengthError extends Error {}
 
+const DEFAULT_PARALLEL_REQUESTS = 4;
+
+const modelSlotContext = new AsyncLocalStorage<boolean>();
+
+const HARMONY_CHANNELS = ['commentary', 'analysis', 'final'];
+
+function createHarmonyChannelFallbackTool() {
+  return tool({
+    description: 'Internal compatibility fallback for model channel output. Do not call directly.',
+    inputSchema: z.record(z.string(), z.any()),
+    execute: async () => ({ message: 'Noted. Continue with your next action.' }),
+  });
+}
+
 let telemetryRegistered = false;
 
 const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
@@ -79,6 +95,8 @@ export class Provider {
   };
 
   lastConversation: Conversation | null = null;
+  private activeModelCalls = 0;
+  private modelCallWaiters: (() => void)[] = [];
 
   constructor(config: AIConfig) {
     if (!config?.model) {
@@ -154,10 +172,28 @@ export class Provider {
   private getRetryOptions(options: any = {}): RetryOptions {
     return {
       ...this.defaultRetryOptions,
-      maxAttempts: options.maxRetries || this.defaultRetryOptions.maxAttempts,
+      maxAttempts: options.maxRetries || this.config.retryAttempts || this.defaultRetryOptions.maxAttempts,
+      baseDelay: this.config.retryDelay || this.defaultRetryOptions.baseDelay,
     };
   }
 
+  private async withModelRequestSlot<T>(fn: () => Promise<T>): Promise<T> {
+    if (modelSlotContext.getStore()) return fn();
+    const limit = Math.max(1, this.config.maxParallelRequests ?? DEFAULT_PARALLEL_REQUESTS);
+    if (this.activeModelCalls >= limit || this.modelCallWaiters.length > 0) {
+      await new Promise<void>((resolve) => this.modelCallWaiters.push(resolve));
+    } else {
+      this.activeModelCalls++;
+    }
+    try {
+      return await modelSlotContext.run(true, fn);
+    } finally {
+      const next = this.modelCallWaiters.shift();
+      if (next) next();
+      else this.activeModelCalls--;
+    }
+  }
+
   private mergeProviderOptions(config: Record<string, any>, agentName?: string): Record<string, any> {
     if (!agentName) return config;
     const agentOptions = this.getProviderOptionsForAgent(agentName);
@@ -302,7 +338,7 @@ export class Provider {
     const toolResults = response.toolResults || [];
 
     const resultsById = new Map(toolResults.map((r: any) => [r.toolCallId, r]));
-    const toolExecutions = toolCalls.map((call: any) => toToolExecution(call.toolName || '', call.input, resultsById.get(call.toolCallId)?.output));
+    const toolExecutions = toolCalls.filter((call: any) => call.toolName !== NARRATION_TOOL).map((call: any) => toToolExecution(call.toolName || '', call.input, resultsById.get(call.toolCallId)?.output));
 
     return { conversation, response, toolExecutions };
   }
@@ -316,21 +352,23 @@ export class Provider {
 
     promptLog(messages[messages.length - 1].content);
     try {
-      const response = await withRetry(async () => {
-        const result = await generateText({ messages, ...config });
-        this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
-        if (!result.text) {
-          debugLog(result);
+      const response = await this.withModelRequestSlot(() =>
+        withRetry(async () => {
+          const result = await generateText({ messages, ...config });
+          this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
+          if (!result.text) {
+            debugLog(result);
+            if (result.finishReason === 'length') {
+              throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
+            }
+            throw new Error('No response text from AI');
+          }
           if (result.finishReason === 'length') {
-            throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
+            debugLog('finishReason=length, response may be truncated');
           }
-          throw new Error('No response text from AI');
-        }
-        if (result.finishReason === 'length') {
-          debugLog('finishReason=length, response may be truncated');
-        }
-        return result;
-      }, this.getRetryOptions(options));
+          return result;
+        }, this.getRetryOptions(options))
+      );
 
       clearActivity();
       responseLog(response.text);
@@ -356,7 +394,8 @@ export class Provider {
     setActivity(`🤖 Asking ${modelName} with dynamic tools`, 'ai');
     promptLog(`Using model: ${modelName}`);
 
-    const toolNames = Object.keys(tools || {});
+    const toolsWithCommentary = tools?.commentary ? tools : { ...tools, commentary: createHarmonyChannelFallbackTool() };
+    const toolNames = Object.keys(toolsWithCommentary || {});
     tag('debug').log(`Tools enabled: [${toolNames.join(', ')}]`);
     promptLog('Available tools:', toolNames);
     promptLog(messages[messages.length - 1].content);
@@ -365,17 +404,19 @@ export class Provider {
     const extraStop = options.stopWhen;
     const stopConditions: any[] = [isStepCount(maxRoundtrips)];
     if (extraStop) stopConditions.push(extraStop);
-    const config = this.buildGenerateConfig({ tools, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
+    const config = this.buildGenerateConfig({ tools: toolsWithCommentary, maxOutputTokens: 16384, toolChoice: 'auto', experimental_repairToolCall: repairToolCall }, { stopWhen: stopConditions, model }, options);
     try {
-      const response = await withRetry(async () => {
-        const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
-        this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
-        const hasToolCall = (result.toolCalls?.length || 0) > 0;
-        if (!result.text && !hasToolCall && result.finishReason === 'length') {
-          throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
-        }
-        return result;
-      }, this.getRetryOptions(options));
+      const response = await this.withModelRequestSlot(() =>
+        withRetry(async () => {
+          const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
+          this.recordUsage(options.agentName || 'unknown', modelName, result.usage);
+          const hasToolCall = (result.toolCalls?.length || 0) > 0;
+          if (!result.text && !hasToolCall && result.finishReason === 'length') {
+            throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
+          }
+          return result;
+        }, this.getRetryOptions(options))
+      );
 
       clearActivity();
 
@@ -418,9 +459,11 @@ export class Provider {
 
     try {
       promptLog(messages[messages.length - 1].content);
-      const response = await withRetry(async () => {
-        return (await this.raceWithIdleTimeout((signal) => generateObject({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
-      }, this.getRetryOptions(options));
+      const response = await this.withModelRequestSlot(() =>
+        withRetry(async () => {
+          return (await this.raceWithIdleTimeout((signal) => generateObject({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
+        }, this.getRetryOptions(options))
+      );
 
       clearActivity();
       responseLog(response.object);
@@ -572,8 +615,6 @@ export class Provider {
 
     setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');
 
-    const imageData = `data:image/png;base64,${image.toString()}`;
-
     const messages: ModelMessage[] = [
       {
         role: 'user',
@@ -585,7 +626,7 @@ export class Provider {
           {
             type: 'file',
             mediaType: 'image/png',
-            data: imageData,
+            data: image,
           },
         ],
       },
@@ -602,12 +643,14 @@ export class Provider {
 
     try {
       promptLog(`Processing image with prompt: ${prompt}`);
-      const response = await withRetry(async () => {
-        return await generateText({
-          messages,
-          ...config,
-        });
-      }, this.getRetryOptions());
+      const response = await this.withModelRequestSlot(() =>
+        withRetry(async () => {
+          return await generateText({
+            messages,
+            ...config,
+          });
+        }, this.getRetryOptions())
+      );
 
       clearActivity();
       responseLog(response.text);
@@ -623,13 +666,13 @@ export class Provider {
   }
 
   hasVision(): boolean {
-    return this.config.visionModel !== undefined;
+    return this.config.visionModel !== undefined && !Stats.visionDisabled;
   }
 }
 
 function repairToolCall(options: ToolCallRepairOptions): any | null {
   if (options.toolCall.toolName.includes('<|channel|>')) return repairChannelMarker(options);
-  return null;
+  return repairHarmonyChannel(options);
 }
 
 function repairChannelMarker({ toolCall, tools }: ToolCallRepairOptions): any | null {
@@ -641,6 +684,17 @@ function repairChannelMarker({ toolCall, tools }: ToolCallRepairOptions): any |
   return { ...toolCall, toolName };
 }
 
+function repairHarmonyChannel({ toolCall, tools }: ToolCallRepairOptions): any | null {
+  if (!HARMONY_CHANNELS.includes(toolCall.toolName)) return null;
+  if (!tools.commentary) return null;
+  let input = toolCall.input;
+  if (typeof input !== 'string' || !input.trim().startsWith('{')) {
+    input = JSON.stringify({ content: typeof input === 'string' ? input : JSON.stringify(input ?? null) });
+  }
+  tag('warning').log(`Repaired tool name '${toolCall.toolName}' → 'commentary'`);
+  return { ...toolCall, toolName: NARRATION_TOOL, input };
+}
+
 export { AiError, Provider as AIProvider };
 
 type ToolCallRepairOptions = { toolCall: any; tools: any };

package/src/ai/tester.ts

@@ -8,7 +8,7 @@ import { clearActivity, setActivity } from '../activity.ts';
 import type { RequestStore } from '../api/request-store.ts';
 import type { TestRun } from '../explorer.ts';
 import { Observability } from '../observability.ts';
-import type { StateTransition } from '../state-manager.ts';
+import { type StateTransition, normalizeUrl } from '../state-manager.ts';
 import { Stats } from '../stats.ts';
 import { type Test, TestResult, type TestResultType } from '../test-plan.ts';
 import { detectFocusArea } from '../utils/aria.ts';
@@ -100,7 +100,7 @@ export class Tester extends TaskAgent implements Agent {
 
   async test(task: Test, opts: TestOptions = {}): Promise<{ success: boolean }> {
     Stats.tests++;
-    const state = this.stateManager.getCurrentState();
+    let state = this.stateManager.getCurrentState();
     if (!state) throw new Error('No state found');
 
     setActivity(`🧪 Testing: ${task.scenario}`, 'action');
@@ -122,7 +122,21 @@ export class Tester extends TaskAgent implements Agent {
       task.addObservation(`Network error: ${r.method} ${r.path} → ${r.status}`);
     });
 
-    const initialState = ActionResult.fromState(state);
+    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}`);
+      try {
+        await this.explorer.visit(task.startUrl);
+        state = this.stateManager.getCurrentState();
+        if (!state) throw new Error('No state found after navigating to test start URL');
+        initialState = ActionResult.fromState(state);
+        startOnCurrentPage = true;
+      } catch (error) {
+        debugLog(`Could not recover from error page: ${compactErrorMessage(error)}`);
+      }
+    }
     if (isErrorPage(initialState)) {
       task.start();
       this.testRun = await this.explorer.beginTest(task);
@@ -153,7 +167,7 @@ export class Tester extends TaskAgent implements Agent {
           expected: task.expected,
         },
       },
-      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest }, opts)
+      async () => this.runTestSession(task, initialState, conversation, { offFailedRequest }, { ...opts, startOnCurrentPage })
     );
   }
 
@@ -481,7 +495,7 @@ export class Tester extends TaskAgent implements Agent {
       <rules>
       Use tools ${this.ACTION_TOOLS.join(', ')} to interact with the page.
       Fall back to interact() when those fail, when the step needs a sequence of actions, or when your context is not enough to locate the element.
-      Use tool names exactly as listed in this prompt. Do not invent combined tool names, aliases, or names with channel markers such as "commentary".
+      Use tool names exactly as listed in this prompt. Do not invent combined tool names or aliases.
       Match each tool input schema exactly. Do not invent parameter names or pass extra fields.
       Do not do unsuccesful clicks again.
       Do not run same tool calls with same parameters again.

package/src/commands/explore-command.ts

@@ -63,23 +63,26 @@ export class ExploreCommand extends BaseCommand {
       return;
     }
 
-    if (cfg.enabled) {
-      await this.runReuseMode(mainUrl, feature, cfg);
-    } else {
-      await this.runFreshMode(mainUrl, feature, cfg.styles);
-    }
+    try {
+      if (cfg.enabled) {
+        await this.runReuseMode(mainUrl, feature, cfg);
+      } else {
+        await this.runFreshMode(mainUrl, feature, cfg.styles);
+      }
 
-    const mainPlan = this.completedPlans[0];
-    if (mainPlan) this.explorBot.setCurrentPlan(mainPlan);
-    if (this.dryRun) {
+      const mainPlan = this.completedPlans[0];
+      if (mainPlan) this.explorBot.setCurrentPlan(mainPlan);
+      if (this.dryRun) {
+        this.printResults();
+        return;
+      }
+      if (mainUrl) await this.explorBot.visit(mainUrl).catch((err) => tag('warning').log(`Could not return to ${mainUrl}: ${browserErrorMessage(err)}`));
+      const savedPath = this.explorBot.savePlans(this.completedPlans);
       this.printResults();
-      return;
+      this.printNextSteps(savedPath);
+    } finally {
+      if (!this.dryRun) await this.explorBot.printSessionAnalysis();
     }
-    if (mainUrl) await this.explorBot.visit(mainUrl).catch((err) => tag('warning').log(`Could not return to ${mainUrl}: ${browserErrorMessage(err)}`));
-    const savedPath = this.explorBot.savePlans(this.completedPlans);
-    this.printResults();
-    await this.explorBot.printSessionAnalysis();
-    this.printNextSteps(savedPath);
   }
 
   private originLabel(test: Test): string {

package/src/config.ts

@@ -175,8 +175,9 @@ interface AIConfig {
   vision?: boolean;
   visionModel?: any;
   agenticModel?: any;
-  maxAttempts?: number;
+  retryAttempts?: number;
   retryDelay?: number;
+  maxParallelRequests?: number;
   agents?: AgentsConfig;
 }