explorbot 0.1.31 → 0.2.0

package/dist/src/ai/historian/screencast.d.ts

@@ -0,0 +1,32 @@
+import type { ExplorbotConfig } from '../../config.js';
+import type { PlaywrightRecorder } from '../../playwright-recorder.js';
+import { type Constructor } from './mixin.js';
+export interface ScreencastMethods {
+    attachScreencast(): void;
+    isScreencastActive(): boolean;
+    stopScreencast(): Promise<void>;
+}
+export declare function WithScreencast<T extends Constructor>(Base: T): {
+    new (...args: any[]): {
+        config: ExplorbotConfig | undefined;
+        savedFiles: Set<string>;
+        playwright: {
+            recorder: PlaywrightRecorder;
+            helper: any;
+        } | undefined;
+        screencastPage: any;
+        screencastActive: boolean;
+        screencastPath: string | null;
+        screencastListenersInstalled: boolean;
+        screencastTask: any;
+        screencastLastChapter: string | null;
+        onTestBefore?: (test: any) => void;
+        onStepPassed?: (step: any) => void;
+        onTestAfter?: () => void;
+        isScreencastActive(): boolean;
+        attachScreencast(): void;
+        startScreencast(test: any): Promise<void>;
+        emitChapter(_step: any): Promise<void>;
+        stopScreencast(): Promise<void>;
+    };
+} & T;

package/dist/src/ai/historian/utils.d.ts

@@ -0,0 +1,3 @@
+import type { ToolExecution } from '../conversation.js';
+export declare function escapeString(str: string): string;
+export declare function getExecutionLabel(exec: ToolExecution, fallback?: string): string;

package/dist/src/ai/historian/utils.js

@@ -1,4 +1,3 @@
-export { isNonReusableCode, stripComments } from "../../utils/step-analyzer.js";
 export function escapeString(str) {
     return str.replace(/'/g, "\\'").replace(/\n/g, ' ');
 }

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

@@ -0,0 +1,109 @@
+import type { ExplorbotConfig } from '../config.js';
+import type { ExperienceTracker } from '../experience-tracker.js';
+import type { PlaywrightRecorder } from '../playwright-recorder.js';
+import type { Reporter } from '../reporter.js';
+import type { StateManager } from '../state-manager.js';
+import type { Plan } from '../test-plan.js';
+import { type CodeceptJSMethods } from './historian/codeceptjs.js';
+import { type ExperienceMethods } from './historian/experience.js';
+import { type PlaywrightMethods } from './historian/playwright.js';
+import { type ScreencastMethods } from './historian/screencast.js';
+import type { Provider } from './provider.js';
+declare const HistorianBase: {
+    new (...args: any[]): {
+        config: ExplorbotConfig | undefined;
+        savedFiles: Set<string>;
+        playwright: {
+            recorder: PlaywrightRecorder;
+            helper: any;
+        };
+        screencastPage: any;
+        screencastActive: boolean;
+        screencastPath: string | null;
+        screencastListenersInstalled: boolean;
+        screencastTask: any;
+        screencastLastChapter: string | null;
+        onTestBefore?: (test: any) => void;
+        onStepPassed?: (step: any) => void;
+        onTestAfter?: () => void;
+        isScreencastActive(): boolean;
+        attachScreencast(): void;
+        startScreencast(test: any): Promise<void>;
+        emitChapter(_step: any): Promise<void>;
+        stopScreencast(): Promise<void>;
+    };
+} & {
+    new (...args: any[]): {
+        playwright: {
+            recorder: PlaywrightRecorder;
+            helper: any;
+        };
+        savedFiles: Set<string>;
+        stateManager?: StateManager;
+        toPlaywrightCode(conversation: import("./conversation.js").Conversation, scenario: string): Promise<string>;
+        savePlaywrightPlanToFile(plan: Plan): string;
+        getPlaywrightKnowledgeLines(url: string, indent?: string): string[];
+    };
+} & {
+    new (...args: any[]): {
+        savedFiles: Set<string>;
+        stateManager?: StateManager;
+        toCode(conversation: import("./conversation.js").Conversation, scenario: string): string;
+        saveCodeceptPlanToFile(plan: Plan): string;
+        getKnowledgeLines(url: string, indent?: string): string[];
+    };
+} & {
+    new (...args: any[]): {
+        provider: Provider;
+        experienceTracker: ExperienceTracker;
+        reporter: Reporter | undefined;
+        stateManager: StateManager | undefined;
+        isPlaywrightFramework: () => boolean;
+        toCode: (conversation: import("./conversation.js").Conversation, scenario: string) => string;
+        toPlaywrightCode: (conversation: import("./conversation.js").Conversation, scenario: string) => Promise<string>;
+        stopScreencast: () => Promise<void>;
+        saveSession(task: import("../test-plan.js").Task, initialState: import("../action-result.js").ActionResult, conversation: import("./conversation.js").Conversation): Promise<void>;
+        reportSession(test: import("../test-plan.js").Test, steps: import("../experience-tracker.js").SessionStep[]): Promise<void>;
+        extractSteps(toolExecutions: import("./conversation.js").ToolExecution[]): Promise<import("../experience-tracker.js").SessionStep[]>;
+        hasRelevantFlowExperience(state: import("../action-result.js").ActionResult): boolean;
+        extractPassedCodeceptSteps(task: import("../test-plan.js").Task): import("../experience-tracker.js").SessionStep[];
+        curateFlow(steps: import("../experience-tracker.js").SessionStep[], task: import("../test-plan.js").Task, initialState: import("../action-result.js").ActionResult): Promise<string>;
+        renderFlowFromSuccessfulSteps(steps: import("../experience-tracker.js").SessionStep[], task: import("../test-plan.js").Task): string;
+        detectRetryPatterns(toolExecutions: import("./conversation.js").ToolExecution[], initialState: import("../action-result.js").ActionResult): Promise<void>;
+        analyzeDiscoveries(stepsWithDiffs: {
+            step: import("../experience-tracker.js").SessionStep;
+            ariaDiff: string | null;
+        }[]): Promise<void>;
+        buildDiscoveryPrompt(stepsWithDiffs: {
+            step: import("../experience-tracker.js").SessionStep;
+            ariaDiff: string | null;
+        }[]): string;
+        extractVisitedUrls(toolExecutions: import("./conversation.js").ToolExecution[], initialUrl: string): string[];
+    };
+} & (new (...args: any[]) => object);
+export interface Historian extends ExperienceMethods, CodeceptJSMethods, PlaywrightMethods, ScreencastMethods {
+}
+export declare class Historian extends HistorianBase {
+    provider: Provider;
+    experienceTracker: ExperienceTracker;
+    reporter: Reporter | undefined;
+    stateManager: StateManager | undefined;
+    config: ExplorbotConfig | undefined;
+    playwright: {
+        recorder: PlaywrightRecorder;
+        helper: any;
+    } | undefined;
+    savedFiles: Set<string>;
+    constructor(provider: Provider, experienceTracker: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager, config?: ExplorbotConfig, playwright?: {
+        recorder: PlaywrightRecorder;
+        helper: any;
+    });
+    isPlaywrightFramework(): boolean;
+    getSavedFiles(): string[];
+    savePlanToFile(plan: Plan): string;
+    rewriteScenarioInFile(filePath: string, healedSteps: Array<{
+        original: string;
+        healed: string;
+    }>): void;
+}
+export {};

package/dist/src/ai/historian.js

@@ -1,18 +1,16 @@
 import { readFileSync, writeFileSync } from 'node:fs';
-import { ExperienceTracker } from "../experience-tracker.js";
 import { tag } from "../utils/logger.js";
 import { relativeToCwd } from "../utils/next-steps.js";
 import { WithCodeceptJS } from "./historian/codeceptjs.js";
 import { WithExperience } from "./historian/experience.js";
 import { WithPlaywright } from "./historian/playwright.js";
 import { WithScreencast } from "./historian/screencast.js";
-export { isNonReusableCode } from "../utils/step-analyzer.js";
 const HistorianBase = WithScreencast(WithPlaywright(WithCodeceptJS(WithExperience(Object))));
 export class Historian extends HistorianBase {
     constructor(provider, experienceTracker, reporter, stateManager, config, playwright) {
         super();
         this.provider = provider;
-        this.experienceTracker = experienceTracker || new ExperienceTracker();
+        this.experienceTracker = experienceTracker;
         this.reporter = reporter;
         this.stateManager = stateManager;
         this.config = config;
@@ -32,8 +30,6 @@ export class Historian extends HistorianBase {
     rewriteScenarioInFile(filePath, healedSteps) {
         let content = readFileSync(filePath, 'utf-8');
         for (const step of healedSteps) {
-            if (!content.includes(step.original))
-                continue;
             content = content.replace(step.original, step.healed);
         }
         writeFileSync(filePath, content);

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

@@ -0,0 +1,54 @@
+import { ActionResult } from '../action-result.js';
+import type Action from '../action.js';
+import type { ExperienceTracker } from '../experience-tracker.js';
+import Explorer from '../explorer.js';
+import type { KnowledgeTracker } from '../knowledge-tracker.js';
+import { HooksRunner } from '../utils/hooks-runner.js';
+import type { Agent } from './agent.js';
+import type { Provider } from './provider.js';
+declare class Navigator implements Agent {
+    emoji: string;
+    provider: Provider;
+    knowledgeTracker: KnowledgeTracker;
+    experienceTracker: ExperienceTracker;
+    hooksRunner: HooksRunner;
+    MAX_ATTEMPTS: number;
+    systemPrompt: string;
+    freeSailSystemPrompt: string;
+    explorer: Explorer;
+    constructor(explorer: Explorer, provider: Provider);
+    get verifyAttempts(): number;
+    get verifyTimeout(): number;
+    getBaseOrigin(): string | null;
+    getComparableCurrentUrl(stateManager: any, expectedUrl: string): string;
+    isSameExpectedOrigin(expectedUrl: string, stateManager: any): boolean;
+    isOnExpectedPage(expectedUrl: string, stateManager: any): boolean;
+    visit(url: string): Promise<void>;
+    visitOnce(url: string): Promise<void>;
+    resolveState(message: string, actionResult: ActionResult, opts?: {
+        action?: Action;
+        expectedUrl?: string;
+    }): Promise<boolean>;
+    buildExperienceTools(): {
+        learnExperience: unknown;
+    } | undefined;
+    freeSail(opts?: {
+        strategy?: 'deep' | 'shallow';
+        scope?: string;
+        visitedUrls?: Set<string>;
+    }, actionResult?: ActionResult): Promise<{
+        target: string;
+        reason: string;
+    } | null>;
+    verifyState(message: string, actionResult: ActionResult): Promise<{
+        verified: boolean;
+        successfulCodes: string[];
+        assertionSteps: Array<{
+            name: string;
+            args: any[];
+        }>;
+        totalAttempted: number;
+    }>;
+    checkAlreadyVerified(aiResponse: string, actionResult: ActionResult): boolean;
+}
+export { Navigator };

package/dist/src/ai/navigator.js

@@ -2,8 +2,6 @@ import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from '../action-result.js';
-import { ExperienceTracker, renderExperienceToc } from '../experience-tracker.js';
-import { KnowledgeTracker } from '../knowledge-tracker.js';
 import { normalizeUrl } from '../state-manager.js';
 import { extractCodeBlocks } from '../utils/code-extractor.js';
 import { HooksRunner } from "../utils/hooks-runner.js";
@@ -14,12 +12,11 @@ import { extractStatePath } from '../utils/url-matcher.js';
 import { Researcher } from "./researcher.js";
 import { actionRule, locatorRule, unexpectedPopupRule } from './rules.js';
 import { isInteractive } from './task-agent.js';
-import { createAgentTools } from "./tools.js";
+import { createLearnExperienceTool } from "./tools.js";
 const debugLog = createDebug('explorbot:navigator');
 class Navigator {
     emoji = '🧭';
     provider;
-    experienceCompactor;
     knowledgeTracker;
     experienceTracker;
     hooksRunner;
@@ -62,12 +59,11 @@ class Navigator {
   </rules>
   `;
     explorer;
-    constructor(explorer, provider, experienceCompactor, experienceTracker) {
+    constructor(explorer, provider) {
         this.provider = provider;
         this.explorer = explorer;
-        this.experienceCompactor = experienceCompactor;
-        this.knowledgeTracker = new KnowledgeTracker();
-        this.experienceTracker = experienceTracker || new ExperienceTracker();
+        this.knowledgeTracker = explorer.getKnowledgeTracker();
+        this.experienceTracker = explorer.getStateManager().getExperienceTracker();
         this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
     }
     get verifyAttempts() {
@@ -171,17 +167,8 @@ class Navigator {
         debugLog('Resolution message:', message);
         const action = opts?.action ?? this.explorer.createAction();
         const expectedUrl = opts?.expectedUrl;
-        let knowledge = '';
+        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
         let experience = '';
-        const relevantKnowledge = this.knowledgeTracker.getRelevantKnowledge(actionResult);
-        if (relevantKnowledge.length > 0) {
-            const knowledgeContent = relevantKnowledge.map((k) => k.content).join('\n\n');
-            knowledge = `
-      <hint>
-      Here is relevant knowledge for this page:
-      ${knowledgeContent}
-      </hint>`;
-        }
         if (!actionResult.isInsideIframe) {
             const successful = this.experienceTracker.getSuccessfulExperience(actionResult);
             if (successful.length > 0) {
@@ -362,7 +349,6 @@ class Navigator {
                     if (freshState.getStateHash() !== prevHash) {
                         try {
                             const diff = await freshState.diff(prevActionResult);
-                            await diff.calculate();
                             ariaChanges = diff.ariaChanged;
                         }
                         catch (err) {
@@ -446,21 +432,14 @@ class Navigator {
         return resolved;
     }
     buildExperienceTools() {
+        if (!this.experienceTracker)
+            return undefined;
         const stateManager = this.explorer.getStateManager();
         const getState = () => {
             const s = stateManager.getCurrentState();
             return s ? ActionResult.fromState(s) : null;
         };
-        const { learnExperience } = createAgentTools({
-            explorer: this.explorer,
-            researcher: null,
-            navigator: this,
-            experienceTracker: this.experienceTracker,
-            getState,
-        });
-        if (!learnExperience)
-            return undefined;
-        return { learnExperience };
+        return { learnExperience: createLearnExperienceTool({ getExperienceTracker: () => this.experienceTracker, getState }) };
     }
     async freeSail(opts, actionResult) {
         const stateManager = this.explorer.getStateManager();
@@ -579,24 +558,10 @@ class Navigator {
             tag('operation').log(`Reusing cached verification: ${cachedVerification ? 'PASS' : 'FAIL'}`);
             return { verified: cachedVerification, successfulCodes: [], assertionSteps: [], totalAttempted: 0 };
         }
-        let knowledge = '';
+        const knowledge = this.knowledgeTracker.renderRelevantKnowledge(actionResult);
         let experience = '';
-        const relevantKnowledge = this.knowledgeTracker.getRelevantKnowledge(actionResult);
-        if (relevantKnowledge.length > 0) {
-            const knowledgeContent = relevantKnowledge.map((k) => k.content).join('\n\n');
-            knowledge = `
-      <hint>
-      Here is relevant knowledge for this page:
-      ${knowledgeContent}
-      </hint>`;
-        }
         if (!actionResult.isInsideIframe) {
-            const toc = this.experienceTracker.getExperienceTableOfContents(actionResult);
-            if (toc.length > 0) {
-                const totalSections = toc.reduce((sum, entry) => sum + entry.sections.length, 0);
-                tag('operation').log(`Found ${toc.length} experience ${pluralize(toc.length, 'file')} (${totalSections} sections) for: ${actionResult.url}`);
-                experience = renderExperienceToc(toc);
-            }
+            experience = this.experienceTracker.renderExperienceTocFor(actionResult);
         }
         const priorVerifications = Object.entries(actionResult.verifications ?? {});
         let verificationContext = '';
@@ -685,7 +650,7 @@ class Navigator {
                     return;
                 }
                 await this.explorer.switchToMainFrame();
-                const verified = await action.attempt(codeBlock, message, false);
+                const verified = await action.attempt(codeBlock, message);
                 if (verified) {
                     tag('success').log('Verification passed');
                     successfulCodes.push(codeBlock);

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

@@ -0,0 +1,81 @@
+import { ActionResult } from '../action-result.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;
+    constructor(provider: Provider, agentTools: any, researcher: Researcher, explorer: Explorer);
+    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/pilot.js

@@ -3,7 +3,6 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { ActionResult } from "../action-result.js";
 import { ConfigParser } from "../config.js";
-import { renderExperienceToc } from "../experience-tracker.js";
 import { TestResult } from "../test-plan.js";
 import { collectInteractiveNodes, detectFocusArea, extractFocusedElement } from "../utils/aria.js";
 import { ErrorPageError } from "../utils/error-page.js";
@@ -22,13 +21,11 @@ export class Pilot {
     researcher;
     explorer;
     fisherman = null;
-    experienceTracker;
-    constructor(provider, agentTools, researcher, explorer, experienceTracker) {
+    constructor(provider, agentTools, researcher, explorer) {
         this.provider = provider;
         this.agentTools = agentTools;
         this.researcher = researcher;
         this.explorer = explorer;
-        this.experienceTracker = experienceTracker || null;
     }
     setFisherman(fisherman) {
         this.fisherman = fisherman;
@@ -90,7 +87,7 @@ export class Pilot {
             requestVerification: z
                 .string()
                 .nullable()
-                .describe('REQUIRED whenever decision is "pass" — a one-sentence natural-language claim about the current page that, if true, proves the scenario goal (e.g., "New test suite \\"Foo\\" is visible in the suites list"). NOT code: do not write I.*, expect(), .then(), grabTitle, or any JavaScript. Navigator translates the claim into CodeceptJS assertions and runs them; passing assertions are saved to the generated test file. Also use when evidence is insufficient before deciding pass/fail. Leave null for "continue", "fail", or "skipped".'),
+                .describe('REQUIRED whenever decision is "pass" — a one-sentence natural-language claim about the current page that, if true, proves the scenario goal (e.g., "New item \\"Foo\\" is visible in the items list"). NOT code: do not write I.*, expect(), .then(), grabTitle, or any JavaScript. Navigator translates the claim into CodeceptJS assertions and runs them; passing assertions are saved to the generated test file. Also use when evidence is insufficient before deciding pass/fail. Leave null for "continue", "fail", or "skipped".'),
         });
         const userContent = dedent `
       Tester wants to ${type} the test.
@@ -124,7 +121,7 @@ export class Pilot {
       - Mixed evidence + final state shows success → pass. Mixed + final state unclear → continue with guidance.
 
       When deciding "pass", you MUST also set requestVerification to a one-sentence natural-language
-      claim about the current page (e.g., "New test suite Foo is visible in the suites list"). NOT
+      claim about the current page (e.g., "New item Foo is visible in the items list"). NOT
       code — do not write I.*, expect(), .then(), or any JavaScript. Choose the strongest single
       piece of evidence (a unique element/text that exists ONLY because the scenario succeeded).
       Navigator translates the claim into CodeceptJS assertions; without it the generated test has
@@ -379,10 +376,6 @@ export class Pilot {
 
         FIRST: Decide if precondition() is needed.
 
-        ${capabilityGroundingRule}
-
-        ${dataProtectionRules}
-
         Call precondition() WHEN:
         - The scenario edits/deletes/modifies an item, and you want a DISPOSABLE item to act on safely
         - The scenario needs specific data clearly NOT on the current page (e.g., items with specific statuses for filtering)
@@ -525,14 +518,10 @@ export class Pilot {
     `;
     }
     getExperienceToc() {
-        if (!this.experienceTracker)
-            return '';
         const state = this.explorer.getStateManager().getCurrentState();
         if (!state)
             return '';
-        const actionResult = ActionResult.fromState(state);
-        const toc = this.experienceTracker.getExperienceTableOfContents(actionResult);
-        return renderExperienceToc(toc);
+        return this.explorer.getStateManager().getExperienceTracker().renderExperienceTocFor(ActionResult.fromState(state));
     }
     pickPlanningTools() {
         const { see, context, verify, research, getVisitedStates, xpathCheck, learnExperience, askUser } = this.agentTools ?? {};
@@ -957,8 +946,8 @@ export class Pilot {
 
       ${dataProtectionRules}
 
-      Describe WHAT to create, not what exists. RIGHT: precondition("1 test"). WRONG:
-      precondition("1 test suite named Updated Suite with existing tests"). Keep descriptions short.
+      Describe WHAT to create, not what exists. RIGHT: precondition("1 post"). WRONG:
+      precondition("1 post named Updated Post with existing comments"). Keep descriptions short.
 
       Response format:
       PROGRESS: <1 sentence assessment>

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 type { 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 { type 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, researcher: Researcher);
+    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 {};