explorbot 0.1.10 → 0.1.11

package/dist/src/commands/plan-save-command.js

@@ -1,5 +1,5 @@
-import path from 'node:path';
-import { tag } from '../utils/logger.js';
+import { getCliName } from "../utils/cli-name.js";
+import { printNextSteps, relativeToCwd } from "../utils/next-steps.js";
 import { BaseCommand } from './base-command.js';
 export class PlanSaveCommand extends BaseCommand {
     name = 'plan:save';
@@ -12,10 +12,22 @@ export class PlanSaveCommand extends BaseCommand {
         }
         const filename = args.trim() || undefined;
         const savedPath = this.explorBot.savePlan(filename);
-        if (savedPath) {
-            const relativePath = path.relative(process.cwd(), savedPath);
-            tag('success').log(`Plan saved to: ${relativePath}`);
-            tag('info').log(`Run /plan:load ${relativePath} to reload it`);
-        }
+        if (!savedPath)
+            return;
+        const cli = getCliName();
+        const relPlan = relativeToCwd(savedPath);
+        const sections = [
+            {
+                label: 'Plan',
+                path: savedPath,
+                commands: [
+                    { label: 'Re-run', command: `${cli} test ${relPlan} 1` },
+                    { label: 'Run all', command: `${cli} test ${relPlan} *` },
+                    { label: 'Run range', command: `${cli} test ${relPlan} 1-3` },
+                    { label: 'Reload', command: `/plan:load ${relPlan}` },
+                ],
+            },
+        ];
+        printNextSteps(sections);
     }
 }

package/dist/src/commands/rerun-command.js

@@ -19,6 +19,10 @@ export class RerunCommand extends BaseCommand {
         if (!existsSync(filePath)) {
             filePath = resolve(ConfigParser.getInstance().getTestsDir(), filename);
         }
+        if (filePath.endsWith('.spec.ts') || filePath.endsWith('.spec.js')) {
+            tag('error').log(`Rerun does not support Playwright tests. Run them with: npx playwright test ${filePath}`);
+            return;
+        }
         const testIndices = indexArg ? parseTestIndices(indexArg) : undefined;
         await this.explorBot.agentRerunner().rerun(filePath, { testIndices });
     }

package/dist/src/components/App.js

@@ -72,16 +72,27 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
             setInterruptPrompt(prompt);
             setShowInput(true);
             return new Promise((resolve) => {
-                interruptResolveRef.current = resolve;
+                interruptResolveRef.current = (value) => {
+                    interruptResolveRef.current = null;
+                    setInterruptPrompt(null);
+                    resolve(value);
+                };
             });
         });
         const handleIdle = () => {
             setShowInput(true);
         };
+        const handleInterrupt = () => {
+            if (interruptResolveRef.current) {
+                interruptResolveRef.current(null);
+            }
+        };
         executionController.on('idle', handleIdle);
+        executionController.on('interrupt', handleInterrupt);
         setInputCallbackReady(true);
         return () => {
             executionController.off('idle', handleIdle);
+            executionController.off('interrupt', handleInterrupt);
             executionController.reset();
         };
     }, []);
@@ -244,9 +255,10 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
             return;
         }
         if (isCommand) {
-            setInterruptPrompt(null);
+            if (interruptResolveRef.current) {
+                interruptResolveRef.current(null);
+            }
             setShowInput(false);
-            interruptResolveRef.current = null;
             executionController.startExecution();
             try {
                 await commandHandler.executeCommand(trimmed);
@@ -264,8 +276,6 @@ export function App({ explorBot, initialShowInput = false, exitOnEmptyInput = fa
         }
         if (interruptResolveRef.current) {
             interruptResolveRef.current(input);
-            interruptResolveRef.current = null;
-            setInterruptPrompt(null);
             setShowInput(false);
             return;
         }

package/dist/src/execution-controller.js

@@ -7,6 +7,7 @@ export class ExecutionController extends EventEmitter {
     inputCallback = null;
     interruptResolvers = [];
     abortController = null;
+    awaitingInput = false;
     constructor() {
         super();
     }
@@ -39,6 +40,9 @@ export class ExecutionController extends EventEmitter {
         this.interruptResolvers = [];
         this.emit('idle');
     }
+    isAwaitingInput() {
+        return this.awaitingInput;
+    }
     isInterrupted() {
         return this.interrupted;
     }
@@ -64,10 +68,16 @@ export class ExecutionController extends EventEmitter {
         return userInput;
     }
     async requestInput(prompt) {
-        if (this.inputCallback) {
+        if (!this.inputCallback) {
+            return await this.readlineInput(prompt);
+        }
+        this.awaitingInput = true;
+        try {
             return await this.inputCallback(prompt);
         }
-        return await this.readlineInput(prompt);
+        finally {
+            this.awaitingInput = false;
+        }
     }
     async readlineInput(prompt) {
         const rl = readline.createInterface({
@@ -86,6 +96,7 @@ export class ExecutionController extends EventEmitter {
         this.interrupted = false;
         this.interruptResolvers = [];
         this.abortController = null;
+        this.awaitingInput = false;
     }
 }
 export const executionController = ExecutionController.getInstance();

package/dist/src/experience-tracker.js

@@ -13,15 +13,17 @@ export const RECENT_WINDOW_DAYS = 30;
 /**
  * Stores and reads per-page experience files (`./experience/<stateHash>.md`).
  *
- * Format rules (enforced by writeFlow/writeAction — the only supported writers):
+ * Two writers, two contracts:
  *
- *   ## FLOW: <imperative title>        multi-step, `*` bullets + optional ```js``` + `>` discovery, ends with `---`
- *   ## ACTION: <imperative title>      single-step, optional `Solution:` line + one ```js``` code block
+ *   writeFlow(state, body, relatedUrls?)  — caller hands in a fully-formatted
+ *                                            `## FLOW: <imperative title>` block (multi-step,
+ *                                            `*` bullets + optional ```js``` + `>` discovery,
+ *                                            ends with `---`). Tracker dedups + prepends.
+ *   writeAction(state, ActionInput)        — `## ACTION: <imperative title>`, single-step,
+ *                                            optional `Solution:` line + one ```js``` code block.
+ *                                            Title normalized via normalizeTitle().
  *
  * - Always h2. Never h3 for FLOW/ACTION.
- * - Title is an imperative verb phrase, lowercase-first, no trailing punctuation.
- *   Writers normalize automatically (strip own `FLOW:` / `ACTION:` prefix if the caller included it,
- *   lowercase first char, trim trailing `.!?,;:`).
  * - On read (getSuccessfulExperience), headings are rendered as
  *   `## HOW to <title> (multi-step|single-step)` so prompts get natural phrasing.
  */
@@ -159,27 +161,25 @@ export class ExperienceTracker {
         this.writeExperienceFile(stateHash, updatedContent, data);
         tag('substep').log(` Added ACTION to: ${stateHash}.md`);
     }
-    writeFlow(state, flow) {
+    writeFlow(state, body, relatedUrls) {
         if (this.disabled || this.isWritingDisabled(state))
             return;
-        if (!flow.steps?.length)
+        if (!body?.trim())
             return;
         this.ensureExperienceFile(state);
         const stateHash = state.getStateHash();
         const { content, data } = this.readExperienceFile(stateHash);
-        if (flow.relatedUrls?.length) {
+        if (content.includes(body)) {
+            debugLog('Skipping duplicate flow body');
+            return;
+        }
+        if (relatedUrls?.length) {
             const currentPath = extractStatePath(state.url || '');
             const existingRelated = Array.isArray(data.related) ? data.related : [];
-            const allRelated = [...new Set([...existingRelated, ...flow.relatedUrls])];
+            const allRelated = [...new Set([...existingRelated, ...relatedUrls])];
             data.related = allRelated.filter((url) => url !== currentPath);
         }
-        const title = normalizeTitle(flow.scenario);
-        if (!title)
-            return;
-        const sessionContent = this.trimSessionContent(generateFlowContent(title, flow.steps));
-        if (!sessionContent)
-            return;
-        const updatedContent = `${sessionContent}\n${content}`;
+        const updatedContent = `${body}\n${content}`;
         this.writeExperienceFile(stateHash, updatedContent, data);
         tag('substep').log(`Added FLOW to: ${stateHash}.md`);
     }
@@ -245,33 +245,6 @@ export class ExperienceTracker {
         // Clear any in-memory state if needed
         // The actual files will be cleaned up by test cleanup
     }
-    trimSessionContent(content) {
-        const q = mdq(content);
-        if (q.query('heading').count() === 0)
-            return null;
-        if (q.query('code').count() === 0)
-            return null;
-        let result = content;
-        const codeBlocks = q.query('code').each();
-        if (codeBlocks.length > 2) {
-            for (const block of codeBlocks.slice(2)) {
-                result = result.replace(block.text(), '');
-            }
-        }
-        const blockquotes = mdq(result).query('blockquote').each();
-        if (blockquotes.length > 5) {
-            for (const bq of blockquotes.slice(5)) {
-                result = result.replace(bq.text(), '');
-            }
-        }
-        const lines = result.split('\n');
-        if (lines.length > 40) {
-            result = lines.slice(0, 40).join('\n');
-        }
-        if (!result.trim())
-            return null;
-        return result;
-    }
     getSuccessfulExperience(state, options) {
         const records = this.getRelevantExperience(state, {
             includeDescendantExperience: options?.includeDescendants,
@@ -469,7 +442,9 @@ export function renderExperienceToc(toc) {
         return '';
     const lines = [];
     lines.push('<experience>');
-    lines.push('Past experience for this page — reusable recipes recorded from prior successful runs.');
+    lines.push('Past experience for this page — recipes recorded from prior successful runs.');
+    lines.push('Locators and step ordering worked then; the page may have changed since.');
+    lines.push('Treat as a starting hypothesis, not ground truth. If a step fails, fall back to ARIA/UI-map.');
     lines.push('FLOW: = multi-step recipe (bullets + code + discovery). ACTION: = single-step snippet (one code block).');
     lines.push('Call learn_experience({ fileTag, sectionIndex }) to read a section when it looks relevant to the current step.');
     lines.push('');
@@ -513,25 +488,6 @@ function generateActionContent(title, code, explanation) {
     lines.push('');
     return lines.join('\n');
 }
-function generateFlowContent(title, steps) {
-    let content = `## FLOW: ${title}\n\n`;
-    for (const step of steps) {
-        content += `* ${step.message}\n\n`;
-        if (step.code) {
-            content += '```js\n';
-            content += `${step.code}\n`;
-            content += '```\n\n';
-        }
-        if (step.discovery) {
-            const discoveries = step.discovery.split('\n').filter((d) => d.trim());
-            for (const discovery of discoveries) {
-                content += `> ${discovery.trim()}\n\n`;
-            }
-        }
-    }
-    content += '---\n';
-    return content;
-}
 function renderAsHowTo(content) {
     const tokens = marked.lexer(content);
     let result = '';

package/dist/src/explorbot.js

@@ -36,6 +36,7 @@ export class ExplorBot {
     currentPlan;
     planFeature;
     lastPlanError = null;
+    lastSavedPlanPath = null;
     agents = {};
     constructor(options = {}) {
         this.options = options;
@@ -214,10 +215,10 @@ export class ExplorBot {
         return this.agents.quartermaster;
     }
     agentHistorian() {
-        return (this.agents.historian ||= this.createAgent(({ ai, explorer }) => {
+        return (this.agents.historian ||= this.createAgent(({ ai, explorer, config }) => {
             const experienceTracker = explorer.getStateManager().getExperienceTracker();
             const reporter = explorer.getReporter();
-            return new Historian(ai, experienceTracker, reporter, explorer.getStateManager());
+            return new Historian(ai, experienceTracker, reporter, explorer.getStateManager(), config, explorer.getPlaywrightRecorder());
         }));
     }
     agentRerunner() {
@@ -314,12 +315,7 @@ export class ExplorBot {
                 return undefined;
             return this.currentPlan;
         }
-        const savedPath = this.savePlan();
-        if (savedPath) {
-            const relativePath = path.relative(process.cwd(), savedPath);
-            tag('info').log(`Plan saved to: ${relativePath}`);
-            tag('info').log(`Edit the plan file and run /plan:load ${relativePath} to reload it`);
-        }
+        this.savePlan();
         return this.currentPlan;
     }
     getPlansDir() {
@@ -341,6 +337,7 @@ export class ExplorBot {
         const planFilename = filename || this.generatePlanFilename();
         const planPath = path.join(plansDir, planFilename);
         Plan.saveMultipleToMarkdown(plans, planPath);
+        this.lastSavedPlanPath = planPath;
         return planPath;
     }
     generatePlanFilename() {

package/dist/src/explorer.js

@@ -12,6 +12,7 @@ import { RequestStore } from "./api/request-store.js";
 import { XhrCapture } from "./api/xhr-capture.js";
 import { ConfigParser, outputPath } from './config.js';
 import { KnowledgeTracker } from './knowledge-tracker.js';
+import { PlaywrightRecorder } from "./playwright-recorder.js";
 import { Reporter } from "./reporter.js";
 import { StateManager } from './state-manager.js';
 import { createDebug, log, tag } from './utils/logger.js';
@@ -35,6 +36,7 @@ class Explorer {
     _activeTest = null;
     xhrCapture = null;
     requestStore = null;
+    playwrightRecorder = new PlaywrightRecorder();
     constructor(config, aiProvider, options) {
         this.config = config;
         this.aiProvider = aiProvider;
@@ -89,7 +91,7 @@ class Explorer {
             tag('substep').log(debugInfo);
         }
         const PlaywrightConfig = {
-            timeout: 1000,
+            timeout: 3000,
             highlightElement: true,
             waitForAction: 500,
             ...playwrightConfig,
@@ -188,6 +190,7 @@ class Explorer {
         const hasSession = this.options?.session && existsSync(this.options.session);
         const contextOptions = hasSession ? { storageState: this.options.session } : undefined;
         await this.playwrightHelper._createContextPage(contextOptions);
+        await this.playwrightRecorder.start(this.playwrightHelper.browserContext);
         this.setupXhrCapture();
         if (hasSession) {
             tag('info').log(`Session restored from ${path.relative(process.cwd(), this.options.session)}`);
@@ -216,7 +219,10 @@ class Explorer {
         await this.playwrightHelper._startBrowser();
     }
     createAction() {
-        return new Action(this.actor, this.stateManager);
+        return new Action(this.actor, this.stateManager, this.playwrightRecorder);
+    }
+    getPlaywrightRecorder() {
+        return this.playwrightRecorder;
     }
     async visit(url) {
         await this.closeOtherTabs();
@@ -411,6 +417,7 @@ class Explorer {
         if (this.xhrCapture && this.playwrightHelper?.page) {
             this.xhrCapture.detach(this.playwrightHelper.page);
         }
+        await this.playwrightRecorder.stop();
         if (this.options?.session && this.playwrightHelper?.browserContext) {
             const dir = path.dirname(this.options.session);
             if (!existsSync(dir))

package/dist/src/observability.js

@@ -1,125 +1,76 @@
-import { randomBytes } from 'node:crypto';
-import { context, trace } from '@opentelemetry/api';
+import { trace } from '@opentelemetry/api';
 let current = null;
-let depth = 0;
 export const Observability = {
     async run(name, metadata, fn) {
-        const started = Observability.startTrace(name, metadata);
-        try {
-            if (!started) {
-                const parentSpan = current?.span;
-                if (!parentSpan || !current)
-                    return await fn();
-                const tracer = trace.getTracer('ai');
-                const childSpan = tracer.startSpan(name, undefined, trace.setSpan(context.active(), parentSpan));
-                const savedSpan = current.span;
-                const savedName = current.name;
-                current.span = childSpan;
-                current.name = name;
-                return await context.with(trace.setSpan(context.active(), childSpan), async () => {
-                    try {
-                        return await fn();
-                    }
-                    finally {
-                        childSpan.end();
-                        current.span = savedSpan;
-                        current.name = savedName;
-                    }
-                });
-            }
-            const tracer = trace.getTracer('ai');
-            const spanContext = {
-                traceId: current?.traceId || randomBytes(16).toString('hex'),
-                spanId: randomBytes(8).toString('hex'),
-                traceFlags: 1,
-            };
-            const rootContext = trace.setSpanContext(context.active(), spanContext);
-            const initSpan = tracer.startSpan(name, undefined, rootContext);
-            initSpan.setAttribute('langfuse.trace.name', name);
-            initSpan.setAttribute('langfuse.trace.id', current?.traceId || '');
-            if (current?.metadata?.sessionId) {
-                initSpan.setAttribute('langfuse.trace.session_id', String(current.metadata.sessionId));
-            }
-            if (current?.metadata?.userId) {
-                initSpan.setAttribute('langfuse.trace.user_id', String(current.metadata.userId));
-            }
-            if (current?.metadata?.tags && Array.isArray(current.metadata.tags)) {
-                initSpan.setAttribute('langfuse.trace.tags', current.metadata.tags);
-            }
-            if (current?.metadata?.input) {
-                initSpan.setAttribute('langfuse.trace.input', JSON.stringify(current.metadata.input));
-            }
-            initSpan.end();
-            const span = tracer.startSpan(name, undefined, rootContext);
-            current.span = span;
-            return await context.with(trace.setSpan(rootContext, span), async () => {
+        const tracer = trace.getTracer('ai');
+        if (current) {
+            return await tracer.startActiveSpan(name, {}, async (span) => {
+                const saved = current;
+                current = {
+                    metadata: { ...saved.metadata, ...metadata },
+                    name,
+                    span,
+                };
                 try {
                     return await fn();
                 }
                 finally {
                     span.end();
-                    current.span = undefined;
+                    current = saved;
                 }
             });
         }
-        finally {
-            Observability.endTrace(started);
-        }
-    },
-    startTrace(name, metadata) {
-        if (current) {
-            depth += 1;
-            return false;
-        }
-        const langfuseTraceId = metadata.langfuseTraceId || randomBytes(16).toString('hex');
-        current = {
-            metadata: {
-                ...metadata,
-                langfuseTraceId,
-            },
-            traceId: langfuseTraceId,
-            updateParent: true,
-            name,
-        };
-        depth = 1;
-        return true;
-    },
-    endTrace(started) {
-        if (!current) {
-            return;
-        }
-        if (!started) {
-            depth -= 1;
-            return;
-        }
-        depth -= 1;
-        if (depth <= 0) {
-            current = null;
-            depth = 0;
-        }
+        const attributes = buildRootSpanAttributes(name, metadata);
+        return await tracer.startActiveSpan(name, { attributes }, async (span) => {
+            current = { metadata, name, span };
+            try {
+                return await fn();
+            }
+            finally {
+                span.end();
+                current = null;
+            }
+        });
     },
     getTelemetry() {
         if (!current) {
             return undefined;
         }
-        const telemetry = {
+        const metadata = {};
+        if (current.metadata.sessionId)
+            metadata.sessionId = current.metadata.sessionId;
+        if (current.metadata.userId)
+            metadata.userId = current.metadata.userId;
+        if (Array.isArray(current.metadata.tags))
+            metadata.tags = current.metadata.tags;
+        return {
             isEnabled: true,
             functionId: current.name,
-            metadata: {
-                ...current.metadata,
-                langfuseTraceId: current.traceId,
-                langfuseUpdateParent: current.updateParent,
-            },
+            metadata,
         };
-        if (current.updateParent) {
-            current.updateParent = false;
-        }
-        return telemetry;
     },
     isTracing() {
         return Boolean(current);
     },
     getSpan() {
-        return current?.span;
+        return current?.span ?? trace.getActiveSpan();
     },
 };
+function buildRootSpanAttributes(name, metadata) {
+    const attributes = {
+        'langfuse.trace.name': name,
+    };
+    if (metadata.sessionId) {
+        attributes['session.id'] = String(metadata.sessionId);
+    }
+    if (metadata.userId) {
+        attributes['user.id'] = String(metadata.userId);
+    }
+    if (Array.isArray(metadata.tags)) {
+        attributes['langfuse.trace.tags'] = metadata.tags;
+    }
+    if (metadata.input !== undefined) {
+        attributes['langfuse.trace.input'] = JSON.stringify(metadata.input);
+    }
+    return attributes;
+}