explorbot 0.1.31 → 0.1.32-beta.1

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

@@ -0,0 +1,83 @@
+import { ActionResult } from '../action-result.js';
+import { type ExperienceTracker } from '../experience-tracker.js';
+import type Explorer from '../explorer.js';
+import { type Test } from '../test-plan.js';
+import type { Agent } from './agent.js';
+import type { Conversation } from './conversation.js';
+import type { Fisherman } from './fisherman.js';
+import type { Navigator } from './navigator.js';
+import type { Provider } from './provider.js';
+import type { Researcher } from './researcher.js';
+export declare class Pilot implements Agent {
+    emoji: string;
+    provider: Provider;
+    agentTools: any;
+    conversation: Conversation | null;
+    researcher: Researcher;
+    explorer: Explorer;
+    fisherman: Fisherman | null;
+    experienceTracker: ExperienceTracker | null;
+    constructor(provider: Provider, agentTools: any, researcher: Researcher, explorer: Explorer, experienceTracker?: ExperienceTracker);
+    setFisherman(fisherman: Fisherman): void;
+    get stepsToReview(): number;
+    reset(): void;
+    getLastAnalysis(): string | null;
+    reviewStop(task: Test, currentState: ActionResult, testerConversation: Conversation, navigator?: Navigator): Promise<boolean>;
+    reviewFinish(task: Test, currentState: ActionResult, testerConversation: Conversation, navigator?: Navigator): Promise<boolean>;
+    reviewCompletion(task: Test, currentState: ActionResult, testerConversation: Conversation, navigator?: Navigator): Promise<boolean>;
+    finalReview(task: Test, currentState: ActionResult, testerConversation: Conversation, navigator?: Navigator): Promise<boolean>;
+    reviewReset(task: Test, currentState: ActionResult, reason: string, testerConversation: Conversation): Promise<boolean>;
+    reviewDecision(type: 'finish' | 'stop', task: Test, currentState: ActionResult, testerConversation: Conversation, navigator?: Navigator): Promise<boolean>;
+    reviewResetDecision(task: Test, currentState: ActionResult, reason: string, testerConversation: Conversation): Promise<boolean>;
+    buildSharedEvidenceRules(task: Test): string;
+    buildResetSystemPrompt(task: Test): string;
+    buildVerdictSystemPrompt(type: string, task: Test): string;
+    planTest(task: Test, currentState: ActionResult): Promise<string>;
+    reviewNewPage(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
+    analyzeProgress(task: Test, currentState: ActionResult, testerConversation: Conversation): Promise<string>;
+    formatExpectations(task: Test): string;
+    sendToPilot(userText: string, functionId: string, opts?: {
+        tools?: boolean;
+        maxToolRoundtrips?: number;
+        task?: Test;
+    }): Promise<string>;
+    getExperienceToc(): string;
+    pickPlanningTools(): Record<string, unknown>;
+    buildPreconditionTool(task: Test): {
+        precondition: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
+            description: any;
+        }, {
+            noted: boolean;
+            prepared: boolean;
+            skipped: boolean;
+            reason: string;
+            created?: undefined;
+        } | {
+            noted: boolean;
+            prepared: boolean;
+            reason: string;
+            skipped?: undefined;
+            created?: undefined;
+        } | {
+            noted: boolean;
+            prepared: boolean;
+            created: {
+                type: string;
+                id?: string | number;
+                title?: string;
+            }[];
+            skipped?: undefined;
+            reason?: undefined;
+        }, import("@ai-sdk/provider-utils").Context>>;
+    };
+    checkDataAvailability(task: Test, requestedData: string, fishermanReason: string | undefined): Promise<string | null>;
+    buildStateContext(state: ActionResult): string;
+    fetchRequestedContext(text: string, currentState: ActionResult): Promise<string>;
+    formatSessionLog(testerConversation: Conversation): string;
+    hasCompletionEvidence(task: Test, currentState: ActionResult, testerConversation: Conversation): boolean;
+    hasSuccessfulCheckEvidence(currentState: ActionResult, testerConversation: Conversation): boolean;
+    formatSuccessfulAssertions(currentState: ActionResult, testerConversation: Conversation): string;
+    formatActions(toolCalls: any[]): string;
+    buildDeletionScope(task: Test): string;
+    getSystemPrompt(task: Test, initialState: ActionResult): string;
+}

package/dist/src/ai/planner/session-dedup.d.ts

@@ -0,0 +1,12 @@
+import type { Plan } from '../../test-plan.js';
+import type { Constructor } from '../researcher/mixin.js';
+export declare function WithSessionDedup<T extends Constructor>(Base: T): {
+    new (...args: any[]): {
+        currentPlan: Plan | null;
+        registerPlanInSession(plan: Plan): void;
+        getSessionTestsSummary(): string;
+        getPreviousSessionScenarios(): Set<string>;
+        getPreviousSessionScenariosExcluding(plan: Plan): Set<string>;
+    };
+} & T;
+export declare function clearSessionDedup(): void;

package/dist/src/ai/planner/styles.d.ts

@@ -0,0 +1,6 @@
+export declare function getStyles(): Record<string, string>;
+export declare function getActiveStyle(iteration: number, override?: string): {
+    name: string;
+    approach: string;
+};
+export declare function clearStyleCache(): void;

package/dist/src/ai/planner/subpages.d.ts

@@ -0,0 +1,35 @@
+import type { StateManager } from '../../state-manager.js';
+import type { Plan } from '../../test-plan.js';
+import type { Provider } from '../provider.js';
+import type { Constructor } from '../researcher/mixin.js';
+export declare function registerPlan(url: string, plan: Plan, feature?: string, stateHash?: string): void;
+export declare function getRegisteredPlan(url: string, feature?: string): PlanRecord | undefined;
+export declare function isPagePlanned(url: string): boolean;
+export declare function clearPlanRegistry(url?: string): void;
+export declare function isTemplateMatch(urlA: string, urlB: string): boolean;
+export declare function getPlannedByStateHash(hash: string): PlanRecord | null;
+export declare function WithSubPages<T extends Constructor>(Base: T): {
+    new (...args: any[]): {
+        provider: Provider;
+        stateManager: StateManager;
+        collectSubPageCandidates(plan: Plan, currentUrl: string): SubPageCandidate[];
+        pickNextSubPage(candidates: SubPageCandidate[]): Promise<{
+            url: string;
+            reason: string;
+        } | null>;
+        findSimilarPlan(url: string): PlanRecord | null;
+    };
+} & T;
+type PlanRecord = {
+    plan: Plan;
+    feature?: string;
+    url: string;
+    stateHash?: string;
+};
+type SubPageCandidate = {
+    url: string;
+    title?: string;
+    h1?: string;
+    visitCount: number;
+};
+export {};

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

@@ -0,0 +1,79 @@
+import { ActionResult } from '../action-result.js';
+import { ExperienceTracker } from '../experience-tracker.js';
+import type Explorer from '../explorer.js';
+import type { StateManager } from '../state-manager.js';
+import { Suite } from '../suite.js';
+import { Plan, Test } from '../test-plan.js';
+import type { Agent } from './agent.js';
+import { Conversation } from './conversation.js';
+import type { Fisherman } from './fisherman.js';
+import type { Provider } from './provider.js';
+import { Researcher } from './researcher.js';
+declare const PlannerBase: {
+    new (...args: any[]): {
+        currentPlan: Plan | null;
+        registerPlanInSession(plan: Plan): void;
+        getSessionTestsSummary(): string;
+        getPreviousSessionScenarios(): Set<string>;
+        getPreviousSessionScenariosExcluding(plan: Plan): Set<string>;
+    };
+} & {
+    new (...args: any[]): {
+        provider: Provider;
+        stateManager: StateManager;
+        collectSubPageCandidates(plan: Plan, currentUrl: string): {
+            url: string;
+            title?: string;
+            h1?: string;
+            visitCount: number;
+        }[];
+        pickNextSubPage(candidates: {
+            url: string;
+            title?: string;
+            h1?: string;
+            visitCount: number;
+        }[]): Promise<{
+            url: string;
+            reason: string;
+        }>;
+        findSimilarPlan(url: string): {
+            plan: Plan;
+            feature?: string;
+            url: string;
+            stateHash?: string;
+        } | null;
+    };
+} & (new (...args: any[]) => object);
+export declare class Planner extends PlannerBase implements Agent {
+    emoji: string;
+    explorer: Explorer;
+    provider: Provider;
+    stateManager: StateManager;
+    experienceTracker: ExperienceTracker;
+    MIN_TASKS: number;
+    MAX_TASKS: number;
+    currentPlan: Plan | null;
+    freshStart: boolean;
+    lastStyleName: string;
+    lastSuite: Suite | null;
+    researcher: Researcher;
+    fisherman: Fisherman | null;
+    constructor(explorer: Explorer, provider: Provider);
+    setFisherman(fisherman: Fisherman): void;
+    get sectionOrder(): string[];
+    getDefaultStartUrl(state: {
+        url: string;
+        fullUrl?: string;
+    }): string;
+    getSystemMessage(feature?: string): string;
+    setPlan(plan: Plan): void;
+    static getCachedPlan(url: string): Plan | null;
+    plan(feature?: string, style?: string, parentPlan?: Plan, completedPlans?: Plan[]): Promise<Plan>;
+    getSuite(): Suite | null;
+    addNewTests(tests: Test[], defaultStartUrl: string): Test[];
+    getExistingTestFileScenarios(currentUrl?: string): Set<string>;
+    cleanExperienceFlows(text: string): string | null;
+    buildApproach(style?: string): string;
+    buildConversation(state: ActionResult, style?: string, parentPlan?: Plan, feature?: string): Promise<Conversation>;
+}
+export {};

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

@@ -0,0 +1,50 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import type { ModelMessage } from 'ai';
+import type { AIConfig } from '../config.js';
+import { type RetryOptions } from '../utils/retry.js';
+import { Conversation } from './conversation.js';
+declare class AiError extends Error {
+}
+export declare class ContextLengthError extends Error {
+}
+export declare class Provider {
+    config: AIConfig;
+    telemetryEnabled: boolean;
+    otelSdk: NodeSDK | null;
+    defaultRetryOptions: RetryOptions;
+    static readonly CONTEXT_LENGTH_PATTERNS: string[];
+    lastConversation: Conversation | null;
+    constructor(config: AIConfig);
+    getModelName(model: any): string;
+    validateConnection(): Promise<void>;
+    getModelForAgent(agentName?: string): any;
+    getAgenticModel(agentName?: string): any;
+    getConfiguredModels(): Record<string, string>;
+    getSystemPromptForAgent(agentName: string, currentUrl?: string): string | undefined;
+    getProviderOptionsForAgent(agentName: string): Record<string, any> | undefined;
+    getReasoningForAgent(agentName?: string): string | undefined;
+    getRetryOptions(options?: any): RetryOptions;
+    mergeProviderOptions(config: Record<string, any>, agentName?: string): Record<string, any>;
+    finalizeConfig(config: Record<string, any>, options: any, telemetry: any): void;
+    initLangfuse(): void;
+    getTelemetry(options: any): any;
+    startConversation(systemMessage: string, agentName?: string, model?: any): Conversation;
+    invokeConversation(conversation: Conversation, tools?: any, options?: any): Promise<{
+        conversation: Conversation;
+        response: any;
+        toolExecutions?: any[];
+    } | null>;
+    chat(messages: ModelMessage[], model: any, options?: any): Promise<any>;
+    generateWithTools(messages: ModelMessage[], model: any, tools: any, options?: any): Promise<any>;
+    generateObject(messages: ModelMessage[], schema: any, model?: any, options?: any): Promise<any>;
+    static isContextLengthError(error: any): boolean;
+    static trimMessagesForRetry(messages: ModelMessage[]): ModelMessage[] | null;
+    static compactMessagesForRetry(messages: ModelMessage[]): ModelMessage[] | null;
+    tryReduceMessages(messages: ModelMessage[], retryLevel: number): {
+        messages: ModelMessage[];
+        nextLevel: number;
+    } | null;
+    processImage(prompt: string, image: string): Promise<any>;
+    hasVision(): boolean;
+}
+export { AiError, Provider as AIProvider };

package/dist/src/ai/provider.js

@@ -28,7 +28,7 @@ function extractCachedTokens(usage) {
     const fromRaw = raw?.prompt_tokens_details?.cached_tokens ?? raw?.promptTokensDetails?.cachedTokens;
     return typeof fromRaw === 'number' ? fromRaw : 0;
 }
-function rejectAfterIdle(ms, signal) {
+function rejectAfterIdle(ms, signal, controller) {
     return new Promise((_, reject) => {
         const tick = () => {
             if (signal.cancelled)
@@ -37,6 +37,7 @@ function rejectAfterIdle(ms, signal) {
                 setTimeout(tick, ms);
                 return;
             }
+            controller.abort();
             reject(new Error('AI request timeout'));
         };
         setTimeout(tick, ms);
@@ -329,13 +330,16 @@ export class Provider {
             const response = await withRetry(async () => {
                 const timeout = config.timeout || 30000;
                 const cancel = { cancelled: false };
+                const controller = new AbortController();
+                const combinedSignal = AbortSignal.any([controller.signal, executionController.getAbortSignal()].filter(Boolean));
                 try {
                     const result = (await Promise.race([
                         generateText({
                             messages,
                             ...config,
+                            abortSignal: combinedSignal,
                         }),
-                        rejectAfterIdle(timeout, cancel),
+                        rejectAfterIdle(timeout, cancel, controller),
                     ]));
                     const hasToolCall = (result.toolCalls?.length || 0) > 0;
                     if (!result.text && !hasToolCall && result.finishReason === 'length') {
@@ -410,13 +414,16 @@ export class Provider {
             const response = await withRetry(async () => {
                 const timeout = config.timeout || 30000;
                 const cancel = { cancelled: false };
+                const controller = new AbortController();
+                const combinedSignal = AbortSignal.any([controller.signal, executionController.getAbortSignal()].filter(Boolean));
                 try {
                     return (await Promise.race([
                         generateObject({
                             messages,
                             ...config,
+                            abortSignal: combinedSignal,
                         }),
-                        rejectAfterIdle(timeout, cancel),
+                        rejectAfterIdle(timeout, cancel, controller),
                     ]));
                 }
                 finally {

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

@@ -0,0 +1,57 @@
+import type { ActionResult } from '../action-result.js';
+import type { StateManager, StateTransition, WebPageState } from '../state-manager.js';
+import type { Task } from '../test-plan.js';
+import type { Conversation, ToolExecution } from './conversation.js';
+import type { Provider } from './provider.js';
+interface AxeViolation {
+    id: string;
+    impact: 'critical' | 'serious' | 'moderate' | 'minor';
+    description: string;
+    helpUrl: string;
+    nodes: Array<{
+        html: string;
+        target: string[];
+    }>;
+}
+interface PageAnalysis {
+    url: string;
+    stateHash: string;
+    timestamp: string;
+    axeViolations: AxeViolation[];
+}
+interface SemanticIssue {
+    type: 'unclear_intention' | 'confusing_naming' | 'hard_to_interact';
+    element: string;
+    issue: string;
+    suggestion: string;
+}
+interface AnalysisReport {
+    scenario: string;
+    timestamp: string;
+    url: string;
+    axeViolations: AxeViolation[];
+    semanticIssues: SemanticIssue[];
+}
+export declare class Quartermaster {
+    provider: Provider;
+    model?: any;
+    outputDir: string;
+    pageAnalyses: Map<string, PageAnalysis>;
+    unsubscribe: (() => void) | null;
+    playwrightHelper: any;
+    pendingAnalyses: Promise<void>[];
+    constructor(provider: Provider, options?: {
+        model?: any;
+    });
+    start(playwrightHelper: any, stateManager: StateManager): void;
+    stop(): void;
+    ensureDirectory(): void;
+    onPageChange(event: StateTransition): void;
+    runAxeAnalysis(state: WebPageState): Promise<void>;
+    analyzeSession(task: Task, initialState: ActionResult, conversation: Conversation): Promise<AnalysisReport | null>;
+    generateSemanticAnalysis(axeViolations: AxeViolation[], executions: ToolExecution[], initialState: ActionResult): Promise<SemanticIssue[]>;
+    addNotesToTask(task: Task, report: AnalysisReport): void;
+    saveReport(stateHash: string, report: AnalysisReport): void;
+    formatReportMarkdown(report: AnalysisReport): string;
+}
+export {};

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

@@ -0,0 +1,49 @@
+import type { ExperienceTracker } from '../experience-tracker.js';
+import type Explorer from '../explorer.js';
+import type { KnowledgeTracker } from '../knowledge-tracker.js';
+import { Test } from '../test-plan.js';
+import type { Agent } from './agent.js';
+import type { Navigator } from './navigator.js';
+import { Provider } from './provider.js';
+import { TaskAgent } from './task-agent.js';
+export declare class Rerunner extends TaskAgent implements Agent {
+    readonly ACTION_TOOLS: string[];
+    emoji: string;
+    explorer: Explorer;
+    provider: Provider;
+    agentTools: any;
+    healedSteps: Array<{
+        test: string;
+        original: string;
+        healed: string;
+    }>;
+    traceDir: string;
+    constructor(explorer: Explorer, provider: Provider, agentTools?: any);
+    getNavigator(): Navigator;
+    getExperienceTracker(): ExperienceTracker;
+    getKnowledgeTracker(): KnowledgeTracker;
+    getProvider(): Provider;
+    get rerunnerConfig(): Record<string, any>;
+    get healLimit(): number;
+    get healMaxIterations(): number;
+    listTests(testsDir: string): void;
+    rerun(filePath: string, options?: {
+        testIndices?: number[];
+    }): Promise<RerunResult>;
+    getCurrentTask(testMap: Map<string, Test>): Test | undefined;
+    setupPlugins(): void;
+    teardownHealing(): void;
+    healStep(step: any, error: Error): Promise<((deps: {
+        I: any;
+    }) => Promise<void>) | null>;
+    getHealSystemPrompt(): string;
+    getHealUserPrompt(failedCode: string, error: Error): string;
+    printResults(result: RerunResult): void;
+}
+interface RerunResult {
+    total: number;
+    passed: number;
+    failed: number;
+    healed: number;
+}
+export {};

package/dist/src/ai/researcher/cache.d.ts

@@ -0,0 +1,6 @@
+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>;

package/dist/src/ai/researcher/coordinates.d.ts

@@ -0,0 +1,56 @@
+import type { Page } from 'playwright';
+import type { ActionResult } from '../../action-result.js';
+import type Explorer from '../../explorer.js';
+import type { Provider } from '../provider.js';
+import { type Constructor } from './mixin.js';
+import type { ResearchResult } from './research-result.js';
+export declare function visuallyAnnotateContainers(page: Page, containers: Array<{
+    css: string;
+    label: string;
+}>): Promise<number>;
+export declare function WithCoordinates<T extends Constructor>(Base: T): {
+    new (...args: any[]): {
+        explorer: Explorer;
+        provider: Provider;
+        actionResult: ActionResult | undefined;
+        analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult>;
+        visuallyAnnotateElements(opts?: {
+            containers?: Array<{
+                css: string;
+                label: string;
+            }>;
+        }): Promise<number>;
+        _analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult>;
+        mergeVisualData(result: ResearchResult, visualData: Map<string, {
+            coordinates: string | null;
+            color: string | null;
+            icon: string | null;
+        }>): Promise<void>;
+        backfillCoordinates(result: ResearchResult): Promise<void>;
+    };
+} & T;
+export interface VisualAnalysisResult {
+    elements: Map<string, {
+        coordinates: string | null;
+        color: string | null;
+        icon: string | null;
+    }>;
+    pagePurpose: string | null;
+    primaryActions: string[] | null;
+    focusedSection: string | null;
+}
+export interface CoordinateMethods {
+    analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult>;
+    mergeVisualData(result: ResearchResult, visualData: Map<string, {
+        coordinates: string | null;
+        color: string | null;
+        icon: string | null;
+    }>): Promise<void>;
+    backfillCoordinates(result: ResearchResult): Promise<void>;
+    visuallyAnnotateElements(opts?: {
+        containers?: Array<{
+            css: string;
+            label: string;
+        }>;
+    }): Promise<number>;
+}

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

@@ -0,0 +1,74 @@
+import { ActionResult, type Diff } from '../../action-result.js';
+import type Explorer from '../../explorer.js';
+import type { StateManager } from '../../state-manager.js';
+import { WebPageState } from '../../state-manager.js';
+import type { Provider } from '../provider.js';
+import { type Constructor } from './mixin.js';
+import { type ResearchElement } from './parser.js';
+import type { ResearchResult } from './research-result.js';
+export declare function WithDeepAnalysis<T extends Constructor>(Base: T): {
+    new (...args: any[]): {
+        explorer: Explorer;
+        provider: Provider;
+        stateManager: StateManager;
+        actionResult: ActionResult | undefined;
+        performDeepAnalysis(state: WebPageState, result: ResearchResult): Promise<void>;
+        researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null>;
+        _loadPreviousExtendedSections(hash: string): PreviousSection[];
+        _replayPreviousSections(state: WebPageState, prevSections: PreviousSection[], maxClicks: number): Promise<{
+            verified: string[];
+            verifiedCodes: string[];
+            missing: PreviousSection[];
+        }>;
+        _appendExtendedResearch(result: ResearchResult, expandedSections: string[], navigationLinks: Array<{
+            code: string;
+            url: string;
+        }>): void;
+        _discoverExpandables(researchText: string, missing?: PreviousSection[], verifiedCodes?: string[]): Promise<ExpandableElement[]>;
+        _buildClickCommands(el: ExpandableElement): string[];
+        _selectExpandables(expandables: ExpandableElement[], url: string, maxClicks: number): Promise<ExpandableElement[]>;
+        _clickExpandableElements(elements: Array<{
+            commands: string[];
+            description: string;
+        }>, state: WebPageState, expandedSections: string[], navigationLinks: Array<{
+            code: string;
+            url: string;
+        }>): Promise<void>;
+        _executeAndAnalyze(commands: string[], description: string, state: WebPageState, originalAria: string, alreadyExpanded: string[]): Promise<ExpansionOutcome>;
+        _restorePageState(url: string, originalAria: string): Promise<void>;
+        _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[]): Promise<string | null>;
+        _deduplicateExpandedSections(sections: string[]): string[];
+        _summarizeExpanded(expandedSections: string[]): string[];
+        _sectionFingerprint(sectionMarkdown: string): string | null;
+        _parseSectionKeys(sectionMarkdown: string): {
+            name: string;
+            keys: string[];
+        } | null;
+    };
+} & T;
+interface ExpandableElement extends ResearchElement {
+    container: string | null;
+}
+interface PreviousSection {
+    name: string;
+    code: string;
+}
+type ExpansionOutcome = {
+    status: 'revealed';
+    code: string;
+    sectionMarkdown: string;
+} | {
+    status: 'navigated';
+    code: string;
+    url: string;
+} | {
+    status: 'none';
+    code: string;
+} | {
+    status: 'failed';
+};
+export interface DeepAnalysisMethods {
+    performDeepAnalysis(state: WebPageState, result: ResearchResult): Promise<void>;
+    researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null>;
+}
+export {};

package/dist/src/ai/researcher/fingerprint-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/ai/researcher/focus.d.ts

@@ -0,0 +1,8 @@
+import type { Page } from 'playwright';
+import type { ResearchSection } from './parser.js';
+import type { ResearchResult } from './research-result.js';
+export declare const FOCUSED_MARKER = "> **Focused**";
+export declare function hasFocusedSection(text: string): boolean;
+export declare function detectFocusedSection(page: Page, sections: ResearchSection[]): Promise<string | null>;
+export declare function markSectionAsFocused(result: ResearchResult, sectionName: string): void;
+export declare function pickDefaultFocusedSection(sections: ResearchSection[]): string | null;

package/dist/src/ai/researcher/locators.d.ts

@@ -0,0 +1,36 @@
+import type { ActionResult } from '../../action-result.js';
+import type Explorer from '../../explorer.js';
+import type { Conversation } from '../conversation.js';
+import type { Provider } from '../provider.js';
+import { type Constructor } from './mixin.js';
+import { parseResearchSections } from './parser.js';
+import type { ResearchResult } from './research-result.js';
+export declare const DYNAMIC_ID_PATTERN: RegExp;
+export declare const isForbiddenLocator: (s: string) => boolean;
+export declare function WithLocators<T extends Constructor>(Base: T): {
+    new (...args: any[]): {
+        explorer: Explorer;
+        provider: Provider;
+        actionResult: ActionResult | undefined;
+        testLocators(locators: Locator[]): Promise<void>;
+        fixBrokenSections(result: ResearchResult, conversation: Conversation): Promise<void>;
+        backfillBrokenLocators(result: ResearchResult): Promise<void>;
+        validateContainers(result: ResearchResult): Promise<void>;
+        updateSectionContainer(result: ResearchResult, section: ReturnType<typeof parseResearchSections>[0], newCss: string | null): void;
+    };
+} & T;
+export interface Locator {
+    section: string;
+    container: string | null;
+    element: string;
+    type: 'css' | 'xpath' | 'aria';
+    locator: string;
+    valid: boolean | null;
+    error: string | null;
+    pwLocator: string | null;
+}
+export interface LocatorMethods {
+    testLocators(locators: Locator[]): Promise<void>;
+    fixBrokenSections(result: ResearchResult, conversation: Conversation): Promise<void>;
+    backfillBrokenLocators(result: ResearchResult): Promise<void>;
+}

package/dist/src/ai/researcher/mixin.d.ts

@@ -0,0 +1,2 @@
+export type Constructor<T = object> = new (...args: any[]) => T;
+export declare const debugLog: (...args: any[]) => void;

package/dist/src/ai/researcher/parser.d.ts

@@ -0,0 +1,35 @@
+export interface ResearchElement {
+    name: string;
+    type: string | null;
+    aria: {
+        role: string;
+        text: string;
+    } | null;
+    css: string | null;
+    xpath: string | null;
+    coordinates: string | null;
+    color: string | null;
+    icon: string | null;
+    eidx: string | null;
+}
+export interface ResearchSection {
+    name: string;
+    containerCss: string | null;
+    elements: ResearchElement[];
+    rawMarkdown: string;
+    isExtended: boolean;
+}
+export declare const RESEARCH_COLUMN_ORDER: string[];
+export declare function mapRowToElement(row: Record<string, string>): ResearchElement | null;
+export declare function extractContainerFromBlockquote(sectionMarkdown: string): string | null;
+export declare function parseResearchSections(markdown: string): ResearchSection[];
+export declare function extractValidContainers(researchText: string, opts?: {
+    exclude?: string[];
+}): Array<{
+    css: string;
+    label: string;
+}>;
+export declare function rebuildSectionMarkdown(section: ResearchSection): string;
+export declare function formatResearchSummary(text: string, opts?: {
+    visionUsed?: boolean;
+}): string;