explorbot 0.2.5 → 0.3.1

package/dist/src/ai/pilot.js

@@ -13,8 +13,11 @@ 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;
 export class Pilot {
     emoji = '🧭';
     provider;
@@ -278,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.
@@ -411,9 +418,13 @@ export class Pilot {
         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.
       `, 'pilot.planTest', { tools: true, maxToolRoundtrips: 3, task });
@@ -452,7 +463,9 @@ export class Pilot {
         ${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.
-      `, 'pilot.reviewNewPage', { task });
+
+        Tester holds no recipe for this page until you load one — open the <experience> entries whose titles fit a step you are about to instruct.
+      `, 'pilot.reviewNewPage', { tools: true, maxToolRoundtrips: 2, task });
     }
     async analyzeProgress(task, currentState, testerConversation) {
         tag('substep').log('Pilot analyzing progress...');
@@ -479,6 +492,8 @@ export class Pilot {
         </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 });
         const contextToAttach = await this.fetchRequestedContext(text, currentState);
         if (contextToAttach) {
@@ -489,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';
@@ -580,10 +595,10 @@ export class Pilot {
         debugLog(`sendToPilot: ${functionId}, tools: ${!!opts.tools}, roundtrips: ${opts.maxToolRoundtrips ?? 0}`);
         let finalUserText = userText;
         if (opts.tools) {
+            this.conversation.cleanupTag('experience', '...cleaned experience index...');
             const tocBlock = this.getExperienceToc();
-            if (tocBlock) {
+            if (tocBlock)
                 finalUserText = `${tocBlock}\n\n${userText}`;
-            }
         }
         this.conversation.addUserText(finalUserText);
         const tools = { ...this.pickPlanningTools(), ...this.buildPreconditionTool(opts.task) };
@@ -595,9 +610,10 @@ export class Pilot {
             telemetry: { functionId },
         });
         const text = result?.response?.text || '';
-        const learned = (result?.toolExecutions || []).filter((e) => e.toolName === 'learnExperience' && e.output?.content).map((e) => e.output.content);
+        const learned = (result?.toolExecutions || []).filter((e) => e.toolName === 'learnExperience' && e.output?.content).map((e) => ({ url: e.output.url, content: e.output.content }));
         if (learned.length === 0)
             return text;
+        opts.task.applyExperience(learned);
         return dedent `
       ${text}
 
@@ -605,7 +621,7 @@ export class Pilot {
       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>
     `;
     }
@@ -638,6 +654,7 @@ export class Pilot {
         return planning;
     }
     buildPreconditionTool(task) {
+        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".',
@@ -652,7 +669,7 @@ export class Pilot {
                         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);
                     if (!result.success || result.created.length === 0) {
@@ -661,7 +678,7 @@ export class Pilot {
                         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) => {
                         const parts = [c.type];
@@ -696,7 +713,7 @@ export class Pilot {
 
       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() ?? '';
@@ -779,14 +796,6 @@ export class Pilot {
     }
     async fetchRequestedContext(text, currentState) {
         const parts = [];
-        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>
@@ -893,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');
     }
@@ -942,6 +951,19 @@ export class Pilot {
             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) => r.status >= 400);
+            if (failedRequests.length > 0) {
+                line += `\n   requests: ${failedRequests.map((r) => `${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) => 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');
@@ -1007,11 +1029,11 @@ export class Pilot {
       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/dist/src/ai/planner/subpages.js

@@ -1,7 +1,7 @@
 import dedent from 'dedent';
 import { z } from 'zod';
 import { normalizeUrl } from "../../state-manager.js";
-import { isDynamicSegment } from "../../utils/url-matcher.js";
+import { isSamePageFamily } from "../../utils/url-matcher.js";
 const planRegistry = new Map();
 export function registerPlan(url, plan, feature, stateHash) {
     const key = buildKey(url, feature);
@@ -28,21 +28,7 @@ function buildKey(url, feature) {
     return normalized;
 }
 export function isTemplateMatch(urlA, urlB) {
-    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) {
     for (const record of planRegistry.values()) {

package/dist/src/ai/planner.js

@@ -127,7 +127,7 @@ export class Planner extends PlannerBase {
             }
             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/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' }, { 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,7 +595,34 @@ 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 repairHarmonyChannel(options);
+}
+function repairChannelMarker({ toolCall, tools }) {
+    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 }) {
+    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/researcher/cache.d.ts

@@ -3,6 +3,11 @@ export declare function reportResearch(hash: string, text: string): void;
 export declare function clearResearchCache(): void;
 export declare function getCachedResearch(hash: string): string;
 export declare function getPreviousResearch(hash: string): string;
-export declare function saveResearch(hash: string, text: string, combinedHtml?: string): string;
-export declare function findSimilarResearch(combinedHtml: string): Promise<string | null>;
-export declare function findSimilarStateHash(combinedHtml: string): Promise<string | null>;
+export declare function saveResearch(state: ResearchState, text: string, combinedHtml?: string): string;
+export declare function findSimilarResearch(combinedHtml: string, url?: string): Promise<string | null>;
+export declare function findSimilarStateHash(combinedHtml: string, url?: string): Promise<string | null>;
+type ResearchState = {
+    hash: string;
+    url?: string;
+};
+export {};

package/dist/src/ai/researcher/cache.js

@@ -55,7 +55,8 @@ export function getPreviousResearch(hash) {
         return '';
     return readFileSync(researchFile, 'utf8');
 }
-export function saveResearch(hash, text, combinedHtml) {
+export function saveResearch(state, text, combinedHtml) {
+    const { hash, url } = state;
     const researchDir = outputPath('research');
     const researchFile = join(researchDir, `${hash}.md`);
     if (!existsSync(researchDir))
@@ -70,12 +71,15 @@ export function saveResearch(hash, text, combinedHtml) {
             mkdirSync(statesDir, { recursive: true });
         const fingerprint = computeHtmlFingerprint(combinedHtml);
         const fingerprintFile = join(statesDir, `${hash}.fingerprint`);
-        writeFileSync(fingerprintFile, fingerprint.join('\n'));
+        const record = { entries: fingerprint };
+        if (url)
+            record.url = url;
+        writeFileSync(fingerprintFile, JSON.stringify(record));
         debugLog(`Fingerprint saved to ${fingerprintFile}`);
     }
     return researchFile;
 }
-function findSimilarMatch(combinedHtml) {
+function findSimilarMatch(combinedHtml, url) {
     const statesDir = getStatesDir();
     if (!existsSync(statesDir))
         return Promise.resolve(null);
@@ -93,23 +97,24 @@ function findSimilarMatch(combinedHtml) {
                 return;
             }
             debugLog(`Similar fingerprint found: ${matchHash} (${similarity}% similar)`);
-            resolve({ hash: matchHash, similarity });
+            resolve({ hash: matchHash, similarity, url: data.url });
         });
         worker.postMessage({
             html: combinedHtml,
             statesDir,
             maxAgeMs: FINGERPRINT_MAX_AGE_MS,
             threshold: SIMILARITY_THRESHOLD,
+            url,
         });
     });
 }
-export async function findSimilarResearch(combinedHtml) {
-    const match = await findSimilarMatch(combinedHtml);
+export async function findSimilarResearch(combinedHtml, url) {
+    const match = await findSimilarMatch(combinedHtml, url);
     if (!match)
         return null;
     return getCachedResearch(match.hash) || null;
 }
-export async function findSimilarStateHash(combinedHtml) {
-    const match = await findSimilarMatch(combinedHtml);
+export async function findSimilarStateHash(combinedHtml, url) {
+    const match = await findSimilarMatch(combinedHtml, url);
     return match?.hash || null;
 }

package/dist/src/ai/researcher/deep-analysis.js

@@ -96,7 +96,7 @@ export function WithDeepAnalysis(Base) {
             else {
                 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;
         }

package/dist/src/ai/researcher/fingerprint-worker.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from "../../utils/html-diff.js";
+import { isSamePageFamily } from "../../utils/url-matcher.js";
 function diceSimilarity(a, b) {
     let intersection = 0;
     for (const item of a) {
@@ -14,7 +15,7 @@ function diceSimilarity(a, b) {
     return Math.round(((2 * intersection) / total) * 100);
 }
 parentPort.on('message', (data) => {
-    const { html, statesDir, maxAgeMs, threshold } = data;
+    const { html, statesDir, maxAgeMs, threshold, url } = data;
     if (!existsSync(statesDir)) {
         parentPort.postMessage({ matchHash: null, similarity: 0 });
         return;
@@ -28,19 +29,35 @@ parentPort.on('message', (data) => {
     const files = readdirSync(statesDir).filter((f) => f.endsWith('.fingerprint'));
     let bestHash = null;
     let bestSimilarity = 0;
+    let bestUrl;
     for (const file of files) {
         const filePath = join(statesDir, file);
         const mtime = statSync(filePath).mtimeMs;
         if (now - mtime > maxAgeMs)
             continue;
-        const lines = readFileSync(filePath, 'utf8').split('\n').filter(Boolean);
-        const storedFingerprint = new Set(lines);
+        const record = readFingerprint(filePath);
+        if (url && record.url && !isSamePageFamily(url, record.url))
+            continue;
+        const storedFingerprint = new Set(record.entries);
         const similarity = diceSimilarity(currentFingerprint, storedFingerprint);
         if (similarity > bestSimilarity) {
             bestSimilarity = similarity;
             bestHash = file.replace('.fingerprint', '');
+            bestUrl = record.url;
         }
     }
     const matched = bestSimilarity >= threshold;
-    parentPort.postMessage({ matchHash: matched ? bestHash : null, similarity: bestSimilarity });
+    parentPort.postMessage({ matchHash: matched ? bestHash : null, similarity: bestSimilarity, url: matched ? bestUrl : undefined });
 });
+function readFingerprint(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    try {
+        const record = JSON.parse(content);
+        if (Array.isArray(record.entries))
+            return record;
+    }
+    catch {
+        return { entries: content.split('\n').filter(Boolean) };
+    }
+    return { entries: content.split('\n').filter(Boolean) };
+}

package/dist/src/ai/researcher.js

@@ -72,6 +72,7 @@ export class Researcher extends ResearcherBase {
         let retriesLeft = opts._retriesLeft ?? maxRetries;
         this.actionResult = ActionResult.fromState(state);
         const stateHash = state.hash || this.actionResult.getStateHash();
+        const researchState = { ...state, hash: stateHash };
         if (!force && stateHash) {
             const cached = getCachedResearch(stateHash);
             if (cached) {
@@ -105,11 +106,11 @@ export class Researcher extends ResearcherBase {
             debugLog('Researching web page:', this.actionResult.url);
             const combinedHtml = await this.actionResult.combinedHtml();
             if (!deep && !force) {
-                const similar = await findSimilarResearch(combinedHtml);
+                const similar = await findSimilarResearch(combinedHtml, state.url);
                 if (similar) {
                     tag('operation').log('Similar research found, reusing cached result');
                     if (stateHash)
-                        saveResearch(stateHash, similar, combinedHtml);
+                        saveResearch(researchState, similar, combinedHtml);
                     tag('multiline').log(formatResearchSummary(similar));
                     tag('success').log('Research complete (reused)');
                     await this.hooksRunner.runAfterHook('researcher', state.url);
@@ -238,7 +239,7 @@ export class Researcher extends ResearcherBase {
             result.cleanup();
             let researchFile = null;
             if (stateHash) {
-                researchFile = saveResearch(stateHash, result.text, combinedHtml);
+                researchFile = saveResearch(researchState, result.text, combinedHtml);
             }
             const summaryText = mdq(result.text).query('section2(/^summary/)').query('paragraph[0]').text().trim();
             const summaryLine = summaryText.split('\n')[0]?.trim().slice(0, 200);