enya-agent 0.1.0

package/docs/content/providers/_index.md

@@ -0,0 +1,206 @@
++++
+title = "Providers"
+weight = 5
+sort_by = "weight"
++++
+
+# LLM Providers
+
+Enact supports multiple LLM providers through the `enact-providers` crate.
+
+## Supported Providers
+
+| Provider | Status | Models |
+|----------|--------|--------|
+| Azure OpenAI | ✅ Implemented | GPT-4, GPT-4 Turbo, GPT-3.5 |
+| OpenAI | ✅ Implemented | GPT-4, GPT-4 Turbo, GPT-3.5 |
+| Anthropic | ✅ Implemented | Claude 3 Opus, Sonnet, Haiku |
+| Google Gemini | ✅ Implemented | Gemini Pro, Gemini Ultra |
+| OpenRouter | ✅ Implemented | Multiple models via API |
+| Ollama | ✅ Implemented | Llama, Mistral, etc. (local) |
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file:
+
+```bash
+# Azure OpenAI
+AZURE_OPENAI_API_KEY=your-key
+AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
+AZURE_OPENAI_DEPLOYMENT=gpt-4
+AZURE_OPENAI_API_VERSION=2024-02-01
+
+# OpenAI
+OPENAI_API_KEY=sk-...
+OPENAI_ORG_ID=org-...  # Optional
+
+# Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Google
+GOOGLE_API_KEY=...
+
+# OpenRouter
+OPENROUTER_API_KEY=sk-or-...
+
+# Ollama (local)
+OLLAMA_ENDPOINT=http://localhost:11434
+```
+
+## Azure OpenAI
+
+```rust
+use enact_providers::azure::AzureOpenAiProvider;
+use enact_config::Config;
+
+let config = Config::load()?;
+let provider = AzureOpenAiProvider::from_config(&config)?;
+```
+
+**Required environment variables:**
+- `AZURE_OPENAI_API_KEY`
+- `AZURE_OPENAI_ENDPOINT`
+- `AZURE_OPENAI_DEPLOYMENT`
+
+**Optional:**
+- `AZURE_OPENAI_API_VERSION` (default: `2024-02-01`)
+
+## OpenAI
+
+```rust
+use enact_providers::openai_compatible::OpenAiProvider;
+
+let provider = OpenAiProvider::new(
+    "https://api.openai.com/v1",
+    std::env::var("OPENAI_API_KEY")?,
+    "gpt-4",
+)?;
+```
+
+## Anthropic
+
+```rust
+use enact_providers::anthropic::AnthropicProvider;
+
+let provider = AnthropicProvider::new(
+    std::env::var("ANTHROPIC_API_KEY")?,
+    "claude-3-opus-20240229",
+)?;
+```
+
+## Google Gemini
+
+```rust
+use enact_providers::gemini::GeminiProvider;
+
+let provider = GeminiProvider::new(
+    std::env::var("GOOGLE_API_KEY")?,
+    "gemini-pro",
+)?;
+```
+
+## OpenRouter
+
+Access multiple models through OpenRouter:
+
+```rust
+use enact_providers::openrouter::OpenRouterProvider;
+
+let provider = OpenRouterProvider::new(
+    std::env::var("OPENROUTER_API_KEY")?,
+    "anthropic/claude-3-opus",  // Or any supported model
+)?;
+```
+
+## Ollama (Local)
+
+Run models locally with Ollama:
+
+```rust
+use enact_providers::openai_compatible::OpenAiProvider;
+
+// Ollama uses OpenAI-compatible API
+let provider = OpenAiProvider::new(
+    "http://localhost:11434/v1",
+    "ollama",  // No real key needed
+    "llama3",
+)?;
+```
+
+**Setup Ollama:**
+
+```bash
+# Install Ollama
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# Pull a model
+ollama pull llama3
+
+# Start server (usually automatic)
+ollama serve
+```
+
+## Provider Trait
+
+All providers implement the `ModelProvider` trait:
+
+```rust
+#[async_trait]
+pub trait ModelProvider: Send + Sync {
+    /// Generate a completion
+    async fn complete(&self, request: ChatRequest) -> Result<ChatResponse>;
+
+    /// Whether this provider requires network access
+    fn requires_network(&self) -> bool { true }
+}
+```
+
+## In YAML Agents
+
+Specify the model in LLM nodes:
+
+```yaml
+nodes:
+  analyze:
+    type: llm
+    model: gpt-4              # Uses default provider for this model
+    system_prompt: "..."
+
+  summarize:
+    type: llm
+    model: claude-3-opus      # Different model
+    system_prompt: "..."
+```
+
+## Air-Gapped Mode
+
+For environments without internet access, use Ollama:
+
+```bash
+# Configure for air-gapped
+export OLLAMA_ENDPOINT=http://localhost:11434
+
+# All LLM calls use local Ollama
+enact serve --air-gapped  # 🚧 Future
+```
+
+## Adding a New Provider (🚧 Future)
+
+```rust
+use enact_providers::ModelProvider;
+
+pub struct MyProvider { /* ... */ }
+
+#[async_trait]
+impl ModelProvider for MyProvider {
+    async fn complete(&self, request: ChatRequest) -> Result<ChatResponse> {
+        // Implementation
+    }
+
+    fn requires_network(&self) -> bool {
+        true
+    }
+}
+```

package/docs/content/roadmap/_index.md

@@ -0,0 +1,199 @@
++++
+title = "Roadmap"
+weight = 9
+sort_by = "weight"
++++
+
+# Roadmap
+
+Current status and planned features for Enact.
+
+## Current Status
+
+Enact is a **complete, working AI agent system** with 900+ tests passing. Skills and MCP are now implemented.
+
+## ✅ Completed Features
+
+### CLI Binary (enact)
+
+| Feature | Status |
+|---------|--------|
+| `enact --help` | ✅ Complete |
+| `enact doctor` | ✅ Complete (pretty table output) |
+| `enact version` | ✅ Complete (0.0.1) |
+| `enact run --input "..."` | ✅ Complete |
+| `enact serve --http-port` | ✅ Complete |
+
+### Runner Integration
+
+| Feature | Status |
+|---------|--------|
+| DefaultAgentRunner | ✅ Complete |
+| RunnerResponder (gateway integration) | ✅ Complete |
+| Retry logic | ✅ Complete |
+| Compaction | ✅ Complete |
+| Checkpoints | ✅ Complete |
+
+### Production-Ready Gateway
+
+| Feature | Status |
+|---------|--------|
+| Health endpoint (`/health`) | ✅ Complete |
+| WhatsApp webhook (challenge + message) | ✅ Complete |
+| Rate limiting (sliding window) | ✅ Complete |
+| Idempotency (dedupe duplicates) | ✅ Complete |
+| Signature verification | ✅ Complete |
+| Request limits (64KB) + timeout (30s) | ✅ Complete |
+| All with tests passing | ✅ Complete |
+
+### LLM Providers
+
+| Provider | Status |
+|----------|--------|
+| OpenAI (via OpenAICompatible) | ✅ Complete |
+| Azure OpenAI | ✅ Complete |
+| Anthropic | ✅ Complete |
+| Google Gemini | ✅ Complete |
+| OpenRouter | ✅ Complete |
+| Ollama (local) | ✅ Complete |
+
+### Channels
+
+| Channel | Status |
+|---------|--------|
+| WhatsApp (gateway integration) | ✅ Complete |
+| Telegram | ✅ Complete |
+| Teams | ✅ Complete |
+
+### Core Components
+
+| Component | Status |
+|-----------|--------|
+| YAML Agent Schema | ✅ Complete |
+| GraphLoader | ✅ Complete |
+| StateGraph | ✅ Complete |
+| LlmCallable | ✅ Complete |
+| Configuration (.env) | ✅ Complete |
+
+### CI/CD Pipeline
+
+| Feature | Status |
+|---------|--------|
+| Automated testing on push/PR | ✅ Complete |
+| Format checking with `rustfmt` | ✅ Complete |
+| Linting with `clippy` | ✅ Complete |
+| Cross-platform builds (Linux, macOS, Windows) | ✅ Complete |
+| Caching for faster builds | ✅ Complete |
+
+### Skills System (crates/enact-skills)
+
+| Feature | Status |
+|---------|--------|
+| TOML skill manifests (`SKILL.toml`) | ✅ Complete |
+| Markdown skill format (`SKILL.md`) | ✅ Complete |
+| Tool definitions (shell, http, script) | ✅ Complete |
+| Open-skills repo integration | ✅ Complete |
+| 15+ comprehensive tests | ✅ Complete |
+| Load skills from workspace directory | ✅ Complete |
+| Convert skills to prompts | ✅ Complete |
+
+### MCP Client (crates/enact-mcp)
+
+| Feature | Status |
+|---------|--------|
+| Stdio transport support | ✅ Complete |
+| JSON-RPC protocol | ✅ Complete |
+| Tool listing | ✅ Complete |
+| Tool calling | ✅ Complete |
+| Async/await support | ✅ Complete |
+
+### gRPC API (Proto Definitions)
+
+Proto definitions are in `proto/`:
+
+| Service | Methods | Status |
+|---------|---------|--------|
+| RuntimeService | RunAgent, RunAgentStream, Resume, Cancel, Pause | ✅ Proto designed |
+| ConfigService | GetSecret, SetSecret, GetConfig, SyncConfig | ✅ Proto designed |
+
+---
+
+## 🚧 In Progress
+
+Currently being implemented:
+
+### Agent-to-Agent (A2A)
+
+- [ ] Agent-to-agent communication protocol
+- [ ] Agent discovery
+- [ ] Orchestration patterns
+- [ ] Shared state management
+
+### Custom Webhooks
+
+- [ ] Generic webhook endpoint
+- [ ] Webhook authentication
+- [ ] Payload transformation
+- [ ] Event routing
+
+### OAuth & Token Lifecycle
+
+- [ ] OAuth 2.0 token management
+- [ ] Automatic token refresh
+- [ ] Secure token storage (keychain integration)
+- [ ] Per-channel authentication
+
+---
+
+## Future Considerations
+
+### Additional Channels
+
+- [ ] Email integration
+
+### Developer Experience
+
+- [ ] `enact init` - Project scaffolding
+- [ ] `enact validate` - YAML validation
+- [ ] `enact console` - Interactive TUI
+- [ ] `enact logs` - Execution logs
+
+### Advanced Features
+
+- [ ] Event sourcing
+- [ ] Policy enforcement
+- [ ] Multi-tenancy
+- [ ] gRPC API (Rust implementation from proto)
+- [ ] WebSocket streaming
+
+---
+
+## Ready to Use
+
+You now have a complete, working AI agent system:
+
+```bash
+# Test the CLI
+./target/release/enact doctor
+
+# Run tests
+cargo test --workspace
+
+# Run an agent (with API key)
+OPENAI_API_KEY="..." ./target/release/enact run --input "Hello!"
+
+# Start gateway (with WhatsApp creds)
+WHATSAPP_ACCESS_TOKEN="..." WHATSAPP_ENDPOINT_ID="..." WHATSAPP_VERIFY_TOKEN="..." \
+    ./target/release/enact serve --http-port 8080
+```
+
+## Contributing
+
+We welcome contributions. Current priorities:
+
+1. **A2A (Agent-to-Agent)** - In progress
+2. **Custom Webhooks** - In progress
+3. **OAuth/Token lifecycle** - In progress
+4. **Documentation improvements**
+
+See the [Developer Guide](/developers/) for how to contribute.

package/docs/content/security/_index.md

@@ -0,0 +1,219 @@
++++
+title = "Security"
+weight = 10
++++
+
+# Security System
+
+The `enact-security` crate provides security policy, audit logging, and action validation for agents.
+
+## Autonomy Levels
+
+| Level | Description | Write Access |
+|-------|-------------|--------------|
+| `read_only` | No modifications allowed | No |
+| `supervised` | Actions require approval | Conditional |
+| `full` | All actions allowed within policy | Yes |
+
+## Security Policy
+
+```rust
+use enact_security::{SecurityPolicy, PolicyConfig, AutonomyLevel};
+
+let config = PolicyConfig {
+    autonomy: AutonomyLevel::Supervised,
+    max_actions_per_hour: 1000,
+    blocked_commands: vec!["rm -rf /".into(), "sudo".into()],
+    require_approval_for: vec!["rm".into(), "mv".into()],
+    ..PolicyConfig::default()
+};
+
+let policy = SecurityPolicy::new(config, workspace_dir);
+
+// Check if action is allowed
+if policy.can_act() {
+    // Validate a command
+    let result = policy.validate_command("rm file.txt", approved);
+    if result.allowed {
+        // Execute command
+    } else if result.requires_approval {
+        // Request user approval
+    } else {
+        // Blocked by policy
+        println!("Denied: {:?}", result.reason);
+    }
+}
+```
+
+### Risk Levels
+
+| Level | Examples |
+|-------|----------|
+| `Low` | `ls`, `cat`, `echo` |
+| `Medium` | `rm`, `mv`, `cp`, `chmod` |
+| `High` | `rm -r`, blocked patterns |
+| `Critical` | `rm -rf /`, `sudo`, `mkfs` |
+
+### Rate Limiting
+
+```rust
+// Check rate limit
+if policy.is_rate_limited() {
+    return Err("Rate limit exceeded");
+}
+
+// Record action (returns false if limit hit)
+if !policy.record_action() {
+    return Err("Action budget exhausted");
+}
+
+// Check remaining actions
+let remaining = policy.remaining_actions();
+```
+
+### Path Validation
+
+```rust
+// Validate file path access
+let result = policy.validate_path("src/main.rs", write: true);
+if !result.allowed {
+    println!("Path blocked: {:?}", result.reason);
+}
+
+// Check if path is in workspace
+if policy.is_path_in_workspace(&resolved_path) {
+    // Safe to access
+}
+```
+
+## Audit Logging
+
+All security-relevant events are logged for compliance and debugging:
+
+```rust
+use enact_security::{AuditLogger, AuditConfig, AuditEvent, AuditEventType};
+
+let config = AuditConfig {
+    enabled: true,
+    log_path: "audit.log".into(),
+    max_size_mb: 100,
+    retain_days: 90,
+};
+
+let logger = AuditLogger::new(config, workspace_dir)?;
+
+// Log a command execution
+logger.log_command(
+    "telegram",      // channel
+    "ls -la",        // command
+    "low",           // risk level
+    false,           // approved
+    true,            // allowed
+    true,            // success
+    15,              // duration_ms
+)?;
+
+// Log a tool invocation
+logger.log_tool(
+    "cli",           // channel
+    "file_write",    // tool name
+    true,            // allowed
+    true,            // success
+    42,              // duration_ms
+    None,            // error
+)?;
+
+// Log a policy violation
+logger.log_violation("telegram", "Attempted to access /etc/passwd")?;
+```
+
+### Event Types
+
+| Type | Description |
+|------|-------------|
+| `CommandExecution` | Shell command executed |
+| `FileAccess` | File read/write |
+| `ConfigChange` | Configuration modified |
+| `AuthSuccess` | Authentication succeeded |
+| `AuthFailure` | Authentication failed |
+| `PolicyViolation` | Security policy violated |
+| `SecurityEvent` | General security event |
+| `ToolInvocation` | Agent tool invoked |
+| `AgentAction` | Agent performed action |
+
+### Log Rotation
+
+Audit logs are automatically rotated when they exceed `max_size_mb`:
+
+```
+audit.log       <- current
+audit.log.1.log <- previous
+audit.log.2.log <- older
+...
+audit.log.9.log <- oldest kept
+```
+
+### Log Format
+
+Each log entry is a JSON line:
+
+```json
+{
+  "timestamp": "2026-02-21T12:00:00Z",
+  "event_id": "550e8400-e29b-41d4-a716-446655440000",
+  "event_type": "command_execution",
+  "actor": {
+    "channel": "telegram",
+    "user_id": "123456",
+    "username": "@alice"
+  },
+  "action": {
+    "command": "ls -la",
+    "risk_level": "low",
+    "approved": false,
+    "allowed": true
+  },
+  "result": {
+    "success": true,
+    "exit_code": 0,
+    "duration_ms": 15
+  },
+  "security": {
+    "policy_violation": false,
+    "rate_limit_remaining": 999
+  }
+}
+```
+
+## Configuration
+
+```yaml
+# In agent config
+security:
+  autonomy: supervised  # read_only, supervised, full
+  max_actions_per_hour: 1000
+
+  blocked_commands:
+    - "rm -rf /"
+    - "sudo"
+    - "chmod 777"
+
+  require_approval_for:
+    - rm
+    - mv
+    - chmod
+
+  audit:
+    enabled: true
+    log_path: audit.log
+    max_size_mb: 100
+    retain_days: 90
+```
+
+## Best Practices
+
+1. **Start with `supervised` mode** - Review actions before enabling `full` autonomy
+2. **Configure blocked_commands** - Block dangerous patterns specific to your environment
+3. **Enable audit logging** - Keep logs for compliance and debugging
+4. **Set appropriate rate limits** - Prevent runaway agents
+5. **Use path sandboxing** - Restrict agents to workspace directories