enya-agent 0.1.0

package/docs/content/api/_index.md

@@ -0,0 +1,323 @@
++++
+title = "API Reference"
+weight = 6
+sort_by = "weight"
++++
+
+# API Reference
+
+HTTP Gateway and Rust library API for Enact.
+
+## Status
+
+| API | Status |
+|-----|--------|
+| HTTP Gateway | ✅ Complete |
+| WhatsApp Webhook | ✅ Complete |
+| Rust Library API | ✅ Complete |
+| gRPC API | 🚧 Future |
+| WebSocket Streaming | 🚧 Future |
+
+## HTTP Gateway
+
+The gateway is started with `enact serve` and provides webhook endpoints for channels.
+
+### Starting the Gateway
+
+```bash
+./target/release/enact serve --http-port 8080
+```
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/health` | GET | Health check |
+| `/webhook/whatsapp` | GET | WhatsApp verification |
+| `/webhook/whatsapp` | POST | WhatsApp messages |
+
+---
+
+## GET /health
+
+Health check endpoint.
+
+**Request:**
+```bash
+curl http://localhost:8080/health
+```
+
+**Response:**
+```json
+{"status": "ok"}
+```
+
+---
+
+## GET /webhook/whatsapp
+
+WhatsApp webhook verification for Meta's challenge-response.
+
+**Request (from Meta):**
+```
+GET /webhook/whatsapp?hub.mode=subscribe&hub.verify_token=YOUR_TOKEN&hub.challenge=CHALLENGE_STRING
+```
+
+**Response:**
+- `200 OK` with challenge string if token matches
+- `403 Forbidden` if token doesn't match
+
+---
+
+## POST /webhook/whatsapp
+
+Process incoming WhatsApp messages.
+
+**Request (from Meta):**
+```json
+{
+  "entry": [{
+    "changes": [{
+      "value": {
+        "messages": [{
+          "from": "+1234567890",
+          "text": {"body": "Hello!"},
+          "id": "wamid.xxx",
+          "timestamp": "1234567890"
+        }]
+      }
+    }]
+  }]
+}
+```
+
+**Headers:**
+- `X-Hub-Signature-256`: HMAC signature (if `WHATSAPP_APP_SECRET` is configured)
+- `X-Idempotency-Key`: Optional, for deduplication
+
+**Response:**
+```json
+{"status": "ok", "processed": 1}
+```
+
+**Response (duplicate):**
+```json
+{"status": "duplicate_ignored"}
+```
+
+**Response (rate limited):**
+```json
+{"error": "rate limit exceeded"}
+```
+Status: `429 Too Many Requests`
+
+**Response (invalid signature):**
+```json
+{"error": "invalid signature"}
+```
+Status: `401 Unauthorized`
+
+---
+
+## Gateway Features
+
+### Rate Limiting
+
+- **Algorithm**: Sliding window
+- **Default**: 120 requests/minute per client IP
+- **Max tracked clients**: 10,000
+
+### Idempotency
+
+- **TTL**: 5 minutes
+- **Key source**: `X-Idempotency-Key` header or SHA-256 of body
+- **Max tracked keys**: 10,000
+
+### Request Limits
+
+- **Max body size**: 64KB
+- **Request timeout**: 30 seconds
+
+### Signature Verification
+
+When `WHATSAPP_APP_SECRET` is set:
+- Validates `X-Hub-Signature-256` header
+- Rejects requests with invalid signatures
+
+---
+
+## Gateway Configuration
+
+```rust
+pub struct GatewayConfig {
+    pub host: String,                      // default: "0.0.0.0"
+    pub port: u16,                         // default: 8080
+    pub webhook_rate_limit_per_minute: u32, // default: 120
+    pub max_rate_limit_keys: usize,        // default: 10,000
+    pub idempotency_ttl_secs: u64,         // default: 300
+    pub idempotency_max_keys: usize,       // default: 10,000
+    pub trust_forwarded_headers: bool,     // default: false
+}
+```
+
+---
+
+## Rust Library API
+
+### Core Types
+
+#### Callable
+
+The main trait for agent implementations:
+
+```rust
+#[async_trait]
+pub trait Callable: Send + Sync {
+    fn name(&self) -> &str;
+    async fn run(&self, input: &str) -> anyhow::Result<String>;
+}
+```
+
+#### LlmCallable
+
+LLM-powered callable:
+
+```rust
+use enact_core::callable::LlmCallable;
+use enact_providers::OpenAICompatible;
+
+let provider = Arc::new(OpenAICompatible::new(
+    "https://api.openai.com",
+    "gpt-4o-mini",
+    Some(api_key),
+));
+
+let callable = LlmCallable::with_provider(
+    "my-agent",
+    "You are a helpful assistant.",
+    provider,
+);
+```
+
+#### DefaultAgentRunner
+
+Executes callables with retry/compaction:
+
+```rust
+use enact_runner::{DefaultAgentRunner, LoopOutcome};
+
+let mut runner = DefaultAgentRunner::default_new();
+let outcome = runner.run(&callable, "Hello!").await?;
+
+match outcome {
+    LoopOutcome::Completed(output) => println!("{}", output),
+    LoopOutcome::MaxIterationsReached { last_output, .. } => { /* ... */ },
+    LoopOutcome::Cancelled => { /* ... */ },
+    LoopOutcome::TimedOut { elapsed_secs } => { /* ... */ },
+}
+```
+
+### Channel Trait
+
+```rust
+#[async_trait]
+pub trait Channel: Send + Sync {
+    fn channel_id(&self) -> &str;
+    fn channel_type(&self) -> ChannelType;
+    async fn receive(&self) -> Result<IncomingMessage>;
+    async fn send(&self, message: OutgoingMessage) -> Result<MessageId>;
+    async fn run(&self) -> Result<()>;
+}
+```
+
+### Provider Trait
+
+```rust
+#[async_trait]
+pub trait ModelProvider: Send + Sync {
+    async fn complete(&self, request: ChatRequest) -> Result<ChatResponse>;
+    fn requires_network(&self) -> bool { true }
+}
+```
+
+### InboundResponder
+
+For custom message handling in the gateway:
+
+```rust
+#[async_trait]
+pub trait InboundResponder: Send + Sync {
+    async fn handle(&self, message: &ChannelMessage) -> anyhow::Result<Option<String>>;
+}
+```
+
+Built-in implementations:
+- `EchoResponder` - Echoes messages back
+- `RunnerResponder` - Routes through `DefaultAgentRunner`
+
+---
+
+## Usage Examples
+
+### Basic Agent Execution
+
+```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, "What is Rust?").await?;
+
+    println!("{:?}", outcome);
+    Ok(())
+}
+```
+
+### Custom Gateway Handler
+
+```rust
+use enact_gateway::{GatewayConfig, GatewayState, InboundResponder, serve};
+use enact_channels::WhatsAppChannel;
+use async_trait::async_trait;
+
+struct MyResponder;
+
+#[async_trait]
+impl InboundResponder for MyResponder {
+    async fn handle(&self, message: &ChannelMessage) -> anyhow::Result<Option<String>> {
+        Ok(Some(format!("Got: {}", message.content)))
+    }
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let channel = Arc::new(WhatsAppChannel::new(/* ... */));
+    let config = GatewayConfig::default();
+    let state = GatewayState::new(
+        channel,
+        Some("app_secret".to_string()),
+        Arc::new(MyResponder),
+        &config,
+    );
+
+    serve(config, state).await
+}
+```

package/docs/content/channels/_index.md

@@ -0,0 +1,160 @@
++++
+title = "Channels"
+weight = 6
+sort_by = "weight"
++++
+
+# Channels
+
+Enact supports deploying agents to multiple messaging platforms.
+
+## Supported Channels
+
+| Channel | Status | Description |
+|---------|--------|-------------|
+| [Telegram](/channels/telegram/) | ✅ Implemented | Bot API integration |
+| [Teams](/channels/teams/) | ✅ Implemented | Microsoft Teams bot |
+| [WhatsApp](/channels/whatsapp/) | ✅ Implemented | Meta Business API |
+| [Webhook](/channels/webhook/) | ✅ Implemented | Generic HTTP webhooks |
+| Discord | ❌ Not Planned | Discord bot (skip) |
+| Slack | ❌ Not Planned | Slack app (skip) |
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                     Messaging Platforms                       │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
+│  │ Telegram │  │  Teams   │  │ WhatsApp │  │ Discord  │    │
+│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘    │
+└───────┼─────────────┼─────────────┼─────────────┼───────────┘
+        │             │             │             │
+        └─────────────┴──────┬──────┴─────────────┘
+                             │
+                    ┌────────▼────────┐
+                    │  Channel Trait  │
+                    │   receive()     │
+                    │   send()        │
+                    │   run()         │
+                    └────────┬────────┘
+                             │
+                    ┌────────▼────────┐
+                    │  Agent Runtime  │
+                    │  (enact-core)   │
+                    └─────────────────┘
+```
+
+## Channel Trait
+
+All channels implement the `Channel` trait:
+
+```rust
+#[async_trait]
+pub trait Channel: Send + Sync {
+    /// Unique channel identifier
+    fn channel_id(&self) -> &str;
+
+    /// Channel type (telegram, teams, whatsapp)
+    fn channel_type(&self) -> ChannelType;
+
+    /// Receive incoming message
+    async fn receive(&self) -> Result<IncomingMessage>;
+
+    /// Send outgoing message
+    async fn send(&self, message: OutgoingMessage) -> Result<MessageId>;
+
+    /// Run the channel event loop
+    async fn run(&self) -> Result<()>;
+}
+```
+
+## Configuration
+
+Each channel requires specific credentials in `.env`:
+
+```bash
+# Telegram
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
+
+# Teams
+TEAMS_APP_ID=...
+TEAMS_APP_SECRET=...
+TEAMS_TENANT_ID=...
+
+# WhatsApp
+WHATSAPP_PHONE_NUMBER_ID=...
+WHATSAPP_ACCESS_TOKEN=...
+WHATSAPP_WEBHOOK_VERIFY_TOKEN=...
+```
+
+## Using Channels (Rust API)
+
+```rust
+use enact_channels::telegram::TelegramChannel;
+use enact_channels::ChannelConfig;
+
+// Create channel
+let config = ChannelConfig::from_env()?;
+let telegram = TelegramChannel::new(config)?;
+
+// Run channel (blocking)
+telegram.run().await?;
+```
+
+## Multi-Channel Deployment (🚧 Future)
+
+Run multiple channels simultaneously:
+
+```rust
+use enact_channels::{telegram, teams, whatsapp};
+use tokio::join;
+
+let tg = telegram::TelegramChannel::new(config)?;
+let ms = teams::TeamsChannel::new(config)?;
+let wa = whatsapp::WhatsAppChannel::new(config)?;
+
+// Run all channels concurrently
+join!(tg.run(), ms.run(), wa.run());
+```
+
+## Channel-Specific Features
+
+### Telegram
+- Inline keyboards
+- Media support (photos, documents)
+- Bot commands
+- Group chat support
+
+### Teams
+- Adaptive cards
+- SSO authentication
+- Proactive messaging
+- Meeting integration (🚧)
+
+### WhatsApp
+- Interactive messages
+- Message templates
+- Media messages
+- Business API features
+
+## Security
+
+Each channel has security features in `enact-channels/src/security/`:
+
+- **Rate limiting**: Prevent abuse
+- **User allowlists**: Restrict access
+- **Message validation**: Verify message integrity
+- **Webhook verification**: Validate incoming webhooks
+
+```rust
+use enact_channels::security::{RateLimiter, AllowList};
+
+let limiter = RateLimiter::new(10, Duration::from_secs(60)); // 10 msg/min
+let allowlist = AllowList::from_users(vec!["+1234567890"]);
+```
+
+## Next Steps
+
+- [Telegram Setup](/channels/telegram/)
+- [Teams Setup](/channels/teams/)
+- [WhatsApp Setup](/channels/whatsapp/)

package/docs/content/channels/teams.md

@@ -0,0 +1,205 @@
++++
+title = "Microsoft Teams"
+weight = 2
++++
+
+# Microsoft Teams Channel
+
+Deploy your Enact agent to Microsoft Teams.
+
+## Status
+
+| Feature | Status |
+|---------|--------|
+| Bot Framework Integration | ✅ Implemented |
+| Text Messages | ✅ Implemented |
+| Adaptive Cards | ✅ Implemented |
+| SSO Authentication | 🚧 Partial |
+| Proactive Messaging | ✅ Implemented |
+| Meeting Integration | 🚧 Future |
+
+## Setup
+
+### 1. Register Azure AD Application
+
+1. Go to [Azure Portal](https://portal.azure.com)
+2. Navigate to Azure Active Directory > App registrations
+3. Click "New registration"
+4. Configure:
+   - Name: Your bot name
+   - Supported account types: Multitenant
+5. Note the **Application (client) ID**
+
+### 2. Create Client Secret
+
+1. In your app, go to "Certificates & secrets"
+2. Click "New client secret"
+3. Copy the secret value immediately
+
+### 3. Register with Bot Framework
+
+1. Go to [Bot Framework Portal](https://dev.botframework.com/bots/new)
+2. Fill in bot details
+3. Use your Azure AD App ID
+4. Add the Teams channel
+
+### 4. Configure Environment
+
+```bash
+# .env
+TEAMS_APP_ID=your-azure-ad-app-id
+TEAMS_APP_SECRET=your-client-secret
+TEAMS_TENANT_ID=your-tenant-id  # or "common" for multi-tenant
+```
+
+### 5. Run Channel (Rust API)
+
+```rust
+use enact_channels::teams::{TeamsChannel, TeamsConfig};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let config = TeamsConfig {
+        app_id: std::env::var("TEAMS_APP_ID")?,
+        app_secret: std::env::var("TEAMS_APP_SECRET")?,
+        tenant_id: std::env::var("TEAMS_TENANT_ID")?,
+        ..Default::default()
+    };
+
+    let channel = TeamsChannel::new(config)?;
+    channel.run().await?;
+
+    Ok(())
+}
+```
+
+## Configuration Options
+
+```rust
+pub struct TeamsConfig {
+    /// Azure AD Application ID
+    pub app_id: String,
+
+    /// Azure AD Client Secret
+    pub app_secret: String,
+
+    /// Tenant ID or "common"
+    pub tenant_id: String,
+
+    /// Service URL for Bot Framework
+    pub service_url: String,
+
+    /// Enable proactive messaging
+    pub enable_proactive: bool,
+}
+```
+
+## Features
+
+### Adaptive Cards
+
+```rust
+use enact_channels::teams::AdaptiveCard;
+
+let card = AdaptiveCard::new()
+    .add_text_block("Welcome!", true)
+    .add_text_block("Choose an action:")
+    .add_action_set(vec![
+        Action::submit("Run Query", "action_query"),
+        Action::submit("Get Help", "action_help"),
+    ]);
+
+channel.send(OutgoingMessage {
+    conversation_id: message.conversation_id,
+    attachments: vec![card.into()],
+    ..Default::default()
+}).await?;
+```
+
+### Handling Card Actions
+
+```rust
+match message.message_type {
+    MessageType::CardAction(action) => {
+        match action.verb.as_str() {
+            "action_query" => { /* Handle query */ }
+            "action_help" => { /* Handle help */ }
+            _ => {}
+        }
+    }
+    _ => {}
+}
+```
+
+### Proactive Messaging
+
+Send messages without user prompting:
+
+```rust
+// Store conversation reference
+let conv_ref = message.conversation_reference();
+store_reference(user_id, conv_ref).await;
+
+// Later, send proactive message
+channel.send_proactive(
+    stored_conv_ref,
+    "Reminder: Your task is due!",
+).await?;
+```
+
+## App Manifest
+
+Create `manifest.json` for Teams:
+
+```json
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.16/MicrosoftTeams.schema.json",
+  "manifestVersion": "1.16",
+  "version": "1.0.0",
+  "id": "your-app-id",
+  "packageName": "com.yourcompany.enact",
+  "developer": {
+    "name": "Your Company",
+    "websiteUrl": "https://yourcompany.com",
+    "privacyUrl": "https://yourcompany.com/privacy",
+    "termsOfUseUrl": "https://yourcompany.com/terms"
+  },
+  "name": {
+    "short": "Enact Bot",
+    "full": "Enact AI Assistant"
+  },
+  "description": {
+    "short": "AI-powered assistant",
+    "full": "Enact AI Assistant for Teams"
+  },
+  "bots": [
+    {
+      "botId": "your-bot-id",
+      "scopes": ["personal", "team", "groupchat"]
+    }
+  ]
+}
+```
+
+## Security
+
+### Tenant Restriction
+
+Restrict to specific tenants:
+
+```rust
+let config = TeamsConfig {
+    tenant_id: "your-specific-tenant-id".to_string(),
+    ..Default::default()
+};
+```
+
+### User Validation
+
+Validate users before processing:
+
+```rust
+if !allowed_users.contains(&message.user_id) {
+    return Err(ChannelError::Unauthorized);
+}
+```