@plures/runebook 0.4.0

package/src/lib/agent/analysis-pipeline.ts

@@ -0,0 +1,347 @@
+// Analysis Pipeline - Background job system for failure analysis
+// Runs analyzers in layers: heuristic → local search → optional LLM/MCP
+
+import type { TerminalObserverEvent, EventStore } from '../core/types';
+import type { Suggestion } from '../types/agent';
+
+/**
+ * Extended suggestion with confidence, actionable snippet, and provenance
+ */
+export interface AnalysisSuggestion extends Suggestion {
+  confidence: number; // 0.0 to 1.0
+  actionableSnippet?: string; // Code snippet or command to fix the issue
+  provenance: {
+    analyzer: string; // Which analyzer produced this
+    layer: number; // Which layer (1, 2, or 3)
+    timestamp: number;
+  };
+}
+
+/**
+ * Analysis job context
+ */
+export interface AnalysisJob {
+  id: string;
+  commandId: string;
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  events: TerminalObserverEvent[]; // Full event context
+  timestamp: number;
+  status: 'pending' | 'running' | 'completed' | 'cancelled' | 'failed';
+  suggestions: AnalysisSuggestion[];
+  error?: string;
+}
+
+/**
+ * Context window for analysis
+ */
+export interface AnalysisContext {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string>;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  previousCommands: Array<{
+    command: string;
+    args: string[];
+    exitCode: number;
+    timestamp: number;
+  }>;
+  repoFiles?: string[]; // Relevant files in the repo
+}
+
+/**
+ * Pluggable analyzer interface
+ */
+export interface Analyzer {
+  name: string;
+  layer: number; // 1, 2, or 3
+  analyze(context: AnalysisContext, store: EventStore): Promise<AnalysisSuggestion[]>;
+}
+
+/**
+ * Job queue for background analysis
+ */
+export class AnalysisJobQueue {
+  private jobs: Map<string, AnalysisJob> = new Map();
+  private running: Set<string> = new Set();
+  private analyzers: Analyzer[] = [];
+  private store: EventStore | null = null;
+  private maxConcurrentJobs = 1;
+  private enableLLM = false; // Gate for LLM/MCP calls
+
+  constructor(store: EventStore | null = null) {
+    this.store = store;
+  }
+
+  /**
+   * Register an analyzer
+   */
+  registerAnalyzer(analyzer: Analyzer): void {
+    this.analyzers.push(analyzer);
+    // Sort by layer
+    this.analyzers.sort((a, b) => a.layer - b.layer);
+  }
+
+  /**
+   * Enable or disable LLM/MCP layer
+   */
+  setLLMEnabled(enabled: boolean): void {
+    this.enableLLM = enabled;
+  }
+
+  /**
+   * Detect failure and enqueue analysis job
+   */
+  async enqueueFailure(
+    commandId: string,
+    events: TerminalObserverEvent[],
+    store: EventStore
+  ): Promise<string | null> {
+    // Find command_start, exit_status, and stderr events
+    const commandStart = events.find(e => e.type === 'command_start' && e.id === commandId);
+    const exitStatus = events.find(e => e.type === 'exit_status' && e.commandId === commandId);
+    const stderrChunks = events
+      .filter(e => e.type === 'stderr_chunk' && 'commandId' in e && e.commandId === commandId)
+      .sort((a, b) => {
+        const aIdx = 'chunkIndex' in a ? a.chunkIndex : 0;
+        const bIdx = 'chunkIndex' in b ? b.chunkIndex : 0;
+        return aIdx - bIdx;
+      });
+    const stdoutChunks = events
+      .filter(e => e.type === 'stdout_chunk' && 'commandId' in e && e.commandId === commandId)
+      .sort((a, b) => {
+        const aIdx = 'chunkIndex' in a ? a.chunkIndex : 0;
+        const bIdx = 'chunkIndex' in b ? b.chunkIndex : 0;
+        return aIdx - bIdx;
+      });
+
+    if (!commandStart || !exitStatus || commandStart.type !== 'command_start' || exitStatus.type !== 'exit_status') {
+      return null;
+    }
+
+    // Check if it's a failure
+    if (exitStatus.success) {
+      return null; // Not a failure
+    }
+
+    // Build context
+    const stderr = stderrChunks
+      .map(e => ('chunk' in e ? e.chunk : ''))
+      .join('');
+    const stdout = stdoutChunks
+      .map(e => ('chunk' in e ? e.chunk : ''))
+      .join('');
+
+    // Get previous commands for context
+    const allEvents = await store.getEvents(undefined, undefined, 50);
+    const previousCommands = allEvents
+      .filter(e => e.type === 'command_start' && e.timestamp < commandStart.timestamp)
+      .slice(-5)
+      .map(e => {
+        if (e.type === 'command_start') {
+          const exit = allEvents.find(
+            ev => ev.type === 'exit_status' && 'commandId' in ev && ev.commandId === e.id
+          );
+          return {
+            command: e.command,
+            args: e.args,
+            exitCode: exit && exit.type === 'exit_status' ? exit.exitCode : 0,
+            timestamp: e.timestamp,
+          };
+        }
+        return null;
+      })
+      .filter((c): c is NonNullable<typeof c> => c !== null);
+
+    const job: AnalysisJob = {
+      id: `job_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
+      commandId,
+      command: commandStart.command,
+      args: commandStart.args,
+      cwd: commandStart.cwd,
+      env: commandStart.envSummary || {},
+      exitCode: exitStatus.exitCode,
+      stdout,
+      stderr,
+      events,
+      timestamp: Date.now(),
+      status: 'pending',
+      suggestions: [],
+    };
+
+    this.jobs.set(job.id, job);
+    this.processQueue(store);
+
+    return job.id;
+  }
+
+  /**
+   * Process the job queue (non-blocking)
+   */
+  private async processQueue(store: EventStore): Promise<void> {
+    if (this.running.size >= this.maxConcurrentJobs) {
+      return;
+    }
+
+    const pendingJob = Array.from(this.jobs.values()).find(j => j.status === 'pending');
+    if (!pendingJob) {
+      return;
+    }
+
+    this.running.add(pendingJob.id);
+    pendingJob.status = 'running';
+
+    // Process in background (non-blocking)
+    this.runAnalysis(pendingJob, store).catch(error => {
+      pendingJob.status = 'failed';
+      pendingJob.error = String(error);
+      this.running.delete(pendingJob.id);
+    });
+  }
+
+  /**
+   * Run analysis on a job (runs analyzers in layers)
+   */
+  private async runAnalysis(job: AnalysisJob, store: EventStore): Promise<void> {
+    try {
+      // Build analysis context
+      const context: AnalysisContext = {
+        command: job.command,
+        args: job.args,
+        cwd: job.cwd,
+        env: job.env,
+        exitCode: job.exitCode,
+        stdout: job.stdout,
+        stderr: job.stderr,
+        previousCommands: await this.getPreviousCommands(job, store),
+      };
+
+      // Run analyzers by layer
+      const suggestions: AnalysisSuggestion[] = [];
+
+      // Layer 1: Heuristic classifiers
+      const layer1Analyzers = this.analyzers.filter(a => a.layer === 1);
+      for (const analyzer of layer1Analyzers) {
+        try {
+          const analyzerSuggestions = await analyzer.analyze(context, store);
+          suggestions.push(...analyzerSuggestions);
+        } catch (error) {
+          console.error(`Analyzer ${analyzer.name} failed:`, error);
+        }
+      }
+
+      // If we have high-confidence suggestions from layer 1, we might skip layer 2
+      const highConfidence = suggestions.filter(s => s.confidence >= 0.8);
+      if (highConfidence.length === 0) {
+        // Layer 2: Local search
+        const layer2Analyzers = this.analyzers.filter(a => a.layer === 2);
+        for (const analyzer of layer2Analyzers) {
+          try {
+            const analyzerSuggestions = await analyzer.analyze(context, store);
+            suggestions.push(...analyzerSuggestions);
+          } catch (error) {
+            console.error(`Analyzer ${analyzer.name} failed:`, error);
+          }
+        }
+      }
+
+      // Layer 3: Optional LLM/MCP (gated)
+      if (this.enableLLM) {
+        const layer3Analyzers = this.analyzers.filter(a => a.layer === 3);
+        for (const analyzer of layer3Analyzers) {
+          try {
+            const analyzerSuggestions = await analyzer.analyze(context, store);
+            suggestions.push(...analyzerSuggestions);
+          } catch (error) {
+            console.error(`Analyzer ${analyzer.name} failed:`, error);
+          }
+        }
+      }
+
+      job.suggestions = suggestions;
+      job.status = 'completed';
+    } catch (error) {
+      job.status = 'failed';
+      job.error = String(error);
+    } finally {
+      this.running.delete(job.id);
+      // Process next job
+      this.processQueue(store);
+    }
+  }
+
+  /**
+   * Get previous commands for context
+   */
+  private async getPreviousCommands(job: AnalysisJob, store: EventStore): Promise<AnalysisContext['previousCommands']> {
+    const events = await store.getEvents(undefined, undefined, 50);
+    const commandStart = job.events.find(e => e.type === 'command_start' && e.id === job.commandId);
+    if (!commandStart) {
+      return [];
+    }
+
+    return events
+      .filter(e => e.type === 'command_start' && e.timestamp < commandStart.timestamp)
+      .slice(-5)
+      .map(e => {
+        if (e.type === 'command_start') {
+          const exit = events.find(
+            ev => ev.type === 'exit_status' && 'commandId' in ev && ev.commandId === e.id
+          );
+          return {
+            command: e.command,
+            args: e.args,
+            exitCode: exit && exit.type === 'exit_status' ? exit.exitCode : 0,
+            timestamp: e.timestamp,
+          };
+        }
+        return null;
+      })
+      .filter((c): c is NonNullable<typeof c> => c !== null);
+  }
+
+  /**
+   * Get a job by ID
+   */
+  getJob(jobId: string): AnalysisJob | undefined {
+    return this.jobs.get(jobId);
+  }
+
+  /**
+   * Get the last completed job
+   */
+  getLastJob(): AnalysisJob | undefined {
+    const completed = Array.from(this.jobs.values())
+      .filter(j => j.status === 'completed')
+      .sort((a, b) => b.timestamp - a.timestamp);
+    return completed[0];
+  }
+
+  /**
+   * Cancel a job
+   */
+  cancelJob(jobId: string): boolean {
+    const job = this.jobs.get(jobId);
+    if (job && job.status === 'pending') {
+      job.status = 'cancelled';
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get all jobs
+   */
+  getAllJobs(): AnalysisJob[] {
+    return Array.from(this.jobs.values());
+  }
+}
+

package/src/lib/agent/analysis-service.ts

@@ -0,0 +1,171 @@
+// Analysis Service - Integrates analysis pipeline with observer
+// Monitors observer events and triggers analysis jobs
+
+import { AnalysisJobQueue } from './analysis-pipeline';
+import { createHeuristicAnalyzers, createLocalSearchAnalyzer, createLLMAnalyzer } from './analyzers';
+import type { TerminalObserverEvent, EventStore } from '../core/types';
+import type { ObserverConfig } from '../core/types';
+import type { LLMProviderConfig } from './llm/types';
+
+// Extended config that includes optional LLM support
+interface AnalysisServiceConfig extends ObserverConfig {
+  llm?: LLMProviderConfig;
+}
+
+/**
+ * Analysis service that monitors observer events and triggers analysis
+ */
+export class AnalysisService {
+  private queue: AnalysisJobQueue;
+  private store: EventStore | null = null;
+  private config: AnalysisServiceConfig | null = null;
+  private enabled = false;
+
+  constructor() {
+    this.queue = new AnalysisJobQueue();
+    this.setupAnalyzers();
+  }
+
+  /**
+   * Initialize the service with observer store
+   */
+  initialize(store: EventStore, config: ObserverConfig): void {
+    this.store = store;
+    this.config = config as AnalysisServiceConfig;
+    this.queue = new AnalysisJobQueue(store);
+    this.setupAnalyzers();
+    
+    // Enable LLM if configured
+    const llmConfig = this.config.llm;
+    if (llmConfig && llmConfig.enabled) {
+      this.queue.setLLMEnabled(true);
+    }
+  }
+
+  /**
+   * Enable or disable the service
+   */
+  setEnabled(enabled: boolean): void {
+    this.enabled = enabled;
+  }
+
+  /**
+   * Check if service is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled && this.store !== null;
+  }
+
+  /**
+   * Setup all analyzers
+   */
+  private setupAnalyzers(): void {
+    // Clear existing
+    this.queue = new AnalysisJobQueue(this.store);
+    
+    // Register Layer 1: Heuristic analyzers
+    const heuristicAnalyzers = createHeuristicAnalyzers();
+    for (const analyzer of heuristicAnalyzers) {
+      this.queue.registerAnalyzer(analyzer);
+    }
+
+    // Register Layer 2: Local search
+    this.queue.registerAnalyzer(createLocalSearchAnalyzer());
+
+    // Register Layer 3: LLM (gated)
+    const llmConfig = this.config?.llm;
+    const llmEnabled = llmConfig?.enabled || false;
+    this.queue.registerAnalyzer(createLLMAnalyzer(llmEnabled, llmConfig));
+    
+    // Set LLM enabled state
+    this.queue.setLLMEnabled(llmEnabled);
+  }
+
+  /**
+   * Process exit status event and trigger analysis if failure
+   */
+  async processExitStatus(event: TerminalObserverEvent): Promise<string | null> {
+    if (!this.isEnabled() || !this.store) {
+      return null;
+    }
+
+    if (event.type !== 'exit_status') {
+      return null;
+    }
+
+    // Check if it's a failure
+    if (event.success) {
+      return null; // Not a failure
+    }
+
+    // Get all events for this command
+    const commandEvents = await this.store.getEventsByCommand(event.commandId);
+    
+    // Enqueue analysis job
+    return await this.queue.enqueueFailure(event.commandId, commandEvents, this.store);
+  }
+
+  /**
+   * Get the last analysis job
+   */
+  getLastJob() {
+    return this.queue.getLastJob();
+  }
+
+  /**
+   * Get a job by ID
+   */
+  getJob(jobId: string) {
+    return this.queue.getJob(jobId);
+  }
+
+  /**
+   * Get all jobs
+   */
+  getAllJobs() {
+    return this.queue.getAllJobs();
+  }
+
+  /**
+   * Cancel a job
+   */
+  cancelJob(jobId: string): boolean {
+    return this.queue.cancelJob(jobId);
+  }
+
+  /**
+   * Enable LLM analysis
+   */
+  setLLMEnabled(enabled: boolean): void {
+    this.queue.setLLMEnabled(enabled);
+    // Re-register LLM analyzer with new setting
+    const llmConfig = this.config?.llm;
+    this.setupAnalyzers();
+  }
+
+  /**
+   * Update LLM configuration
+   */
+  setLLMConfig(config: LLMProviderConfig | undefined): void {
+    if (this.config) {
+      this.config.llm = config;
+      this.setupAnalyzers();
+    }
+  }
+}
+
+/**
+ * Global analysis service instance
+ */
+let globalAnalysisService: AnalysisService | null = null;
+
+/**
+ * Get or create the global analysis service
+ */
+export function getAnalysisService(): AnalysisService {
+  if (!globalAnalysisService) {
+    globalAnalysisService = new AnalysisService();
+  }
+  return globalAnalysisService;
+}
+

package/src/lib/agent/analysis.ts

@@ -0,0 +1,159 @@
+// Analysis engine for Ambient Agent Mode
+// Analyzes patterns and generates suggestions
+
+import type { TerminalEvent, CommandPattern, Suggestion, EventStorage } from '../types/agent';
+
+export interface Analyzer {
+  analyzeEvent(event: TerminalEvent, storage: EventStorage): Promise<Suggestion[]>;
+  analyzePatterns(storage: EventStorage): Promise<Suggestion[]>;
+}
+
+/**
+ * Default analyzer implementation
+ */
+export class DefaultAnalyzer implements Analyzer {
+  async analyzeEvent(event: TerminalEvent, storage: EventStorage): Promise<Suggestion[]> {
+    const suggestions: Suggestion[] = [];
+
+    // Check for repeated failures
+    if (!event.success) {
+      const recentFailures = await storage.getEventsByCommand(event.command, 5);
+      const failureCount = recentFailures.filter((e: TerminalEvent) => !e.success).length;
+      
+      if (failureCount >= 3) {
+        suggestions.push({
+          id: `suggestion_${Date.now()}_repeated_failure`,
+          type: 'warning',
+          priority: 'high',
+          title: 'Repeated Command Failures',
+          description: `The command "${event.command}" has failed ${failureCount} times recently. Consider checking the command syntax or environment.`,
+          timestamp: Date.now(),
+        });
+      }
+    }
+
+    // Check for slow commands
+    if (event.duration && event.duration > 5000) {
+      suggestions.push({
+        id: `suggestion_${Date.now()}_slow_command`,
+        type: 'optimization',
+        priority: 'medium',
+        title: 'Slow Command Execution',
+        description: `Command "${event.command}" took ${(event.duration / 1000).toFixed(1)}s to execute. Consider optimizing or using a faster alternative.`,
+        timestamp: Date.now(),
+      });
+    }
+
+    // Check for common patterns
+    const patterns = await storage.getPatterns();
+    const pattern = patterns.find((p: CommandPattern) => p.command === event.command);
+    
+    if (pattern && pattern.frequency > 5) {
+      // Suggest shortcuts for frequently used commands
+      if (pattern.commonArgs.length > 0 && event.args.length === 0) {
+        suggestions.push({
+          id: `suggestion_${Date.now()}_common_args`,
+          type: 'tip',
+          priority: 'low',
+          title: 'Common Arguments',
+          description: `You often use "${event.command}" with arguments. Consider creating a shortcut or alias.`,
+          command: event.command,
+          args: pattern.commonArgs[0].split(' '),
+          timestamp: Date.now(),
+        });
+      }
+    }
+
+    // Check for similar successful commands
+    if (!event.success) {
+      const similarEvents = await storage.getEvents(20);
+      const similarSuccessful = similarEvents.filter(
+        (e: TerminalEvent) => e.command === event.command && e.success && e.args.length === event.args.length
+      );
+      
+      if (similarSuccessful.length > 0) {
+        const lastSuccessful = similarSuccessful[0];
+        suggestions.push({
+          id: `suggestion_${Date.now()}_similar_success`,
+          type: 'command',
+          priority: 'medium',
+          title: 'Similar Successful Command',
+          description: `A similar command succeeded recently. Compare the differences.`,
+          command: lastSuccessful.command,
+          args: lastSuccessful.args,
+          context: {
+            previousTimestamp: lastSuccessful.timestamp,
+            previousCwd: lastSuccessful.cwd,
+          },
+          timestamp: Date.now(),
+        });
+      }
+    }
+
+    return suggestions;
+  }
+
+  async analyzePatterns(storage: EventStorage): Promise<Suggestion[]> {
+    const suggestions: Suggestion[] = [];
+    const patterns = await storage.getPatterns();
+    const stats = await storage.getStats();
+
+    // Suggest frequently used commands as shortcuts
+    const frequentPatterns = patterns
+      .filter((p: CommandPattern) => p.frequency >= 5)
+      .sort((a: CommandPattern, b: CommandPattern) => b.frequency - a.frequency)
+      .slice(0, 5);
+
+    for (const pattern of frequentPatterns) {
+      suggestions.push({
+        id: `suggestion_${Date.now()}_frequent_${pattern.id}`,
+        type: 'shortcut',
+        priority: 'low',
+        title: 'Frequently Used Command',
+        description: `"${pattern.command}" has been used ${pattern.frequency} times. Consider creating an alias or script.`,
+        command: pattern.command,
+        timestamp: Date.now(),
+      });
+    }
+
+    // Suggest optimization for slow commands
+    const slowPatterns = patterns
+      .filter((p: CommandPattern) => p.avgDuration > 3000)
+      .sort((a: CommandPattern, b: CommandPattern) => b.avgDuration - a.avgDuration)
+      .slice(0, 3);
+
+    for (const pattern of slowPatterns) {
+      suggestions.push({
+        id: `suggestion_${Date.now()}_slow_${pattern.id}`,
+        type: 'optimization',
+        priority: 'medium',
+        title: 'Slow Command Pattern',
+        description: `"${pattern.command}" averages ${(pattern.avgDuration / 1000).toFixed(1)}s execution time. Consider optimization.`,
+        command: pattern.command,
+        timestamp: Date.now(),
+      });
+    }
+
+    // Overall stats suggestions
+    if (stats.avgSuccessRate < 0.7) {
+      suggestions.push({
+        id: `suggestion_${Date.now()}_low_success_rate`,
+        type: 'tip',
+        priority: 'medium',
+        title: 'Low Success Rate',
+        description: `Overall command success rate is ${(stats.avgSuccessRate * 100).toFixed(1)}%. Review failed commands for patterns.`,
+        timestamp: Date.now(),
+      });
+    }
+
+    return suggestions;
+  }
+}
+
+/**
+ * Create analyzer instance
+ */
+export function createAnalyzer(): Analyzer {
+  return new DefaultAnalyzer();
+}
+