storkit/server/src/matrix/mod.rs

//! Matrix bot integration for Story Kit.
//!
//! When a `.story_kit/bot.toml` file is present with `enabled = true`, the
//! server spawns a Matrix bot that:
//!
//! 1. Connects to the configured homeserver and joins the configured room.
//! 2. Listens for messages from other users in the room.
//! 3. Passes each message to Claude Code (the same provider as the web UI),
//!    which has native access to Story Kit MCP tools.
//! 4. Posts Claude Code's response back to the room.
//!
//! The bot is optional — if `bot.toml` is missing or `enabled = false`, the
//! server starts normally with no Matrix connection.
//!
//! Multi-room support: configure `room_ids = ["!room1:…", "!room2:…"]` in
//! `bot.toml`. Each room maintains its own independent conversation history.

mod bot;
mod config;

pub use config::BotConfig;

use std::path::Path;

/// Attempt to start the Matrix bot.
///
/// Reads the bot configuration from `.story_kit/bot.toml`. If the file is
/// absent or `enabled = false`, this function returns immediately without
/// spawning anything — the server continues normally.
///
/// Must be called from within a Tokio runtime context (e.g., from `main`).
pub fn spawn_bot(project_root: &Path) {
    let config = match BotConfig::load(project_root) {
        Some(c) => c,
        None => {
            crate::slog!("[matrix-bot] bot.toml absent or disabled; Matrix integration skipped");
            return;
        }
    };

    crate::slog!(
        "[matrix-bot] Starting Matrix bot → homeserver={} rooms={:?}",
        config.homeserver,
        config.effective_room_ids()
    );

    let root = project_root.to_path_buf();
    tokio::spawn(async move {
        if let Err(e) = bot::run_bot(config, root).await {
            crate::slog!("[matrix-bot] Fatal error: {e}");
        }
    });
}