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
//! Toolset inbound adapter for Documents.
mod canvas;
mod comment_on_text;
mod create_document;
mod create_skill;
mod design;
mod edit_document;
mod illustrator;
mod photoshop;
mod presentation;
mod read_content;
mod read_metadata;
mod rename_document;
mod spreadsheet;
mod upload_file;
mod word_document;
#[cfg(test)]
mod comment_test;
#[cfg(test)]
mod test;
use crate::{
domain::comments::{DocumentCommentReader, DocumentComments},
domain::create::DocumentCreator,
domain::design::{DesignFiles, DesignService, NoDesignFiles},
domain::illustrator::{IllustratorFiles, IllustratorService, NoIllustratorFiles},
domain::photoshop::{NoPhotoshopFiles, PhotoshopFiles, PhotoshopService},
domain::ports::DocumentService,
domain::ports::create::DocumentCreationService,
domain::ports::editing::{EditingWorkerService, EditorName},
domain::ports::mentions::NoOpDocumentMentionTracker,
domain::presentation::{NoPresentationFiles, PresentationFiles, PresentationService},
domain::word_document::WordDocumentFiles,
inbound::toolset::{
canvas::{ApplyCanvasEdits, EditCanvas, ReadCanvas, RenderCanvas},
comment_on_text::CommentOnText,
create_document::CreateDocument,
create_skill::CreateSkill,
design::ReadDesign,
edit_document::EditDocument,
illustrator::ReadIllustratorDocument,
photoshop::ReadPhotoshopDocument,
presentation::{EditPresentation, ReadPresentation},
read_content::ReadContent,
read_metadata::ReadMetadata,
rename_document::RenameDocument,
spreadsheet::{CalculateSpreadsheet, EditSpreadsheet, ReadSpreadsheet},
upload_file::UploadFile,
word_document::{EditWordDocument, ReadWordDocument},
},
outbound::{
document_bytes_upload::ReqwestDocumentBytesUploader,
lexical_comment_marks::LexicalCommentMarks, markdown_init::LexicalSyncMarkdownInitializer,
},
};
use ai_toolset::{AsyncToolCollection, RequestContext, ToolCallError};
use bot_id::BotId;
use entity_access::domain::{
models::{AccessError, BotAccessScope, EntityAccessReceipt, EntityType},
ports::EntityAccessService,
};
use lexical_client::LexicalClient;
use macro_user_id::user_id::MacroUserIdStr;
use messages::domain::{
api::MessageServiceApi, models::MessageAttribution, ports::MessageError, service::MessageWrite,
};
use model_owner::CreationPrincipal;
use std::sync::Arc;
use sync_service_client::SyncServiceClient;
use uuid::Uuid;
/// Default backend-owned document creation use case for document tools.
pub type DefaultDocumentToolCreator<DSvc> = DocumentCreator<
Arc<DSvc>,
LexicalSyncMarkdownInitializer,
ReqwestDocumentBytesUploader,
NoOpDocumentMentionTracker,
>;
/// Service context for document AI tools
pub struct DocumentToolContext<
DSvc: DocumentService + DocumentCreationService,
ESvc: EntityAccessService,
EDSvc: EditingWorkerService,
> {
/// The document service instance
pub service: Arc<DSvc>,
/// The entity access service instance
pub entity_access_service: Arc<ESvc>,
/// The lexical client
pub lexical_client: Arc<LexicalClient>,
/// The sync-service client
pub sync_service_client: Arc<SyncServiceClient>,
/// Backend-owned document creation use case.
pub creator: DefaultDocumentToolCreator<DSvc>,
/// Editing worker service for the EditDocument tool.
pub editing: Arc<EDSvc>,
/// Whether a user has Canvas artifacts. Hosts without a flag provider keep
/// the default, which is off for everyone; wire one with
/// [`Self::with_canvas_artifacts`].
pub canvas_artifacts: crate::domain::canvas::CanvasArtifactsRollout,
/// A document's comment threads, read by the ReadContent tool.
pub comments: Arc<dyn DocumentComments>,
/// Shared message service the comment tools reply and resolve through.
pub messages: Arc<dyn MessageServiceApi>,
/// Permission-scoped deterministic spreadsheet workflows.
pub spreadsheet: Arc<crate::domain::spreadsheet::SpreadsheetService<DSvc, EDSvc>>,
/// Reading and editing uploaded Word documents through their live copy.
/// Hosts without a file store keep the default, which cannot seed a
/// document nobody has opened yet; wire one with
/// [`Self::with_word_document_files`].
pub word_documents:
Arc<crate::domain::word_document::WordDocumentService<DSvc, EDSvc, SyncServiceClient>>,
/// Reading and editing PowerPoint presentations. Hosts without a file
/// store keep the default, whose calls fail with a clear message; wire
/// one with [`Self::with_presentation_files`].
pub presentations: Arc<PresentationService>,
/// Reading Figma designs. Hosts without a file store keep the default,
/// whose calls fail with a clear message; wire one with
/// [`Self::with_design_files`].
pub designs: Arc<DesignService>,
/// Reading Photoshop documents. Hosts without a file store keep the
/// default, whose calls fail with a clear message; wire one with
/// [`Self::with_photoshop_files`].
pub photoshop_documents: Arc<PhotoshopService>,
/// Reading Illustrator documents. Hosts without a file store keep the
/// default, whose calls fail with a clear message; wire one with
/// [`Self::with_illustrator_files`].
pub illustrator_documents: Arc<IllustratorService>,
/// JWT secret used to mint document permission tokens for the editing worker.
pub document_permission_jwt_secret: String,
/// Shared admission used by the domain AI-editing use case.
pub admission: Arc<dyn ai_billing::domain::admission::AiAdmissionService>,
/// Records the token usage the editing worker reports. Defaults to a no-op;
/// the chat path injects the real (Postgres-backed) recorder per request.
pub recorder: Arc<dyn ai_usage::UsageRecorder>,
/// 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 display name of [`Self::actor`] as the host knows it, set with
/// [`Self::with_actor_name`]. First-party bots need none: their names are
/// compile-time constants. A user- or team-owned bot is a row the host has
/// already read, so it hands the name over rather than have every tool
/// look it up again.
actor_name: Option<EditorName>,
/// The client the requesting user drives these tools through, such as an
/// MCP client, set with [`Self::with_via`]; comments carry it as a label.
via: Option<String>,
}
impl<
DSvc: DocumentService + DocumentCreationService,
ESvc: EntityAccessService,
EDSvc: EditingWorkerService,
> Clone for DocumentToolContext<DSvc, ESvc, EDSvc>
{
fn clone(&self) -> Self {
Self {
service: self.service.clone(),
entity_access_service: self.entity_access_service.clone(),
lexical_client: self.lexical_client.clone(),
sync_service_client: self.sync_service_client.clone(),
creator: self.creator.clone(),
editing: self.editing.clone(),
canvas_artifacts: self.canvas_artifacts.clone(),
comments: self.comments.clone(),
messages: self.messages.clone(),
spreadsheet: self.spreadsheet.clone(),
word_documents: self.word_documents.clone(),
presentations: self.presentations.clone(),
designs: self.designs.clone(),
photoshop_documents: self.photoshop_documents.clone(),
illustrator_documents: self.illustrator_documents.clone(),
document_permission_jwt_secret: self.document_permission_jwt_secret.clone(),
admission: self.admission.clone(),
recorder: self.recorder.clone(),
actor: self.actor,
actor_name: self.actor_name.clone(),
via: self.via.clone(),
}
}
}
impl<
DSvc: DocumentService + DocumentCreationService,
ESvc: EntityAccessService,
EDSvc: EditingWorkerService,
> DocumentToolContext<DSvc, ESvc, EDSvc>
{
/// Create a new document tool context
pub fn new(
service: DSvc,
entity_access_service: ESvc,
lexical_client: LexicalClient,
sync_service_client: SyncServiceClient,
editing: EDSvc,
document_permission_jwt_secret: String,
messages: Arc<dyn MessageServiceApi>,
) -> Self {
let service = Arc::new(service);
let lexical_client = Arc::new(lexical_client);
let sync_service_client = Arc::new(sync_service_client);
let creator = DocumentCreator::new(
service.clone(),
LexicalSyncMarkdownInitializer::detached(
lexical_client.as_ref().clone(),
sync_service_client.as_ref().clone(),
),
ReqwestDocumentBytesUploader::default(),
NoOpDocumentMentionTracker,
);
let comments = Arc::new(DocumentCommentReader::new(
messages.clone(),
LexicalCommentMarks::new(lexical_client.clone()),
));
let editing = Arc::new(editing);
let spreadsheet = Arc::new(crate::domain::spreadsheet::SpreadsheetService::new(
service.clone(),
editing.clone(),
document_permission_jwt_secret.clone(),
));
let word_documents = Arc::new(crate::domain::word_document::WordDocumentService::new(
service.clone(),
editing.clone(),
sync_service_client.clone(),
Arc::new(crate::domain::word_document::NoWordDocumentFiles),
document_permission_jwt_secret.clone(),
));
Self {
service,
entity_access_service: Arc::new(entity_access_service),
lexical_client,
sync_service_client,
creator,
editing,
canvas_artifacts: Arc::new(|_| Box::pin(async { false })),
comments,
messages,
spreadsheet,
word_documents,
presentations: Arc::new(PresentationService::new(Arc::new(NoPresentationFiles))),
designs: Arc::new(DesignService::new(Arc::new(NoDesignFiles))),
photoshop_documents: Arc::new(PhotoshopService::new(Arc::new(NoPhotoshopFiles))),
illustrator_documents: Arc::new(IllustratorService::new(Arc::new(NoIllustratorFiles))),
document_permission_jwt_secret,
admission: Arc::new(ai_billing::domain::admission::DisabledAiAdmissionService),
recorder: Arc::new(ai_usage::NoOpUsageRecorder),
actor: bot_id::MACRO_AI_BOT_ID,
actor_name: None,
via: None,
}
}
/// Configure admission for AI edits; deterministic operations do not use it.
pub fn with_admission(
mut self,
admission: Arc<dyn ai_billing::domain::admission::AiAdmissionService>,
) -> Self {
self.admission = admission;
self
}
/// The AI-editing use case using the currently injected services.
pub fn ai_editing(&self) -> crate::domain::ai_editing::AiEditingService<EDSvc> {
crate::domain::ai_editing::AiEditingService::new(
self.editing.clone(),
self.admission.clone(),
self.recorder.clone(),
)
}
/// Store presentations the presentation tools read and edit through `files`.
pub fn with_presentation_files(mut self, files: Arc<dyn PresentationFiles>) -> Self {
self.presentations = Arc::new(PresentationService::new(files));
self
}
/// Read uploaded Word files through `files`, so the Word tools can seed a
/// document nobody has opened yet.
pub fn with_word_document_files(mut self, files: Arc<dyn WordDocumentFiles>) -> Self {
self.word_documents = Arc::new(crate::domain::word_document::WordDocumentService::new(
self.service.clone(),
self.editing.clone(),
self.sync_service_client.clone(),
files,
self.document_permission_jwt_secret.clone(),
));
self
}
/// Read designs the design tools describe through `files`.
pub fn with_design_files(mut self, files: Arc<dyn DesignFiles>) -> Self {
self.designs = Arc::new(DesignService::new(files));
self
}
/// Read the Photoshop documents the Photoshop tools describe through
/// `files`.
pub fn with_photoshop_files(mut self, files: Arc<dyn PhotoshopFiles>) -> Self {
self.photoshop_documents = Arc::new(PhotoshopService::new(files));
self
}
/// Read the Illustrator documents the Illustrator tools describe through
/// `files`.
pub fn with_illustrator_files(mut self, files: Arc<dyn IllustratorFiles>) -> Self {
self.illustrator_documents = Arc::new(IllustratorService::new(files));
self
}
/// Set the usage recorder the EditDocument tool logs worker token usage to.
pub fn with_recorder(mut self, recorder: Arc<dyn ai_usage::UsageRecorder>) -> Self {
self.recorder = recorder;
self
}
/// Read each user's Canvas artifacts rollout from this provider.
pub fn with_canvas_artifacts(
mut self,
rollout: crate::domain::canvas::CanvasArtifactsRollout,
) -> Self {
self.canvas_artifacts = rollout;
self
}
/// Set the bot these tools act as.
pub fn with_actor(mut self, actor: BotId) -> Self {
self.actor = actor;
self
}
/// Set the display name of the bot these tools act as. A blank name is
/// no name: the actor's own is used, when it has one.
pub fn with_actor_name(mut self, name: &str) -> Self {
self.actor_name = EditorName::new(name);
self
}
/// Label the comments these tools post 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 comment posted by these tools is attributed.
pub fn attribution(&self) -> MessageAttribution {
match &self.via {
Some(client) => MessageAttribution::ActingUserVia {
client: client.clone(),
},
None => MessageAttribution::ActingUser,
}
}
/// The name readers see on what these tools write as it happens - the
/// label on the cursor the editing worker draws: the host-supplied name,
/// else the first-party bot's own. `None` for a user- or team-owned bot
/// the host did not name.
pub fn actor_editor_name(&self) -> Option<EditorName> {
self.actor_name
.clone()
.or_else(|| bot_id::system_bot(self.actor).and_then(|bot| EditorName::new(bot.name)))
}
/// Mint the bot's comment capability on the document on behalf of the
/// requesting user: the same comment access the web composer requires.
pub async fn require_comment_write(
&self,
request_context: &RequestContext,
document_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()),
&document_id.to_string(),
EntityType::Document,
)
.await
.map_err(comment_access_error)
}
/// Who these tools create entities as when acting for `user`.
pub fn creation_principal(&self, user: MacroUserIdStr<'static>) -> CreationPrincipal {
CreationPrincipal::BotForUser {
bot: self.actor,
user,
}
}
}
/// Create a document toolset
pub fn document_toolset<DSvc, ESvc, EDSvc>()
-> AsyncToolCollection<DocumentToolContext<DSvc, ESvc, EDSvc>>
where
DSvc: DocumentService + DocumentCreationService,
ESvc: EntityAccessService,
EDSvc: EditingWorkerService,
{
AsyncToolCollection::new()
.add_tool::<ReadMetadata, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ReadContent, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<CreateDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<CreateSkill, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<UploadFile, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<RenameDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<EditDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ReadCanvas, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<RenderCanvas, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ApplyCanvasEdits, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<EditCanvas, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<CommentOnText, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ReadSpreadsheet, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<CalculateSpreadsheet, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<EditSpreadsheet, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ReadPresentation, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<EditPresentation, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ReadDesign, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ReadPhotoshopDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ReadIllustratorDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<ReadWordDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>()
.add_tool::<EditWordDocument, DocumentToolContext<DSvc, ESvc, EDSvc>>()
}
fn comment_access_error(err: AccessError) -> ToolCallError {
let description = match err {
AccessError::Unauthorized | AccessError::UnauthorizedWithMessage(_) => {
"you need comment access to the document to comment on it"
}
AccessError::NotFound(_) => "document not found",
AccessError::BadRequest(_) => "invalid document id",
AccessError::Unavailable(_) | AccessError::Internal(_) => {
"failed to verify access to the document"
}
};
ToolCallError {
description: description.to_string(),
internal_error: err.into(),
}
}
fn comment_error(description: &'static str) -> impl FnOnce(MessageError) -> ToolCallError {
move |err| {
let description = match &err {
MessageError::NotFound => "comment thread not found on this document".to_string(),
MessageError::Forbidden => {
"you need comment access to the document to comment on it".to_string()
}
MessageError::Invalid(reason) => format!("{description}: {reason}"),
MessageError::Conflict => format!("{description}: message id already exists"),
MessageError::Repository(_) => description.to_string(),
};
ToolCallError {
description,
internal_error: anyhow::Error::new(err),
}
}
}