explorbot 0.2.5 → 0.3.0

package/src/action.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { context, trace } from '@opentelemetry/api';
 import { container, recorder } from 'codeceptjs';
 import * as codeceptjs from 'codeceptjs';
-import { ActionResult, type FocusedElement } from './action-result.js';
+import { ActionResult, type FocusedElement, type NetworkCall } from './action-result.js';
 import { clearActivity, setActivity } from './activity.ts';
 import { ConfigParser, outputPath } from './config.js';
 import type { ExplorbotConfig } from './config.js';
@@ -21,6 +21,8 @@ const debugLog = createDebug('explorbot:action');
 const CAPTURE_NAVIGATION_TRANSITION_ATTEMPTS = 3;
 const DEFAULT_ACTION_TIMEOUT = 3000;
 const DEFAULT_PAGE_TIMEOUT = 3000;
+const MAX_NETWORK_CALLS = 10;
+const IMPORTANT_LOG_LEVELS = new Set(['info', 'error', 'warning', 'warn']);
 
 class Action {
   private actor: CodeceptJS.I;
@@ -38,6 +40,8 @@ class Action {
   private recorder?: PlaywrightRecorder;
   private recovery: RecoveryRunner;
   private mainDocumentStatus: number | undefined = undefined;
+  private networkRequests: NetworkCall[] = [];
+  private baseOrigin: string;
 
   constructor(actor: CodeceptJS.I, stateManager: StateManager, recorder?: PlaywrightRecorder, recovery?: RecoveryRunner) {
     this.actor = actor;
@@ -46,6 +50,7 @@ class Action {
     this.playwrightHelper = container.helpers('Playwright');
     this.recorder = recorder;
     this.recovery = recovery || ((fn) => fn());
+    this.baseOrigin = URL.parse(this.config.playwright?.url || '')?.origin || '';
   }
 
   async saveScreenshot(): Promise<string | undefined> {
@@ -127,9 +132,7 @@ class Action {
       const logPath = join(statesDir, logFile);
       const formattedLogs = browserLogs.map((log: any) => {
         const logTimestamp = new Date().toISOString();
-        const level = (log.type || log.level || 'LOG').toUpperCase();
-        const message = log.text || log.message || String(log);
-        return `[${logTimestamp}] ${level}: ${message}`;
+        return `[${logTimestamp}] ${log.type.toUpperCase()}: ${log.text}`;
       });
       fs.writeFileSync(logPath, `${formattedLogs.join('\n')}\n`, 'utf8');
 
@@ -157,12 +160,16 @@ class Action {
         ariaSnapshotFile = ariaFileName;
       }
 
+      const networkRequests = this.networkRequests;
+      this.networkRequests = [];
+
       const result = new ActionResult({
         html,
         title,
         httpStatus: await this.captureMainDocumentStatus(),
         url,
         browserLogs,
+        networkRequests,
         htmlFile,
         logFile,
         screenshotFile,
@@ -202,26 +209,53 @@ class Action {
     }
   }
 
-  private captureMainDocumentResponse(): () => void {
+  private captureResponses(): () => void {
     const page = this.playwrightHelper.page;
     if (!page?.on || !page?.off) return () => {};
 
     this.mainDocumentStatus = undefined;
+    this.networkRequests = [];
 
     const handler = (response: any) => {
       const request = response.request();
-      if (request.resourceType() !== 'document') return;
-      if (response.frame() !== page.mainFrame()) return;
       const status = response.status();
       if (typeof status !== 'number') return;
       if (status <= 0) return;
-      this.mainDocumentStatus = status;
+
+      if (request.resourceType() === 'document') {
+        if (response.frame() !== page.mainFrame()) return;
+        this.mainDocumentStatus = status;
+        return;
+      }
+
+      this.recordNetworkCall(request, status);
     };
 
     page.on('response', handler);
     return () => page.off('response', handler);
   }
 
+  private recordNetworkCall(request: any, status: number): void {
+    const resourceType = request.resourceType();
+    if (resourceType !== 'xhr' && resourceType !== 'fetch') return;
+
+    const url = URL.parse(request.url());
+    if (!url) return;
+    if (url.origin !== this.baseOrigin) return;
+
+    const call: NetworkCall = { method: request.method(), path: url.pathname, status };
+    if (this.networkRequests.some((r) => r.method === call.method && r.path === call.path && r.status === call.status)) return;
+
+    if (this.networkRequests.length >= MAX_NETWORK_CALLS) {
+      if (status < 400) return;
+      const succeeded = this.networkRequests.findIndex((r) => r.status < 400);
+      if (succeeded === -1) return;
+      this.networkRequests.splice(succeeded, 1);
+    }
+
+    this.networkRequests.push(call);
+  }
+
   /**
    * Capture HTML snapshots of all iframes on the page
    */
@@ -267,13 +301,7 @@ class Action {
     try {
       const logs = await (this.actor as any).grabBrowserLogs();
 
-      // Filter for important logs (info, error, warning)
-      const importantLogs = logs.filter((log: any) => {
-        const level = log.type || log.level;
-        return ['info', 'error', 'warning', 'warn'].includes(level);
-      });
-
-      return importantLogs;
+      return logs.map(toBrowserLog).filter((log: any) => IMPORTANT_LOG_LEVELS.has(log.type));
     } catch (error) {
       debugLog('Failed to capture browser logs:', error);
       return [];
@@ -292,7 +320,7 @@ class Action {
     const stepListener = attachStepLogger(executedSteps, assertionSteps);
     const groupId = this.recorder ? await this.recorder.beginAction(codeString) : null;
     this.playwrightGroupId = groupId;
-    const detachMainDocumentResponse = this.captureMainDocumentResponse();
+    const detachResponses = this.captureResponses();
     const activeSpan = Observability.getSpan();
     const tracer = trace.getTracer('ai');
     const stepSpan = activeSpan ? tracer.startSpan('codeceptjs.step', undefined, trace.setSpan(context.active(), activeSpan)) : null;
@@ -341,7 +369,7 @@ class Action {
       throw err;
     } finally {
       this.restorePageTimeout();
-      detachMainDocumentResponse();
+      detachResponses();
       if (groupId) await this.recorder!.endAction();
       detachStepLogger(stepListener);
       if (stepSpan) {
@@ -429,6 +457,12 @@ async function captureHtml(page: any, frame: any, actor: any): Promise<string> {
   throw new Error('Playwright page is unavailable for HTML capture');
 }
 
+function toBrowserLog(log: any): { type: string; text: string } {
+  const type = typeof log.type === 'function' ? log.type() : log.type || log.level || 'log';
+  const text = typeof log.text === 'function' ? log.text() : log.text || log.message || String(log);
+  return { type, text: text.replace(/\s+/g, ' ').trim() };
+}
+
 async function captureTitle(page: any, actor: any): Promise<string> {
   if (page?.title) return page.title();
   if (actor?.grabTitle) return actor.grabTitle();

package/src/ai/captain/web-mode.ts

@@ -16,7 +16,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
         researcher: ctx.explorBot.agentResearcher(),
         navigator: ctx.explorBot.agentNavigator(),
       });
-      const { see, context, visualClick, learnExperience } = agentTools;
+      const { see, context, visualClick } = agentTools;
 
       const tools: Record<string, any> = {
         navigate: tool({
@@ -124,7 +124,6 @@ export function WithWebMode<T extends Constructor>(Base: T) {
 
         ...codeceptTools,
         context,
-        learnExperience,
       };
 
       if (see) tools.see = see;

package/src/ai/captain.ts

@@ -21,7 +21,7 @@ import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { TaskAgent } from './task-agent.ts';
-import { withdrawVisionTools } from './tools.ts';
+import { createLearnExperienceTool, withdrawVisionTools } from './tools.ts';
 
 const MAX_STEPS = 15;
 
@@ -241,6 +241,14 @@ export class Captain extends CaptainBase implements Agent {
 
   private coreTools(task: Task, onDone: (summary: string) => void) {
     return {
+      learnExperience: createLearnExperienceTool({
+        getExperienceTracker: () => this.getExperienceTracker(),
+        getState: () => {
+          const state = this.explorBot.stateManager().getCurrentState();
+          if (!state) return null;
+          return ActionResult.fromState(state);
+        },
+      }),
       done: tool({
         description: 'Call when the user request is fulfilled.',
         inputSchema: z.object({

package/src/ai/driller.ts

@@ -30,7 +30,7 @@ import type { Navigator } from './navigator.ts';
 import type { Provider } from './provider.ts';
 import { drillLocatorRule } from './rules.ts';
 import { TaskAgent, isInteractive } from './task-agent.ts';
-import { createCodeceptJSTools } from './tools.ts';
+import { createCodeceptJSTools, createLearnExperienceTool } from './tools.ts';
 
 const debugLog = createDebug('explorbot:driller');
 
@@ -306,7 +306,11 @@ export class Driller extends TaskAgent implements Agent {
 
     let finished = false;
     const actionTools = this.createVerifiedActionTools(createCodeceptJSTools(this.toolDeps, test), component);
-    const tools = { ...actionTools, ...this.createDrillFlowTools(originalState, test, interactive) };
+    const learnExperience = createLearnExperienceTool({
+      getExperienceTracker: () => this.getExperienceTracker(),
+      getState: () => ActionResult.fromState(this.stateManager.getCurrentState() || originalState),
+    });
+    const tools = { ...actionTools, learnExperience, ...this.createDrillFlowTools(originalState, test, interactive) };
 
     await loop(
       async ({ stop, iteration }) => {

package/src/ai/fisherman-tools.ts

@@ -29,6 +29,28 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
 
         const captured = requestStore.findCapturedRequest(method, path);
         if (captured) {
+          if (captured.status >= 400) {
+            const rejectedCapture = {
+              status: captured.status,
+              requestBody: captured.requestBody || 'no body',
+            };
+            if (opts.spec) {
+              try {
+                const definition = extractEndpointDefinition(opts.spec, path, opts.baseEndpoint);
+                return { source: 'spec', method, path, definition, rejectedCapture };
+              } catch {
+                return { source: 'captured', method, path, usable: false, rejectedRequestBody: captured.requestBody || 'no body', status: captured.status };
+              }
+            }
+            return {
+              source: 'captured',
+              method: captured.method,
+              path: captured.path,
+              status: captured.status,
+              usable: false,
+              rejectedRequestBody: captured.requestBody || 'no body',
+            };
+          }
           return {
             source: 'captured',
             method: captured.method,
@@ -87,6 +109,7 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
             success: false,
             status: reqResult.status,
             statusText: reqResult.statusText,
+            category: responseCategory(reqResult.status),
             errorPreview: reqResult.rawResponseBody.substring(0, 300),
           };
         }
@@ -149,6 +172,16 @@ export function createFishermanTools(apiClient: ApiClient, requestStore: Request
   return { tools, getResult, isFinished };
 }
 
+function responseCategory(status: number): ResponseCategory {
+  if (status === 400 || status === 422) return 'validation';
+  if (status === 401 || status === 403) return 'authorization';
+  if (status === 404) return 'not_found';
+  if (status === 409) return 'conflict';
+  if (status === 408 || status === 425 || status === 429) return 'temporary';
+  if (status >= 500) return 'server';
+  return 'client';
+}
+
 function extractKeyFields(body: any, result: Record<string, any> = {}, depth = 0): Record<string, any> {
   if (!body || typeof body !== 'object' || depth > 5) return result;
 
@@ -179,3 +212,5 @@ export interface FishermanResult {
   created: Array<{ type: string; id?: string | number; title?: string }>;
   failed: Array<{ type: string; reason: string }>;
 }
+
+type ResponseCategory = 'validation' | 'authorization' | 'not_found' | 'conflict' | 'temporary' | 'server' | 'client';

package/src/ai/fisherman.ts

@@ -208,7 +208,8 @@ export class Fisherman implements Agent {
       RULES:
       - Always call getEndpointSpec before your first request to an unfamiliar endpoint
       - Chain requests logically — create parent resources before children
-      - If a request fails, try once more with adjusted data before reporting failure
+      - Use the response category and error text to decide what failed: validation requires corrected data, authorization requires valid access, not_found requires a valid path or parent, and conflict requires resolving the conflicting state
+      - Retry temporary or server failures once. Retry other failures only when the specification or error text gives a concrete correction
       - Use realistic but unique data for each item (vary names, titles)
 
       ${dataProtectionRules}

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

@@ -27,6 +27,8 @@ import { withdrawVisionTools } from './tools.ts';
 
 const CHECK_TOOLS = ['verify', 'see', 'research', 'context'];
 const META_TOOLS = ['record', 'reset', 'stop', 'finish'];
+const PILOT_MESSAGE_LIMIT = 2;
+const PILOT_MESSAGE_MAX_LENGTH = 160;
 
 export class Pilot implements Agent {
   emoji = '🧭';
@@ -465,9 +467,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 +519,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 +557,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 }
@@ -665,10 +675,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 +691,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 +701,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 +728,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 +743,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 +752,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 +789,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 +881,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>
@@ -1048,6 +1050,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,10 +1133,10 @@ 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.
+      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".
 
       ${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

@@ -365,7 +365,7 @@ 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, 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;
@@ -627,4 +627,20 @@ export class Provider {
   }
 }
 
+function repairToolCall(options: ToolCallRepairOptions): any | null {
+  if (options.toolCall.toolName.includes('<|channel|>')) return repairChannelMarker(options);
+  return null;
+}
+
+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 };
+}
+
 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;
     }