enya-agent 0.1.0

package/docs/content/skills/_index.md

@@ -0,0 +1,228 @@
++++
+title = "Skills System"
+weight = 7
+sort_by = "weight"
++++
+
+# Skills System
+
+The Skills System allows you to extend Enact with custom capabilities through TOML manifests or simple Markdown files.
+
+## Status
+
+| 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 |
+| Load skills from workspace directory | ✅ Complete |
+| Convert skills to prompts | ✅ Complete |
+| 15+ comprehensive tests | ✅ Complete |
+
+## Skill Locations
+
+Skills can be loaded from two locations:
+
+1. **Workspace directory**: `./skills/<skill-name>/`
+2. **Open-skills repository**: Auto-synced from [besoeasy/open-skills](https://github.com/besoeasy/open-skills)
+
+## SKILL.toml Format
+
+The structured format for skills with tool definitions:
+
+```toml
+[skill]
+name = "my-skill"
+description = "What this skill does"
+version = "0.1.0"
+author = "your-name"
+tags = ["productivity", "automation"]
+
+[[tools]]
+name = "my_tool"
+description = "What this tool does"
+kind = "shell"
+command = "echo hello"
+
+[[tools]]
+name = "http_tool"
+description = "Makes an HTTP request"
+kind = "http"
+command = "https://api.example.com/endpoint"
+
+[tools.args]
+method = "GET"
+```
+
+### Skill Metadata
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique skill identifier |
+| `description` | Yes | What the skill does |
+| `version` | No | Semantic version (default: "0.1.0") |
+| `author` | No | Skill author |
+| `tags` | No | Categorization tags |
+
+### Tool Types
+
+| Kind | Description |
+|------|-------------|
+| `shell` | Execute a shell command |
+| `http` | Make an HTTP request |
+| `script` | Run a script file |
+
+## SKILL.md Format
+
+A simpler format for prompt-based skills:
+
+```markdown
+# My Skill
+
+Instructions for the agent to follow.
+
+When the user asks about X, do Y.
+
+## Examples
+
+- If user says "hello", respond warmly
+- If user asks for help, provide guidance
+```
+
+The entire markdown content becomes the skill's prompt.
+
+## Loading Skills
+
+### Programmatic Usage
+
+```rust
+use enact_skills::{load_skills, skills_to_prompt};
+use std::path::Path;
+
+// Load all skills from workspace
+let skills = load_skills(Path::new("."));
+
+// Convert to system prompt addition
+let prompt_addition = skills_to_prompt(&skills);
+```
+
+### Skill Directory Structure
+
+```
+my-project/
+├── skills/
+│   ├── greeting/
+│   │   └── SKILL.toml
+│   ├── code-review/
+│   │   └── SKILL.md
+│   └── README.md
+└── agents/
+    └── my-agent.yaml
+```
+
+## Open-Skills Integration
+
+Enact automatically syncs with the open-skills community repository:
+
+- **Repository**: [besoeasy/open-skills](https://github.com/besoeasy/open-skills)
+- **Location**: `~/open-skills/`
+- **Sync interval**: Weekly (7 days)
+- **Format**: Markdown files
+
+### Configuration
+
+```bash
+# Disable open-skills
+export ENACT_OPEN_SKILLS_ENABLED=false
+
+# Custom open-skills directory
+export ENACT_OPEN_SKILLS_DIR=/path/to/skills
+```
+
+## Initialize Skills Directory
+
+```rust
+use enact_skills::init_skills_dir;
+use std::path::Path;
+
+// Creates ./skills/ with a README.md
+init_skills_dir(Path::new("."))?;
+```
+
+## Rust API
+
+### Skill Struct
+
+```rust
+pub struct Skill {
+    pub name: String,
+    pub description: String,
+    pub version: String,
+    pub author: Option<String>,
+    pub tags: Vec<String>,
+    pub tools: Vec<SkillTool>,
+    pub prompts: Vec<String>,
+    pub location: Option<PathBuf>,
+}
+```
+
+### SkillTool Struct
+
+```rust
+pub struct SkillTool {
+    pub name: String,
+    pub description: String,
+    pub kind: String,      // "shell", "http", "script"
+    pub command: String,
+    pub args: HashMap<String, String>,
+}
+```
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `load_skills(workspace_dir)` | Load all skills from workspace and open-skills |
+| `skills_to_prompt(skills)` | Convert skills to system prompt addition |
+| `skills_dir(workspace_dir)` | Get the skills directory path |
+| `init_skills_dir(workspace_dir)` | Initialize skills directory with README |
+
+## Example Skills
+
+### Shell Tool Skill
+
+```toml
+[skill]
+name = "git-helper"
+description = "Git operations helper"
+version = "1.0.0"
+tags = ["git", "vcs"]
+
+[[tools]]
+name = "git_status"
+description = "Show git status"
+kind = "shell"
+command = "git status"
+
+[[tools]]
+name = "git_log"
+description = "Show recent commits"
+kind = "shell"
+command = "git log --oneline -10"
+```
+
+### Prompt-Based Skill
+
+```markdown
+# Code Reviewer
+
+You are a code review assistant. When reviewing code:
+
+1. Check for bugs and logic errors
+2. Suggest performance improvements
+3. Ensure code follows best practices
+4. Be constructive and specific
+
+Always explain your reasoning.
+```

package/docs/content/tools/_index.md

@@ -0,0 +1,485 @@
++++
+title = "Tools"
+weight = 12
++++
+
+# Built-in Tools
+
+Enact provides **7 production-ready tools** for agents with security sandboxing and policy enforcement. These tools enable agents to interact with the filesystem, execute commands, search the web, make API calls, and track costs.
+
+## Available Tools
+
+| Tool | Description | Network Required | Risk Level |
+|------|-------------|------------------|------------|
+| `file_read` | Read file contents securely | ❌ No | Low |
+| `file_write` | Write/create files | ❌ No | Medium |
+| `shell` | Execute shell commands | ❌ No* | Medium-High |
+| `git` | Git repository operations | ✅ Yes | Low-Medium |
+| `web_search` | Web search (DuckDuckGo/Brave) | ✅ Yes | Low |
+| `http_request` | Make HTTP requests | ✅ Yes | Medium |
+| `cost` | Track API costs & usage | ❌ No | Low |
+
+\* Shell commands themselves may require network access
+
+---
+
+## Quick Start
+
+```rust
+use enact_core::tool::{
+    FileReadTool, FileWriteTool, ShellTool, GitTool,
+    WebSearchTool, HttpRequestTool, CostTracker, CostTool
+};
+
+// Read a file
+let tool = FileReadTool::new();
+let result = tool.execute(json!({"path": "README.md"})).await?;
+
+// Search the web
+let tool = WebSearchTool::new("duckduckgo");
+let result = tool.execute(json!({"query": "Rust async patterns"})).await?;
+
+// Run a shell command
+let tool = ShellTool::new();
+let result = tool.execute(json!({"command": "cargo test"})).await?;
+```
+
+---
+
+## File Read Tool
+
+Read file contents with path traversal protection:
+
+```rust
+use enact_core::tool::FileReadTool;
+
+let tool = FileReadTool::new();
+
+let result = tool.execute(serde_json::json!({
+    "path": "src/main.rs"
+})).await?;
+
+// Returns:
+// {
+//   "success": true,
+//   "content": "file contents...",
+//   "path": "src/main.rs",
+//   "size": 1234
+// }
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | Yes | Relative path to file |
+
+### Security Features
+
+- ✅ Path traversal attacks blocked (`../etc/passwd`)
+- ✅ Maximum file size: 10MB
+- ✅ Only regular files (not directories)
+
+---
+
+## File Write Tool
+
+Write or create files with automatic parent directory creation:
+
+```rust
+use enact_core::tool::FileWriteTool;
+
+let tool = FileWriteTool::new();
+
+let result = tool.execute(serde_json::json!({
+    "path": "output/results.txt",
+    "content": "Hello, World!"
+})).await?;
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `path` | string | Yes | Relative path to file |
+| `content` | string | Yes | Content to write |
+
+### Security Features
+
+- ✅ Path traversal prevention
+- ✅ Parent directories created automatically
+- ✅ Works within workspace boundaries
+
+---
+
+## Shell Tool
+
+Execute shell commands with timeout protection:
+
+```rust
+use enact_core::tool::ShellTool;
+
+let tool = ShellTool::new();
+
+// Basic command
+let result = tool.execute(serde_json::json!({
+    "command": "ls -la"
+})).await?;
+
+// With timeout
+let result = tool.execute(serde_json::json!({
+    "command": "cargo build",
+    "timeout": 120  // seconds
+})).await?;
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `command` | string | Yes | Shell command to execute |
+| `timeout` | number | No | Timeout in seconds (default: 60, max: 300) |
+
+### Output
+
+```json
+{
+  "success": true,
+  "stdout": "command output...",
+  "stderr": "error output...",
+  "exit_code": 0,
+  "command": "ls -la"
+}
+```
+
+### Security Features
+
+- ⏱️ Timeout protection (prevents hanging)
+- 📏 Max output: 1MB (truncated with notice)
+- 🔒 Runs through `sh -c` for compatibility
+
+---
+
+## Git Tool
+
+Perform Git operations on repositories:
+
+```rust
+use enact_core::tool::GitTool;
+
+let tool = GitTool::new();
+
+// Check status
+let result = tool.execute(serde_json::json!({
+    "operation": "status"
+})).await?;
+
+// Clone a repository
+let result = tool.execute(serde_json::json!({
+    "operation": "clone",
+    "repo_url": "https://github.com/user/repo.git",
+    "directory": "./cloned-repo"
+})).await?;
+
+// Create a commit
+let result = tool.execute(serde_json::json!({
+    "operation": "commit",
+    "message": "Add new feature",
+    "directory": "./my-project"
+})).await?;
+```
+
+### Operations
+
+| Operation | Parameters | Description |
+|-----------|------------|-------------|
+| `clone` | `repo_url`, `directory` | Clone a repository |
+| `status` | `directory` | Show working tree status |
+| `add` | `args` | Stage files |
+| `commit` | `message` | Create a commit |
+| `push` | `args` | Push to remote |
+| `pull` | `args` | Pull from remote |
+| `branch` | - | List branches |
+| `checkout` | `args` | Switch branches |
+
+---
+
+## Web Search Tool
+
+Search the web using DuckDuckGo (free) or Brave API:
+
+```rust
+use enact_core::tool::WebSearchTool;
+
+// Using DuckDuckGo (free, no API key)
+let tool = WebSearchTool::new("duckduckgo");
+
+let result = tool.execute(serde_json::json!({
+    "query": "Rust async programming",
+    "max_results": 5
+})).await?;
+
+// Using Brave (requires API key)
+let tool = WebSearchTool::new("brave")
+    .with_brave_key("your-api-key");
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Search query |
+| `max_results` | number | No | Max results 1-10 (default: 5) |
+
+### Output
+
+```json
+{
+  "success": true,
+  "query": "Rust async programming",
+  "provider": "duckduckgo",
+  "results": [
+    {
+      "title": "Asynchronous Programming in Rust",
+      "url": "https://rust-lang.github.io/async-book/",
+      "snippet": "..."
+    }
+  ],
+  "count": 5
+}
+```
+
+### Providers
+
+- **DuckDuckGo**: Free, no API key required
+- **Brave**: Requires API key, better results
+
+---
+
+## HTTP Request Tool
+
+Make HTTP requests to APIs and web services:
+
+```rust
+use enact_core::tool::HttpRequestTool;
+
+let tool = HttpRequestTool::new();
+
+// GET request
+let result = tool.execute(serde_json::json!({
+    "url": "https://api.example.com/data",
+    "method": "GET"
+})).await?;
+
+// POST request with JSON body
+let result = tool.execute(serde_json::json!({
+    "url": "https://api.example.com/users",
+    "method": "POST",
+    "headers": {
+        "Content-Type": "application/json",
+        "Authorization": "Bearer token123"
+    },
+    "body": {
+        "name": "John",
+        "email": "john@example.com"
+    }
+})).await?;
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `url` | string | Yes | Request URL |
+| `method` | string | No | HTTP method (default: GET) |
+| `headers` | object | No | Request headers |
+| `body` | string/object | No | Request body |
+| `timeout` | number | No | Timeout in seconds (default: 30) |
+
+### Supported Methods
+
+`GET`, `POST`, `PUT`, `DELETE`, `PATCH`, `HEAD`, `OPTIONS`
+
+### Output
+
+```json
+{
+  "success": true,
+  "status_code": 200,
+  "status_text": "OK",
+  "headers": { "content-type": "application/json" },
+  "body": { "data": "..." },
+  "url": "https://api.example.com/data",
+  "method": "GET"
+}
+```
+
+### Security Features
+
+- 📏 Max response size: 10MB
+- ⏱️ Configurable timeout
+- 🔒 Automatic JSON parsing for JSON responses
+
+---
+
+## Cost Tracking Tool
+
+Track API costs and usage for budget management:
+
+```rust
+use enact_core::tool::{CostTool, CostTracker};
+use std::sync::Arc;
+
+// Create tracker
+let tracker = Arc::new(CostTracker::new());
+
+// Track a request
+tracker.track_request("gpt-4o-mini", 1000, 500);
+
+// Query costs
+let tool = CostTool::new(tracker.clone());
+let result = tool.execute(serde_json::json!({
+    "action": "get"
+})).await?;
+
+// Reset metrics
+let result = tool.execute(serde_json::json!({
+    "action": "reset"
+})).await?;
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `action` | string | No | `"get"` or `"reset"` (default: get) |
+
+### Output
+
+```json
+{
+  "success": true,
+  "metrics": {
+    "total_requests": 42,
+    "total_input_tokens": 15000,
+    "total_output_tokens": 8000,
+    "total_cost_usd": 0.045,
+    "requests_by_model": {
+      "gpt-4o-mini": 40,
+      "claude-3-sonnet": 2
+    },
+    "cost_by_model": {
+      "gpt-4o-mini": 0.015,
+      "claude-3-sonnet": 0.030
+    }
+  }
+}
+```
+
+### Supported Models
+
+Pricing is built-in for:
+- OpenAI: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`
+- Anthropic: `claude-3-opus`, `claude-3-sonnet`
+- Google: `gemini-pro`
+
+---
+
+## Tool Trait
+
+All tools implement the `Tool` trait:
+
+```rust
+use enact_core::tool::Tool;
+use async_trait::async_trait;
+use serde_json::Value;
+
+#[async_trait]
+pub trait Tool: Send + Sync {
+    /// Tool name (used by LLM to invoke)
+    fn name(&self) -> &str;
+    
+    /// Description (shown to LLM)
+    fn description(&self) -> &str;
+    
+    /// JSON Schema for parameters
+    fn parameters_schema(&self) -> Value;
+    
+    /// Whether tool needs network
+    fn requires_network(&self) -> bool { true }
+    
+    /// Execute the tool
+    async fn execute(&self, args: Value) -> anyhow::Result<Value>;
+}
+```
+
+---
+
+## Error Handling
+
+All tools return structured errors:
+
+```rust
+match tool.execute(args).await {
+    Ok(result) => {
+        if result["success"].as_bool().unwrap_or(false) {
+            // Tool executed successfully
+            println!("Output: {}", result["stdout"]);
+        } else {
+            // Tool executed but operation failed
+            eprintln!("Error: {}", result["error"]);
+        }
+    }
+    Err(e) => {
+        // Tool execution failed
+        eprintln!("Tool error: {}", e);
+    }
+}
+```
+
+---
+
+## Security Best Practices
+
+1. **Path Validation**: All file tools prevent directory traversal
+2. **Timeouts**: Shell and HTTP tools have timeouts to prevent hangs
+3. **Size Limits**: File reads limited to 10MB, HTTP responses to 10MB
+4. **Workspace Boundaries**: Tools operate within workspace directory
+5. **No Secrets**: Tools don't log or expose sensitive data
+
+---
+
+## Testing
+
+All tools have comprehensive tests:
+
+```bash
+# Run tool tests
+cargo test -p enact-core filesystem
+cargo test -p enact-core shell
+cargo test -p enact-core git
+cargo test -p enact-core web_search
+cargo test -p enact-core http
+cargo test -p enact-core cost
+```
+
+**Total: 694 tests passing** ✅
+
+---
+
+## MCP vs Built-in Tools
+
+**Use Built-in Tools for:**
+- ✅ File system operations (file_read, file_write)
+- ✅ Shell commands
+- ✅ Git operations
+- ✅ Cost tracking
+- ✅ Memory operations (via enact-memory crate)
+- ✅ Cron jobs (via enact-cron crate)
+
+**Use MCP Tools for:**
+- 🔗 External APIs (GitHub, Slack, Notion)
+- 🔗 Third-party services
+- 🔗 Non-Enact integrations
+
+**Built-in tools are faster, more secure, and don't require external dependencies!**