Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

16.0 KB
Raw Blame
//! AI tools for reading channel messages and mutating channel membership.

mod create_channel;
mod create_channel_media_upload;
mod delete_channel_message;
mod edit_channel_message;
mod manage_channel_participants;
mod open_direct_message;
mod react_to_channel_message;
mod read_channel_message_context;
mod read_channel_messages;
mod read_channel_thread;
mod rename_channel;
mod send_channel_message;
mod share_with_channel;
mod types;

#[cfg(test)]
mod test;

use crate::{
    domain::{models::Sender, ports::ChannelMutationErr, ports::ChannelService},
    inbound::toolset::{
        create_channel::CreateChannel, delete_channel_message::DeleteChannelMessage,
        edit_channel_message::EditChannelMessage,
        manage_channel_participants::ManageChannelParticipants,
        open_direct_message::OpenDirectMessage, react_to_channel_message::ReactToChannelMessage,
        rename_channel::RenameChannel, send_channel_message::SendChannelMessage,
        share_with_channel::ShareWithChannel,
    },
};
use ai_toolset::{AsyncToolCollection, RequestContext, ToolCallError};
use bot_id::BotId;
use entity_access::domain::{
    models::{
        AccessError, BotAccessScope, EntityAccessReceipt, EntityType, MemberParticipantRole,
        RequiredPermission,
    },
    ports::EntityAccessService,
};
use macro_user_id::user_id::MacroUserIdStr;
use messages::domain::{
    api::MessageServiceApi,
    models::MessageAttribution,
    ports::MessageError,
    service::{MessageView, MessageWrite},
};
use std::{collections::HashSet, sync::Arc};
use types::SenderNames;
use uuid::Uuid;

pub use create_channel_media_upload::{
    ChannelMediaUploadToolContext, CreateChannelMediaUpload, CreateChannelMediaUploadResponse,
};
pub use read_channel_message_context::{
    ReadChannelMessageContext, ReadChannelMessageContextResponse,
};
pub use read_channel_messages::{ReadChannelMessages, ReadChannelMessagesResponse};
pub use read_channel_thread::{ReadChannelThread, ReadChannelThreadResponse};
pub use types::{ChannelAttachmentKind, ChannelMessageAttachmentInput};

/// Service context for channel AI tools.
pub struct ChannelToolContext<Svc, AccessSvc>
where
    Svc: ChannelService,
    AccessSvc: EntityAccessService,
{
    /// Shared message application: channel timelines, threads, and posts.
    pub messages: Arc<dyn MessageServiceApi>,
    /// Channel service used for channel metadata and membership mutations.
    pub service: Arc<Svc>,
    /// Entity access service used to ensure the caller is a channel member.
    pub entity_access_service: Arc<AccessSvc>,
    /// The bot these tools act as, on behalf of the requesting user. Defaults
    /// to Macro AI; hosts running a specific agent set it with [`Self::with_actor`].
    pub actor: BotId,
    /// The client the requesting user works through, labelled on posts.
    pub via: Option<String>,
}

impl<Svc, AccessSvc> Clone for ChannelToolContext<Svc, AccessSvc>
where
    Svc: ChannelService,
    AccessSvc: EntityAccessService,
{
    fn clone(&self) -> Self {
        Self {
            messages: self.messages.clone(),
            service: self.service.clone(),
            entity_access_service: self.entity_access_service.clone(),
            actor: self.actor,
            via: self.via.clone(),
        }
    }
}

impl<Svc, AccessSvc> ChannelToolContext<Svc, AccessSvc>
where
    Svc: ChannelService,
    AccessSvc: EntityAccessService,
{
    /// Create a new channel tool context.
    pub fn new(
        messages: Arc<dyn MessageServiceApi>,
        service: Svc,
        entity_access_service: AccessSvc,
    ) -> Self {
        Self {
            messages,
            service: Arc::new(service),
            entity_access_service: Arc::new(entity_access_service),
            actor: bot_id::MACRO_AI_BOT_ID,
            via: None,
        }
    }

    /// Mint the bot's channel write capability on behalf of the requesting user.
    pub async fn require_channel_message_write(
        &self,
        request_context: &RequestContext,
        channel_id: Uuid,
    ) -> Result<EntityAccessReceipt<MessageWrite>, ToolCallError> {
        self.entity_access_service
            .generate_bot_entity_access_receipt::<MessageWrite>(
                self.actor,
                BotAccessScope::user(request_context.user_id.clone()),
                &channel_id.to_string(),
                EntityType::Channel,
            )
            .await
            .map_err(|error| channel_receipt_error(ChannelReceiptKind::Member, error))
    }

    /// Set the bot these tools act as.
    pub fn with_actor(mut self, actor: BotId) -> Self {
        self.actor = actor;
        self
    }

    /// Label the posts these tools make with the client the requesting user
    /// works through, such as an MCP client.
    pub fn with_via(mut self, client: String) -> Self {
        self.via = Some(client);
        self
    }

    /// How a post made by these tools is attributed.
    pub fn attribution(&self) -> MessageAttribution {
        match &self.via {
            Some(client) => MessageAttribution::ActingUserVia {
                client: client.clone(),
            },
            None => MessageAttribution::ActingUser,
        }
    }

    /// Mint the requesting user's own channel write capability, for actions
    /// the app attributes to the user rather than to the tool actor bot.
    pub async fn require_user_message_write(
        &self,
        request_context: &RequestContext,
        channel_id: Uuid,
    ) -> Result<EntityAccessReceipt<MessageWrite>, ToolCallError> {
        self.entity_access_service
            .generate_entity_access_receipt::<MessageWrite>(
                &request_context.user_id,
                None,
                &channel_id.to_string(),
                EntityType::Channel,
            )
            .await
            .map_err(channel_access_error)
    }

    /// Mint the write capability for changing an existing message as its
    /// author: messages the tool actor bot posted are changed as the bot, and
    /// every other message as the user, so the message service applies the
    /// same authorship and moderation rules as in the app.
    pub async fn require_message_author_write(
        &self,
        request_context: &RequestContext,
        channel_id: Uuid,
        message_id: Uuid,
    ) -> Result<EntityAccessReceipt<MessageWrite>, ToolCallError> {
        let view = self
            .require_channel_member(request_context, channel_id)
            .await?;
        let message = self
            .messages
            .get(view, message_id)
            .await
            .map_err(message_mutation_error("read the message"))?;
        if message.sender_id == Sender::new_from_bot(self.actor) {
            self.require_channel_message_write(request_context, channel_id)
                .await
        } else {
            self.require_user_message_write(request_context, channel_id)
                .await
        }
    }

    /// Require that the request user is an active member of the channel before
    /// reading it, minting the read capability the message reads take.
    pub async fn require_channel_member(
        &self,
        request_context: &RequestContext,
        channel_id: Uuid,
    ) -> Result<EntityAccessReceipt<MessageView>, ToolCallError> {
        self.entity_access_service
            .generate_entity_access_receipt::<MessageView>(
                &request_context.user_id,
                None,
                &channel_id.to_string(),
                EntityType::Channel,
            )
            .await
            .map_err(channel_access_error)
    }

    /// Profile names for the people among `user_senders`, so the read tools
    /// name them as the app does. A failed lookup leaves the names out rather
    /// than failing the read.
    pub(crate) async fn sender_names(
        &self,
        user_senders: HashSet<MacroUserIdStr<'static>>,
    ) -> SenderNames {
        if user_senders.is_empty() {
            return SenderNames::new();
        }
        self.service
            .get_user_display_names(user_senders.into_iter().collect())
            .await
            .inspect_err(|error| tracing::warn!(error = ?error, "failed to resolve sender names"))
            .unwrap_or_default()
    }

    /// Mint a member receipt before renaming a channel.
    pub async fn require_channel_rename(
        &self,
        request_context: &RequestContext,
        channel_id: Uuid,
    ) -> Result<EntityAccessReceipt<MemberParticipantRole>, ToolCallError> {
        self.channel_receipt(request_context, channel_id, ChannelReceiptKind::Rename)
            .await
    }

    /// Mint the same member receipt HTTP uses before changing participants.
    pub async fn require_channel_member_role(
        &self,
        request_context: &RequestContext,
        channel_id: Uuid,
    ) -> Result<EntityAccessReceipt<MemberParticipantRole>, ToolCallError> {
        self.channel_receipt(request_context, channel_id, ChannelReceiptKind::Member)
            .await
    }

    async fn channel_receipt<P: RequiredPermission>(
        &self,
        request_context: &RequestContext,
        channel_id: Uuid,
        kind: ChannelReceiptKind,
    ) -> Result<EntityAccessReceipt<P>, ToolCallError> {
        self.entity_access_service
            .generate_entity_access_receipt::<P>(
                &request_context.user_id,
                None,
                &channel_id.to_string(),
                EntityType::Channel,
            )
            .await
            .map_err(|error| channel_receipt_error(kind, error))
    }
}

#[derive(Clone, Copy)]
enum ChannelReceiptKind {
    Rename,
    Member,
}

fn channel_access_error(err: AccessError) -> ToolCallError {
    let description = match err {
        AccessError::Unauthorized | AccessError::UnauthorizedWithMessage(_) => {
            "user is not a member of the requested channel"
        }
        AccessError::NotFound(_) => "channel not found",
        AccessError::BadRequest(_) => "invalid channel id",
        AccessError::Unavailable(_) | AccessError::Internal(_) => {
            "failed to verify channel membership"
        }
    };

    ToolCallError {
        description: description.to_string(),
        internal_error: err.into(),
    }
}

fn channel_receipt_error(kind: ChannelReceiptKind, err: AccessError) -> ToolCallError {
    let description = match (kind, &err) {
        (
            ChannelReceiptKind::Rename,
            AccessError::Unauthorized | AccessError::UnauthorizedWithMessage(_),
        ) => "you must be a member of the channel to rename it",
        (
            ChannelReceiptKind::Member,
            AccessError::Unauthorized | AccessError::UnauthorizedWithMessage(_),
        ) => "you must be a member of the channel to change its participants",
        (_, AccessError::NotFound(_)) => "channel not found",
        (_, AccessError::BadRequest(_)) => "invalid channel id",
        (_, AccessError::Unavailable(_) | AccessError::Internal(_)) => {
            "failed to verify channel membership"
        }
    };

    ToolCallError {
        description: description.to_string(),
        internal_error: err.into(),
    }
}

fn user_sender<P: RequiredPermission>(
    receipt: &EntityAccessReceipt<P>,
) -> Result<Sender, ToolCallError> {
    receipt
        .get_authenticated_user()
        .cloned()
        .map(Sender::new_from_user)
        .map_err(|error| ToolCallError {
            description: "authenticated user required".to_string(),
            internal_error: error.into(),
        })
}

fn channel_mutation_error(action: &'static str, err: ChannelMutationErr) -> ToolCallError {
    let description = match &err {
        ChannelMutationErr::BadRequest(message)
        | ChannelMutationErr::Unauthorized(message)
        | ChannelMutationErr::Forbidden(message)
        | ChannelMutationErr::NotFound(message) => message.clone(),
        ChannelMutationErr::Repo(_)
        | ChannelMutationErr::Gateway(_)
        | ChannelMutationErr::Notification(_)
        | ChannelMutationErr::Contacts(_) => format!("failed to {action}"),
    };

    ToolCallError {
        description,
        internal_error: err.into(),
    }
}

/// Map a message mutation failure onto an actionable tool error.
fn message_mutation_error(action: &'static str) -> impl FnOnce(MessageError) -> ToolCallError {
    move |err| {
        let description = match &err {
            MessageError::NotFound => "message not found in this channel".to_string(),
            MessageError::Forbidden => format!(
                "not allowed to {action}: only the message's author or a channel admin or owner can change it"
            ),
            MessageError::Invalid(message) => (*message).to_string(),
            MessageError::Conflict | MessageError::Repository(_) => format!("failed to {action}"),
        };
        ToolCallError {
            description,
            internal_error: anyhow::Error::new(err),
        }
    }
}

const MAX_CHANNEL_NAME_CHARS: usize = 255;

fn channel_name(name: &str) -> Result<String, ToolCallError> {
    let trimmed = name.trim();
    if trimmed.is_empty() {
        return Err(ToolCallError {
            description: "channel name must not be empty".to_string(),
            internal_error: anyhow::anyhow!("empty channel name"),
        });
    }
    if trimmed.chars().count() > MAX_CHANNEL_NAME_CHARS {
        return Err(ToolCallError {
            description: format!(
                "channel name must be {MAX_CHANNEL_NAME_CHARS} characters or fewer"
            ),
            internal_error: anyhow::anyhow!("channel name exceeds {MAX_CHANNEL_NAME_CHARS} chars"),
        });
    }
    Ok(trimmed.to_string())
}

fn parse_participants(entries: &[String]) -> Result<Vec<MacroUserIdStr<'static>>, ToolCallError> {
    let mut participants = Vec::new();
    let mut seen = std::collections::HashSet::new();
    let mut invalid = Vec::new();

    for (index, raw) in entries.iter().enumerate() {
        let trimmed = raw.trim();
        if trimmed.is_empty() {
            invalid.push(format!("participants[{index}] is empty"));
            continue;
        }
        match parse_participant(trimmed) {
            Ok(user_id) => {
                if seen.insert(user_id.as_ref().to_string()) {
                    participants.push(user_id);
                }
            }
            Err(()) => invalid.push(format!(
                "participants[{index}] `{trimmed}` is not a user id (`macro|<email>`) or email"
            )),
        }
    }

    if !invalid.is_empty() {
        return Err(ToolCallError {
            description: invalid.join("; "),
            internal_error: anyhow::anyhow!("invalid channel participant ids"),
        });
    }

    Ok(participants)
}

fn parse_participant(raw: &str) -> Result<MacroUserIdStr<'static>, ()> {
    MacroUserIdStr::try_from(raw.to_string())
        .or_else(|_| MacroUserIdStr::try_from_email(raw))
        .map_err(|_| ())
}

fn participant_id_strings(participants: &[MacroUserIdStr<'static>]) -> Vec<String> {
    participants
        .iter()
        .map(|user_id| user_id.as_ref().to_string())
        .collect()
}

/// Create the channel AI toolset.
pub fn channel_toolset<Svc, AccessSvc>() -> AsyncToolCollection<ChannelToolContext<Svc, AccessSvc>>
where
    Svc: ChannelService,
    AccessSvc: EntityAccessService,
{
    AsyncToolCollection::new()
        .add_tool::<ReadChannelMessages, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<ReadChannelMessageContext, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<ReadChannelThread, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<SendChannelMessage, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<ShareWithChannel, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<CreateChannel, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<RenameChannel, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<ManageChannelParticipants, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<EditChannelMessage, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<DeleteChannelMessage, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<ReactToChannelMessage, ChannelToolContext<Svc, AccessSvc>>()
        .add_tool::<OpenDirectMessage, ChannelToolContext<Svc, AccessSvc>>()
}