explorbot 0.1.9 → 0.1.10

package/src/commands/plan-edit-command.ts

@@ -1,9 +1,9 @@
-import { BaseCommand } from './base-command.js';
+import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class PlanEditCommand extends BaseCommand {
   name = 'plan:edit';
   description = 'Open test plan editor';
-  suggestions = ['/plan:edit - toggle tests on/off'];
+  suggestions: Suggestion[] = [{ command: 'plan:edit', hint: 'toggle tests on/off' }];
 
   async execute(_args: string): Promise<void> {}
 }

package/src/commands/plan-load-command.ts

@@ -1,10 +1,13 @@
 import { tag } from '../utils/logger.js';
-import { BaseCommand } from './base-command.js';
+import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class PlanLoadCommand extends BaseCommand {
   name = 'plan:load';
   description = 'Load plan from file';
-  suggestions = ['/test - to launch first test', '/test * - to launch all tests'];
+  suggestions: Suggestion[] = [
+    { command: 'test', hint: 'launch first test' },
+    { command: 'test *', hint: 'launch all tests' },
+  ];
 
   async execute(args: string): Promise<void> {
     const filename = args.trim();

package/src/commands/plan-reload-command.ts

@@ -1,10 +1,13 @@
 import { tag } from '../utils/logger.js';
-import { BaseCommand } from './base-command.js';
+import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class PlanReloadCommand extends BaseCommand {
   name = 'plan:reload';
   description = 'Clear current plan and regenerate';
-  suggestions = ['/test - to launch first test', '/test * - to launch all tests'];
+  suggestions: Suggestion[] = [
+    { command: 'test', hint: 'launch first test' },
+    { command: 'test *', hint: 'launch all tests' },
+  ];
 
   async execute(args: string): Promise<void> {
     const currentPlan = this.explorBot.getCurrentPlan();

package/src/commands/plan-save-command.ts

@@ -1,11 +1,11 @@
 import path from 'node:path';
 import { tag } from '../utils/logger.js';
-import { BaseCommand } from './base-command.js';
+import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class PlanSaveCommand extends BaseCommand {
   name = 'plan:save';
   description = 'Save current plan to file';
-  suggestions = ['/test - to launch first test'];
+  suggestions: Suggestion[] = [{ command: 'test', hint: 'launch first test' }];
 
   async execute(args: string): Promise<void> {
     const plan = this.explorBot.getCurrentPlan();

package/src/commands/research-command.ts

@@ -1,12 +1,15 @@
 import { join } from 'node:path';
 import { ConfigParser } from '../config.ts';
 import { tag } from '../utils/logger.ts';
-import { BaseCommand } from './base-command.js';
+import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class ResearchCommand extends BaseCommand {
   name = 'research';
   description = 'Research current page or navigate to URI and research. Use --deep to explore interactive elements by clicking them. Use --data to include page data.';
-  suggestions = ['/navigate <page> - to go to another page', '/plan <feature> - to plan testing'];
+  suggestions: Suggestion[] = [
+    { command: 'navigate <page>', hint: 'go to another page' },
+    { command: 'plan <feature>', hint: 'plan testing' },
+  ];
   options = [
     { flags: '--data', description: 'Include page data' },
     { flags: '--deep', description: 'Explore interactive elements by clicking them' },
@@ -45,7 +48,7 @@ export class ResearchCommand extends BaseCommand {
     }
 
     if (!enableDeep) {
-      this.suggestions = ['/research <page> --deep - analyze page for all expandable elements and interactions'];
+      this.suggestions = [{ command: 'research <page> --deep', hint: 'analyze page for all expandable elements and interactions' }];
     }
   }
 }

package/src/commands/start-command.ts

@@ -1,10 +1,14 @@
-import { BaseCommand } from './base-command.js';
+import { BaseCommand, type Suggestion } from './base-command.js';
 import { ExploreCommand } from './explore-command.js';
 
 export class StartCommand extends BaseCommand {
   name = 'start';
   description = 'Start web exploration';
-  suggestions = ['/navigate <page> - to go to another page', '/research - to analyze', '/plan <feature> - to plan testing'];
+  suggestions: Suggestion[] = [
+    { command: 'navigate <page>', hint: 'go to another page' },
+    { command: 'research', hint: 'analyze current page' },
+    { command: 'plan <feature>', hint: 'plan testing' },
+  ];
 
   async execute(args: string): Promise<void> {
     await new ExploreCommand(this.explorBot).execute(args);

package/src/commands/test-command.ts

@@ -1,14 +1,20 @@
+import { Stats } from '../stats.js';
 import { Test } from '../test-plan.js';
 import { tag } from '../utils/logger.js';
-import { BaseCommand } from './base-command.js';
+import { BaseCommand, type Suggestion } from './base-command.js';
 
 export class TestCommand extends BaseCommand {
   name = 'test';
   description = 'Launch tester agent to execute test scenarios';
-  suggestions = ['/test - to run next test', '/plan - to create new plan'];
+  suggestions: Suggestion[] = [
+    { command: 'test', hint: 'run next test' },
+    { command: 'plan', hint: 'create new plan' },
+  ];
 
   async execute(args: string): Promise<void> {
     const plan = this.explorBot.getCurrentPlan();
+    Stats.mode = 'test';
+    Stats.focus = plan?.title;
     const toExecute: Test[] = [];
 
     const requirePlan = () => {

package/src/experience-tracker.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import matter from 'gray-matter';
-import { marked, type Tokens } from 'marked';
+import { type Tokens, marked } from 'marked';
 import type { ActionResult } from './action-result.js';
 import { ConfigParser } from './config.js';
 import { KnowledgeTracker } from './knowledge-tracker.js';
@@ -13,6 +13,23 @@ import { extractStatePath } from './utils/url-matcher.js';
 const debugLog = createDebug('explorbot:experience');
 const DEFAULT_MAX_EXPERIENCE_LINES = 100;
 
+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):
+ *
+ *   ## FLOW: <imperative title>        multi-step, `*` bullets + optional ```js``` + `>` discovery, ends with `---`
+ *   ## ACTION: <imperative title>      single-step, optional `Solution:` line + one ```js``` code block
+ *
+ * - 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.
+ */
 export class ExperienceTracker {
   private experienceDir: string;
   private disabled: boolean;
@@ -144,35 +161,57 @@ export class ExperienceTracker {
     return this.knowledgeTracker.getRelevantKnowledge(state).some((k) => k.noExperienceWriting === true || k.noExperienceWriting === 'true');
   }
 
-  async saveSuccessfulResolution(state: ActionResult, originalMessage: string, code: string, explanation?: string): Promise<void> {
+  writeAction(state: ActionResult, action: ActionInput): void {
     if (this.disabled || this.isWritingDisabled(state)) return;
+    if (!action.code?.trim()) return;
 
     this.ensureExperienceFile(state);
     const stateHash = state.getStateHash();
     const { content, data } = this.readExperienceFile(stateHash);
-    if (content.includes(code)) {
-      debugLog('Skipping duplicate successful resolution', code);
+    if (content.includes(action.code)) {
+      debugLog('Skipping duplicate action', action.code);
       return;
     }
 
-    const filteredCode = code.replace(/I\.amOnPage\s*\([^)]*\)/gs, '');
-    const newEntryContent = `### SUCCEEDED: ${originalMessage.split('\n')[0]}
+    const title = normalizeTitle(action.title.split('\n')[0]);
+    if (!title) return;
 
-${explanation ? `Solution: ${explanation}` : ''}
+    const filteredCode = action.code.replace(/I\.amOnPage\s*\([^)]*\)/gs, '');
+    const newEntry = generateActionContent(title, filteredCode, action.explanation);
+    const updatedContent = `${newEntry}\n\n${content}`;
+    this.writeExperienceFile(stateHash, updatedContent, data);
+
+    tag('substep').log(` Added ACTION to: ${stateHash}.md`);
+  }
+
+  writeFlow(state: ActionResult, flow: FlowInput): void {
+    if (this.disabled || this.isWritingDisabled(state)) return;
+    if (!flow.steps?.length) return;
+
+    this.ensureExperienceFile(state);
+    const stateHash = state.getStateHash();
+    const { content, data } = this.readExperienceFile(stateHash);
+
+    if (flow.relatedUrls?.length) {
+      const currentPath = extractStatePath(state.url || '');
+      const existingRelated = Array.isArray(data.related) ? data.related : [];
+      const allRelated = [...new Set([...existingRelated, ...flow.relatedUrls])];
+      data.related = allRelated.filter((url) => url !== currentPath);
+    }
 
-\`\`\`javascript
-${filteredCode}
-\`\`\`
-`;
+    const title = normalizeTitle(flow.scenario);
+    if (!title) return;
 
-    const updatedContent = `${newEntryContent}\n\n${content}`;
+    const sessionContent = this.trimSessionContent(generateFlowContent(title, flow.steps));
+    if (!sessionContent) return;
+    const updatedContent = `${sessionContent}\n${content}`;
     this.writeExperienceFile(stateHash, updatedContent, data);
 
-    tag('substep').log(` Added successful resolution to: ${stateHash}.md`);
+    tag('substep').log(`Added FLOW to: ${stateHash}.md`);
   }
 
-  getAllExperience(): { filePath: string; data: any; content: string }[] {
-    const allFiles: { filePath: string; data: any; content: string }[] = [];
+  getAllExperience(): ExperienceFile[] {
+    const allFiles: ExperienceFile[] = [];
 
     for (const experienceDir of this.getExperienceDirectories()) {
       if (!existsSync(experienceDir)) {
@@ -188,10 +227,12 @@ ${filteredCode}
           try {
             const content = readFileSync(file, 'utf8');
             const parsed = matter(content);
+            const mtime = statSync(file).mtime;
             allFiles.push({
               filePath: file,
               data: parsed.data,
               content: parsed.content,
+              mtime,
             });
           } catch (error) {
             debugLog(`Failed to read experience file ${file}:`, error);
@@ -205,7 +246,7 @@ ${filteredCode}
     return allFiles;
   }
 
-  getRelevantExperience(state: ActionResult, options?: { includeDescendantExperience?: boolean }): { filePath: string; data: any; content: string }[] {
+  getRelevantExperience(state: ActionResult, options?: { includeDescendantExperience?: boolean }): ExperienceFile[] {
     const relevantKnowledge = this.knowledgeTracker.getRelevantKnowledge(state);
     const readingDisabled = relevantKnowledge.some((knowledge) => knowledge.noExperienceReading === true || knowledge.noExperienceReading === 'true');
     if (readingDisabled) {
@@ -236,50 +277,6 @@ ${filteredCode}
     // The actual files will be cleaned up by test cleanup
   }
 
-  saveSessionExperience(state: ActionResult, entry: SessionExperienceEntry): void {
-    if (this.disabled || this.isWritingDisabled(state)) return;
-
-    this.ensureExperienceFile(state);
-    const stateHash = state.getStateHash();
-    const { content, data } = this.readExperienceFile(stateHash);
-
-    if (entry.relatedUrls?.length) {
-      const currentPath = extractStatePath(state.url || '');
-      const existingRelated = Array.isArray(data.related) ? data.related : [];
-      const allRelated = [...new Set([...existingRelated, ...entry.relatedUrls])];
-      data.related = allRelated.filter((url) => url !== currentPath);
-    }
-
-    const sessionContent = this.trimSessionContent(this.generateSessionContent(entry));
-    if (!sessionContent) return;
-    const updatedContent = `${sessionContent}\n${content}`;
-    this.writeExperienceFile(stateHash, updatedContent, data);
-
-    tag('substep').log(`Added session experience to: ${stateHash}.md`);
-  }
-
-  private generateSessionContent(entry: SessionExperienceEntry): string {
-    let content = `## Successful Flow: ${entry.scenario}\n\n`;
-
-    for (const step of entry.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;
-  }
-
   private trimSessionContent(content: string): string | null {
     const q = mdq(content);
     if (q.query('heading').count() === 0) return null;
@@ -318,12 +315,14 @@ ${filteredCode}
     for (const record of records) {
       if (!record.content) continue;
 
-      const successFlows = mdq(record.content).query('section(~"Successful Flow")').text();
-      const succeeded = mdq(record.content).query('section(~"SUCCEEDED")').text();
-      let combined = [successFlows, succeeded].filter(Boolean).join('\n\n');
+      const flows = mdq(record.content).query('section(~"FLOW:")').text();
+      const actions = mdq(record.content).query('section(~"ACTION:")').text();
+      let combined = [flows, actions].filter(Boolean).join('\n\n');
 
       if (!combined.trim()) continue;
 
+      combined = renderAsHowTo(combined);
+
       if (options?.stripCode) {
         combined = mdq(combined).query('code').replace('');
       }
@@ -383,6 +382,72 @@ ${filteredCode}
     }
     return null;
   }
+
+  listAllExperienceToc(filter?: string, options?: { recency?: 'recent' | 'old' }): ExperienceTocEntry[] {
+    const records = this.getAllExperience();
+    if (records.length === 0) return [];
+
+    const trimmed = filter?.trim();
+    let matching = records;
+
+    if (trimmed) {
+      if (trimmed.endsWith('.md')) {
+        const bare = trimmed.slice(0, -3);
+        const byFilename = records.find((record) => basename(record.filePath, '.md') === bare);
+        matching = byFilename ? [byFilename] : [];
+      } else {
+        const lower = trimmed.toLowerCase();
+        matching = records.filter((record) => {
+          const url = ((record.data as WebPageState)?.url || '').toLowerCase();
+          if (!url) return false;
+          return url.includes(lower);
+        });
+      }
+    }
+
+    if (options?.recency) {
+      const cutoff = Date.now() - RECENT_WINDOW_DAYS * 24 * 60 * 60 * 1000;
+      matching = matching.filter((record) => {
+        const isRecent = record.mtime.getTime() >= cutoff;
+        return options.recency === 'recent' ? isRecent : !isRecent;
+      });
+    }
+
+    const sorted = matching.sort((a, b) => {
+      const aUrl = (a.data as WebPageState)?.url || '';
+      const bUrl = (b.data as WebPageState)?.url || '';
+      return aUrl.localeCompare(bUrl);
+    });
+
+    const toc: ExperienceTocEntry[] = [];
+    for (let i = 0; i < sorted.length; i++) {
+      const record = sorted[i];
+      const sections = listTocHeadings(record.content);
+      if (sections.length === 0) continue;
+      toc.push({
+        fileTag: indexToLetters(toc.length),
+        fileHash: basename(record.filePath, '.md'),
+        url: (record.data as WebPageState)?.url || '',
+        sections,
+      });
+    }
+    return toc;
+  }
+
+  getExperienceSectionByTag(fileTag: string, sectionIndex: number, filter?: string): { title: string; url: string; content: string; fileHash: string } | null {
+    const toc = this.listAllExperienceToc(filter);
+    const entry = toc.find((e) => e.fileTag === fileTag);
+    if (!entry) return null;
+
+    const filePath = this.findExperienceFileByHash(entry.fileHash);
+    if (!filePath) return null;
+
+    const { content } = this.readExperienceFile(entry.fileHash);
+    const extracted = extractHeadingSection(content, sectionIndex);
+    if (!extracted) return null;
+
+    return { title: extracted.title, url: entry.url, content: extracted.body, fileHash: entry.fileHash };
+  }
 }
 
 function listTocHeadings(content: string): { index: number; level: 2 | 3; title: string }[] {
@@ -448,7 +513,9 @@ export function renderExperienceToc(toc: ExperienceTocEntry[]): string {
 
   const lines: string[] = [];
   lines.push('<experience>');
-  lines.push('Past experience for this page. Call learn_experience({ fileTag, sectionIndex }) to read a section.');
+  lines.push('Past experience for this page — reusable recipes recorded from prior successful runs.');
+  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('');
   for (const entry of toc) {
     lines.push(`File ${entry.fileTag} ${entry.url}:`);
@@ -462,6 +529,95 @@ export function renderExperienceToc(toc: ExperienceTocEntry[]): string {
   return lines.join('\n');
 }
 
+function normalizeTitle(raw: string): string {
+  let t = (raw || '').trim();
+  for (const p of ['FLOW:', 'ACTION:']) {
+    if (t.toLowerCase().startsWith(p.toLowerCase())) {
+      t = t.slice(p.length).trim();
+      break;
+    }
+  }
+  while (t.length > 0 && '.!?,;:'.includes(t[t.length - 1])) {
+    t = t.slice(0, -1);
+  }
+  if (t.length > 0) t = t[0].toLowerCase() + t.slice(1);
+  return t;
+}
+
+function generateActionContent(title: string, code: string, explanation?: string): string {
+  const lines: string[] = [];
+  lines.push(`## ACTION: ${title}`);
+  lines.push('');
+  if (explanation) {
+    lines.push(`Solution: ${explanation}`);
+    lines.push('');
+  }
+  lines.push('```javascript');
+  lines.push(code);
+  lines.push('```');
+  lines.push('');
+  return lines.join('\n');
+}
+
+function generateFlowContent(title: string, steps: SessionStep[]): string {
+  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: string): string {
+  const tokens = marked.lexer(content);
+  let result = '';
+  for (const token of tokens) {
+    if (token.type === 'heading' && (token as Tokens.Heading).depth === 2) {
+      const text = (token as Tokens.Heading).text.trim();
+      if (text.startsWith('FLOW:')) {
+        result += `## HOW to ${text.slice(5).trim()} (multi-step)\n\n`;
+        continue;
+      }
+      if (text.startsWith('ACTION:')) {
+        result += `## HOW to ${text.slice(7).trim()} (single-step)\n\n`;
+        continue;
+      }
+    }
+    result += (token as any).raw || '';
+  }
+  return result;
+}
+
+export interface ExperienceFile {
+  filePath: string;
+  data: { url?: string; title?: string; [key: string]: any };
+  content: string;
+  mtime: Date;
+}
+
+export interface FlowInput {
+  scenario: string;
+  steps: SessionStep[];
+  relatedUrls?: string[];
+}
+
+export interface ActionInput {
+  title: string;
+  code: string;
+  explanation?: string;
+}
+
 export interface SessionStep {
   message: string;
   status: 'passed' | 'failed' | 'neutral';
@@ -470,13 +626,6 @@ export interface SessionStep {
   discovery?: string;
 }
 
-export interface SessionExperienceEntry {
-  scenario: string;
-  result: 'success' | 'partial' | 'failed';
-  steps: SessionStep[];
-  relatedUrls?: string[];
-}
-
 export interface ExperienceTocEntry {
   fileTag: string;
   fileHash: string;

package/src/explorbot.ts

@@ -1,9 +1,6 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { ActionResult } from './action-result.ts';
-import { ApiClient } from './api/api-client.ts';
-import { RequestStore } from './api/request-store.ts';
-import { loadSpec } from './api/spec-reader.ts';
 import { Bosun } from './ai/bosun.ts';
 import { Captain } from './ai/captain.ts';
 import { ExperienceCompactor } from './ai/experience-compactor.ts';
@@ -14,16 +11,20 @@ import { Pilot } from './ai/pilot.ts';
 import { Planner } from './ai/planner.ts';
 import { AIProvider } from './ai/provider.ts';
 import { Quartermaster } from './ai/quartermaster.ts';
-import { Researcher } from './ai/researcher.ts';
 import { Rerunner } from './ai/rerunner.ts';
+import { Researcher } from './ai/researcher.ts';
 import { Tester } from './ai/tester.ts';
 import { createAgentTools } from './ai/tools.ts';
+import { ApiClient } from './api/api-client.ts';
+import { RequestStore } from './api/request-store.ts';
+import { loadSpec } from './api/spec-reader.ts';
 import type { ExplorbotConfig } from './config.js';
 import { ConfigParser } from './config.ts';
+import { ExperienceTracker } from './experience-tracker.ts';
 import Explorer from './explorer.ts';
-import type { Suite } from './suite.ts';
 import { KnowledgeTracker } from './knowledge-tracker.ts';
 import { WebPageState } from './state-manager.ts';
+import type { Suite } from './suite.ts';
 import { Plan } from './test-plan.ts';
 import { setVerboseMode, tag } from './utils/logger.ts';
 import { sanitizeFilename } from './utils/strings.ts';
@@ -51,6 +52,7 @@ export class ExplorBot {
   public needsInput = false;
   private currentPlan?: Plan;
   private planFeature?: string;
+  lastPlanError: Error | null = null;
   private agents: Record<string, any> = {};
 
   constructor(options: ExplorBotOptions = {}) {
@@ -76,13 +78,11 @@ export class ExplorBot {
     }
 
     try {
-      this.config = await this.configParser.loadConfig(this.options);
-      this.provider = new AIProvider(this.config.ai);
-      await this.provider.validateConnection();
+      await this.startProviderOnly();
       this.explorer = new Explorer(this.config, this.provider, this.options);
       await this.explorer.start();
       if (!this.options.incognito) {
-        await this.agentExperienceCompactor().compactAllExperiences();
+        await this.agentExperienceCompactor().autocompact();
       }
       if (this.userResolveFn) this.explorer.setUserResolve(this.userResolveFn);
     } catch (error) {
@@ -92,9 +92,16 @@ export class ExplorBot {
     }
   }
 
+  async startProviderOnly(): Promise<void> {
+    if (this.provider) return;
+    this.config = await this.configParser.loadConfig(this.options);
+    this.provider = new AIProvider(this.config.ai);
+    await this.provider.validateConnection();
+  }
+
   async stop(): Promise<void> {
     this.agents.quartermaster?.stop();
-    await this.explorer.stop();
+    await this.explorer?.stop();
   }
 
   async visitInitialState(): Promise<void> {
@@ -125,6 +132,13 @@ export class ExplorBot {
     return new KnowledgeTracker();
   }
 
+  getExperienceTracker(): ExperienceTracker {
+    if (this.explorer) {
+      return this.explorer.getStateManager().getExperienceTracker();
+    }
+    return new ExperienceTracker();
+  }
+
   getConfig(): ExplorbotConfig {
     return this.config;
   }
@@ -227,10 +241,7 @@ export class ExplorBot {
   }
 
   agentExperienceCompactor(): ExperienceCompactor {
-    return (this.agents.experienceCompactor ||= this.createAgent(({ ai, explorer }) => {
-      const experienceTracker = explorer.getStateManager().getExperienceTracker();
-      return new ExperienceCompactor(ai, experienceTracker);
-    }));
+    return (this.agents.experienceCompactor ||= new ExperienceCompactor(this.provider, this.getExperienceTracker()));
   }
 
   agentQuartermaster(): Quartermaster | null {
@@ -348,10 +359,12 @@ export class ExplorBot {
     if (this.currentPlan) {
       planner.setPlan(this.currentPlan);
     }
+    this.lastPlanError = null;
     try {
       this.currentPlan = await planner.plan(feature, opts.style, opts.extend, opts.completedPlans);
     } catch (err) {
-      tag('warning').log(`Planning failed: ${err instanceof Error ? err.message : err}`);
+      this.lastPlanError = err instanceof Error ? err : new Error(String(err));
+      tag('warning').log(`Planning failed: ${this.lastPlanError.message}`);
       if (!this.currentPlan) return undefined;
       return this.currentPlan;
     }

package/src/explorer.ts

@@ -9,6 +9,8 @@ import { ActionResult } from './action-result.ts';
 import Action from './action.js';
 import { AIProvider } from './ai/provider.js';
 import { visuallyAnnotateContainers } from './ai/researcher/coordinates.ts';
+import { RequestStore } from './api/request-store.ts';
+import { XhrCapture } from './api/xhr-capture.ts';
 import type { ExplorbotConfig } from './config.js';
 import { ConfigParser, outputPath } from './config.js';
 import type { UserResolveFunction } from './explorbot.js';
@@ -16,8 +18,6 @@ import { KnowledgeTracker } from './knowledge-tracker.js';
 import { Reporter } from './reporter.ts';
 import { StateManager } from './state-manager.js';
 import { Test } from './test-plan.ts';
-import { RequestStore } from './api/request-store.ts';
-import { XhrCapture } from './api/xhr-capture.ts';
 import { createDebug, log, tag } from './utils/logger.js';
 import { WebElement, extractElementData } from './utils/web-element.ts';
 
@@ -68,7 +68,7 @@ class Explorer {
     this.initializeContainer();
     this.stateManager = new StateManager({ incognito: this.options?.incognito });
     this.knowledgeTracker = new KnowledgeTracker();
-    this.reporter = new Reporter(config.reporter);
+    this.reporter = new Reporter(config.reporter, this.stateManager);
   }
 
   private initializeContainer() {