explorbot 0.2.5 → 0.3.1

package/src/ai/navigator.ts

@@ -213,7 +213,7 @@ class Navigator implements Agent {
     return reasons.join('; ') || null;
   }
 
-  async resolveState(message: string, actionResult: ActionResult, opts?: { action?: Action; expectedUrl?: string; onAttempt?: (attempt: { code: string; error?: string }) => void }): Promise<boolean> {
+  async resolveState(message: string, actionResult: ActionResult, opts?: { action?: Action; expectedUrl?: string; experience?: string; onAttempt?: (attempt: { code: string; error?: string }) => void }): Promise<boolean> {
     if (!this.provider) throw new Error('AI-assisted recovery is unavailable: no AI model is configured.');
 
     this.lastFailureReason = null;
@@ -226,7 +226,7 @@ class Navigator implements Agent {
     const knowledge = this.knowledgeTracker.renderRelevantContext(actionResult);
 
     const conversation = this.provider.startConversation(this.systemPrompt, 'navigator');
-    conversation.addUserText(await this.buildResolutionPrompt(message, actionResult));
+    conversation.addUserText(await this.buildResolutionPrompt(message, actionResult, opts?.experience));
 
     let stopReason: string | null = null;
     const tools = {
@@ -369,14 +369,10 @@ class Navigator implements Agent {
     return resolved;
   }
 
-  private async buildResolutionPrompt(message: string, actionResult: ActionResult): Promise<string> {
-    let experience = '';
-    if (!actionResult.isInsideIframe) {
-      const successful = this.experienceTracker.getSuccessfulExperience(actionResult);
-      if (successful.length > 0) {
-        tag('operation').log(`Found ${successful.length} experience ${pluralize(successful.length, 'file')} for: ${actionResult.url}`);
-        experience = `<experience>\nPast successful recipes recorded from prior runs for this page. Prefer these solutions first if they match the goal.\n\n${successful.join('\n\n')}\n</experience>`;
-      }
+  private async buildResolutionPrompt(message: string, actionResult: ActionResult, injectedExperience?: string): Promise<string> {
+    let experience = injectedExperience || '';
+    if (!experience && !actionResult.isInsideIframe) {
+      experience = this.experienceTracker.renderExperienceFor(actionResult);
     }
 
     return dedent`

package/src/ai/pilot.ts

@@ -25,8 +25,11 @@ 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;
 
 export class Pilot implements Agent {
   emoji = '🧭';
@@ -324,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.
@@ -465,9 +472,13 @@ export class Pilot implements Agent {
         the elements needed for the scenario. The page summary does not list every element.
         Prefer interacting with the current page over navigating away.
 
-        If you load a recipe via learnExperience, do NOT rewrite its code in your plan — the
-        raw recipe is forwarded to Tester automatically. Reference it by step ("apply recipe
-        steps 1–3, then…") and call out anywhere your scenario diverges from it.
+        Tester never sees <experience> — a recorded recipe reaches it only when you open one.
+        The entries listed are what was recorded on the page you are on now; recipes for the
+        pages this test moves to are listed when it gets there. Open the ones whose titles fit a
+        step taken from here, and say so in the plan when none of them fit.
+        Do NOT rewrite a loaded recipe's code — the raw recipe is forwarded to Tester
+        automatically. Reference it by step ("apply recipe steps 1–3, then…") and call out
+        anywhere your scenario diverges from it.
 
         Be concise and specific. Tester will follow your plan.
       `,
@@ -513,9 +524,11 @@ export class Pilot implements Agent {
         ${this.formatExpectations(task)}
 
         First: evaluate whether this navigation makes sense for the scenario goal. If the page is unrelated, instruct Tester to back() or reset(). Then plan next steps.
+
+        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',
-      { task }
+      { tools: true, maxToolRoundtrips: 2, task }
     );
   }
 
@@ -549,6 +562,8 @@ export class Pilot implements Agent {
         </recent_actions>
 
         What should Tester do next?
+
+        Before proposing new locators for a step that keeps failing, check <experience> for a recorded recipe covering it and load it.
       `,
       'pilot.analyze',
       { tools: hasFailures, maxToolRoundtrips: hasFailures ? 2 : 0, task }
@@ -564,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';
@@ -665,10 +680,9 @@ export class Pilot implements Agent {
 
     let finalUserText = userText;
     if (opts.tools) {
+      this.conversation!.cleanupTag('experience', '...cleaned experience index...');
       const tocBlock = this.getExperienceToc();
-      if (tocBlock) {
-        finalUserText = `${tocBlock}\n\n${userText}`;
-      }
+      if (tocBlock) finalUserText = `${tocBlock}\n\n${userText}`;
     }
     this.conversation!.addUserText(finalUserText);
 
@@ -682,8 +696,9 @@ export class Pilot implements Agent {
       telemetry: { functionId },
     });
     const text = result?.response?.text || '';
-    const learned = (result?.toolExecutions || []).filter((e: any) => e.toolName === 'learnExperience' && e.output?.content).map((e: any) => e.output.content);
+    const learned = (result?.toolExecutions || []).filter((e: any) => e.toolName === 'learnExperience' && e.output?.content).map((e: any) => ({ url: e.output.url, content: e.output.content }));
     if (learned.length === 0) return text;
+    opts.task.applyExperience(learned);
     return dedent`
       ${text}
 
@@ -691,7 +706,7 @@ export class Pilot implements Agent {
       Recipes from prior successful runs that Pilot judged relevant. Locators worked then; the page may have changed since.
       Treat code blocks below as a starting hypothesis. If a locator misses, fall back to ARIA/UI-map.
 
-      ${learned.join('\n\n')}
+      ${learned.map((recipe) => recipe.content).join('\n\n')}
       </applied_experience>
     `;
   }
@@ -718,6 +733,7 @@ export class Pilot implements Agent {
   }
 
   private buildPreconditionTool(task: Test) {
+    const unavailable = 'Data was not created and cannot be created automatically. Do not call precondition again for this test — continue with what the page already shows.';
     return {
       precondition: tool({
         description: 'Create fresh disposable data that the test will act on (edit, delete, filter). Describe WHAT to create, not what exists. Do NOT request users. Examples: "1 post", "1 comment", "1 label named Bug".',
@@ -732,7 +748,7 @@ export class Pilot implements Agent {
           if (!this.fisherman || !this.fisherman.isAvailable()) {
             const skipReason = await this.checkDataAvailability(task, description, 'Fisherman not available');
             if (skipReason) return { noted: true, prepared: false, skipped: true, reason: skipReason };
-            return { noted: true, prepared: false, reason: 'Fisherman not available' };
+            return { noted: true, prepared: false, reason: unavailable };
           }
 
           const result = await this.fisherman.prepareData(description, task.startUrl, task.sessionName);
@@ -741,7 +757,7 @@ export class Pilot implements Agent {
             if (result.summary) tag('warning').log(`Precondition failed: ${result.summary}`);
             const skipReason = await this.checkDataAvailability(task, description, result.summary);
             if (skipReason) return { noted: true, prepared: false, skipped: true, reason: skipReason };
-            return { noted: true, prepared: false, reason: result.summary };
+            return { noted: true, prepared: false, reason: `${result.summary || 'Data preparation failed'}. ${unavailable}` };
           }
 
           const items = result.created.map((c) => {
@@ -778,7 +794,7 @@ export class Pilot implements Agent {
       Reply with YES or NO on the first line, then a one-sentence reason on the second line.
     `;
 
-    const answer = await this.researcher.answerQuestionAboutScreenshot(screenshotState, question);
+    const answer = await this.researcher.answerQuestionAboutScreenshot(screenshotState, question).catch(() => null);
     if (!answer) return null;
 
     const firstLine = answer.split('\n')[0]?.trim().toUpperCase() ?? '';
@@ -870,15 +886,6 @@ export class Pilot implements Agent {
   private async fetchRequestedContext(text: string, currentState: ActionResult): Promise<string> {
     const parts: string[] = [];
 
-    if (text.includes('ATTACH_HTML')) {
-      const html = await currentState.simplifiedHtml();
-      parts.push(dedent`
-        <page_html>
-        ${html}
-        </page_html>
-      `);
-    }
-
     if (text.includes('ATTACH_ARIA')) {
       parts.push(dedent`
         <page_aria>
@@ -993,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');
@@ -1048,6 +1055,21 @@ export class Pilot implements Agent {
         const ariaDiff = t.output?.pageDiff?.ariaChanges;
         if (ariaDiff) line += `\n   ${ariaDiff}`;
 
+        if (t.output?.pageDiff?.urlChanged) line += `\n   moved: ${t.output.pageDiff.previousUrl} → ${t.output.pageDiff.currentUrl}`;
+
+        const failedRequests = (t.output?.pageDiff?.requests ?? []).filter((r: any) => r.status >= 400);
+        if (failedRequests.length > 0) {
+          line += `\n   requests: ${failedRequests.map((r: any) => `${r.method} ${r.path} → ${r.status}`).join(', ')}`;
+        }
+
+        const messages = (t.output?.pageDiff?.messages ?? []).slice(0, PILOT_MESSAGE_LIMIT);
+        if (messages.length > 0) {
+          line += `\n   messages: ${messages.map((m: string) => m.slice(0, PILOT_MESSAGE_MAX_LENGTH)).join(' | ')}`;
+        }
+
+        const consoleError = t.output?.pageDiff?.consoleErrors?.[0];
+        if (consoleError) line += `\n   console: ${consoleError.slice(0, PILOT_MESSAGE_MAX_LENGTH)}`;
+
         return line;
       })
       .join('\n\n');
@@ -1116,11 +1138,11 @@ export class Pilot implements Agent {
       role, icon classes with "or" in one XPath. If empty, broaden (drop role filter). Pass discovered
       XPath into NEXT instruction.
 
-      To request more context, mention ATTACH_HTML, ATTACH_ARIA, or ATTACH_UI_MAP — only when recent actions show failures.
+      To request more context, mention ATTACH_ARIA, ATTACH_SUMMARY, or ATTACH_UI_MAP — only when recent actions show failures.
 
-      Tester tools: click, pressKey, form, see, verify, 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".
+      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 or aliases.
 
       ${capabilityGroundingRule}
 

package/src/ai/planner/subpages.ts

@@ -4,7 +4,7 @@ import { normalizeUrl } from '../../state-manager.ts';
 import type { StateManager } from '../../state-manager.ts';
 import type { Plan } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
-import { isDynamicSegment } from '../../utils/url-matcher.ts';
+import { isSamePageFamily } from '../../utils/url-matcher.ts';
 import type { Provider } from '../provider.ts';
 import type { Constructor } from '../researcher/mixin.ts';
 
@@ -39,18 +39,7 @@ function buildKey(url: string, feature?: string): string {
 }
 
 export function isTemplateMatch(urlA: string, urlB: string): boolean {
-  const partsA = normalizeUrl(urlA).split('/');
-  const partsB = normalizeUrl(urlB).split('/');
-  if (partsA.length !== partsB.length) return false;
-
-  let diffCount = 0;
-  for (let i = 0; i < partsA.length; i++) {
-    if (partsA[i] === partsB[i]) continue;
-    diffCount++;
-    if (diffCount > 1) return false;
-    if (!isDynamicSegment(partsA[i]) && !isDynamicSegment(partsB[i])) return false;
-  }
-  return diffCount === 1;
+  return isSamePageFamily(urlA, urlB);
 }
 
 export function getPlannedByStateHash(hash: string): PlanRecord | null {

package/src/ai/planner.ts

@@ -149,7 +149,7 @@ export class Planner extends PlannerBase implements Agent {
 
       const actionResult = ActionResult.fromState(state);
       const combinedHtml = await actionResult.combinedHtml();
-      const similarHash = await findSimilarStateHash(combinedHtml);
+      const similarHash = await findSimilarStateHash(combinedHtml, state.url);
       if (similarHash) {
         const planned = getPlannedByStateHash(similarHash);
         if (planned) {

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' }, { 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,8 +666,35 @@ 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 repairHarmonyChannel(options);
+}
+
+function repairChannelMarker({ toolCall, tools }: ToolCallRepairOptions): any | null {
+  const markerIndex = toolCall.toolName.indexOf('<|channel|>');
+  if (markerIndex <= 0) return null;
+  const toolName = toolCall.toolName.slice(0, markerIndex);
+  if (!tools[toolName]) return null;
+  tag('warning').log(`Repaired tool name '${toolCall.toolName}' → '${toolName}'`);
+  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/researcher/cache.ts

@@ -60,7 +60,8 @@ export function getPreviousResearch(hash: string): string {
   return readFileSync(researchFile, 'utf8');
 }
 
-export function saveResearch(hash: string, text: string, combinedHtml?: string): string {
+export function saveResearch(state: ResearchState, text: string, combinedHtml?: string): string {
+  const { hash, url } = state;
   const researchDir = outputPath('research');
   const researchFile = join(researchDir, `${hash}.md`);
   if (!existsSync(researchDir)) mkdirSync(researchDir, { recursive: true });
@@ -74,14 +75,16 @@ export function saveResearch(hash: string, text: string, combinedHtml?: string):
     if (!existsSync(statesDir)) mkdirSync(statesDir, { recursive: true });
     const fingerprint = computeHtmlFingerprint(combinedHtml);
     const fingerprintFile = join(statesDir, `${hash}.fingerprint`);
-    writeFileSync(fingerprintFile, fingerprint.join('\n'));
+    const record: FingerprintRecord = { entries: fingerprint };
+    if (url) record.url = url;
+    writeFileSync(fingerprintFile, JSON.stringify(record));
     debugLog(`Fingerprint saved to ${fingerprintFile}`);
   }
 
   return researchFile;
 }
 
-function findSimilarMatch(combinedHtml: string): Promise<{ hash: string; similarity: number } | null> {
+function findSimilarMatch(combinedHtml: string, url?: string): Promise<FingerprintMatch | null> {
   const statesDir = getStatesDir();
   if (!existsSync(statesDir)) return Promise.resolve(null);
 
@@ -93,7 +96,7 @@ function findSimilarMatch(combinedHtml: string): Promise<{ hash: string; similar
       resolve(null);
     }, FINGERPRINT_WORKER_TIMEOUT_MS);
 
-    worker.on('message', (data: { matchHash: string | null; similarity: number }) => {
+    worker.on('message', (data: { matchHash: string | null; similarity: number; url?: string }) => {
       clearTimeout(timeout);
       const { matchHash, similarity } = data;
       if (!matchHash) {
@@ -102,7 +105,7 @@ function findSimilarMatch(combinedHtml: string): Promise<{ hash: string; similar
       }
 
       debugLog(`Similar fingerprint found: ${matchHash} (${similarity}% similar)`);
-      resolve({ hash: matchHash, similarity });
+      resolve({ hash: matchHash, similarity, url: data.url });
     });
 
     worker.postMessage({
@@ -110,17 +113,22 @@ function findSimilarMatch(combinedHtml: string): Promise<{ hash: string; similar
       statesDir,
       maxAgeMs: FINGERPRINT_MAX_AGE_MS,
       threshold: SIMILARITY_THRESHOLD,
+      url,
     });
   });
 }
 
-export async function findSimilarResearch(combinedHtml: string): Promise<string | null> {
-  const match = await findSimilarMatch(combinedHtml);
+export async function findSimilarResearch(combinedHtml: string, url?: string): Promise<string | null> {
+  const match = await findSimilarMatch(combinedHtml, url);
   if (!match) return null;
   return getCachedResearch(match.hash) || null;
 }
 
-export async function findSimilarStateHash(combinedHtml: string): Promise<string | null> {
-  const match = await findSimilarMatch(combinedHtml);
+export async function findSimilarStateHash(combinedHtml: string, url?: string): Promise<string | null> {
+  const match = await findSimilarMatch(combinedHtml, url);
   return match?.hash || null;
 }
+
+type FingerprintRecord = { entries: string[]; url?: string };
+type FingerprintMatch = { hash: string; similarity: number; url?: string };
+type ResearchState = { hash: string; url?: string };

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

@@ -128,7 +128,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
         updated = `${cached.trimEnd()}\n\n# Extended Research\n\n${sectionMarkdown}\n`;
       }
 
-      saveResearch(pageStateHash, updated);
+      saveResearch({ hash: pageStateHash }, updated);
       tag('substep').log(`Overlay research appended: ${focusArea.name}`);
       return sectionMarkdown;
     }