Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! AI tools for the Discussion of every entity that carries one, addressed
//! the way the rest of the system addresses a discussion: by the kind and id
//! of its parent, or by a thread or comment id alone.
mod comment;
mod delete_comment;
mod edit_comment;
mod read_discussion;
mod resolve_comment;
#[cfg(test)]
mod test;
use std::sync::Arc;
use ai_toolset::{AsyncToolCollection, RequestContext, ToolCallError};
use bot_id::BotId;
use entity_access::domain::{
models::{AccessError, BotAccessScope, EntityAccessReceipt},
ports::EntityAccessService,
};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use uuid::Uuid;
pub use comment::Comment;
pub use delete_comment::DeleteComment;
pub use edit_comment::EditComment;
pub use read_discussion::ReadDiscussion;
pub use resolve_comment::ResolveComment;
use crate::domain::{
api::MessageServiceApi,
models::{InvalidParent, MessageAttribution, MessageParent},
ports::MessageError,
service::{MessageView, MessageWrite},
};
/// Service context for the discussion tools.
pub struct MessageToolContext<ESvc: EntityAccessService> {
/// Shared message service the tools read and write discussions through.
pub messages: Arc<dyn MessageServiceApi>,
/// Mints the capabilities the message service requires.
pub entity_access_service: Arc<ESvc>,
/// The bot these tools post 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<ESvc: EntityAccessService> Clone for MessageToolContext<ESvc> {
fn clone(&self) -> Self {
Self {
messages: self.messages.clone(),
entity_access_service: self.entity_access_service.clone(),
actor: self.actor,
via: self.via.clone(),
}
}
}
impl<ESvc: EntityAccessService> MessageToolContext<ESvc> {
/// Create a discussion tool context acting as Macro AI.
pub fn new(messages: Arc<dyn MessageServiceApi>, entity_access_service: Arc<ESvc>) -> Self {
Self {
messages,
entity_access_service,
actor: bot_id::MACRO_AI_BOT_ID,
via: None,
}
}
/// 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,
}
}
/// The requesting user's own view of a discussion.
async fn discussion_view(
&self,
request_context: &RequestContext,
parent: &MessageParent,
) -> Result<EntityAccessReceipt<MessageView>, ToolCallError> {
self.entity_access_service
.generate_entity_access_receipt::<MessageView>(
&request_context.user_id,
None,
&parent.entity_id(),
parent.access_entity_type(),
)
.await
.map_err(access_error(parent, "view"))
}
/// The bot's comment capability on a discussion on behalf of the
/// requesting user: the same comment access the web composer requires.
async fn discussion_write(
&self,
request_context: &RequestContext,
parent: &MessageParent,
) -> Result<EntityAccessReceipt<MessageWrite>, ToolCallError> {
self.entity_access_service
.generate_bot_entity_access_receipt::<MessageWrite>(
self.actor,
BotAccessScope::user(request_context.user_id.clone()),
&parent.entity_id(),
parent.access_entity_type(),
)
.await
.map_err(access_error(parent, "comment"))
}
/// The write capability for changing an existing comment as its author:
/// comments the tool actor bot posted are changed as the bot, and every
/// other comment as the user, so the message service applies the same
/// authorship and moderation rules as the web composer.
async fn comment_author_write(
&self,
request_context: &RequestContext,
parent: &MessageParent,
comment_id: Uuid,
) -> Result<EntityAccessReceipt<MessageWrite>, ToolCallError> {
let view = self.discussion_view(request_context, parent).await?;
let comment = self
.messages
.get(view, comment_id)
.await
.map_err(comment_error("unable to read the comment"))?;
if comment.sender_id.as_ref() == self.actor.into_storage_id().as_ref() {
return self.discussion_write(request_context, parent).await;
}
self.entity_access_service
.generate_entity_access_receipt::<MessageWrite>(
&request_context.user_id,
None,
&parent.entity_id(),
parent.access_entity_type(),
)
.await
.map_err(access_error(parent, "comment"))
}
/// The Discussion a comment or thread belongs to, found from its id
/// alone. Grants nothing: the caller mints the parent's receipt before
/// reading or writing.
async fn discussion_of(
&self,
id: Uuid,
) -> Result<(DiscussionParentType, MessageParent), ToolCallError> {
let parent = match self.messages.parent_of(id).await {
Ok(Some(parent)) => parent,
Ok(None) => {
return Err(ToolCallError {
description: format!("no comment or thread with id {id}"),
internal_error: MessageError::NotFound.into(),
});
}
Err(error) => {
return Err(ToolCallError {
description: "unable to look up the comment".to_owned(),
internal_error: error.into(),
});
}
};
match DiscussionParentType::from_parent(&parent) {
Some(kind) => Ok((kind, parent)),
None => Err(ToolCallError {
description: format!(
"{id} is a message in a {}, not a Discussion comment; use the channel message tools for it",
parent_noun(&parent)
),
internal_error: MessageError::Invalid("message is not a discussion comment").into(),
}),
}
}
}
/// Create the discussion toolset.
pub fn message_toolset<ESvc: EntityAccessService>() -> AsyncToolCollection<MessageToolContext<ESvc>>
{
AsyncToolCollection::new()
.add_tool::<ReadDiscussion, MessageToolContext<ESvc>>()
.add_tool::<Comment, MessageToolContext<ESvc>>()
.add_tool::<EditComment, MessageToolContext<ESvc>>()
.add_tool::<DeleteComment, MessageToolContext<ESvc>>()
.add_tool::<ResolveComment, MessageToolContext<ESvc>>()
}
/// The kinds of item that carry a Discussion.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum DiscussionParentType {
/// A document of any type, including tasks, PDFs and uploaded files: the
/// id in a macro.com/app/<block>/<id> link such as /app/md/<id>,
/// /app/task/<id> or /app/pdf/<id>.
Document,
/// A Tasks project, which the API calls an initiative: the id in a
/// macro.com/app/tasks/projects/<id> link, the kind ReadInitiative reads.
/// Not a folder: folders (ReadProject) have no Discussion.
Initiative,
/// A CRM company, the kind GetCompany reads.
CrmCompany,
/// A CRM contact.
CrmContact,
}
impl DiscussionParentType {
/// The parent an item of this kind addresses, from its id.
fn parent(self, id: &str) -> Result<MessageParent, InvalidParent> {
let uuid = || id.parse::<Uuid>().map_err(|_| InvalidParent);
Ok(match self {
Self::Document => MessageParent::Document(id.to_owned().try_into()?),
Self::Initiative => MessageParent::Initiative(uuid()?),
Self::CrmCompany => MessageParent::CrmCompany(uuid()?),
Self::CrmContact => MessageParent::CrmContact(uuid()?),
})
}
/// The kind of a parent that carries a Discussion; `None` for a channel
/// or call, whose messages are not comments. Exhaustive on purpose: a new
/// parent decides here whether the discussion tools address it.
fn from_parent(parent: &MessageParent) -> Option<Self> {
match parent {
MessageParent::Document(_) => Some(Self::Document),
MessageParent::Initiative(_) => Some(Self::Initiative),
MessageParent::CrmCompany(_) => Some(Self::CrmCompany),
MessageParent::CrmContact(_) => Some(Self::CrmContact),
MessageParent::Channel(_) | MessageParent::Call(_) => None,
}
}
/// The word the application uses for an item of this kind.
fn noun(self) -> &'static str {
match self {
Self::Document => "document",
Self::Initiative => "project",
Self::CrmCompany => "company",
Self::CrmContact => "contact",
}
}
}
/// A parent addressed by kind and id, when both were given.
fn parse_target(
entity_type: Option<DiscussionParentType>,
entity_id: Option<&str>,
) -> Result<Option<(DiscussionParentType, MessageParent)>, ToolCallError> {
match (entity_type, entity_id) {
(None, None) => Ok(None),
(Some(kind), Some(id)) => {
kind.parent(id)
.map(|parent| Some((kind, parent)))
.map_err(|error| ToolCallError {
description: format!("{id} is not a valid {} id", kind.noun()),
internal_error: error.into(),
})
}
(Some(_), None) | (None, Some(_)) => Err(ToolCallError {
description: "entityType and entityId go together: pass both to address an item"
.to_owned(),
internal_error: InvalidParent.into(),
}),
}
}
/// The word the application uses for a parent, including the ones that
/// carry no Discussion.
fn parent_noun(parent: &MessageParent) -> &'static str {
match DiscussionParentType::from_parent(parent) {
Some(kind) => kind.noun(),
None => match parent {
MessageParent::Channel(_) => "channel",
_ => "call",
},
}
}
/// `need` is the access the tool spends on the parent: `view` or `comment`.
fn access_error(
parent: &MessageParent,
need: &'static str,
) -> impl FnOnce(AccessError) -> ToolCallError {
let kind = parent_noun(parent);
let id = parent.entity_id();
move |error| {
let description = match &error {
AccessError::Unauthorized | AccessError::UnauthorizedWithMessage(_) => {
format!("you need {need} access to this {kind} to use its Discussion")
}
AccessError::NotFound(_) => format!(
"no {kind} with id {id}; check entityType: a Tasks project is initiative, a task or PDF is document, and a folder has no Discussion"
),
AccessError::BadRequest(_) => format!("{id} is not a valid {kind} id"),
AccessError::Unavailable(_) | AccessError::Internal(_) => {
format!("failed to verify access to the {kind}")
}
};
ToolCallError {
description,
internal_error: error.into(),
}
}
}
fn comment_error(description: &'static str) -> impl FnOnce(MessageError) -> ToolCallError {
move |error| {
let description = match &error {
MessageError::NotFound => {
"comment thread not found in this item's Discussion".to_owned()
}
MessageError::Forbidden => {
"you need comment access to this item to comment on it".to_owned()
}
MessageError::Invalid(reason) => format!("{description}: {reason}"),
MessageError::Conflict => format!("{description}: message id already exists"),
MessageError::Repository(_) => description.to_owned(),
};
ToolCallError {
description,
internal_error: error.into(),
}
}
}