enya-agent 0.1.0

package/docs/content/cron/_index.md

@@ -0,0 +1,248 @@
++++
+title = "Cron/Scheduler"
+weight = 11
++++
+
+# Cron Scheduling System
+
+The `enact-cron` crate provides job scheduling with SQLite persistence for running agents and commands on schedules.
+
+## Job Types
+
+| Type | Description |
+|------|-------------|
+| `Shell` | Execute shell commands |
+| `Agent` | Run an agent with a prompt |
+
+## Schedule Types
+
+### Cron Expressions
+
+Standard cron syntax (5, 6, or 7 fields):
+
+```
+# 5 fields: minute hour day month weekday
+0 9 * * *           # Every day at 9:00 AM
+
+# 6 fields: second minute hour day month weekday
+0 30 9 * * *        # Every day at 9:30 AM
+
+# 7 fields: second minute hour day month weekday year
+0 0 12 * * 1 2026   # Mondays at noon in 2026
+```
+
+With timezone support:
+
+```rust
+Schedule::Cron {
+    expr: "0 9 * * *".into(),
+    tz: Some("America/Los_Angeles".into()),
+}
+```
+
+### One-Shot Execution
+
+Run once at a specific time:
+
+```rust
+Schedule::At {
+    at: Utc.with_ymd_and_hms(2026, 3, 15, 14, 30, 0).unwrap(),
+}
+```
+
+### Interval-Based
+
+Run at fixed intervals:
+
+```rust
+Schedule::Every {
+    every_ms: 60_000,  // Every minute
+}
+```
+
+## Usage
+
+### Creating Jobs
+
+```rust
+use enact_cron::{CronStore, Schedule};
+
+let store = CronStore::new(workspace_dir, max_history, max_tasks)?;
+
+// Simple shell job
+let job = store.add_job("0 9 * * *", "echo good morning")?;
+
+// Shell job with options
+let job = store.add_shell_job(
+    Some("daily-backup".into()),
+    Schedule::Cron { expr: "0 2 * * *".into(), tz: None },
+    "backup.sh"
+)?;
+
+// Agent job
+let job = store.add_agent_job(
+    Some("daily-summary".into()),
+    Schedule::Cron { expr: "0 18 * * *".into(), tz: Some("UTC".into()) },
+    "Summarize today's activities",
+    Some("claude-3-sonnet".into()),
+    SessionTarget::Isolated,
+)?;
+```
+
+### Managing Jobs
+
+```rust
+// List all jobs
+let jobs = store.list_jobs()?;
+
+// Get a specific job
+let job = store.get_job(&job_id)?;
+
+// Get jobs that are due to run
+let due = store.due_jobs(Utc::now())?;
+
+// Update a job
+store.update_job(&job_id, CronJobPatch {
+    enabled: Some(false),
+    ..Default::default()
+})?;
+
+// Remove a job
+store.remove_job(&job_id)?;
+```
+
+### Running Jobs
+
+```rust
+// After executing a job, update its status
+store.reschedule_after_run(&job, success, &output)?;
+
+// Record execution history
+store.record_run(
+    &job_id,
+    started_at,
+    finished_at,
+    "success",
+    Some(&output),
+)?;
+
+// Get job history
+let runs = store.list_runs(&job_id, 10)?;
+```
+
+## Job Configuration
+
+### CronJob Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | String | Unique job identifier |
+| `expression` | String | Original schedule expression |
+| `schedule` | Schedule | Parsed schedule (Cron/At/Every) |
+| `command` | String | Shell command (for shell jobs) |
+| `prompt` | Option<String> | Agent prompt (for agent jobs) |
+| `name` | Option<String> | Human-readable name |
+| `job_type` | JobType | Shell or Agent |
+| `session_target` | SessionTarget | Isolated or Main |
+| `model` | Option<String> | LLM model for agent jobs |
+| `enabled` | bool | Whether job is active |
+| `delivery` | DeliveryConfig | Output delivery config |
+| `delete_after_run` | bool | Auto-delete after execution |
+| `created_at` | DateTime | Creation timestamp |
+| `next_run` | DateTime | Next scheduled run |
+| `last_run` | Option<DateTime> | Last execution time |
+| `last_status` | Option<String> | Last execution status |
+| `last_output` | Option<String> | Last execution output |
+
+### Session Targets
+
+| Target | Description |
+|--------|-------------|
+| `Isolated` | Run in a fresh, isolated session |
+| `Main` | Run in the main conversation session |
+
+### Delivery Config
+
+Configure how job output is delivered:
+
+```rust
+DeliveryConfig {
+    mode: "telegram".into(),  // none, telegram, webhook
+    channel: Some("@mychannel".into()),
+    to: Some("user_id".into()),
+    best_effort: true,
+}
+```
+
+## Schedule Utilities
+
+### Parse Delay Strings
+
+```rust
+use enact_cron::parse_delay;
+
+let duration = parse_delay("5m")?;  // 5 minutes
+let duration = parse_delay("2h")?;  // 2 hours
+let duration = parse_delay("1d")?;  // 1 day
+let duration = parse_delay("30s")?; // 30 seconds
+```
+
+### Validate Schedules
+
+```rust
+use enact_cron::validate_schedule;
+
+// Check if a schedule is valid
+validate_schedule(&schedule, Utc::now())?;
+```
+
+### Calculate Next Run
+
+```rust
+use enact_cron::next_run_for_schedule;
+
+let next = next_run_for_schedule(&schedule, Utc::now())?;
+println!("Next run at: {}", next);
+```
+
+## Example: Daily Agent Summary
+
+```rust
+// Create a daily summary job
+let job = store.add_agent_job(
+    Some("end-of-day-summary".into()),
+    Schedule::Cron {
+        expr: "0 18 * * 1-5".into(),  // 6 PM weekdays
+        tz: Some("America/New_York".into()),
+    },
+    "Generate a summary of today's completed tasks and tomorrow's priorities",
+    Some("claude-3-sonnet".into()),
+    SessionTarget::Main,
+)?;
+
+// Configure delivery to Telegram
+store.update_job(&job.id, CronJobPatch {
+    delivery: Some(DeliveryConfig {
+        mode: "telegram".into(),
+        channel: Some("@team-updates".into()),
+        to: None,
+        best_effort: true,
+    }),
+    ..Default::default()
+})?;
+```
+
+## Persistence
+
+Jobs are stored in SQLite with automatic schema management:
+
+```
+workspace/
+  └── cron.db       # Job definitions and history
+```
+
+The store handles:
+- Automatic table creation
+- Job serialization/deserialization
+- History cleanup (configurable max entries)
+- Concurrent access safety

package/docs/content/developers/_index.md

@@ -0,0 +1,278 @@
++++
+title = "Developers"
+weight = 8
+sort_by = "weight"
++++
+
+# Developer Guide
+
+Contributing to Enact and understanding its internals.
+
+## Crate Architecture
+
+| Crate | Purpose | Status |
+|-------|---------|--------|
+| `enact-cli` | CLI binary (doctor, run, serve, version) | ✅ Complete |
+| `enact-runner` | Execution loop, retry, compaction | ✅ Complete |
+| `enact-core` | Callable, LlmCallable, Graph system | ✅ Complete |
+| `enact-providers` | LLM provider implementations | ✅ Complete |
+| `enact-gateway` | HTTP server, webhooks, rate limiting | ✅ Complete |
+| `enact-channels` | WhatsApp, Telegram, Teams | ✅ Complete |
+| `enact-config` | Configuration management | ✅ Complete |
+| `enact-skills` | Skills system (TOML/MD manifests) | ✅ Complete |
+| `enact-mcp` | MCP client (stdio, JSON-RPC) | ✅ Complete |
+| `enact-context` | Context management | ✅ Complete |
+| `enact-memory` | Memory/state persistence | ✅ Complete |
+
+### Dependency Graph
+
+```
+enact-cli
+    │
+    ├── enact-runner
+    │       │
+    │       └── enact-core
+    │               │
+    │               ├── enact-providers
+    │               ├── enact-config
+    │               ├── enact-skills
+    │               └── enact-mcp
+    │
+    ├── enact-gateway
+    │       │
+    │       ├── enact-channels
+    │       └── enact-runner
+    │
+    ├── enact-skills
+    │       │
+    │       └── enact-core
+    │
+    ├── enact-mcp
+    │       │
+    │       └── enact-core
+    │
+    └── enact-channels
+```
+
+## Building from Source
+
+```bash
+git clone https://github.com/your-org/enact-agent.git
+cd enact-agent
+
+# Build all crates
+cargo build
+
+# Build release
+cargo build --release
+
+# Run tests
+cargo test
+
+# Run specific crate tests
+cargo test -p enact-gateway
+```
+
+## Key Components
+
+### Callable (enact-core)
+
+The core trait for processing:
+
+```rust
+#[async_trait]
+pub trait Callable: Send + Sync {
+    fn name(&self) -> &str;
+    async fn run(&self, input: &str) -> anyhow::Result<String>;
+}
+```
+
+### LlmCallable (enact-core)
+
+LLM-powered callable:
+
+```rust
+pub struct LlmCallable {
+    name: String,
+    system_prompt: String,
+    provider: Arc<dyn ModelProvider>,
+}
+
+impl LlmCallable {
+    pub fn with_provider(
+        name: impl Into<String>,
+        system_prompt: impl Into<String>,
+        provider: Arc<dyn ModelProvider>,
+    ) -> Self;
+}
+```
+
+### DefaultAgentRunner (enact-runner)
+
+Executes callables with production features:
+
+```rust
+pub struct DefaultAgentRunner {
+    // retry, compaction, checkpoints
+}
+
+impl DefaultAgentRunner {
+    pub fn default_new() -> Self;
+    pub async fn run(&mut self, callable: &dyn Callable, input: &str)
+        -> anyhow::Result<LoopOutcome>;
+}
+```
+
+### Gateway (enact-gateway)
+
+HTTP server with webhooks:
+
+```rust
+pub fn router(state: GatewayState) -> Router;
+pub async fn serve(config: GatewayConfig, state: GatewayState) -> anyhow::Result<()>;
+```
+
+Key types:
+- `GatewayConfig` - Server configuration
+- `GatewayState` - Shared state (channel, responder, rate limiter)
+- `InboundResponder` - Message handler trait
+- `RunnerResponder` - Routes to DefaultAgentRunner
+- `EchoResponder` - Simple echo
+
+### Providers (enact-providers)
+
+```rust
+pub struct OpenAICompatible {
+    base_url: String,
+    model: String,
+    api_key: Option<String>,
+}
+```
+
+### Channels (enact-channels)
+
+```rust
+pub struct WhatsAppChannel {
+    access_token: String,
+    endpoint_id: String,
+    verify_token: String,
+    allowed_numbers: Vec<String>,
+}
+```
+
+## Testing
+
+### Unit Tests
+
+```bash
+# All tests
+cargo test
+
+# Specific crate
+cargo test -p enact-gateway
+
+# With output
+cargo test -- --nocapture
+```
+
+### Gateway Tests
+
+The gateway has comprehensive tests:
+
+```rust
+#[tokio::test]
+async fn health_route_returns_ok() { ... }
+
+#[tokio::test]
+async fn whatsapp_verify_route_returns_challenge() { ... }
+
+#[tokio::test]
+async fn whatsapp_webhook_rejects_invalid_signature() { ... }
+
+#[tokio::test]
+async fn webhook_duplicate_payload_is_ignored() { ... }
+
+#[tokio::test]
+async fn webhook_accepts_valid_signature() { ... }
+
+#[tokio::test]
+async fn runner_responder_returns_callable_output() { ... }
+```
+
+## Code Style
+
+```bash
+# Format
+cargo fmt
+
+# Lint
+cargo clippy --all-targets
+
+# Check all
+cargo fmt --check && cargo clippy --all-targets -- -D warnings
+```
+
+## Project Structure
+
+```
+enact-agent/
+├── Cargo.toml              # Workspace definition
+├── crates/
+│   ├── enact-cli/          # CLI binary
+│   ├── enact-runner/       # Execution runtime
+│   ├── enact-core/         # Core types
+│   ├── enact-providers/    # LLM providers
+│   ├── enact-gateway/      # HTTP server
+│   ├── enact-channels/     # Messaging channels
+│   └── enact-config/       # Configuration
+└── docs/                   # This documentation (Zola)
+```
+
+## Adding a Provider
+
+1. Create module in `enact-providers/src/`
+2. Implement `ModelProvider` trait
+3. Export from `lib.rs`
+
+```rust
+pub struct MyProvider { ... }
+
+#[async_trait]
+impl ModelProvider for MyProvider {
+    async fn complete(&self, request: ChatRequest) -> Result<ChatResponse> {
+        // Implementation
+    }
+}
+```
+
+## Adding a Channel
+
+1. Create module in `enact-channels/src/`
+2. Implement `Channel` trait
+3. Add gateway integration in `enact-gateway/`
+
+## Documentation
+
+```bash
+cd docs
+
+# Development server
+make serve  # http://127.0.0.1:1111
+
+# Build
+make build
+```
+
+## Pull Request Process
+
+1. Fork the repository
+2. Create feature branch
+3. Write tests
+4. Update docs
+5. Run checks (`cargo fmt && cargo clippy && cargo test`)
+6. Submit PR
+
+## Current Priorities
+
+1. **OAuth/Token lifecycle** (Phase 1)
+2. **Multi-agent** (Phase 2)

package/docs/content/getting-started/_index.md

@@ -0,0 +1,180 @@
++++
+title = "Getting Started"
+weight = 2
+sort_by = "weight"
++++
+
+# Getting Started
+
+Get up and running with Enact in minutes.
+
+## Prerequisites
+
+- **Rust** 1.75 or later
+- **API Key** for at least one LLM provider (OpenAI, Azure, etc.)
+
+## Quick Start
+
+### 1. Build from Source
+
+```bash
+git clone https://github.com/adl-tan-theta/enactai.git
+cd enya/enact-agent
+cargo build --release
+```
+
+### 2. Check System Status
+
+```bash
+./target/release/enact doctor
+```
+
+This shows:
+
+- API key configuration status
+- WhatsApp configuration status
+- Current model settings
+
+### 3. Run Your First Agent
+
+```bash
+OPENAI_API_KEY="sk-..." ./target/release/enact run --input "Hello!"
+```
+
+The agent will respond using the configured LLM provider.
+
+### 4. Start the Gateway (Optional)
+
+For WhatsApp integration:
+
+```bash
+WHATSAPP_ACCESS_TOKEN="..." \
+WHATSAPP_ENDPOINT_ID="..." \
+WHATSAPP_VERIFY_TOKEN="..." \
+OPENAI_API_KEY="..." \
+./target/release/enact serve --http-port 8080
+```
+
+## Configuration
+
+### Environment Variables
+
+Create a `.env` file:
+
+```bash
+# LLM Provider (required)
+OPENAI_API_KEY=sk-...
+OPENAI_MODEL=gpt-4o-mini
+
+# Or Azure OpenAI
+AZURE_OPENAI_API_KEY=...
+OPENAI_BASE_URL=https://your-resource.openai.azure.com
+
+# WhatsApp (for gateway)
+WHATSAPP_ACCESS_TOKEN=EAABc...
+WHATSAPP_ENDPOINT_ID=123456789012345
+WHATSAPP_VERIFY_TOKEN=my-secret-token
+WHATSAPP_APP_SECRET=abc123  # Optional
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `enact doctor` | Check system status |
+| `enact run --input "..."` | Run agent |
+| `enact serve --http-port 8080` | Start gateway |
+| `enact version` | Show version |
+
+## Gateway Flow
+
+When you run `enact serve`, messages flow through:
+
+```
+WhatsApp Message (webhook)
+    │
+    ▼
+WhatsAppChannel (parse)
+    │
+    ▼
+RunnerResponder
+    │
+    ▼
+DefaultAgentRunner (retry/compaction)
+    │
+    ▼
+Response sent back via WhatsApp
+```
+
+## Production Features
+
+The gateway includes enterprise-ready features:
+
+- **Rate limiting**: 120 requests/minute per client (sliding window)
+- **Idempotency**: Duplicate messages ignored (5-minute TTL)
+- **Signature verification**: Validates WhatsApp signatures
+- **Request limits**: 64KB max body, 30s timeout
+- **All with tests passing**
+
+## Using as a Library
+
+You can also use Enact as a Rust library:
+
+```rust
+use enact_core::callable::LlmCallable;
+use enact_providers::OpenAICompatible;
+use enact_runner::DefaultAgentRunner;
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let api_key = std::env::var("OPENAI_API_KEY")?;
+
+    let provider = Arc::new(OpenAICompatible::new(
+        "https://api.openai.com",
+        "gpt-4o-mini",
+        Some(api_key),
+    ));
+
+    let callable = LlmCallable::with_provider(
+        "assistant",
+        "You are a helpful assistant.",
+        provider,
+    );
+
+    let mut runner = DefaultAgentRunner::default_new();
+    let outcome = runner.run(&callable, "Hello!").await?;
+
+    println!("{:?}", outcome);
+    Ok(())
+}
+```
+
+## YAML Agent Definitions
+
+Define agents as YAML files (for future YAML-based execution):
+
+```yaml
+name: hello-agent
+version: "1.0"
+description: "A simple greeting agent"
+
+nodes:
+  greet:
+    type: llm
+    system_prompt: "You are a friendly assistant. Greet the user warmly."
+    edges:
+      _default: END
+```
+
+See [YAML Schema](/yaml-schema/) for full documentation.
+
+## Next Steps
+
+- [CLI Reference](/cli/) — Full command documentation
+- [Gateway API](/api/) — HTTP endpoint documentation
+- [YAML Schema](/yaml-schema/) — Agent definition format
+- [Channels](/channels/) — WhatsApp, Telegram, Teams setup
+- [Providers](/providers/) — LLM provider configuration
+- [Skills](/skills/) — Skills system (TOML/MD manifests)
+- [MCP Client](/mcp/) — Model Context Protocol integration