@plures/runebook 0.4.0

package/src/lib/agent/llm/types.ts

@@ -0,0 +1,118 @@
+// LLM/MCP Integration Types
+// Defines contracts for model-backed reasoning
+
+import type { AnalysisContext, AnalysisSuggestion } from '../analysis-pipeline';
+
+/**
+ * Repository metadata for context
+ */
+export interface RepoMetadata {
+  root?: string;
+  type?: 'git' | 'hg' | 'svn' | 'none';
+  files?: string[]; // Relevant files (e.g., *.nix, flake.nix)
+  language?: string;
+  framework?: string;
+}
+
+/**
+ * Error summary for LLM context
+ */
+export interface ErrorSummary {
+  command: string;
+  args: string[];
+  exitCode: number;
+  stderr: string;
+  stdout: string;
+  cwd: string;
+  timestamp: number;
+}
+
+/**
+ * MCP Tool Contract Input
+ * What we send to the LLM/MCP provider
+ */
+export interface MCPToolInput {
+  contextWindow: AnalysisContext;
+  errorSummary: ErrorSummary;
+  repoMetadata: RepoMetadata;
+  previousSuggestions?: AnalysisSuggestion[]; // From heuristic/local search layers
+}
+
+/**
+ * MCP Tool Contract Output
+ * What we expect back from the LLM/MCP provider
+ */
+export interface MCPToolOutput {
+  suggestions: Array<{
+    title: string;
+    description: string;
+    actionableSnippet?: string;
+    confidence: number; // 0.0 to 1.0
+    type: 'command' | 'optimization' | 'shortcut' | 'warning' | 'tip';
+    priority: 'low' | 'medium' | 'high';
+  }>;
+  provenance: {
+    provider: string; // 'ollama', 'openai', 'mcp', etc.
+    model?: string;
+    timestamp: number;
+    tokensUsed?: number;
+  };
+}
+
+/**
+ * Sanitized context (after redaction)
+ */
+export interface SanitizedContext {
+  original: AnalysisContext;
+  sanitized: AnalysisContext;
+  redactions: Array<{
+    type: 'env' | 'stdout' | 'stderr' | 'command';
+    pattern: string;
+    replaced: string;
+  }>;
+}
+
+// Re-export for convenience
+export type { AnalysisContext, AnalysisSuggestion } from '../analysis-pipeline';
+
+/**
+ * LLM Provider Configuration
+ */
+export interface LLMProviderConfig {
+  type: 'ollama' | 'openai' | 'mcp' | 'mock';
+  enabled: boolean;
+  // Ollama config
+  ollama?: {
+    baseUrl?: string; // Default: http://localhost:11434
+    model?: string; // Default: llama3.2
+  };
+  // OpenAI config
+  openai?: {
+    apiKey?: string; // From env var OPENAI_API_KEY
+    model?: string; // Default: gpt-4o-mini
+    baseUrl?: string; // Default: https://api.openai.com/v1
+  };
+  // MCP config
+  mcp?: {
+    serverUrl?: string;
+    toolName?: string;
+  };
+  // Safety settings
+  safety?: {
+    requireUserReview?: boolean; // Show context before sending (default: true)
+    maxContextLength?: number; // Truncate if too long (default: 8000 tokens)
+    cacheEnabled?: boolean; // Cache responses (default: false)
+    cacheTtl?: number; // Cache TTL in seconds (default: 3600)
+  };
+}
+
+/**
+ * LLM Provider Interface
+ */
+export interface LLMProvider {
+  name: string;
+  isAvailable(): Promise<boolean>;
+  analyze(input: MCPToolInput): Promise<MCPToolOutput>;
+  sanitizeContext(context: AnalysisContext): Promise<SanitizedContext>;
+}
+

package/src/lib/agent/memory.ts

@@ -0,0 +1,363 @@
+// Memory/storage layer for Ambient Agent Mode
+// Stores terminal events and patterns for analysis
+
+import type { TerminalEvent, CommandPattern, Suggestion, AgentConfig } from '../types/agent';
+
+export interface EventStorage {
+  saveEvent(event: TerminalEvent): Promise<void>;
+  getEvents(limit?: number, since?: number): Promise<TerminalEvent[]>;
+  getEventsByCommand(command: string, limit?: number): Promise<TerminalEvent[]>;
+  getPatterns(): Promise<CommandPattern[]>;
+  savePattern(pattern: CommandPattern): Promise<void>;
+  saveSuggestion(suggestion: Suggestion): Promise<void>;
+  getSuggestions(limit: number): Promise<Suggestion[]>;
+  clearEvents(olderThan?: number): Promise<void>;
+  getStats(): Promise<{
+    totalEvents: number;
+    uniqueCommands: number;
+    avgSuccessRate: number;
+    totalDuration: number;
+  }>;
+}
+
+/**
+ * In-memory storage adapter (for testing and headless mode)
+ */
+export class MemoryStorage implements EventStorage {
+  private events: TerminalEvent[] = [];
+  private patterns: Map<string, CommandPattern> = new Map();
+  private suggestions: Suggestion[] = [];
+  private config: AgentConfig;
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+  }
+
+  async saveEvent(event: TerminalEvent): Promise<void> {
+    this.events.push(event);
+    
+    // Enforce max events limit
+    if (this.config.maxEvents && this.events.length > this.config.maxEvents) {
+      this.events = this.events.slice(-this.config.maxEvents);
+    }
+
+    // Update patterns
+    await this.updatePattern(event);
+  }
+
+  async getEvents(limit?: number, since?: number): Promise<TerminalEvent[]> {
+    let filtered = this.events;
+    
+    if (since) {
+      filtered = filtered.filter(e => e.timestamp >= since);
+    }
+    
+    if (limit) {
+      filtered = filtered.slice(-limit);
+    }
+    
+    return filtered.sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  async getEventsByCommand(command: string, limit?: number): Promise<TerminalEvent[]> {
+    let filtered = this.events.filter(e => e.command === command);
+    
+    if (limit) {
+      filtered = filtered.slice(-limit);
+    }
+    
+    return filtered.sort((a, b) => b.timestamp - a.timestamp);
+  }
+
+  async getPatterns(): Promise<CommandPattern[]> {
+    return Array.from(this.patterns.values());
+  }
+
+  async savePattern(pattern: CommandPattern): Promise<void> {
+    this.patterns.set(pattern.id, pattern);
+  }
+
+  async saveSuggestion(suggestion: Suggestion): Promise<void> {
+    this.suggestions.push(suggestion);
+    // Keep only recent suggestions (last 100)
+    if (this.suggestions.length > 100) {
+      this.suggestions = this.suggestions.slice(-100);
+    }
+  }
+
+  async getSuggestions(limit: number): Promise<Suggestion[]> {
+    return this.suggestions
+      .sort((a, b) => b.timestamp - a.timestamp)
+      .slice(0, limit);
+  }
+
+  async clearEvents(olderThan?: number): Promise<void> {
+    if (olderThan) {
+      this.events = this.events.filter(e => e.timestamp >= olderThan);
+    } else {
+      this.events = [];
+    }
+  }
+
+  async getStats(): Promise<{
+    totalEvents: number;
+    uniqueCommands: number;
+    avgSuccessRate: number;
+    totalDuration: number;
+  }> {
+    const uniqueCommands = new Set(this.events.map(e => e.command)).size;
+    const successful = this.events.filter(e => e.success).length;
+    const avgSuccessRate = this.events.length > 0 ? successful / this.events.length : 0;
+    const totalDuration = this.events.reduce((sum, e) => sum + (e.duration || 0), 0);
+
+    return {
+      totalEvents: this.events.length,
+      uniqueCommands,
+      avgSuccessRate,
+      totalDuration,
+    };
+  }
+
+  private async updatePattern(event: TerminalEvent): Promise<void> {
+    const patternId = `pattern_${event.command}`;
+    let pattern = this.patterns.get(patternId);
+
+    if (!pattern) {
+      pattern = {
+        id: patternId,
+        command: event.command,
+        frequency: 0,
+        lastUsed: event.timestamp,
+        successRate: 0,
+        avgDuration: 0,
+        commonArgs: [],
+        commonEnv: {},
+      };
+    }
+
+    pattern.frequency += 1;
+    pattern.lastUsed = Math.max(pattern.lastUsed, event.timestamp);
+    
+    // Update success rate
+    const commandEvents = await this.getEventsByCommand(event.command);
+    const successful = commandEvents.filter(e => e.success).length;
+    pattern.successRate = commandEvents.length > 0 ? successful / commandEvents.length : 0;
+    
+    // Update average duration
+    const durations = commandEvents.filter(e => e.duration !== undefined).map(e => e.duration!);
+    pattern.avgDuration = durations.length > 0
+      ? durations.reduce((sum, d) => sum + d, 0) / durations.length
+      : 0;
+    
+    // Track common args
+    if (event.args.length > 0) {
+      const argKey = event.args.join(' ');
+      const existing = pattern.commonArgs.find(a => a === argKey);
+      if (!existing) {
+        pattern.commonArgs.push(argKey);
+        if (pattern.commonArgs.length > 10) {
+          pattern.commonArgs = pattern.commonArgs.slice(-10);
+        }
+      }
+    }
+
+    this.patterns.set(patternId, pattern);
+  }
+}
+
+/**
+ * PluresDB storage adapter (for persistent storage)
+ */
+export class PluresDBStorage implements EventStorage {
+  private db: any = null;
+  private readonly eventPrefix = 'agent:event:';
+  private readonly patternPrefix = 'agent:pattern:';
+  private readonly suggestionPrefix = 'agent:suggestion:';
+  private initialized = false;
+  private config: AgentConfig;
+
+  constructor(config: AgentConfig) {
+    this.config = config;
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (this.initialized && this.db) {
+      return;
+    }
+
+    try {
+      const { SQLiteCompatibleAPI } = await import('pluresdb');
+      
+      this.db = new SQLiteCompatibleAPI({
+        config: {
+          port: 34567,
+          host: 'localhost',
+          dataDir: this.config.storagePath || './pluresdb-data',
+        },
+        autoStart: true,
+      });
+
+      await this.db.start();
+      this.initialized = true;
+    } catch (error) {
+      console.error('Failed to initialize PluresDB for agent storage:', error);
+      throw new Error('PluresDB initialization failed for agent storage');
+    }
+  }
+
+  async saveEvent(event: TerminalEvent): Promise<void> {
+    await this.ensureInitialized();
+    const key = `${this.eventPrefix}${event.id}`;
+    await this.db.put(key, event);
+    await this.updatePattern(event);
+  }
+
+  async getEvents(limit?: number, since?: number): Promise<TerminalEvent[]> {
+    await this.ensureInitialized();
+    const keys = await this.db.list(this.eventPrefix);
+    const events: TerminalEvent[] = [];
+
+    for (const key of keys) {
+      try {
+        const event = await this.db.getValue(key);
+        if (event && (!since || event.timestamp >= since)) {
+          events.push(event as TerminalEvent);
+        }
+      } catch (error) {
+        console.error('Failed to load event:', error);
+      }
+    }
+
+    events.sort((a, b) => b.timestamp - a.timestamp);
+    return limit ? events.slice(0, limit) : events;
+  }
+
+  async getEventsByCommand(command: string, limit?: number): Promise<TerminalEvent[]> {
+    const allEvents = await this.getEvents();
+    const filtered = allEvents.filter(e => e.command === command);
+    return limit ? filtered.slice(0, limit) : filtered;
+  }
+
+  async getPatterns(): Promise<CommandPattern[]> {
+    await this.ensureInitialized();
+    const keys = await this.db.list(this.patternPrefix);
+    const patterns: CommandPattern[] = [];
+
+    for (const key of keys) {
+      try {
+        const pattern = await this.db.getValue(key);
+        if (pattern) {
+          patterns.push(pattern as CommandPattern);
+        }
+      } catch (error) {
+        console.error('Failed to load pattern:', error);
+      }
+    }
+
+    return patterns;
+  }
+
+  async savePattern(pattern: CommandPattern): Promise<void> {
+    await this.ensureInitialized();
+    const key = `${this.patternPrefix}${pattern.id}`;
+    await this.db.put(key, pattern);
+  }
+
+  async saveSuggestion(suggestion: Suggestion): Promise<void> {
+    await this.ensureInitialized();
+    const key = `${this.suggestionPrefix}${suggestion.id}`;
+    await this.db.put(key, suggestion);
+  }
+
+  async getSuggestions(limit: number): Promise<Suggestion[]> {
+    await this.ensureInitialized();
+    const keys = await this.db.list(this.suggestionPrefix);
+    const suggestions: Suggestion[] = [];
+
+    for (const key of keys) {
+      try {
+        const suggestion = await this.db.getValue(key);
+        if (suggestion) {
+          suggestions.push(suggestion as Suggestion);
+        }
+      } catch (error) {
+        console.error('Failed to load suggestion:', error);
+      }
+    }
+
+    suggestions.sort((a, b) => b.timestamp - a.timestamp);
+    return suggestions.slice(0, limit);
+  }
+
+  async clearEvents(olderThan?: number): Promise<void> {
+    await this.ensureInitialized();
+    const keys = await this.db.list(this.eventPrefix);
+    
+    for (const key of keys) {
+      try {
+        const event = await this.db.getValue(key);
+        if (event && (!olderThan || event.timestamp < olderThan)) {
+          await this.db.delete(key);
+        }
+      } catch (error) {
+        console.error('Failed to delete event:', error);
+      }
+    }
+  }
+
+  async getStats(): Promise<{
+    totalEvents: number;
+    uniqueCommands: number;
+    avgSuccessRate: number;
+    totalDuration: number;
+  }> {
+    const events = await this.getEvents();
+    const uniqueCommands = new Set(events.map(e => e.command)).size;
+    const successful = events.filter(e => e.success).length;
+    const avgSuccessRate = events.length > 0 ? successful / events.length : 0;
+    const totalDuration = events.reduce((sum, e) => sum + (e.duration || 0), 0);
+
+    return {
+      totalEvents: events.length,
+      uniqueCommands,
+      avgSuccessRate,
+      totalDuration,
+    };
+  }
+
+  private async updatePattern(event: TerminalEvent): Promise<void> {
+    const patternId = `pattern_${event.command}`;
+    const existingEvents = await this.getEventsByCommand(event.command);
+    
+    const successful = existingEvents.filter(e => e.success).length;
+    const successRate = existingEvents.length > 0 ? successful / existingEvents.length : 0;
+    const durations = existingEvents.filter(e => e.duration !== undefined).map(e => e.duration!);
+    const avgDuration = durations.length > 0
+      ? durations.reduce((sum, d) => sum + d, 0) / durations.length
+      : 0;
+
+    const pattern: CommandPattern = {
+      id: patternId,
+      command: event.command,
+      frequency: existingEvents.length,
+      lastUsed: Math.max(...existingEvents.map(e => e.timestamp)),
+      successRate,
+      avgDuration,
+      commonArgs: [...new Set(existingEvents.flatMap(e => e.args.join(' ')))].slice(0, 10),
+      commonEnv: {},
+    };
+
+    await this.savePattern(pattern);
+  }
+}
+
+/**
+ * Create storage instance based on config
+ */
+export function createStorage(config: AgentConfig): EventStorage {
+  if (config.storagePath) {
+    return new PluresDBStorage(config);
+  }
+  return new MemoryStorage(config);
+}
+

package/src/lib/agent/node-status.ts

@@ -0,0 +1,56 @@
+// Node.js-only agent status tracking with file persistence
+// This file should only be imported in Node.js environments
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import type { AgentStatusData } from './status';
+
+const STATUS_FILE = join(homedir(), '.runebook', 'agent-status.json');
+
+/**
+ * Get current agent status from file (Node.js only)
+ */
+export function getAgentStatusFromFile(): AgentStatusData {
+  if (existsSync(STATUS_FILE)) {
+    try {
+      const content = readFileSync(STATUS_FILE, 'utf-8');
+      const data = JSON.parse(content);
+      return {
+        status: data.status || 'idle',
+        lastCommand: data.lastCommand,
+        lastCommandTimestamp: data.lastCommandTimestamp,
+        suggestionCount: data.suggestionCount || 0,
+        highPriorityCount: data.highPriorityCount || 0,
+        lastUpdated: data.lastUpdated || Date.now(),
+      };
+    } catch (error) {
+      console.error('Failed to load agent status:', error);
+    }
+  }
+  
+  return {
+    status: 'idle',
+    suggestionCount: 0,
+    highPriorityCount: 0,
+    lastUpdated: Date.now(),
+  };
+}
+
+/**
+ * Update agent status to file (Node.js only)
+ */
+export function updateAgentStatusToFile(current: AgentStatusData, updates: Partial<AgentStatusData>): void {
+  const configDir = join(homedir(), '.runebook');
+  if (!existsSync(configDir)) {
+    mkdirSync(configDir, { recursive: true });
+  }
+  
+  const updated: AgentStatusData = {
+    ...current,
+    ...updates,
+    lastUpdated: Date.now(),
+  };
+  
+  writeFileSync(STATUS_FILE, JSON.stringify(updated, null, 2), 'utf-8');
+}

package/src/lib/agent/node-suggestions.ts

@@ -0,0 +1,64 @@
+// Node.js-only suggestion store with file persistence
+// This file should only be imported in Node.js environments (CLI, server)
+
+import type { Suggestion } from '../types/agent';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { MemorySuggestionStore } from './suggestions';
+
+/**
+ * File-based persistent suggestion store (Node.js only)
+ */
+export class FileSuggestionStore extends MemorySuggestionStore {
+  private storePath: string;
+
+  constructor(storePath?: string) {
+    super();
+    this.storePath = storePath || join(homedir(), '.runebook', 'suggestions.json');
+  }
+
+  async save(): Promise<void> {
+    const configDir = join(homedir(), '.runebook');
+    if (!existsSync(configDir)) {
+      mkdirSync(configDir, { recursive: true });
+    }
+    
+    const data = {
+      suggestions: this.suggestions,
+      lastUpdated: Date.now(),
+    };
+    
+    writeFileSync(this.storePath, JSON.stringify(data, null, 2), 'utf-8');
+  }
+
+  async load(): Promise<void> {
+    if (existsSync(this.storePath)) {
+      try {
+        const content = readFileSync(this.storePath, 'utf-8');
+        const data = JSON.parse(content);
+        if (data.suggestions && Array.isArray(data.suggestions)) {
+          this.suggestions = data.suggestions;
+        }
+      } catch (error) {
+        console.error('Failed to load suggestions from file:', error);
+      }
+    }
+  }
+
+  add(suggestion: Suggestion): void {
+    super.add(suggestion);
+    // Auto-save on add (async, don't wait)
+    this.save().catch(err => console.error('Failed to save suggestions:', err));
+  }
+
+  remove(id: string): void {
+    super.remove(id);
+    this.save().catch(err => console.error('Failed to save suggestions:', err));
+  }
+
+  clear(): void {
+    super.clear();
+    this.save().catch(err => console.error('Failed to save suggestions:', err));
+  }
+}

package/src/lib/agent/status.ts

@@ -0,0 +1,80 @@
+// Agent status tracking for UX surfaces
+
+export type AgentStatus = 'idle' | 'analyzing' | 'issues_found';
+
+export interface AgentStatusData {
+  status: AgentStatus;
+  lastCommand?: string;
+  lastCommandTimestamp?: number;
+  suggestionCount: number;
+  highPriorityCount: number;
+  lastUpdated: number;
+}
+
+// In-memory status for browser environment
+let inMemoryStatus: AgentStatusData = {
+  status: 'idle',
+  suggestionCount: 0,
+  highPriorityCount: 0,
+  lastUpdated: Date.now(),
+};
+
+// Check if we're in Node.js environment
+const isNode = typeof process !== 'undefined' && process.versions?.node;
+
+/**
+ * Get current agent status
+ */
+export function getAgentStatus(): AgentStatusData {
+  if (isNode) {
+    // Dynamically load from file in Node.js
+    try {
+      // Use dynamic import to avoid bundling Node.js modules
+      return inMemoryStatus; // Return in-memory for now, will be updated async
+    } catch (error) {
+      console.error('Failed to load agent status:', error);
+    }
+  }
+  
+  return inMemoryStatus;
+}
+
+/**
+ * Update agent status
+ */
+export function updateAgentStatus(updates: Partial<AgentStatusData>): void {
+  inMemoryStatus = {
+    ...inMemoryStatus,
+    ...updates,
+    lastUpdated: Date.now(),
+  };
+  
+  // In Node.js, also persist to file
+  if (isNode) {
+    import('./node-status').then(({ updateAgentStatusToFile }) => {
+      updateAgentStatusToFile(inMemoryStatus, updates);
+    }).catch(err => {
+      console.error('Failed to persist status to file:', err);
+    });
+  }
+}
+
+/**
+ * Format status for display
+ */
+export function formatStatus(status: AgentStatusData): string {
+  const statusSymbol = {
+    idle: '●',
+    analyzing: '⟳',
+    issues_found: '⚠',
+  };
+  
+  const statusText = {
+    idle: 'idle',
+    analyzing: 'analyzing',
+    issues_found: `${status.highPriorityCount} issue${status.highPriorityCount !== 1 ? 's' : ''}`,
+  };
+  
+  return `${statusSymbol[status.status]} ${statusText[status.status]}`;
+}
+