@plures/runebook 0.4.0

package/src/lib/agent/llm/providers/base.ts

@@ -0,0 +1,99 @@
+// Base LLM Provider
+// Abstract base class for all LLM providers
+
+import type { LLMProvider, MCPToolInput, MCPToolOutput, SanitizedContext } from '../types';
+import { sanitizeContext, formatContextForReview } from '../sanitizer';
+
+/**
+ * Base provider implementation
+ */
+export abstract class BaseLLMProvider implements LLMProvider {
+  abstract name: string;
+  protected requireUserReview: boolean = true;
+  protected cacheEnabled: boolean = false;
+  protected cache: Map<string, { output: MCPToolOutput; timestamp: number }> = new Map();
+  protected cacheTtl: number = 3600; // 1 hour default
+
+  constructor(requireUserReview: boolean = true, cacheEnabled: boolean = false, cacheTtl: number = 3600) {
+    this.requireUserReview = requireUserReview;
+    this.cacheEnabled = cacheEnabled;
+    this.cacheTtl = cacheTtl;
+  }
+
+  abstract isAvailable(): Promise<boolean>;
+  abstract callLLM(input: MCPToolInput, sanitized: SanitizedContext): Promise<MCPToolOutput>;
+
+  /**
+   * Sanitize context before sending
+   */
+  async sanitizeContext(context: MCPToolInput['contextWindow']): Promise<SanitizedContext> {
+    return sanitizeContext(context);
+  }
+
+  /**
+   * Analyze with safety checks
+   */
+  async analyze(input: MCPToolInput): Promise<MCPToolOutput> {
+    // Sanitize context
+    const sanitized = await this.sanitizeContext(input.contextWindow);
+    
+    // Check cache if enabled
+    if (this.cacheEnabled) {
+      const cacheKey = this.getCacheKey(input, sanitized);
+      const cached = this.cache.get(cacheKey);
+      if (cached && (Date.now() - cached.timestamp) < this.cacheTtl * 1000) {
+        return cached.output;
+      }
+    }
+    
+    // User review (if required)
+    if (this.requireUserReview) {
+      const reviewText = formatContextForReview(sanitized);
+      // In CLI mode, we'll log this and wait for confirmation
+      // In GUI mode, this would show a dialog
+      console.log(reviewText);
+      console.log('\n⚠️  Context will be sent to LLM. Review above and confirm.');
+      // For now, we'll proceed (in real implementation, this would wait for user input)
+    }
+    
+    // Call LLM with sanitized context
+    const sanitizedInput: MCPToolInput = {
+      ...input,
+      contextWindow: sanitized.sanitized,
+    };
+    
+    const output = await this.callLLM(sanitizedInput, sanitized);
+    
+    // Cache result if enabled
+    if (this.cacheEnabled) {
+      const cacheKey = this.getCacheKey(input, sanitized);
+      this.cache.set(cacheKey, {
+        output,
+        timestamp: Date.now(),
+      });
+    }
+    
+    return output;
+  }
+
+  /**
+   * Generate cache key from input
+   */
+  protected getCacheKey(input: MCPToolInput, sanitized: SanitizedContext): string {
+    const key = JSON.stringify({
+      command: sanitized.sanitized.command,
+      args: sanitized.sanitized.args,
+      exitCode: sanitized.sanitized.exitCode,
+      stderr: sanitized.sanitized.stderr.substring(0, 500), // First 500 chars
+    });
+    return Buffer.from(key).toString('base64');
+  }
+
+  /**
+   * Clear cache
+   */
+  clearCache(): void {
+    this.cache.clear();
+  }
+}
+

package/src/lib/agent/llm/providers/index.ts

@@ -0,0 +1,60 @@
+// LLM Provider Factory
+// Creates appropriate provider based on config
+
+import type { LLMProvider, LLMProviderConfig } from '../types';
+import { OllamaProvider } from './ollama';
+import { OpenAIProvider } from './openai';
+import { MockProvider } from './mock';
+
+export { MockProvider, OllamaProvider, OpenAIProvider };
+
+/**
+ * Create LLM provider from config
+ */
+export function createLLMProvider(config: LLMProviderConfig): LLMProvider | null {
+  if (!config.enabled) {
+    return null;
+  }
+
+  switch (config.type) {
+    case 'ollama':
+      return new OllamaProvider(config);
+    
+    case 'openai':
+      try {
+        return new OpenAIProvider(config);
+      } catch (error) {
+        console.error('Failed to create OpenAI provider:', error);
+        return null;
+      }
+    
+    case 'mock':
+      return new MockProvider(config);
+    
+    case 'mcp':
+      // TODO: Implement MCP provider
+      console.warn('MCP provider not yet implemented');
+      return null;
+    
+    default:
+      console.warn(`Unknown LLM provider type: ${config.type}`);
+      return null;
+  }
+}
+
+/**
+ * Check if a provider is available
+ */
+export async function isProviderAvailable(config: LLMProviderConfig): Promise<boolean> {
+  if (!config.enabled) {
+    return false;
+  }
+
+  const provider = createLLMProvider(config);
+  if (!provider) {
+    return false;
+  }
+
+  return await provider.isAvailable();
+}
+

package/src/lib/agent/llm/providers/mock.ts

@@ -0,0 +1,67 @@
+// Mock Provider for Testing
+// Returns deterministic responses for testing
+
+import { BaseLLMProvider } from './base';
+import type { LLMProviderConfig, MCPToolInput, MCPToolOutput } from '../types';
+
+export class MockProvider extends BaseLLMProvider {
+  name = 'mock';
+  private responses: Map<string, MCPToolOutput> = new Map();
+
+  constructor(config: LLMProviderConfig) {
+    super(
+      config.safety?.requireUserReview ?? false, // Mock doesn't need review
+      config.safety?.cacheEnabled ?? false,
+      config.safety?.cacheTtl ?? 3600
+    );
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return true; // Mock is always available
+  }
+
+  /**
+   * Set a mock response for a specific input
+   */
+  setMockResponse(input: MCPToolInput, output: MCPToolOutput): void {
+    const key = this.getInputKey(input);
+    this.responses.set(key, output);
+  }
+
+  /**
+   * Clear all mock responses
+   */
+  clearMockResponses(): void {
+    this.responses.clear();
+  }
+
+  async callLLM(input: MCPToolInput, _sanitized: any): Promise<MCPToolOutput> {
+    const key = this.getInputKey(input);
+    
+    // Check if we have a preset response
+    if (this.responses.has(key)) {
+      return this.responses.get(key)!;
+    }
+    
+    // Default mock response
+    return {
+      suggestions: [{
+        title: 'Mock Suggestion',
+        description: `This is a mock suggestion for command: ${input.contextWindow.command}`,
+        actionableSnippet: `# Mock fix for ${input.contextWindow.command}`,
+        confidence: 0.7,
+        type: 'tip',
+        priority: 'medium',
+      }],
+      provenance: {
+        provider: 'mock',
+        timestamp: Date.now(),
+      },
+    };
+  }
+
+  private getInputKey(input: MCPToolInput): string {
+    return `${input.contextWindow.command}_${input.contextWindow.exitCode}_${input.contextWindow.stderr.substring(0, 100)}`;
+  }
+}
+

package/src/lib/agent/llm/providers/ollama.ts

@@ -0,0 +1,151 @@
+// Ollama Provider
+// Local model support via Ollama API
+
+import { BaseLLMProvider } from './base';
+import type { LLMProviderConfig, MCPToolInput, MCPToolOutput } from '../types';
+
+export class OllamaProvider extends BaseLLMProvider {
+  name = 'ollama';
+  private baseUrl: string;
+  private model: string;
+
+  constructor(config: LLMProviderConfig) {
+    super(
+      config.safety?.requireUserReview ?? true,
+      config.safety?.cacheEnabled ?? false,
+      config.safety?.cacheTtl ?? 3600
+    );
+    this.baseUrl = config.ollama?.baseUrl || 'http://localhost:11434';
+    this.model = config.ollama?.model || 'llama3.2';
+  }
+
+  async isAvailable(): Promise<boolean> {
+    try {
+      const response = await fetch(`${this.baseUrl}/api/tags`, {
+        method: 'GET',
+        headers: { 'Content-Type': 'application/json' },
+      });
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+
+  async callLLM(input: MCPToolInput, _sanitized: any): Promise<MCPToolOutput> {
+    // Build prompt
+    const prompt = this.buildPrompt(input);
+    
+    // Call Ollama API
+    const response = await fetch(`${this.baseUrl}/api/generate`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        model: this.model,
+        prompt,
+        stream: false,
+        options: {
+          temperature: 0.7,
+          top_p: 0.9,
+        },
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Ollama API error: ${response.statusText}`);
+    }
+
+    const data = await response.json();
+    const text = data.response || '';
+    
+    // Parse response
+    return this.parseResponse(text, input);
+  }
+
+  private buildPrompt(input: MCPToolInput): string {
+    const { contextWindow, errorSummary, repoMetadata } = input;
+    
+    return `You are a helpful assistant analyzing terminal command failures. Provide actionable suggestions.
+
+Command: ${contextWindow.command} ${contextWindow.args.join(' ')}
+Working Directory: ${contextWindow.cwd}
+Exit Code: ${contextWindow.exitCode}
+
+Error Output:
+${contextWindow.stderr.substring(0, 2000)}
+
+Standard Output:
+${contextWindow.stdout.substring(0, 1000)}
+
+Previous Commands:
+${contextWindow.previousCommands.slice(-3).map(c => `  ${c.command} ${c.args.join(' ')} (exit: ${c.exitCode})`).join('\n')}
+
+Repository Context:
+${repoMetadata.type ? `Type: ${repoMetadata.type}` : 'Unknown'}
+${repoMetadata.language ? `Language: ${repoMetadata.language}` : ''}
+${repoMetadata.files && repoMetadata.files.length > 0 ? `Relevant files: ${repoMetadata.files.slice(0, 5).join(', ')}` : ''}
+
+Provide 1-3 actionable suggestions in JSON format:
+{
+  "suggestions": [
+    {
+      "title": "Short title",
+      "description": "Detailed explanation",
+      "actionableSnippet": "Code or command to fix",
+      "confidence": 0.0-1.0,
+      "type": "command|optimization|shortcut|warning|tip",
+      "priority": "low|medium|high"
+    }
+  ]
+}
+
+Only return valid JSON, no other text.`;
+  }
+
+  private parseResponse(text: string, input: MCPToolInput): MCPToolOutput {
+    try {
+      // Try to extract JSON from response
+      const jsonMatch = text.match(/\{[\s\S]*\}/);
+      if (!jsonMatch) {
+        throw new Error('No JSON found in response');
+      }
+      
+      const parsed = JSON.parse(jsonMatch[0]);
+      
+      // Convert to MCPToolOutput format
+      const suggestions = (parsed.suggestions || []).map((s: any) => ({
+        title: s.title || 'Suggestion',
+        description: s.description || '',
+        actionableSnippet: s.actionableSnippet,
+        confidence: Math.max(0, Math.min(1, s.confidence || 0.5)),
+        type: s.type || 'tip',
+        priority: s.priority || 'medium',
+      }));
+      
+      return {
+        suggestions,
+        provenance: {
+          provider: 'ollama',
+          model: this.model,
+          timestamp: Date.now(),
+        },
+      };
+    } catch (error) {
+      // Fallback: create a generic suggestion from the text
+      return {
+        suggestions: [{
+          title: 'LLM Analysis',
+          description: text.substring(0, 500),
+          confidence: 0.5,
+          type: 'tip',
+          priority: 'medium',
+        }],
+        provenance: {
+          provider: 'ollama',
+          model: this.model,
+          timestamp: Date.now(),
+        },
+      };
+    }
+  }
+}
+

package/src/lib/agent/llm/providers/openai.ts

@@ -0,0 +1,153 @@
+// OpenAI Provider
+// OpenAI API support via API key
+
+import { BaseLLMProvider } from './base';
+import type { LLMProviderConfig, MCPToolInput, MCPToolOutput } from '../types';
+
+export class OpenAIProvider extends BaseLLMProvider {
+  name = 'openai';
+  private apiKey: string;
+  private model: string;
+  private baseUrl: string;
+
+  constructor(config: LLMProviderConfig) {
+    super(
+      config.safety?.requireUserReview ?? true,
+      config.safety?.cacheEnabled ?? false,
+      config.safety?.cacheTtl ?? 3600
+    );
+    
+    // Get API key from env var
+    this.apiKey = config.openai?.apiKey || process.env.OPENAI_API_KEY || '';
+    if (!this.apiKey) {
+      throw new Error('OpenAI API key not found. Set OPENAI_API_KEY environment variable.');
+    }
+    
+    this.model = config.openai?.model || 'gpt-4o-mini';
+    this.baseUrl = config.openai?.baseUrl || 'https://api.openai.com/v1';
+  }
+
+  async isAvailable(): Promise<boolean> {
+    return this.apiKey.length > 0;
+  }
+
+  async callLLM(input: MCPToolInput, _sanitized: any): Promise<MCPToolOutput> {
+    // Build messages
+    const messages = this.buildMessages(input);
+    
+    // Call OpenAI API
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages,
+        temperature: 0.7,
+        response_format: { type: 'json_object' },
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`OpenAI API error: ${response.statusText} - ${error}`);
+    }
+
+    const data = await response.json();
+    const text = data.choices[0]?.message?.content || '';
+    
+    // Parse response
+    return this.parseResponse(text, input, data.usage);
+  }
+
+  private buildMessages(input: MCPToolInput): Array<{ role: string; content: string }> {
+    const { contextWindow, errorSummary, repoMetadata } = input;
+    
+    const systemPrompt = `You are a helpful assistant analyzing terminal command failures. Provide actionable suggestions in JSON format.`;
+    
+    const userPrompt = `Analyze this command failure:
+
+Command: ${contextWindow.command} ${contextWindow.args.join(' ')}
+Working Directory: ${contextWindow.cwd}
+Exit Code: ${contextWindow.exitCode}
+
+Error Output:
+${contextWindow.stderr.substring(0, 2000)}
+
+Standard Output:
+${contextWindow.stdout.substring(0, 1000)}
+
+Previous Commands:
+${contextWindow.previousCommands.slice(-3).map(c => `  ${c.command} ${c.args.join(' ')} (exit: ${c.exitCode})`).join('\n')}
+
+Repository Context:
+${repoMetadata.type ? `Type: ${repoMetadata.type}` : 'Unknown'}
+${repoMetadata.language ? `Language: ${repoMetadata.language}` : ''}
+${repoMetadata.files && repoMetadata.files.length > 0 ? `Relevant files: ${repoMetadata.files.slice(0, 5).join(', ')}` : ''}
+
+Provide 1-3 actionable suggestions in this JSON format:
+{
+  "suggestions": [
+    {
+      "title": "Short title",
+      "description": "Detailed explanation",
+      "actionableSnippet": "Code or command to fix",
+      "confidence": 0.0-1.0,
+      "type": "command|optimization|shortcut|warning|tip",
+      "priority": "low|medium|high"
+    }
+  ]
+}`;
+    
+    return [
+      { role: 'system', content: systemPrompt },
+      { role: 'user', content: userPrompt },
+    ];
+  }
+
+  private parseResponse(text: string, input: MCPToolInput, usage?: any): MCPToolOutput {
+    try {
+      const parsed = JSON.parse(text);
+      
+      // Convert to MCPToolOutput format
+      const suggestions = (parsed.suggestions || []).map((s: any) => ({
+        title: s.title || 'Suggestion',
+        description: s.description || '',
+        actionableSnippet: s.actionableSnippet,
+        confidence: Math.max(0, Math.min(1, s.confidence || 0.5)),
+        type: s.type || 'tip',
+        priority: s.priority || 'medium',
+      }));
+      
+      return {
+        suggestions,
+        provenance: {
+          provider: 'openai',
+          model: this.model,
+          timestamp: Date.now(),
+          tokensUsed: usage?.total_tokens,
+        },
+      };
+    } catch (error) {
+      // Fallback: create a generic suggestion
+      return {
+        suggestions: [{
+          title: 'LLM Analysis',
+          description: text.substring(0, 500),
+          confidence: 0.5,
+          type: 'tip',
+          priority: 'medium',
+        }],
+        provenance: {
+          provider: 'openai',
+          model: this.model,
+          timestamp: Date.now(),
+          tokensUsed: usage?.total_tokens,
+        },
+      };
+    }
+  }
+}
+

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

@@ -0,0 +1,170 @@
+// Context Sanitization for LLM Safety
+// Redacts secrets, tokens, and sensitive information before sending to LLM
+
+import type { AnalysisContext, SanitizedContext } from './types';
+
+/**
+ * Patterns to redact from context
+ */
+const SECRET_PATTERNS = [
+  // API keys and tokens
+  /\b[A-Za-z0-9]{32,}\b/g, // Long alphanumeric strings (likely tokens)
+  /\bghp_[A-Za-z0-9]{36,}\b/g, // GitHub personal access tokens
+  /\bgho_[A-Za-z0-9]{36,}\b/g, // GitHub OAuth tokens
+  /\bghu_[A-Za-z0-9]{36,}\b/g, // GitHub user-to-server tokens
+  /\bghs_[A-Za-z0-9]{36,}\b/g, // GitHub server-to-server tokens
+  /\bsk-[A-Za-z0-9]{32,}\b/g, // Stripe keys
+  /\bpk_[A-Za-z0-9]{32,}\b/g, // Stripe publishable keys
+  /\bAIza[0-9A-Za-z_-]{35}\b/g, // Google API keys
+  /\bAKIA[0-9A-Z]{16}\b/g, // AWS access keys
+  /\b[A-Za-z0-9/+=]{40}\b/g, // Base64 encoded secrets (40+ chars)
+  
+  // Environment variables that might contain secrets
+  /(?:password|passwd|pwd|secret|token|key|api_key|apikey|auth|credential)\s*=\s*['"]?([^'"\s]+)['"]?/gi,
+  
+  // Private keys
+  /-----BEGIN\s+(?:RSA\s+)?PRIVATE\s+KEY-----[\s\S]*?-----END\s+(?:RSA\s+)?PRIVATE\s+KEY-----/gi,
+  
+  // JWT tokens
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+];
+
+/**
+ * Redact a string, replacing secrets with placeholders
+ */
+function redactString(text: string): { sanitized: string; redactions: Array<{ pattern: string; replaced: string }> } {
+  let sanitized = text;
+  const redactions: Array<{ pattern: string; replaced: string }> = [];
+  
+  for (const pattern of SECRET_PATTERNS) {
+    const matches = text.matchAll(pattern);
+    for (const match of matches) {
+      if (match[0] && match.index !== undefined) {
+        const placeholder = `[REDACTED:${match[0].substring(0, 8)}...]`;
+        sanitized = sanitized.replace(match[0], placeholder);
+        redactions.push({
+          pattern: match[0],
+          replaced: placeholder,
+        });
+      }
+    }
+  }
+  
+  return { sanitized, redactions };
+}
+
+/**
+ * Sanitize environment variables
+ */
+function sanitizeEnv(env: Record<string, string>): { sanitized: Record<string, string>; redactions: Array<{ pattern: string; replaced: string }> } {
+  const sanitized: Record<string, string> = {};
+  const redactions: Array<{ pattern: string; replaced: string }> = [];
+  
+  for (const [key, value] of Object.entries(env)) {
+    const keyLower = key.toLowerCase();
+    // Redact common secret env vars
+    if (keyLower.includes('password') || 
+        keyLower.includes('secret') || 
+        keyLower.includes('token') || 
+        keyLower.includes('key') ||
+        keyLower.includes('credential') ||
+        keyLower.includes('api_key')) {
+      sanitized[key] = '[REDACTED]';
+      redactions.push({
+        pattern: `${key}=${value}`,
+        replaced: `${key}=[REDACTED]`,
+      });
+    } else {
+      // Still check value for secrets
+      const { sanitized: sanitizedValue, redactions: valueRedactions } = redactString(value);
+      sanitized[key] = sanitizedValue;
+      redactions.push(...valueRedactions.map(r => ({
+        pattern: r.pattern,
+        replaced: r.replaced,
+      })));
+    }
+  }
+  
+  return { sanitized, redactions };
+}
+
+/**
+ * Sanitize analysis context
+ */
+export function sanitizeContext(context: AnalysisContext): SanitizedContext {
+  // Sanitize environment
+  const { sanitized: sanitizedEnv, redactions: envRedactions } = sanitizeEnv(context.env);
+  
+  // Sanitize stdout and stderr
+  const { sanitized: sanitizedStdout, redactions: stdoutRedactions } = redactString(context.stdout);
+  const { sanitized: sanitizedStderr, redactions: stderrRedactions } = redactString(context.stderr);
+  
+  // Sanitize command args (might contain secrets)
+  const sanitizedArgs = context.args.map(arg => {
+    const { sanitized } = redactString(arg);
+    return sanitized;
+  });
+  
+  const sanitized: AnalysisContext = {
+    ...context,
+    env: sanitizedEnv,
+    stdout: sanitizedStdout,
+    stderr: sanitizedStderr,
+    args: sanitizedArgs,
+  };
+  
+  const redactions = [
+    ...envRedactions.map(r => ({ ...r, type: 'env' as const })),
+    ...stdoutRedactions.map(r => ({ ...r, type: 'stdout' as const })),
+    ...stderrRedactions.map(r => ({ ...r, type: 'stderr' as const })),
+  ];
+  
+  return {
+    original: context,
+    sanitized,
+    redactions,
+  };
+}
+
+/**
+ * Format sanitized context for user review
+ */
+export function formatContextForReview(sanitized: SanitizedContext): string {
+  const lines: string[] = [];
+  
+  lines.push('=== Context to be sent to LLM ===\n');
+  lines.push(`Command: ${sanitized.sanitized.command} ${sanitized.sanitized.args.join(' ')}`);
+  lines.push(`CWD: ${sanitized.sanitized.cwd}`);
+  lines.push(`Exit Code: ${sanitized.sanitized.exitCode}\n`);
+  
+  if (sanitized.sanitized.stderr) {
+    lines.push(`Stderr (${sanitized.sanitized.stderr.length} chars):`);
+    lines.push(sanitized.sanitized.stderr.substring(0, 500));
+    if (sanitized.sanitized.stderr.length > 500) {
+      lines.push('... (truncated)');
+    }
+    lines.push('');
+  }
+  
+  if (sanitized.sanitized.stdout) {
+    lines.push(`Stdout (${sanitized.sanitized.stdout.length} chars):`);
+    lines.push(sanitized.sanitized.stdout.substring(0, 500));
+    if (sanitized.sanitized.stdout.length > 500) {
+      lines.push('... (truncated)');
+    }
+    lines.push('');
+  }
+  
+  if (sanitized.redactions.length > 0) {
+    lines.push(`\n=== Redactions Applied (${sanitized.redactions.length}) ===`);
+    for (const redaction of sanitized.redactions.slice(0, 10)) {
+      lines.push(`  [${redaction.type}] ${redaction.pattern.substring(0, 50)}... → ${redaction.replaced}`);
+    }
+    if (sanitized.redactions.length > 10) {
+      lines.push(`  ... and ${sanitized.redactions.length - 10} more`);
+    }
+  }
+  
+  return lines.join('\n');
+}
+