@plures/runebook 0.4.0

package/docs/demo.md

@@ -0,0 +1,338 @@
+# RuneBook Ambient Agent Mode - "Zero to Hero" Demo
+
+This walkthrough demonstrates RuneBook's Ambient Agent Mode from setup to analysis, showing how it captures terminal commands, analyzes failures, and provides intelligent suggestions.
+
+## Prerequisites
+
+- Node.js 20.x or higher
+- RuneBook installed (or development environment)
+- Nix installed (for demo commands that will fail)
+- Terminal access
+
+## Demo Overview
+
+This demo will:
+1. Enable Ambient Agent Mode
+2. Run a few failing Nix commands
+3. Show RuneBook capturing the events
+4. Display analysis results and suggestions
+5. Show how to inspect and manage stored data
+
+## Step 1: Enable Ambient Agent Mode
+
+First, enable the agent:
+
+```bash
+npm run agent enable
+npm run agent status
+```
+
+You should see:
+```
+=== Ambient Agent Status ===
+
+Enabled: Yes
+Capture Events: Yes
+Analyze Patterns: Yes
+Suggest Improvements: Yes
+Storage Path: Memory (in-memory)
+...
+```
+
+## Step 2: Run Failing Commands
+
+Now let's run some commands that will fail. These are common Nix development errors:
+
+### Command 1: Missing Attribute Error
+
+```bash
+nix build .#cursor
+```
+
+This will likely fail with an error like:
+```
+error: attribute 'cursor' missing
+```
+
+### Command 2: Flake-Parts Template Path Error
+
+```bash
+nix flake init -t flake-parts#devShells
+```
+
+This might fail with:
+```
+error: path '/nix/store/.../devShells' does not exist
+```
+
+### Command 3: Build Environment Font Conflict
+
+```bash
+nix build .#packages.x86_64-linux.default
+```
+
+This might fail with font-related errors in buildEnv.
+
+## Step 3: View Captured Events
+
+Check what RuneBook captured:
+
+```bash
+npm run agent events 10
+```
+
+You should see output like:
+```
+=== Recent Events (3) ===
+
+✗ [2024-12-27 10:30:15] nix build .#cursor
+   Duration: 2.34s, Exit Code: 1
+   CWD: /home/user/projects/myproject
+
+✗ [2024-12-27 10:30:20] nix flake init -t flake-parts#devShells
+   Duration: 1.89s, Exit Code: 1
+   CWD: /home/user/projects/myproject
+
+✗ [2024-12-27 10:30:25] nix build .#packages.x86_64-linux.default
+   Duration: 15.67s, Exit Code: 1
+   CWD: /home/user/projects/myproject
+```
+
+## Step 4: Analyze Last Failure
+
+Analyze the most recent failure:
+
+```bash
+npm run analyze last
+```
+
+You should see detailed analysis:
+
+```
+=== Analysis Results ===
+
+Command: nix build .#cursor
+Exit Code: 1
+Status: completed
+CWD: /home/user/projects/myproject
+
+Stderr:
+error: attribute 'cursor' missing
+...
+
+=== Suggestions (2) ===
+
+[NixErrorAnalyzer] Missing Attribute "cursor" (confidence: 90%)
+  The attribute "cursor" is missing from your flake outputs or packages.
+  
+  Check your flake.nix file and ensure the attribute exists:
+  
+  outputs = { self, nixpkgs, ... }: {
+    packages.x86_64-linux.cursor = ...;
+    # or
+    packages.cursor = ...;
+  };
+
+[LocalSearchAnalyzer] Check flake.nix for available attributes (confidence: 75%)
+  Your flake.nix might have similar attributes. Check the file for available options.
+  
+  grep -r "packages\|outputs" flake.nix
+```
+
+## Step 5: View All Suggestions
+
+See all current suggestions:
+
+```bash
+npm run agent suggestions
+```
+
+Output:
+```
+=== Suggestions ===
+
+[high] Missing Attribute "cursor"
+  The attribute "cursor" is missing from your flake outputs.
+  Confidence: 90%
+
+[medium] Check flake.nix for available attributes
+  Your flake.nix might have similar attributes.
+  Confidence: 75%
+
+[low] Consider using nix search for available packages
+  Use 'nix search' to find available packages.
+  Confidence: 60%
+```
+
+## Step 6: Inspect Memory Storage
+
+If using PluresDB, inspect the cognitive memory:
+
+```bash
+npm run memory inspect
+```
+
+Output:
+```
+=== RuneBook Cognitive Memory ===
+
+Sessions: 1
+Recent Errors: 3
+Active Suggestions: 3
+
+=== Recent Sessions ===
+  abc12345... - bash (started: 12/27/2024, 10:30:00 AM)
+
+=== Recent Errors ===
+  [high] exit_code - error: attribute 'cursor' missing
+  [high] exit_code - path '/nix/store/.../devShells' does not exist
+  [medium] exit_code - font conflict in buildEnv
+
+=== Top Suggestions ===
+  [high] Missing Attribute "cursor" - The attribute "cursor" is missing...
+  [medium] Check flake.nix for available attributes - Your flake.nix might...
+  [low] Consider using nix search - Use 'nix search' to find...
+```
+
+## Step 7: View Agent Statistics
+
+Check overall agent statistics:
+
+```bash
+npm run agent status
+```
+
+Output:
+```
+=== Ambient Agent Status ===
+
+Enabled: Yes
+Capture Events: Yes
+Analyze Patterns: Yes
+Suggest Improvements: Yes
+Storage Path: Memory (in-memory)
+Max Events: Unlimited
+Retention Days: 30
+
+=== Statistics ===
+Total Events: 3
+Unique Commands: 3
+Average Success Rate: 0.0%
+Total Duration: 20.0s
+```
+
+## Step 8: Observer Mode (Optional)
+
+For more detailed event capture, enable the observer:
+
+```bash
+npm run observer enable
+npm run observer status
+```
+
+Then tail events in real-time:
+
+```bash
+npm run observer events tail
+```
+
+In another terminal, run a command:
+```bash
+nix build .#test
+```
+
+You'll see events stream in:
+```
+[2024-12-27T10:35:00.000Z] command_start   nix build .#test
+  CWD: /home/user/projects/myproject
+[2024-12-27T10:35:02.000Z] stdout_chunk     [0] building...
+[2024-12-27T10:35:05.000Z] exit_status      exitCode: 1, success: false
+```
+
+## Step 9: Clean Up Data
+
+Clear old events (optional):
+
+```bash
+# Clear events older than 7 days
+npm run agent clear 7
+
+# Or clear all events older than 30 days (default)
+npm run agent clear
+```
+
+## Troubleshooting
+
+### Agent not capturing events
+
+1. Check if agent is enabled:
+   ```bash
+   npm run agent status
+   ```
+
+2. Verify configuration:
+   ```bash
+   cat ~/.runebook/agent-config.json
+   ```
+
+3. Ensure `captureEvents: true` in config
+
+### No suggestions appearing
+
+1. Run some commands first (agent needs data to analyze)
+2. Check for failures:
+   ```bash
+   npm run agent events 20
+   ```
+3. Run analysis:
+   ```bash
+   npm run analyze last
+   ```
+
+### PluresDB not available
+
+If you see "PluresDB server not available":
+
+1. Check if PluresDB is running:
+   ```bash
+   curl http://localhost:34567/health
+   ```
+
+2. Start PluresDB:
+   ```bash
+   pluresdb --port 34567
+   ```
+
+3. Or use in-memory storage (default):
+   - The agent works fine with in-memory storage
+   - Data will be lost on restart, but it's fine for testing
+
+### Analysis not working
+
+1. Ensure observer is enabled:
+   ```bash
+   npm run observer status
+   ```
+
+2. Check that commands are being captured:
+   ```bash
+   npm run observer events 10
+   ```
+
+3. Verify analysis service is initialized (check logs)
+
+## Next Steps
+
+- **Read the documentation**: See [README.md](../README.md) for full feature list
+- **Explore analysis ladder**: See [ANALYSIS_LADDER.md](../ANALYSIS_LADDER.md) for analysis details
+- **Check architecture**: See [ARCHITECTURE.md](../ARCHITECTURE.md) for technical details
+- **Review memory schema**: See [MEMORY.md](../MEMORY.md) for storage details
+
+## Demo Script
+
+For an automated version of this demo, run:
+
+```bash
+bash scripts/demo.sh
+```
+

package/docs/llm-integration.md

@@ -0,0 +1,300 @@
+# LLM/MCP Integration
+
+RuneBook supports optional model-backed reasoning via LLM providers or MCP (Model Context Protocol). This feature is **disabled by default** and must be explicitly enabled in configuration.
+
+## Overview
+
+The LLM integration provides intelligent suggestions for command failures by analyzing:
+- Command context (command, args, working directory)
+- Error output (stderr, stdout)
+- Previous commands
+- Repository metadata
+
+All LLM analysis is **suggestion-only** - it never executes commands automatically.
+
+## Safety Features
+
+### Context Sanitization
+Before sending context to an LLM, RuneBook automatically redacts:
+- API keys and tokens (GitHub tokens, OpenAI keys, AWS keys, etc.)
+- Environment variables containing secrets
+- Private keys
+- JWT tokens
+- Long alphanumeric strings that look like tokens
+
+### User Review
+By default, the sanitized context is shown to the user before sending to the LLM. This can be disabled in configuration, but is recommended for privacy.
+
+### Caching (Optional)
+Responses can be cached to reduce API calls and costs. Cache TTL is configurable.
+
+### Never Auto-Execute
+LLM suggestions are **never executed automatically**. They are only displayed as suggestions that the user can review and apply manually.
+
+## Configuration
+
+### Basic Configuration
+
+Add LLM configuration to your observer config file (`~/.runebook/observer-config.json`):
+
+```json
+{
+  "enabled": true,
+  "redactSecrets": true,
+  "llm": {
+    "type": "ollama",
+    "enabled": true,
+    "ollama": {
+      "model": "llama3.2",
+      "baseUrl": "http://localhost:11434"
+    },
+    "safety": {
+      "requireUserReview": true,
+      "cacheEnabled": false,
+      "cacheTtl": 3600
+    }
+  }
+}
+```
+
+### Provider Types
+
+#### Ollama (Local)
+Runs models locally via Ollama. No API keys required.
+
+```json
+{
+  "llm": {
+    "type": "ollama",
+    "enabled": true,
+    "ollama": {
+      "model": "llama3.2",
+      "baseUrl": "http://localhost:11434"
+    }
+  }
+}
+```
+
+**Requirements:**
+- Ollama installed and running (`ollama serve`)
+- Model pulled (`ollama pull llama3.2`)
+
+#### OpenAI
+Uses OpenAI API. Requires API key.
+
+```json
+{
+  "llm": {
+    "type": "openai",
+    "enabled": true,
+    "openai": {
+      "model": "gpt-4o-mini",
+      "apiKey": "${OPENAI_API_KEY}"
+    }
+  }
+}
+```
+
+**Requirements:**
+- `OPENAI_API_KEY` environment variable set
+- Or provide `apiKey` in config (less secure)
+
+#### Mock (Testing)
+Returns deterministic responses for testing.
+
+```json
+{
+  "llm": {
+    "type": "mock",
+    "enabled": true
+  }
+}
+```
+
+#### MCP (Future)
+MCP provider support is planned but not yet implemented.
+
+### Safety Configuration
+
+```json
+{
+  "safety": {
+    "requireUserReview": true,    // Show context before sending (default: true)
+    "maxContextLength": 8000,      // Truncate if too long (default: 8000 tokens)
+    "cacheEnabled": false,        // Cache responses (default: false)
+    "cacheTtl": 3600              // Cache TTL in seconds (default: 3600)
+  }
+}
+```
+
+## CLI Commands
+
+### Check LLM Status
+
+```bash
+runebook llm status
+```
+
+Shows:
+- Provider type and availability
+- Configuration settings
+- Safety settings
+- Provider-specific configuration
+
+## Privacy Considerations
+
+### What Data is Sent
+
+When LLM analysis is enabled, the following data may be sent to the LLM provider:
+- Command and arguments (sanitized)
+- Working directory
+- Error output (stderr, sanitized)
+- Standard output (stdout, sanitized)
+- Previous commands (last 3-5)
+- Repository metadata (type, language, relevant files)
+
+### What is NOT Sent
+
+- Full environment variables (only sanitized summary)
+- Secrets, tokens, API keys (redacted)
+- Full file contents (only metadata)
+- Personal information (if present in commands, may be included)
+
+### Data Retention
+
+- **Ollama (Local)**: Data never leaves your machine
+- **OpenAI**: Data is sent to OpenAI's API. Check OpenAI's privacy policy for data retention.
+- **Mock**: No external calls, only for testing
+
+### Recommendations
+
+1. **Use Ollama for maximum privacy** - All processing happens locally
+2. **Enable user review** - Review context before sending
+3. **Review sanitization** - Check what was redacted before sending
+4. **Disable if sensitive** - If working with highly sensitive data, disable LLM analysis
+
+## MCP Tool Contract
+
+The LLM integration uses a standardized contract for communication:
+
+### Input
+
+```typescript
+{
+  contextWindow: {
+    command: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>; // Sanitized
+    exitCode: number;
+    stdout: string; // Sanitized
+    stderr: string; // Sanitized
+    previousCommands: Array<{...}>;
+  };
+  errorSummary: {
+    command: string;
+    args: string[];
+    exitCode: number;
+    stderr: string;
+    stdout: string;
+    cwd: string;
+    timestamp: number;
+  };
+  repoMetadata: {
+    root?: string;
+    type?: 'git' | 'hg' | 'svn' | 'none';
+    files?: string[];
+    language?: string;
+    framework?: string;
+  };
+}
+```
+
+### Output
+
+```typescript
+{
+  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;
+    model?: string;
+    timestamp: number;
+    tokensUsed?: number;
+  };
+}
+```
+
+## Troubleshooting
+
+### Ollama Not Available
+
+```
+Error: Ollama provider is not available
+```
+
+**Solution:**
+1. Make sure Ollama is running: `ollama serve`
+2. Check if the model is installed: `ollama list`
+3. Pull the model if needed: `ollama pull llama3.2`
+4. Verify base URL in config matches Ollama's port
+
+### OpenAI API Key Missing
+
+```
+Error: OpenAI API key not found
+```
+
+**Solution:**
+1. Set `OPENAI_API_KEY` environment variable: `export OPENAI_API_KEY=sk-...`
+2. Or provide `apiKey` in config (less secure)
+
+### Provider Not Responding
+
+If the provider times out or fails:
+1. Check network connectivity (for OpenAI)
+2. Check provider logs (for Ollama)
+3. Try disabling and re-enabling LLM analysis
+4. Check `runebook llm status` for detailed error messages
+
+## Examples
+
+### Example: Nix Build Error
+
+When a Nix build fails, the LLM analyzer receives:
+- Command: `nix build`
+- Error: Missing attribute "cursor"
+- Repository: Nix flake with `flake.nix`
+
+The LLM might suggest:
+- Check if the attribute exists in the flake
+- Verify the input source
+- Check for typos in attribute names
+
+### Example: Git Authentication Error
+
+When Git authentication fails:
+- Command: `git push`
+- Error: Authentication failed
+- Repository: Git repository
+
+The LLM might suggest:
+- Check if credentials are configured
+- Verify SSH key or token
+- Check GitHub rate limits
+
+## Future Enhancements
+
+- [ ] MCP protocol support
+- [ ] Additional providers (Anthropic, local models)
+- [ ] Fine-tuned models for specific error types
+- [ ] Context window optimization
+- [ ] Streaming responses
+- [ ] Multi-model ensemble
+