enya-agent 0.1.0

package/docs/content/memory/_index.md

@@ -0,0 +1,163 @@
++++
+title = "Memory"
+weight = 9
++++
+
+# Memory System
+
+The `enact-memory` crate provides local-first memory backends for agents with semantic search capabilities.
+
+## Backends
+
+| Backend | Description | Use Case |
+|---------|-------------|----------|
+| `sqlite` | SQLite with FTS5 full-text search | Production, persistent storage |
+| `markdown` | Markdown files in workspace | Development, version control |
+| `none` | No persistence | Testing, stateless agents |
+
+## Features
+
+### Core Memory Operations
+
+```rust
+use enact_memory::{create_memory, MemoryCategory};
+
+let memory = create_memory("sqlite", workspace_path)?;
+
+// Store a memory
+memory.store("user_preference", "prefers dark mode", MemoryCategory::Core, None).await?;
+
+// Recall memories (keyword search)
+let results = memory.recall("dark mode", 10, None).await?;
+
+// Get specific memory
+let entry = memory.get("user_preference").await?;
+
+// List all memories in a category
+let all_core = memory.list(Some(&MemoryCategory::Core), None).await?;
+
+// Forget a memory
+memory.forget("user_preference").await?;
+```
+
+### Memory Categories
+
+| Category | Purpose |
+|----------|---------|
+| `Core` | Long-term facts, preferences, decisions |
+| `Daily` | Session logs, daily context |
+| `Conversation` | Current conversation context |
+| `Custom(name)` | User-defined categories |
+
+### Embeddings for Semantic Search
+
+The memory system supports embeddings for semantic similarity search:
+
+```rust
+use enact_memory::{create_embedding_provider, cosine_similarity};
+
+// Create an embedding provider
+let provider = create_embedding_provider(
+    "openai",
+    Some(&api_key),
+    "text-embedding-3-small",
+    1536
+);
+
+// Embed text
+let embedding = provider.embed_one("Hello world").await?;
+
+// Compare embeddings
+let similarity = cosine_similarity(&embedding_a, &embedding_b);
+```
+
+#### Supported Providers
+
+| Provider | Model | Dimensions |
+|----------|-------|------------|
+| `openai` | text-embedding-3-small | 1536 |
+| `openai` | text-embedding-3-large | 3072 |
+| `custom:URL` | Any OpenAI-compatible | Configurable |
+| `none` | N/A (keyword-only) | 0 |
+
+### Text Chunking
+
+For large documents, use the chunker to split into semantic chunks:
+
+```rust
+use enact_memory::chunk_markdown;
+
+let chunks = chunk_markdown(document_text, 512); // 512 tokens per chunk
+
+for chunk in chunks {
+    println!("Chunk {}: {}", chunk.index, chunk.content);
+    if let Some(heading) = chunk.heading {
+        println!("  Under heading: {}", heading);
+    }
+}
+```
+
+The chunker:
+- Splits on markdown headings (`#`, `##`, `###`)
+- Falls back to paragraph boundaries
+- Then to line boundaries
+- Preserves heading context in each chunk
+
+### Hybrid Search (Vector + Keyword)
+
+Combine semantic and keyword search for best results:
+
+```rust
+use enact_memory::hybrid_merge;
+
+let vector_results = vec![("doc1".into(), 0.9), ("doc2".into(), 0.7)];
+let keyword_results = vec![("doc2".into(), 10.0), ("doc3".into(), 5.0)];
+
+let merged = hybrid_merge(
+    &vector_results,
+    &keyword_results,
+    0.7,  // vector weight
+    0.3,  // keyword weight
+    10    // limit
+);
+
+for result in merged {
+    println!("{}: final_score={}", result.id, result.final_score);
+}
+```
+
+### Vector Operations
+
+```rust
+use enact_memory::{vec_to_bytes, bytes_to_vec};
+
+// Serialize for storage
+let bytes = vec_to_bytes(&embedding);
+
+// Deserialize
+let restored = bytes_to_vec(&bytes);
+```
+
+## Configuration
+
+```yaml
+# In agent config
+memory:
+  backend: sqlite  # sqlite, markdown, none
+  embeddings:
+    provider: openai
+    model: text-embedding-3-small
+    dimensions: 1536
+```
+
+## Session Scoping
+
+Memories can be scoped to sessions for conversation context:
+
+```rust
+// Store with session
+memory.store("topic", "discussing rust", MemoryCategory::Conversation, Some("session-123")).await?;
+
+// Recall within session
+let results = memory.recall("rust", 10, Some("session-123")).await?;
+```

package/docs/content/oauth/_index.md

@@ -0,0 +1,515 @@
++++
+title = "OAuth Authentication"
+weight = 16
++++
+
+# OAuth Authentication
+
+The `enact-oauth` crate provides OAuth 2.0 authentication with device-code flow, enabling secure authentication with OpenAI and other providers without storing API keys in environment variables.
+
+## Overview
+
+OAuth support includes:
+
+- **Device-code flow** - User-friendly authentication via browser
+- **PKCE support** - Secure code exchange
+- **Token refresh** - Automatic access token renewal
+- **Local storage** - Secure token storage on disk
+- **Account ID extraction** - JWT token parsing
+
+## Supported Providers
+
+| Provider | Flow | Status |
+|----------|------|--------|
+| OpenAI | Device-code | ✅ Complete |
+| Anthropic | OAuth 2.0 | ✅ Supported via generic flow |
+| Custom | OAuth 2.0 | ✅ Supported |
+
+## Quick Start
+
+### Device-Code Flow (Recommended)
+
+```rust
+use enact_oauth::{start_device_code_flow, poll_device_code_tokens};
+use reqwest::Client;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let client = Client::new();
+    
+    // Step 1: Start device-code flow
+    let device = start_device_code_flow(&client).await?;
+    
+    println!("Go to: {}", device.verification_uri);
+    println!("Enter code: {}", device.user_code);
+    println!("Expires in: {} seconds", device.expires_in);
+    
+    // Step 2: Poll for tokens
+    // User must visit URL and enter code in their browser
+    let tokens = poll_device_code_tokens(&client, &device).await?;
+    
+    println!("Access token: {}", tokens.access_token);
+    println!("Refresh token: {:?}", tokens.refresh_token);
+    println!("Expires at: {:?}", tokens.expires_at);
+    
+    // Step 3: Save tokens securely
+    // See Token Storage section below
+    
+    Ok(())
+}
+```
+
+### User Experience
+
+```
+$ enact login
+
+To authenticate with OpenAI:
+
+1. Visit: https://auth.openai.com/device
+2. Enter code: ABCD-EFGH
+
+Waiting for authentication...
+✓ Successfully authenticated!
+Account ID: user-abc123
+```
+
+## Token Types
+
+### TokenSet
+
+```rust
+use enact_oauth::TokenSet;
+
+let tokens = TokenSet {
+    access_token: "eyJhbG...".to_string(),
+    refresh_token: Some("dGhpcyBpcyBh...".to_string()),
+    id_token: Some("eyJhbG...".to_string()),
+    expires_at: Some(chrono::Utc::now() + chrono::Duration::hours(1)),
+    token_type: Some("Bearer".to_string()),
+    scope: Some("openid profile".to_string()),
+};
+
+// Check if token is expiring soon
+let expiring = tokens.is_expiring_within(Duration::from_secs(300));
+```
+
+## Token Refresh
+
+Automatically refresh access tokens:
+
+```rust
+use enact_oauth::refresh_access_token;
+
+async fn get_valid_token(client: &Client) -> anyhow::Result<String> {
+    let tokens = load_stored_tokens()?; // Your storage function
+    
+    // Check if token needs refresh
+    if tokens.is_expiring_within(Duration::from_secs(300)) {
+        if let Some(refresh_token) = &tokens.refresh_token {
+            let new_tokens = refresh_access_token(client, refresh_token).await?;
+            
+            // Save new tokens
+            save_tokens(&new_tokens)?;
+            
+            return Ok(new_tokens.access_token);
+        }
+    }
+    
+    Ok(tokens.access_token)
+}
+```
+
+## Token Storage
+
+### Local File Storage
+
+```rust
+use enact_oauth::TokenStorage;
+use std::path::Path;
+
+// Create storage
+let storage = TokenStorage::new(Path::new("~/.config/enact/tokens"));
+
+// Save tokens
+storage.save_token(
+    "openai",      // provider
+    "default",     // profile name
+    &tokens
+)?;
+
+// Load tokens
+if let Some(tokens) = storage.load_token("openai", "default")? {
+    println!("Access token: {}", tokens.access_token);
+}
+```
+
+### Secure Storage (Recommended)
+
+```rust
+use enact_oauth::TokenStorage;
+use std::path::PathBuf;
+
+fn get_token_dir() -> PathBuf {
+    dirs::config_dir()
+        .expect("Could not find config directory")
+        .join("enact")
+        .join("tokens")
+}
+
+let storage = TokenStorage::new(&get_token_dir());
+
+// Tokens are stored as JSON files:
+// ~/.config/enact/tokens/openai_default.json
+```
+
+## PKCE (Proof Key for Code Exchange)
+
+PKCE adds security to OAuth flows:
+
+```rust
+use enact_oauth::{generate_pkce_state, build_authorize_url};
+
+// Generate PKCE parameters
+let pkce = generate_pkce_state();
+
+println!("Code verifier: {}", pkce.code_verifier);
+println!("Code challenge: {}", pkce.code_challenge);
+println!("State: {}", pkce.state);
+
+// Build authorization URL
+let auth_url = build_authorize_url(&pkce);
+println!("Open this URL: {}", auth_url);
+
+// After user authorizes, exchange code for tokens
+let tokens = exchange_code_for_tokens(&client, &code, &pkce
+).await?;
+```
+
+## Complete Example
+
+```rust
+use enact_oauth::*;
+use reqwest::Client;
+use std::path::Path;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let client = Client::new();
+    let storage = TokenStorage::new(Path::new("~/.config/enact/tokens"));
+    
+    // Try to load existing token
+    if let Some(tokens) = storage.load_token("openai", "default")? {
+        if !tokens.is_expiring_within(Duration::from_secs(300)) {
+            println!("Using cached token");
+            return Ok(());
+        }
+        
+        // Try to refresh
+        if let Some(refresh) = &tokens.refresh_token {
+            match refresh_access_token(&client, refresh).await {
+                Ok(new_tokens) => {
+                    storage.save_token("openai", "default", &new_tokens)?;
+                    println!("Token refreshed successfully");
+                    return Ok(());
+                }
+                Err(e) => {
+                    eprintln!("Refresh failed: {}, starting new auth flow", e);
+                }
+            }
+        }
+    }
+    
+    // Start new device-code flow
+    let device = start_device_code_flow(&client).await?;
+    
+    println!("\n=== Authentication Required ===");
+    println!("Visit: {}", device.verification_uri);
+    println!("Code: {}", device.user_code);
+    println!("Expires in {} seconds\n", device.expires_in);
+    
+    // Poll for completion
+    let tokens = poll_device_code_tokens(&client, &device).await?;
+    
+    // Extract account info
+    if let Some(account_id) = extract_account_id_from_jwt(&tokens.access_token) {
+        println!("Authenticated as: {}", account_id);
+    }
+    
+    // Save tokens
+    storage.save_token("openai", "default", &tokens)?;
+    println!("Tokens saved successfully");
+    
+    Ok(())
+}
+```
+
+## CLI Integration
+
+```rust
+// In your CLI
+#[derive(Subcommand)]
+enum Commands {
+    /// Authenticate with a provider
+    Login {
+        /// Provider name (openai, anthropic)
+        #[arg(default_value = "openai")]
+        provider: String,
+        
+        /// Profile name
+        #[arg(default_value = "default")]
+        profile: String,
+    },
+    
+    /// List authenticated profiles
+    Profiles,
+    
+    /// Remove authentication
+    Logout {
+        provider: String,
+        profile: String,
+    },
+}
+
+async fn login(provider: &str, profile: &str) -> anyhow::Result<()> {
+    let client = Client::new();
+    let storage = TokenStorage::new(&get_token_dir());
+    
+    match provider {
+        "openai" => {
+            let device = start_device_code_flow(&client).await?;
+            
+            println!("Go to: {}", device.verification_uri);
+            println!("Enter code: {}", device.user_code);
+            
+            let tokens = poll_device_code_tokens(&client, &device).await?;
+            storage.save_token(provider, profile, &tokens)?;
+            
+            println!("✓ Successfully authenticated with OpenAI");
+        }
+        _ => anyhow::bail!("Unsupported provider: {}", provider),
+    }
+    
+    Ok(())
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Token storage directory
+export ENACT_TOKEN_DIR="$HOME/.config/enact/tokens"
+
+# Default provider
+export ENACT_DEFAULT_PROVIDER="openai"
+
+# Provider-specific settings
+export ENACT_OPENAI_CLIENT_ID="app_EMoamEEZ73f0CkXaXp7hrann"
+```
+
+### YAML Configuration
+
+```yaml
+# config.yaml
+oauth:
+  default_provider: openai
+  
+  providers:
+    openai:
+      client_id: "app_EMoamEEZ73f0CkXaXp7hrann"
+      authorize_url: "https://auth.openai.com/oauth/authorize"
+      token_url: "https://auth.openai.com/oauth/token"
+      device_code_url: "https://auth.openai.com/oauth/device/code"
+      
+    anthropic:
+      client_id: "your-client-id"
+      authorize_url: "https://auth.anthropic.com/oauth/authorize"
+      token_url: "https://auth.anthropic.com/oauth/token"
+  
+  storage:
+    type: file
+    path: "~/.config/enact/tokens"
+```
+
+## Security Considerations
+
+### Token Storage
+
+- ✅ Tokens stored in user's home directory
+- ✅ File permissions should be `600` (user read/write only)
+- ✅ Never commit tokens to version control
+- ✅ Use OS keychain when available (future enhancement)
+
+```rust
+// Set restrictive permissions (Unix)
+#[cfg(unix)]
+use std::os::unix::fs::PermissionsExt;
+
+let mut perms = std::fs::metadata(&token_path)?.permissions();
+perms.set_mode(0o600);
+std::fs::set_permissions(&token_path, perms)?;
+```
+
+### Token Lifecycle
+
+1. **Short-lived access tokens** (typically 1 hour)
+2. **Long-lived refresh tokens** (can be revoked)
+3. **Automatic refresh** before expiration
+4. **Secure storage** with proper permissions
+
+### Best Practices
+
+```rust
+// 1. Always check token expiration
+if tokens.is_expiring_within(Duration::from_secs(300)) {
+    // Refresh token
+}
+
+// 2. Handle refresh failures gracefully
+match refresh_access_token(&client, refresh_token).await {
+    Ok(new_tokens) => { /* use new tokens */ }
+    Err(_) => {
+        // Start new auth flow
+        initiate_device_code_flow().await?;
+    }
+}
+
+// 3. Never log tokens
+// ❌ BAD
+println!("Token: {}", tokens.access_token);
+
+// ✅ GOOD
+println!("Token obtained successfully");
+```
+
+## Testing
+
+```bash
+# Run OAuth tests
+cargo test -p enact-oauth
+
+# Run with output
+cargo test -p enact-oauth -- --nocapture
+```
+
+### Mock Testing
+
+```rust
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    #[test]
+    fn test_pkce_generation() {
+        let pkce = generate_pkce_state();
+        assert!(!pkce.code_verifier.is_empty());
+        assert!(!pkce.code_challenge.is_empty());
+        assert!(!pkce.state.is_empty());
+    }
+    
+    #[test]
+    fn test_parse_redirect_url() {
+        let code = parse_code_from_redirect(
+            "http://localhost:1455/auth/callback?code=abc123&state=xyz",
+            Some("xyz"),
+        ).unwrap();
+        assert_eq!(code, "abc123");
+    }
+    
+    #[test]
+    fn test_extract_account_from_jwt() {
+        let jwt = "eyJhbG..."; // Valid JWT with account_id claim
+        let account = extract_account_id_from_jwt(jwt);
+        assert!(account.is_some());
+    }
+}
+```
+
+## Troubleshooting
+
+### "Device code expired"
+
+The user didn't complete authentication in time:
+
+```rust
+match poll_device_code_tokens(&client, &device).await {
+    Ok(tokens) => { /* success */ }
+    Err(e) if e.to_string().contains("expired") => {
+        println!("Authentication timed out. Please try again.");
+    }
+    Err(e) => {
+        eprintln!("Authentication failed: {}", e);
+    }
+}
+```
+
+### "Access denied"
+
+User denied the authorization request:
+
+```rust
+Err(e) if e.to_string().contains("access_denied") => {
+    println!("Authorization was denied by user.");
+}
+```
+
+### Token refresh failing
+
+Refresh token may be revoked or expired:
+
+```rust
+match refresh_access_token(&client, refresh_token).await {
+    Ok(tokens) => { /* success */ }
+    Err(_) => {
+        // Clear stored tokens and re-authenticate
+        storage.remove_token("openai", "default")?;
+        println!("Please run 'enact login' again.");
+    }
+}
+```
+
+## Provider-Specific Notes
+
+### OpenAI
+
+- Client ID: `app_EMoamEEZ73f0CkXaXp7hrann` (fixed)
+- Device-code flow: Supported ✅
+- PKCE: Supported ✅
+- Scopes: `openid profile email offline_access`
+- Account ID: Extractable from JWT claims
+
+### Anthropic
+
+- Requires separate OAuth application registration
+- Client ID provided after registration
+- Same flow as OpenAI with different endpoints
+
+## Comparison: OAuth vs API Keys
+
+| Feature | OAuth | API Keys |
+|---------|-------|----------|
+| **Security** | ✅ Token rotation, limited scope | ⚠️ Single key, full access |
+| **User Experience** | 🔐 Browser auth, no copy-paste | ⌨️ Manual key management |
+| **Revocation** | ✅ Can revoke without changing code | ❌ Must regenerate and update |
+| **Expiration** | ✅ Short-lived tokens | ❌ Never expires (risky) |
+| **Setup Complexity** | Medium (one-time browser auth) | Low (copy-paste key) |
+| **CI/CD** | ⚠️ Requires token storage | ✅ Simple env var |
+
+**Recommendation**: Use OAuth for interactive usage, API keys for CI/CD.
+
+## Future Enhancements
+
+- [ ] OS keychain integration (macOS Keychain, Windows Credential Manager, Linux Secret Service)
+- [ ] Browser-based OAuth flow (authorization code)
+- [ ] Multiple profile support
+- [ ] Token encryption at rest
+- [ ] Automatic background refresh
+- [ ] Provider discovery (OIDC)
+
+## Resources
+
+- [enact-oauth crate](/docs/crates/enact-oauth/)
+- [OAuth 2.0 Device Authorization Grant (RFC 8628)](https://tools.ietf.org/html/rfc8628)
+- [PKCE (RFC 7636)](https://tools.ietf.org/html/rfc7636)