explorbot 0.1.32-beta.1 → 0.2.0

package/src/ai/provider.ts

@@ -11,7 +11,7 @@ import { Stats } from '../stats.ts';
 import { createDebug, tag } from '../utils/logger.js';
 import { type RetryOptions, withRetry } from '../utils/retry.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
-import { Conversation } from './conversation.js';
+import { Conversation, toToolExecution } from './conversation.js';
 
 const debugLog = createDebug('explorbot:provider');
 const promptLog = createDebug('explorbot:provider:out');
@@ -22,6 +22,8 @@ export class ContextLengthError extends Error {}
 
 let telemetryRegistered = false;
 
+const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
+
 function extractCachedTokens(usage: any): number {
   if (!usage) return 0;
   const direct = usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens;
@@ -31,10 +33,10 @@ function extractCachedTokens(usage: any): number {
   return typeof fromRaw === 'number' ? fromRaw : 0;
 }
 
-function rejectAfterIdle(ms: number, signal: { cancelled: boolean }, controller: AbortController): Promise<never> {
+function abortAfterIdle(ms: number, cancel: { cancelled: boolean }, controller: AbortController): Promise<never> {
   return new Promise((_, reject) => {
     const tick = () => {
-      if (signal.cancelled) return;
+      if (cancel.cancelled) return;
       if (executionController.isAwaitingInput()) {
         setTimeout(tick, ms);
         return;
@@ -46,6 +48,12 @@ function rejectAfterIdle(ms: number, signal: { cancelled: boolean }, controller:
   });
 }
 
+function combinedAbortSignal(controller: AbortController): AbortSignal {
+  const executionSignal = executionController.getAbortSignal();
+  if (!executionSignal) return controller.signal;
+  return AbortSignal.any([controller.signal, executionSignal]);
+}
+
 export class Provider {
   private config: AIConfig;
   private telemetryEnabled = false;
@@ -70,7 +78,6 @@ export class Provider {
     },
   };
 
-  static readonly CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
   lastConversation: Conversation | null = null;
 
   constructor(config: AIConfig) {
@@ -138,12 +145,12 @@ export class Provider {
     return parts.length > 0 ? parts.join('\n\n') : undefined;
   }
 
-  getProviderOptionsForAgent(agentName: string): Record<string, any> | undefined {
+  private getProviderOptionsForAgent(agentName: string): Record<string, any> | undefined {
     const agentConfig = this.config.agents?.[agentName as keyof typeof this.config.agents];
     return agentConfig?.providerOptions;
   }
 
-  getReasoningForAgent(agentName?: string): string | undefined {
+  private getReasoningForAgent(agentName?: string): string | undefined {
     if (!agentName) return undefined;
     const agentConfig = this.config.agents?.[agentName as keyof typeof this.config.agents];
     return agentConfig?.reasoning;
@@ -172,6 +179,50 @@ export class Provider {
     if (reasoning) config.reasoning ??= reasoning;
   }
 
+  private buildGenerateConfig(defaults: Record<string, any>, overrides: Record<string, any>, options: any): Record<string, any> {
+    const telemetry = this.getTelemetry(options);
+    const config = this.mergeProviderOptions(
+      {
+        ...defaults,
+        allowSystemInMessages: true,
+        ...(this.config.config || {}),
+        ...options,
+        ...overrides,
+      },
+      options.agentName
+    );
+    this.finalizeConfig(config, options, telemetry);
+    return config;
+  }
+
+  private recordUsage(agentName: string, modelName: string, usage: any): void {
+    if (!usage) return;
+    Stats.recordTokens(agentName, modelName, {
+      input: usage.inputTokens ?? usage.promptTokens ?? 0,
+      output: usage.outputTokens ?? usage.completionTokens ?? 0,
+      total: usage.totalTokens ?? 0,
+      cached: extractCachedTokens(usage),
+    });
+  }
+
+  private async raceWithIdleTimeout<T>(fn: (signal: AbortSignal) => Promise<T>, timeoutMs: number): Promise<T> {
+    const cancel = { cancelled: false };
+    const controller = new AbortController();
+    const combinedSignal = combinedAbortSignal(controller);
+    try {
+      return await Promise.race([fn(combinedSignal), abortAfterIdle(timeoutMs, cancel, controller)]);
+    } finally {
+      cancel.cancelled = true;
+    }
+  }
+
+  private async recoverFromContextLength(error: any, messages: ModelMessage[], options: any, retry: (messages: ModelMessage[], options: any) => Promise<any>): Promise<any> {
+    const reduced = this.tryReduceMessages(messages, options._contextRetryLevel || 0);
+    if (!reduced) throw new ContextLengthError(error.message || error.toString());
+    tag('warning').log('Context length exceeded, retrying with reduced messages...');
+    return retry(reduced.messages, { ...options, _contextRetryLevel: reduced.nextLevel });
+  }
+
   private initLangfuse() {
     const langfuseConfig = this.config.langfuse;
     const publicKey = langfuseConfig?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
@@ -207,20 +258,25 @@ export class Provider {
 
     const runTelemetry = Observability.getTelemetry();
 
-    if (!options.telemetry) {
+    let optionTelemetry = options.telemetry;
+    if (options.telemetryFunctionId && !optionTelemetry?.functionId) {
+      optionTelemetry = { ...optionTelemetry, functionId: options.telemetryFunctionId };
+    }
+
+    if (!optionTelemetry) {
       return runTelemetry;
     }
 
     if (!runTelemetry) {
-      return options.telemetry;
+      return optionTelemetry;
     }
 
     return {
       ...runTelemetry,
-      ...options.telemetry,
+      ...optionTelemetry,
       metadata: {
         ...runTelemetry.metadata,
-        ...options.telemetry.metadata,
+        ...optionTelemetry.metadata,
       },
     };
   }
@@ -254,12 +310,8 @@ export class Provider {
     const toolCalls = response.toolCalls || [];
     const toolResults = response.toolResults || [];
 
-    const toolExecutions = toolCalls.map((call: any, index: number) => ({
-      toolName: call.toolName || '',
-      input: call.input,
-      output: toolResults[index]?.output,
-      wasSuccessful: toolResults[index]?.output?.success || false,
-    }));
+    const resultsById = new Map(toolResults.map((r: any) => [r.toolCallId, r]));
+    const toolExecutions = toolCalls.map((call: any) => toToolExecution(call.toolName || '', call.input, resultsById.get(call.toolCallId)?.output));
 
     return { conversation, response, toolExecutions };
   }
@@ -269,19 +321,7 @@ export class Provider {
     setActivity(`🤖 Asking ${modelName}`, 'ai');
     promptLog(`Using model: ${modelName}`);
 
-    const telemetry = this.getTelemetry(options);
-    const config = this.mergeProviderOptions(
-      {
-        maxOutputTokens: 16384,
-        allowSystemInMessages: true,
-        ...(this.config.config || {}),
-        ...options,
-        model,
-        abortSignal: executionController.getAbortSignal(),
-      },
-      options.agentName
-    );
-    this.finalizeConfig(config, options, telemetry);
+    const config = this.buildGenerateConfig({ maxOutputTokens: 16384 }, { model, abortSignal: executionController.getAbortSignal() }, options);
 
     promptLog(messages[messages.length - 1].content);
     try {
@@ -303,14 +343,7 @@ export class Provider {
       clearActivity();
       responseLog(response.text);
 
-      if (response.usage) {
-        Stats.recordTokens(options.agentName || 'unknown', modelName, {
-          input: response.usage.inputTokens ?? response.usage.promptTokens ?? 0,
-          output: response.usage.outputTokens ?? response.usage.completionTokens ?? 0,
-          total: response.usage.totalTokens ?? 0,
-          cached: extractCachedTokens(response.usage),
-        });
-      }
+      this.recordUsage(options.agentName || 'unknown', modelName, response.usage);
 
       return response;
     } catch (error: any) {
@@ -318,12 +351,7 @@ export class Provider {
       if (error?.name === 'AbortError') throw error;
       if (error instanceof ContextLengthError) throw error;
       if (Provider.isContextLengthError(error)) {
-        const reduced = this.tryReduceMessages(messages, options._contextRetryLevel || 0);
-        if (reduced) {
-          tag('warning').log('Context length exceeded, retrying with reduced messages...');
-          return this.chat(reduced.messages, model, { ...options, _contextRetryLevel: reduced.nextLevel });
-        }
-        throw new ContextLengthError(error.message || error.toString());
+        return this.recoverFromContextLength(error, messages, options, (m, o) => this.chat(m, model, o));
       }
       const message = error.message || error.toString();
       if (message !== 'No response text from AI') {
@@ -343,50 +371,19 @@ export class Provider {
     promptLog('Available tools:', toolNames);
     promptLog(messages[messages.length - 1].content);
 
-    const telemetry = this.getTelemetry(options);
     const maxRoundtrips = options.maxToolRoundtrips ?? 5;
     const extraStop = options.stopWhen;
     const stopConditions: any[] = [isStepCount(maxRoundtrips)];
     if (extraStop) stopConditions.push(extraStop);
-    const { stopWhen: _ignoredStopWhen, ...optionsWithoutStop } = options;
-    const config = this.mergeProviderOptions(
-      {
-        tools,
-        maxOutputTokens: 16384,
-        toolChoice: 'auto',
-        allowSystemInMessages: true,
-        ...(this.config.config || {}),
-        ...optionsWithoutStop,
-        stopWhen: stopConditions,
-        model,
-        abortSignal: executionController.getAbortSignal(),
-      },
-      options.agentName
-    );
-    this.finalizeConfig(config, options, telemetry);
+    const config = this.buildGenerateConfig({ tools, maxOutputTokens: 16384, toolChoice: 'auto' }, { stopWhen: stopConditions, model }, options);
     try {
       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) as AbortSignal[]);
-        try {
-          const result = (await Promise.race([
-            generateText({
-              messages,
-              ...config,
-              abortSignal: combinedSignal,
-            }),
-            rejectAfterIdle(timeout, cancel, controller),
-          ])) as any;
-          const hasToolCall = (result.toolCalls?.length || 0) > 0;
-          if (!result.text && !hasToolCall && result.finishReason === 'length') {
-            throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
-          }
-          return result;
-        } finally {
-          cancel.cancelled = true;
+        const result = (await this.raceWithIdleTimeout((signal) => generateText({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
+        const hasToolCall = (result.toolCalls?.length || 0) > 0;
+        if (!result.text && !hasToolCall && result.finishReason === 'length') {
+          throw new ContextLengthError('AI response empty: output truncated at maxTokens. Increase maxOutputTokens in config or use a model with higher output capacity.');
         }
+        return result;
       }, this.getRetryOptions(options));
 
       clearActivity();
@@ -401,14 +398,7 @@ export class Provider {
 
       responseLog(response.text);
 
-      if (response.usage) {
-        Stats.recordTokens(options.agentName || 'unknown', modelName, {
-          input: response.usage.inputTokens ?? response.usage.promptTokens ?? 0,
-          output: response.usage.outputTokens ?? response.usage.completionTokens ?? 0,
-          total: response.usage.totalTokens ?? 0,
-          cached: extractCachedTokens(response.usage),
-        });
-      }
+      this.recordUsage(options.agentName || 'unknown', modelName, response.usage);
 
       return response;
     } catch (error: any) {
@@ -419,12 +409,7 @@ export class Provider {
       if (error?.name === 'AbortError') throw error;
       if (error instanceof ContextLengthError) throw error;
       if (Provider.isContextLengthError(error)) {
-        const reduced = this.tryReduceMessages(messages, options._contextRetryLevel || 0);
-        if (reduced) {
-          tag('warning').log('Context length exceeded, retrying with reduced messages...');
-          return this.generateWithTools(reduced.messages, model, tools, { ...options, _contextRetryLevel: reduced.nextLevel });
-        }
-        throw new ContextLengthError(error.message || error.toString());
+        return this.recoverFromContextLength(error, messages, options, (m, o) => this.generateWithTools(m, model, tools, o));
       }
       if (error.constructor?.name === 'AI_APICallError') {
         responseLog(error.message);
@@ -440,52 +425,18 @@ export class Provider {
     setActivity(`🤖 Asking ${modelName} for structured output`, 'ai');
     promptLog(`Using model: ${modelName}`);
 
-    const telemetry = this.getTelemetry(options);
-    const config = this.mergeProviderOptions(
-      {
-        schema,
-        allowSystemInMessages: true,
-        ...(this.config.config || {}),
-        ...options,
-        model: modelToUse,
-        abortSignal: executionController.getAbortSignal(),
-      },
-      options.agentName
-    );
-    this.finalizeConfig(config, options, telemetry);
+    const config = this.buildGenerateConfig({ schema }, { model: modelToUse }, options);
 
     try {
       promptLog(messages[messages.length - 1].content);
       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) as AbortSignal[]);
-        try {
-          return (await Promise.race([
-            generateObject({
-              messages,
-              ...config,
-              abortSignal: combinedSignal,
-            }),
-            rejectAfterIdle(timeout, cancel, controller),
-          ])) as any;
-        } finally {
-          cancel.cancelled = true;
-        }
+        return (await this.raceWithIdleTimeout((signal) => generateObject({ messages, ...config, abortSignal: signal }), config.timeout || 30000)) as any;
       }, this.getRetryOptions(options));
 
       clearActivity();
       responseLog(response.object);
 
-      if (response.usage) {
-        Stats.recordTokens(options.agentName || 'unknown', modelName, {
-          input: response.usage.inputTokens ?? response.usage.promptTokens ?? 0,
-          output: response.usage.outputTokens ?? response.usage.completionTokens ?? 0,
-          total: response.usage.totalTokens ?? 0,
-          cached: extractCachedTokens(response.usage),
-        });
-      }
+      this.recordUsage(options.agentName || 'unknown', modelName, response.usage);
 
       return response;
     } catch (error: any) {
@@ -493,12 +444,7 @@ export class Provider {
       if (error?.name === 'AbortError') throw error;
       if (error instanceof ContextLengthError) throw error;
       if (Provider.isContextLengthError(error)) {
-        const reduced = this.tryReduceMessages(messages, options._contextRetryLevel || 0);
-        if (reduced) {
-          tag('warning').log('Context length exceeded, retrying with reduced messages...');
-          return this.generateObject(reduced.messages, schema, model, { ...options, _contextRetryLevel: reduced.nextLevel });
-        }
-        throw new ContextLengthError(error.message || error.toString());
+        return this.recoverFromContextLength(error, messages, options, (m, o) => this.generateObject(m, schema, model, o));
       }
       throw new AiError(error.message || error.toString());
     }
@@ -506,7 +452,7 @@ export class Provider {
 
   static isContextLengthError(error: any): boolean {
     const msg = (error?.message || error?.toString() || '').toLowerCase();
-    return Provider.CONTEXT_LENGTH_PATTERNS.some((p) => msg.includes(p));
+    return CONTEXT_LENGTH_PATTERNS.some((p) => msg.includes(p));
   }
 
   static trimMessagesForRetry(messages: ModelMessage[]): ModelMessage[] | null {
@@ -677,13 +623,7 @@ export class Provider {
       clearActivity();
       responseLog(response.text);
 
-      if (response.usage) {
-        Stats.recordTokens('vision', this.getModelName(this.config.visionModel), {
-          input: response.usage.inputTokens ?? response.usage.promptTokens ?? 0,
-          output: response.usage.outputTokens ?? response.usage.completionTokens ?? 0,
-          total: response.usage.totalTokens ?? 0,
-        });
-      }
+      this.recordUsage('vision', this.getModelName(this.config.visionModel), response.usage);
 
       return response;
     } catch (error: any) {

package/src/ai/quartermaster.ts

@@ -1,8 +1,8 @@
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { z } from 'zod';
 import type { ActionResult } from '../action-result.ts';
-import { ConfigParser } from '../config.ts';
+import { outputPath } from '../config.ts';
 import type { StateManager, StateTransition, WebPageState } from '../state-manager.ts';
 import type { Task } from '../test-plan.ts';
 import { createDebug, tag } from '../utils/logger.ts';
@@ -12,36 +12,6 @@ import type { Provider } from './provider.ts';
 
 const debugLog = createDebug('explorbot:quartermaster');
 
-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 class Quartermaster {
   private provider: Provider;
   private model?: any;
@@ -55,13 +25,12 @@ export class Quartermaster {
     this.provider = provider;
     this.model = options?.model;
 
-    const configParser = ConfigParser.getInstance();
-    this.outputDir = join(configParser.getOutputDir(), 'a11y');
+    this.outputDir = outputPath('a11y');
   }
 
   start(playwrightHelper: any, stateManager: StateManager): void {
     this.playwrightHelper = playwrightHelper;
-    this.ensureDirectory();
+    mkdirSync(this.outputDir, { recursive: true });
 
     this.unsubscribe = stateManager.onStateChange((event) => {
       this.onPageChange(event);
@@ -78,12 +47,6 @@ export class Quartermaster {
     debugLog('Quartermaster stopped');
   }
 
-  private ensureDirectory(): void {
-    if (!existsSync(this.outputDir)) {
-      mkdirSync(this.outputDir, { recursive: true });
-    }
-  }
-
   private onPageChange(event: StateTransition): void {
     const state = event.toState;
     if (!state?.hash) return;
@@ -284,3 +247,33 @@ Focus on what would confuse a real user or caused the agent to make mistakes.`;
     return content;
   }
 }
+
+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[];
+}

package/src/ai/rerunner.ts

@@ -17,10 +17,10 @@ import type Explorer from '../explorer.ts';
 import type { KnowledgeTracker } from '../knowledge-tracker.ts';
 import { Stats } from '../stats.ts';
 import { Task, Test, TestResult } from '../test-plan.ts';
+import { formatHeadings } from '../utils/context-formatter.ts';
 import { createDebug, tag } from '../utils/logger.ts';
 import { loop } from '../utils/loop.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
-import { loadTestSuites, printTestList } from '../utils/test-files.ts';
 import type { Agent } from './agent.ts';
 import { toolExecutionLabel } from './conversation.ts';
 import type { Navigator } from './navigator.ts';
@@ -38,8 +38,9 @@ export class Rerunner extends TaskAgent implements Agent {
   private explorer: Explorer;
   private provider: Provider;
   private agentTools: any;
-  private healedSteps: Array<{ test: string; original: string; healed: string }> = [];
+  private healedSteps: Array<{ original: string; healed: string }> = [];
   private traceDir = '';
+  private static pluginsWired = false;
 
   constructor(explorer: Explorer, provider: Provider, agentTools?: any) {
     super();
@@ -76,10 +77,6 @@ export class Rerunner extends TaskAgent implements Agent {
     return this.rerunnerConfig.healMaxIterations ?? 3;
   }
 
-  listTests(testsDir: string): void {
-    printTestList(loadTestSuites(testsDir));
-  }
-
   async rerun(filePath: string, options?: { testIndices?: number[] }): Promise<RerunResult> {
     const absPath = resolve(filePath);
     if (!existsSync(absPath)) {
@@ -219,7 +216,6 @@ export class Rerunner extends TaskAgent implements Agent {
 
   private setupPlugins(): void {
     const healMod = heal.default || heal;
-    healMod.connectToEvents();
 
     healMod.addRecipe('explorbot-ai-healer', {
       priority: 10,
@@ -233,21 +229,29 @@ export class Rerunner extends TaskAgent implements Agent {
       healMod.addRecipe(name, recipe);
     }
 
+    const outputDir = (global as any).output_dir || 'output';
+    this.traceDir = `${outputDir}/rerun-traces`;
+
+    if (Rerunner.pluginsWired) return;
+    Rerunner.pluginsWired = true;
+
+    healMod.connectToEvents();
+
     let currentTest: any = null;
     let healTries = 0;
     let isHealing = false;
     let caughtError: any = null;
-    const healLimit = this.healLimit;
 
     codeceptjs.event.dispatcher.on('test.before', (test: any) => {
       currentTest = test;
       healTries = 0;
       caughtError = null;
+      isHealing = false;
     });
 
     codeceptjs.event.dispatcher.on('step.after', (step: any) => {
       if (isHealing) return;
-      if (healTries >= healLimit) return;
+      if (healTries >= this.healLimit) return;
       if (!healMod.hasCorrespondingRecipes(step)) return;
 
       codeceptjs.recorder.catchWithoutStop(async (err: any) => {
@@ -286,10 +290,6 @@ export class Rerunner extends TaskAgent implements Agent {
       factor: 1.5,
     });
 
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
-    const outputDir = (global as any).output_dir || 'output';
-    this.traceDir = `${outputDir}/rerun_${timestamp}`;
-
     const aiTrace = aiTracePlugin.default || aiTracePlugin;
     aiTrace(this.rerunnerConfig.aiTrace || { output: this.traceDir });
 
@@ -303,9 +303,9 @@ export class Rerunner extends TaskAgent implements Agent {
 
   private teardownHealing(): void {
     const healMod = heal.default || heal;
-    healMod.recipes['explorbot-ai-healer'] = undefined;
+    Reflect.deleteProperty(healMod.recipes, 'explorbot-ai-healer');
     for (const name of Object.keys(this.rerunnerConfig.recipes || {})) {
-      healMod.recipes[name] = undefined;
+      Reflect.deleteProperty(healMod.recipes, name);
     }
   }
 
@@ -432,7 +432,7 @@ export class Rerunner extends TaskAgent implements Agent {
         throw new Error(`Could not heal: ${failedCode}`);
       }
 
-      this.healedSteps.push({ test: '', original: failedCode, healed: healedCommand });
+      this.healedSteps.push({ original: failedCode, healed: healedCommand });
       console.log(chalk.green(`    ${figureSet.tick} Healed: ${healedCommand}`));
     };
   }
@@ -477,11 +477,7 @@ export class Rerunner extends TaskAgent implements Agent {
     const state = this.explorer.getStateManager().getCurrentState();
     const actionResult = state ? ActionResult.fromState(state) : null;
 
-    const headings: string[] = [];
-    if (state?.h1) headings.push(`H1: ${state.h1}`);
-    if (state?.h2) headings.push(`H2: ${state.h2}`);
-    if (state?.h3) headings.push(`H3: ${state.h3}`);
-    if (state?.h4) headings.push(`H4: ${state.h4}`);
+    const headings = formatHeadings(state || {});
 
     return dedent`
       A test step failed and needs healing.

package/src/ai/researcher/cache.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'no
 import { join } from 'node:path';
 import { Worker } from 'node:worker_threads';
 import { outputPath } from '../../config.ts';
+import { TTLCache } from '../../utils/cache.ts';
 import { computeHtmlFingerprint } from '../../utils/html-diff.ts';
 import { debugLog } from './mixin.ts';
 
@@ -10,8 +11,7 @@ const FINGERPRINT_MAX_AGE_MS = 60 * 60 * 1000; // 1 hour
 const FINGERPRINT_WORKER_TIMEOUT_MS = 10_000;
 const SIMILARITY_THRESHOLD = 90;
 
-const memoryCache: Record<string, string> = {};
-const memoryCacheTimestamps: Record<string, number> = {};
+const memoryCache = new TTLCache<string>(CACHE_TTL_MS);
 
 let fingerprintWorker: Worker | null = null;
 
@@ -28,25 +28,20 @@ function getFingerprintWorker(): Worker {
 }
 
 export function clearResearchCache(): void {
-  for (const key of Object.keys(memoryCache)) delete memoryCache[key];
-  for (const key of Object.keys(memoryCacheTimestamps)) delete memoryCacheTimestamps[key];
+  memoryCache.clear();
 }
 
 export function getCachedResearch(hash: string): string {
   if (!hash) return '';
-  const now = Date.now();
-  const timestamp = memoryCacheTimestamps[hash];
-  if (timestamp && now - timestamp <= CACHE_TTL_MS) {
-    return memoryCache[hash] || '';
-  }
+  const cached = memoryCache.get(hash);
+  if (cached !== undefined) return cached;
   const researchFile = outputPath('research', `${hash}.md`);
   if (!existsSync(researchFile)) return '';
   const stats = statSync(researchFile);
-  if (now - stats.mtimeMs > CACHE_TTL_MS) return '';
-  const cached = readFileSync(researchFile, 'utf8');
-  memoryCache[hash] = cached;
-  memoryCacheTimestamps[hash] = now;
-  return cached;
+  if (Date.now() - stats.mtimeMs > CACHE_TTL_MS) return '';
+  const fromDisk = readFileSync(researchFile, 'utf8');
+  memoryCache.set(hash, fromDisk);
+  return fromDisk;
 }
 
 export function getPreviousResearch(hash: string): string {
@@ -61,8 +56,7 @@ export function saveResearch(hash: string, text: string, combinedHtml?: string):
   const researchFile = join(researchDir, `${hash}.md`);
   if (!existsSync(researchDir)) mkdirSync(researchDir, { recursive: true });
   writeFileSync(researchFile, text);
-  memoryCache[hash] = text;
-  memoryCacheTimestamps[hash] = Date.now();
+  memoryCache.set(hash, text);
   debugLog(`Research saved to ${researchFile}`);
 
   if (combinedHtml) {