enya-agent 0.1.0

package/crates/enact-channels/examples/README.md

@@ -0,0 +1,80 @@
+# Channel Examples
+
+## WhatsApp Echo (`whatsapp-echo`)
+
+This example exposes a webhook endpoint that:
+
+- verifies Meta webhook challenge (`GET /whatsapp`)
+- accepts incoming WhatsApp events (`POST /whatsapp`)
+- echoes text replies back to sender
+
+### 1) Run locally
+
+```bash
+WHATSAPP_ACCESS_TOKEN="<meta_access_token>" \
+WHATSAPP_ENDPOINT_ID="<phone_number_id>" \
+WHATSAPP_VERIFY_TOKEN="<verify_token_you_choose>" \
+WHATSAPP_APP_SECRET="<meta_app_secret_optional_but_recommended>" \
+WHATSAPP_ALLOWED_NUMBERS="+15551234567,*" \
+WHATSAPP_WEBHOOK_PORT=8080 \
+cargo run -p enact-channels --example whatsapp-echo
+```
+
+Notes:
+
+- `WHATSAPP_APP_SECRET` enables signature validation (`X-Hub-Signature-256`).
+- `WHATSAPP_ALLOWED_NUMBERS` filters inbound senders. Use `*` to allow all.
+
+### 2) Expose webhook publicly
+
+Meta needs a public HTTPS URL. For local testing, use a tunnel (for example ngrok):
+
+```bash
+ngrok http 8080
+```
+
+Use the generated HTTPS URL + `/whatsapp` as your callback URL.
+
+### 3) Configure Meta Webhooks
+
+In your Meta app dashboard:
+
+1. Open **WhatsApp > Configuration > Webhooks**.
+2. Set callback URL to `https://<public-host>/whatsapp`.
+3. Set verify token to exactly `WHATSAPP_VERIFY_TOKEN`.
+4. Subscribe to `messages` field.
+
+### 4) Quick verification tests
+
+#### Verify webhook challenge
+
+```bash
+curl -i "http://localhost:8080/whatsapp?hub.mode=subscribe&hub.verify_token=<verify_token_you_choose>&hub.challenge=12345"
+```
+
+Expected body: `12345`
+
+#### Send sample message payload
+
+```bash
+curl -i -X POST "http://localhost:8080/whatsapp" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "entry": [{
+      "changes": [{
+        "value": {
+          "messages": [{
+            "from": "15551234567",
+            "timestamp": "1700000000",
+            "type": "text",
+            "text": { "body": "hello" }
+          }]
+        }
+      }]
+    }]
+  }'
+```
+
+Expected JSON response: `{"status":"ok"}`
+
+If your tokens and endpoint ID are valid, the sender should receive `echo: hello` on WhatsApp.

package/crates/enact-channels/examples/channel_bot.rs

@@ -0,0 +1,169 @@
+//! Example: Run a bot on Telegram and/or Teams channels.
+//!
+//! This example shows how to:
+//! 1. Load channel configuration
+//! 2. Set up Telegram and Teams channels
+//! 3. Route messages through a custom handler (or AgentRunner)
+//!
+//! ## Usage
+//!
+//! Set environment variables:
+//! ```bash
+//! # Telegram
+//! export TELEGRAM_BOT_TOKEN="your-bot-token"
+//!
+//! # Teams (optional)
+//! export TEAMS_APP_ID="your-app-id"
+//! export TEAMS_APP_PASSWORD="your-app-password"
+//! ```
+//!
+//! Run:
+//! ```bash
+//! cargo run --example channel_bot
+//! ```
+
+use async_trait::async_trait;
+use enact_channels::{
+    ChannelMessage, ChannelRuntime, MessageHandler,
+    TelegramChannel, TeamsChannel, TeamsActivity,
+    StreamMode, TelegramConfig, TeamsConfig,
+};
+use tokio::sync::mpsc;
+
+/// Simple handler that echoes messages.
+/// Replace this with AgentRunner integration for real use.
+struct SimpleHandler;
+
+#[async_trait]
+impl MessageHandler for SimpleHandler {
+    async fn handle(&self, message: &ChannelMessage) -> anyhow::Result<String> {
+        tracing::info!(
+            "Received from {}: {}",
+            message.sender,
+            message.content
+        );
+
+        // Simple echo response
+        // In production, you'd call AgentRunner here:
+        //
+        // let mut runner = DefaultAgentRunner::default_new();
+        // let outcome = runner.run(&my_callable, &message.content).await?;
+        // match outcome {
+        //     LoopOutcome::Completed(response) => Ok(response),
+        //     _ => Ok("Processing incomplete".to_string()),
+        // }
+
+        Ok(format!(
+            "Hello from enact! You said: \"{}\"",
+            message.content
+        ))
+    }
+
+    async fn on_start(&self, message: &ChannelMessage) {
+        tracing::debug!("Processing message {} from {}", message.id, message.sender);
+    }
+
+    async fn on_complete(&self, message: &ChannelMessage, response: &str) {
+        tracing::debug!(
+            "Completed message {} with {} chars response",
+            message.id,
+            response.len()
+        );
+    }
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // Initialize tracing
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::from_default_env()
+                .add_directive("enact_channels=debug".parse().unwrap())
+                .add_directive("channel_bot=debug".parse().unwrap()),
+        )
+        .init();
+
+    tracing::info!("Starting enact channel bot...");
+
+    // Create runtime with our handler
+    let mut runtime = ChannelRuntime::new(SimpleHandler);
+
+    // Add Telegram channel if configured
+    if let Ok(token) = std::env::var("TELEGRAM_BOT_TOKEN") {
+        let config = TelegramConfig {
+            bot_token: token,
+            allowed_users: std::env::var("TELEGRAM_ALLOWED_USERS")
+                .map(|s| s.split(',').map(String::from).collect())
+                .unwrap_or_default(),
+            mention_only: false,
+            stream_mode: StreamMode::Off,
+            draft_update_interval_ms: 1000,
+        };
+
+        let telegram = TelegramChannel::new(
+            config.bot_token.clone(),
+            config.allowed_users.clone(),
+            config.mention_only,
+        );
+
+        runtime = runtime.add_channel(telegram);
+        tracing::info!("Telegram channel enabled");
+    } else {
+        tracing::warn!("TELEGRAM_BOT_TOKEN not set, Telegram disabled");
+    }
+
+    // Add Teams channel if configured
+    if let (Ok(app_id), Ok(app_password)) = (
+        std::env::var("TEAMS_APP_ID"),
+        std::env::var("TEAMS_APP_PASSWORD"),
+    ) {
+        let config = TeamsConfig {
+            app_id,
+            app_password,
+            allowed_users: std::env::var("TEAMS_ALLOWED_USERS")
+                .map(|s| s.split(',').map(String::from).collect())
+                .unwrap_or_default(),
+            bot_name: std::env::var("TEAMS_BOT_NAME")
+                .unwrap_or_else(|_| "enact".to_string()),
+        };
+
+        let teams = TeamsChannel::new(&config);
+        let webhook_tx = teams.webhook_sender();
+
+        runtime = runtime.add_channel(teams);
+        tracing::info!("Teams channel enabled");
+
+        // Start webhook server for Teams
+        tokio::spawn(start_teams_webhook_server(webhook_tx));
+    } else {
+        tracing::warn!("TEAMS_APP_ID/TEAMS_APP_PASSWORD not set, Teams disabled");
+    }
+
+    // Run the channel runtime
+    tracing::info!("Bot is running. Press Ctrl+C to stop.");
+    runtime.run().await
+}
+
+/// Start an HTTP server for Teams webhook.
+async fn start_teams_webhook_server(webhook_tx: mpsc::Sender<TeamsActivity>) {
+    use axum::{routing::post, Router};
+
+    let app = Router::new()
+        .route("/api/messages", post(enact_channels::teams_webhook_handler))
+        .with_state(webhook_tx);
+
+    let port = std::env::var("TEAMS_WEBHOOK_PORT")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(3978);
+
+    let addr = std::net::SocketAddr::from(([0, 0, 0, 0], port));
+    tracing::info!("Teams webhook server listening on http://{}/api/messages", addr);
+
+    if let Err(e) = axum::serve(
+        tokio::net::TcpListener::bind(addr).await.unwrap(),
+        app,
+    ).await {
+        tracing::error!("Teams webhook server error: {}", e);
+    }
+}

package/crates/enact-channels/examples/telegram-echo.rs

@@ -0,0 +1,34 @@
+use async_trait::async_trait;
+use enact_channels::{ChannelMessage, ChannelRuntime, MessageHandler, TelegramChannel};
+
+struct EchoHandler;
+
+#[async_trait]
+impl MessageHandler for EchoHandler {
+    async fn handle(&self, message: &ChannelMessage) -> anyhow::Result<String> {
+        Ok(format!("echo: {}", message.content))
+    }
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let token = std::env::var("TELEGRAM_BOT_TOKEN")
+        .map_err(|_| anyhow::anyhow!("TELEGRAM_BOT_TOKEN is required"))?;
+
+    let allowlist = std::env::var("TELEGRAM_ALLOWED_USERS")
+        .ok()
+        .map(|value| {
+            value
+                .split(',')
+                .map(|entry| entry.trim().to_string())
+                .filter(|entry| !entry.is_empty())
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_default();
+
+    let telegram = TelegramChannel::new(token, allowlist, false);
+    let mut runtime = ChannelRuntime::new(EchoHandler).add_channel(telegram);
+
+    println!("telegram-echo running; press Ctrl+C to stop");
+    runtime.run().await
+}

package/crates/enact-channels/examples/whatsapp-echo.rs

@@ -0,0 +1,142 @@
+use axum::body::Bytes;
+use axum::extract::{Query, State};
+use axum::http::{HeaderMap, StatusCode};
+use axum::response::IntoResponse;
+use axum::routing::get;
+use axum::{Json, Router};
+use enact_channels::{Channel, SendMessage, WhatsAppChannel, verify_whatsapp_signature};
+use std::sync::Arc;
+
+#[derive(Clone)]
+struct AppState {
+    channel: Arc<WhatsAppChannel>,
+    app_secret: Option<String>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct VerifyQuery {
+    #[serde(rename = "hub.mode")]
+    mode: Option<String>,
+    #[serde(rename = "hub.verify_token")]
+    verify_token: Option<String>,
+    #[serde(rename = "hub.challenge")]
+    challenge: Option<String>,
+}
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    tracing_subscriber::fmt()
+        .with_env_filter(
+            tracing_subscriber::EnvFilter::from_default_env()
+                .add_directive("whatsapp_echo=info".parse().unwrap()),
+        )
+        .init();
+
+    let access_token = std::env::var("WHATSAPP_ACCESS_TOKEN")
+        .map_err(|_| anyhow::anyhow!("WHATSAPP_ACCESS_TOKEN is required"))?;
+    let endpoint_id = std::env::var("WHATSAPP_ENDPOINT_ID")
+        .map_err(|_| anyhow::anyhow!("WHATSAPP_ENDPOINT_ID is required"))?;
+    let verify_token = std::env::var("WHATSAPP_VERIFY_TOKEN")
+        .map_err(|_| anyhow::anyhow!("WHATSAPP_VERIFY_TOKEN is required"))?;
+
+    let allowed_numbers = std::env::var("WHATSAPP_ALLOWED_NUMBERS")
+        .ok()
+        .map(|value| {
+            value
+                .split(',')
+                .map(|entry| entry.trim().to_string())
+                .filter(|entry| !entry.is_empty())
+                .collect::<Vec<_>>()
+        })
+        .unwrap_or_else(|| vec!["*".to_string()]);
+
+    let channel = Arc::new(WhatsAppChannel::new(
+        access_token,
+        endpoint_id,
+        verify_token,
+        allowed_numbers,
+    ));
+    let app_secret = std::env::var("WHATSAPP_APP_SECRET").ok();
+    let state = AppState {
+        channel,
+        app_secret,
+    };
+
+    let app = Router::new()
+        .route("/whatsapp", get(handle_verify).post(handle_message))
+        .with_state(state);
+
+    let port = std::env::var("WHATSAPP_WEBHOOK_PORT")
+        .ok()
+        .and_then(|s| s.parse::<u16>().ok())
+        .unwrap_or(8080);
+    let addr = std::net::SocketAddr::from(([0, 0, 0, 0], port));
+
+    tracing::info!("whatsapp-echo listening on http://{}/whatsapp", addr);
+    let listener = tokio::net::TcpListener::bind(addr).await?;
+    axum::serve(listener, app).await?;
+    Ok(())
+}
+
+async fn handle_verify(
+    State(state): State<AppState>,
+    Query(query): Query<VerifyQuery>,
+) -> impl IntoResponse {
+    let token_matches = query
+        .verify_token
+        .as_deref()
+        .is_some_and(|token| token == state.channel.verify_token());
+
+    if query.mode.as_deref() == Some("subscribe") && token_matches {
+        if let Some(challenge) = query.challenge {
+            return (StatusCode::OK, challenge);
+        }
+        return (StatusCode::BAD_REQUEST, "missing hub.challenge".to_string());
+    }
+
+    (StatusCode::FORBIDDEN, "forbidden".to_string())
+}
+
+async fn handle_message(
+    State(state): State<AppState>,
+    headers: HeaderMap,
+    body: Bytes,
+) -> impl IntoResponse {
+    if let Some(secret) = state.app_secret.as_deref() {
+        let signature = headers
+            .get("X-Hub-Signature-256")
+            .and_then(|v| v.to_str().ok())
+            .unwrap_or("");
+
+        if !verify_whatsapp_signature(secret, &body, signature) {
+            return (
+                StatusCode::UNAUTHORIZED,
+                Json(serde_json::json!({"error": "Invalid signature"})),
+            );
+        }
+    }
+
+    let payload: serde_json::Value = match serde_json::from_slice(&body) {
+        Ok(value) => value,
+        Err(_) => {
+            return (
+                StatusCode::BAD_REQUEST,
+                Json(serde_json::json!({"error": "Invalid JSON payload"})),
+            );
+        }
+    };
+
+    let messages = state.channel.parse_webhook_payload(&payload);
+    for msg in messages {
+        let reply = format!("echo: {}", msg.content);
+        if let Err(err) = state
+            .channel
+            .send(&SendMessage::new(reply, &msg.reply_target))
+            .await
+        {
+            tracing::warn!("failed to send WhatsApp reply: {err}");
+        }
+    }
+
+    (StatusCode::OK, Json(serde_json::json!({"status": "ok"})))
+}

package/crates/enact-channels/src/config.rs

@@ -0,0 +1,213 @@
+//! Channel configuration types.
+//!
+//! Simplified from zeroclaw's config schema for enact-channels.
+
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+/// Build an HTTP client for channel communication.
+///
+/// The `_service_key` parameter is for future proxy configuration.
+pub fn build_runtime_proxy_client(_service_key: &str) -> reqwest::Client {
+    reqwest::Client::builder()
+        .timeout(std::time::Duration::from_secs(30))
+        .build()
+        .unwrap_or_else(|_| reqwest::Client::new())
+}
+
+/// Streaming mode for progressive message updates.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum StreamMode {
+    /// No streaming — send the complete response as a single message.
+    #[default]
+    Off,
+    /// Update a draft message with every flush interval.
+    Partial,
+}
+
+/// Telegram channel configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TelegramConfig {
+    /// Bot token from @BotFather.
+    pub bot_token: String,
+    /// List of allowed user IDs (empty = allow all).
+    #[serde(default)]
+    pub allowed_users: Vec<String>,
+    /// Whether to only respond when mentioned in groups.
+    #[serde(default)]
+    pub mention_only: bool,
+    /// Streaming mode for draft updates.
+    #[serde(default)]
+    pub stream_mode: StreamMode,
+    /// Draft update interval in milliseconds.
+    #[serde(default = "default_draft_interval")]
+    pub draft_update_interval_ms: u64,
+}
+
+fn default_draft_interval() -> u64 {
+    1000
+}
+
+impl Default for TelegramConfig {
+    fn default() -> Self {
+        Self {
+            bot_token: String::new(),
+            allowed_users: Vec::new(),
+            mention_only: false,
+            stream_mode: StreamMode::Off,
+            draft_update_interval_ms: 1000,
+        }
+    }
+}
+
+/// Teams channel configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct TeamsConfig {
+    /// Microsoft App ID from Azure Bot registration.
+    pub app_id: String,
+    /// Microsoft App Password (client secret).
+    pub app_password: String,
+    /// List of allowed user IDs (empty = allow all).
+    #[serde(default)]
+    pub allowed_users: Vec<String>,
+    /// Bot display name.
+    #[serde(default = "default_bot_name")]
+    pub bot_name: String,
+}
+
+/// WhatsApp channel configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct WhatsAppConfig {
+    /// WhatsApp Cloud API access token.
+    pub access_token: String,
+    /// Meta phone number ID used in Graph API paths.
+    pub endpoint_id: String,
+    /// Verify token used by webhook challenge endpoint.
+    pub verify_token: String,
+    /// Allowed sender numbers in E.164 format (+123...).
+    #[serde(default)]
+    pub allowed_numbers: Vec<String>,
+}
+
+impl Default for WhatsAppConfig {
+    fn default() -> Self {
+        Self {
+            access_token: String::new(),
+            endpoint_id: String::new(),
+            verify_token: String::new(),
+            allowed_numbers: Vec::new(),
+        }
+    }
+}
+
+fn default_bot_name() -> String {
+    "enact".to_string()
+}
+
+impl Default for TeamsConfig {
+    fn default() -> Self {
+        Self {
+            app_id: String::new(),
+            app_password: String::new(),
+            allowed_users: Vec::new(),
+            bot_name: "enact".to_string(),
+        }
+    }
+}
+
+/// Channels configuration container.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct ChannelsConfig {
+    /// Telegram configuration.
+    pub telegram: Option<TelegramConfig>,
+    /// Teams configuration.
+    pub teams: Option<TeamsConfig>,
+    /// WhatsApp configuration.
+    pub whatsapp: Option<WhatsAppConfig>,
+}
+
+/// Main configuration (simplified for channels).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Config {
+    /// Workspace directory.
+    #[serde(skip)]
+    pub workspace_dir: PathBuf,
+    /// Config file path.
+    #[serde(skip)]
+    pub config_path: PathBuf,
+    /// Channels configuration.
+    #[serde(default)]
+    pub channels: ChannelsConfig,
+}
+
+impl Default for Config {
+    fn default() -> Self {
+        let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from("."));
+        let workspace_dir = home.join(".enact");
+        let config_path = workspace_dir.join("config.toml");
+
+        Self {
+            workspace_dir,
+            config_path,
+            channels: ChannelsConfig::default(),
+        }
+    }
+}
+
+impl Config {
+    /// Load configuration from the default path.
+    pub fn load() -> anyhow::Result<Self> {
+        let home =
+            dirs::home_dir().ok_or_else(|| anyhow::anyhow!("Could not find home directory"))?;
+        let workspace_dir = home.join(".enact");
+        let config_path = workspace_dir.join("config.toml");
+
+        Self::load_from(&config_path)
+    }
+
+    /// Load configuration from a specific path.
+    pub fn load_from(path: &PathBuf) -> anyhow::Result<Self> {
+        if !path.exists() {
+            return Ok(Self::default());
+        }
+
+        let contents = std::fs::read_to_string(path)?;
+        let mut config: Config = toml::from_str(&contents)?;
+
+        let home = dirs::home_dir().unwrap_or_else(|| PathBuf::from("."));
+        config.workspace_dir = home.join(".enact");
+        config.config_path = path.clone();
+
+        Ok(config)
+    }
+
+    /// Get the workspace directory.
+    pub fn workspace_dir(&self) -> &PathBuf {
+        &self.workspace_dir
+    }
+
+    /// Save configuration to disk.
+    pub fn save(&self) -> anyhow::Result<()> {
+        // Ensure parent directory exists
+        if let Some(parent) = self.config_path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+
+        let contents = toml::to_string_pretty(self)?;
+        std::fs::write(&self.config_path, contents)?;
+        Ok(())
+    }
+
+    /// Alias for backward compatibility with zeroclaw code.
+    #[inline]
+    pub fn channels_config(&self) -> &ChannelsConfig {
+        &self.channels
+    }
+
+    /// Mutable access to channels config.
+    #[inline]
+    pub fn channels_config_mut(&mut self) -> &mut ChannelsConfig {
+        &mut self.channels
+    }
+}

package/crates/enact-channels/src/lib.rs

@@ -0,0 +1,25 @@
+//! enact-channels — Channel integrations for Enact
+//!
+//! Provides messaging platform integrations (Telegram, Teams, etc.)
+//! based on zeroclaw's proven channel abstraction.
+
+pub mod config;
+pub mod runtime;
+pub mod security;
+pub mod teams;
+pub mod telegram;
+pub mod traits;
+pub mod webhook;
+pub mod whatsapp;
+
+pub use config::{
+    ChannelsConfig, Config, StreamMode, TeamsConfig, TelegramConfig, WhatsAppConfig,
+    build_runtime_proxy_client,
+};
+pub use runtime::{ChannelRuntime, MessageHandler};
+pub use security::PairingGuard;
+pub use teams::{TeamsChannel, TeamsActivity, teams_webhook_handler};
+pub use traits::{Channel, ChannelMessage, SendMessage};
+pub use telegram::TelegramChannel;
+pub use webhook::{WebhookChannel, WebhookPayload};
+pub use whatsapp::{WhatsAppChannel, verify_whatsapp_signature};