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
//! A document's comments as an agent reads them: inline threads with what they
//! are anchored to, and Discussion threads on the document as a whole.
#[cfg(test)]
mod test;
use std::{collections::HashMap, sync::Arc};
use chrono::{DateTime, Utc};
use entity_access::domain::models::{EntityAccessReceipt, ViewAccessLevel};
use futures::{StreamExt, stream};
use messages::domain::{
api::MessageReader,
discussions::{live_roots, with_replies},
models::{Message, MessageThread, ThreadAnchor},
ports::MessageError,
service::MessageView,
};
use uuid::Uuid;
use super::models::DocumentError;
/// Concurrent mark lookups for one read.
const LOOKUP_CONCURRENCY: usize = 8;
/// Reads what a comment mark covers in the live document.
#[async_trait::async_trait]
pub trait CommentMarks: Send + Sync + 'static {
/// The text the mark covers now, `None` when the document no longer
/// carries it. Checks no access of its own: it is only asked after the
/// discussions were read under the caller's capability on the document.
async fn marked_text(&self, document_id: &str, mark_id: Uuid)
-> anyhow::Result<Option<String>>;
}
/// Where a discussion sits in its document.
#[derive(serde::Serialize, Debug, Clone, PartialEq)]
#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
#[serde(tag = "type", rename_all = "camelCase")]
pub enum CommentAnchor {
/// A cell or rectangular range in a native spreadsheet.
#[serde(rename_all = "camelCase")]
Spreadsheet {
/// Stable sheet identity within the workbook.
sheet_id: String,
/// Sheet name when the discussion was created.
sheet_name: String,
/// A1 cell or range, such as B4 or B4:C9.
range: String,
},
/// A Discussion comment on the document as a whole.
Document,
/// An inline comment on a passage of a markdown document.
#[serde(rename_all = "camelCase")]
Text {
/// The comment mark in the document.
mark_id: Uuid,
/// The text the comment is on, as the document reads now; the text
/// when the comment was written if the document could not be read.
#[serde(skip_serializing_if = "Option::is_none")]
marked_text: Option<String>,
/// The text when the comment was written, when it differs from now.
#[serde(skip_serializing_if = "Option::is_none")]
original_marked_text: Option<String>,
/// The commented text has since been removed from the document.
#[serde(default, skip_serializing_if = "std::ops::Not::not")]
removed: bool,
},
/// A comment on a PDF highlight.
#[serde(rename_all = "camelCase")]
PdfHighlight {
/// The highlight annotation.
anchor_id: Uuid,
/// The text the highlight covers; absent when the highlight carries none.
#[serde(skip_serializing_if = "Option::is_none")]
marked_text: Option<String>,
},
/// A comment pinned to a point on a PDF page. A pin marks a place, not a
/// span of text, so it has no marked text.
#[serde(rename_all = "camelCase")]
PdfPin {
/// The pin annotation.
anchor_id: Uuid,
},
/// A comment pinned to a point on a design (`.fig`). A pin marks a
/// place, not a span of text, so it has no marked text.
#[serde(rename_all = "camelCase")]
Fig {
/// The page (canvas) the pin is on.
page_id: String,
/// The layer the pin follows; absent for a pin on the bare canvas.
#[serde(skip_serializing_if = "Option::is_none")]
node_id: Option<String>,
/// Horizontal offset from the layer's origin, or the page's when the
/// pin is on no layer, in design units.
x: f64,
/// Vertical offset, measured like `x`.
y: f64,
},
}
/// A single comment in a discussion.
#[derive(serde::Serialize, Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub struct DocumentComment {
/// The comment id.
pub id: Uuid,
/// The user or bot id of the author.
pub author: String,
/// The author's display name, for bots and comments imported from other documents.
#[serde(skip_serializing_if = "Option::is_none")]
pub author_name: Option<String>,
/// The comment body in markdown; absent when the comment was deleted.
#[serde(skip_serializing_if = "Option::is_none")]
pub content: Option<String>,
/// When the comment was written.
pub created_at: DateTime<Utc>,
/// When the comment was last edited.
#[serde(skip_serializing_if = "Option::is_none")]
pub edited_at: Option<DateTime<Utc>>,
}
/// Whether a thread is on part of a document or on the document as a whole.
#[derive(serde::Serialize, Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub enum CommentThreadKind {
/// An inline comment on a passage, PDF highlight, PDF pin or spreadsheet range.
Inline,
/// A comment in the document's Discussion panel.
Discussion,
}
/// A comment thread on a document: its first comment followed by the replies.
#[derive(serde::Serialize, Debug, Clone, PartialEq)]
#[cfg_attr(feature = "ai_tools", derive(schemars::JsonSchema))]
#[serde(rename_all = "camelCase")]
pub struct DocumentDiscussion {
/// The thread id, which is the id of its first comment. Replies and
/// resolution address the thread by this id.
pub id: Uuid,
/// Whether the thread is inline or a Discussion comment.
pub kind: CommentThreadKind,
/// Whether the thread has been resolved.
pub resolved: bool,
/// What the thread is attached to.
pub anchor: CommentAnchor,
/// The comments in order, first comment first.
pub comments: Vec<DocumentComment>,
}
/// Reads a document's comments.
#[async_trait::async_trait]
pub trait DocumentComments: Send + Sync + 'static {
/// Every live discussion on the document, oldest first, capped at
/// [`messages::domain::discussions::MAX_DISCUSSIONS`].
async fn discussions(
&self,
receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> Result<Vec<DocumentDiscussion>, DocumentError>;
}
/// [`DocumentComments`] over the shared message service.
pub struct DocumentCommentReader<M> {
messages: Arc<dyn MessageReader>,
marks: M,
}
impl<M: CommentMarks> DocumentCommentReader<M> {
/// Read discussions from `messages`, resolving inline anchors with `marks`.
pub fn new(messages: Arc<dyn MessageReader>, marks: M) -> Self {
Self { messages, marks }
}
/// What each markdown mark covers now. A failed lookup leaves the mark
/// out, so the snapshot stands in rather than failing the read.
async fn live_marks(
&self,
document_id: &str,
mark_ids: Vec<Uuid>,
) -> HashMap<Uuid, Option<String>> {
stream::iter(mark_ids)
.map(|mark_id| async move {
self.marks
.marked_text(document_id, mark_id)
.await
.inspect_err(|error| {
tracing::warn!(error = ?error, %mark_id, "reading comment without the live marked text");
})
.ok()
.map(|text| (mark_id, text))
})
.buffer_unordered(LOOKUP_CONCURRENCY)
.filter_map(std::future::ready)
.collect()
.await
}
}
#[async_trait::async_trait]
impl<M: CommentMarks> DocumentComments for DocumentCommentReader<M> {
#[tracing::instrument(err, skip_all, fields(document_id = %receipt.entity().entity_id))]
async fn discussions(
&self,
receipt: EntityAccessReceipt<ViewAccessLevel>,
) -> Result<Vec<DocumentDiscussion>, DocumentError> {
let document_id = receipt.entity().entity_id.clone();
let access = receipt
.try_into_requirement::<MessageView>()
.map_err(|_| DocumentError::Unauthorized)?;
let roots = live_roots(self.messages.as_ref(), &access)
.await
.map_err(message_error)?;
let mark_ids: Vec<Uuid> = roots
.iter()
.filter_map(|item| match &item.state.anchor {
Some(ThreadAnchor::Markdown { mark_id, .. }) => Some(*mark_id),
_ => None,
})
.collect();
let (threads, marks) = futures::join!(
with_replies(self.messages.as_ref(), &access, roots),
self.live_marks(&document_id, mark_ids)
);
Ok(threads
.map_err(message_error)?
.into_iter()
.map(|thread| discussion(thread, &marks))
.collect())
}
}
fn discussion(thread: MessageThread, marks: &HashMap<Uuid, Option<String>>) -> DocumentDiscussion {
let kind = match thread.state.anchor {
None => CommentThreadKind::Discussion,
Some(_) => CommentThreadKind::Inline,
};
DocumentDiscussion {
id: thread.root.id,
kind,
resolved: thread.state.resolved,
anchor: comment_anchor(thread.state.anchor, marks),
comments: std::iter::once(thread.root)
.chain(thread.replies)
.map(comment)
.collect(),
}
}
fn comment_anchor(
anchor: Option<ThreadAnchor>,
marks: &HashMap<Uuid, Option<String>>,
) -> CommentAnchor {
match anchor {
None => CommentAnchor::Document,
Some(ThreadAnchor::Spreadsheet {
sheet_id,
sheet_name,
range,
}) => CommentAnchor::Spreadsheet {
sheet_id,
sheet_name,
range,
},
Some(ThreadAnchor::Markdown {
mark_id,
marked_text: snapshot,
}) => match marks.get(&mark_id) {
Some(Some(current)) => CommentAnchor::Text {
mark_id,
original_marked_text: snapshot.filter(|snapshot| snapshot != current),
marked_text: Some(current.clone()),
removed: false,
},
Some(None) => CommentAnchor::Text {
mark_id,
marked_text: snapshot,
original_marked_text: None,
removed: true,
},
None => CommentAnchor::Text {
mark_id,
marked_text: snapshot,
original_marked_text: None,
removed: false,
},
},
Some(ThreadAnchor::PdfHighlight {
anchor_id,
marked_text,
}) => CommentAnchor::PdfHighlight {
anchor_id,
marked_text,
},
Some(ThreadAnchor::PdfPlaceable { anchor_id }) => CommentAnchor::PdfPin { anchor_id },
Some(ThreadAnchor::Fig {
page_id,
node_id,
x,
y,
}) => CommentAnchor::Fig {
page_id,
node_id,
x,
y,
},
}
}
fn comment(message: Message) -> DocumentComment {
let deleted = message.deleted_at.is_some();
DocumentComment {
id: message.id,
author: message.sender_id.as_ref().to_owned(),
author_name: message
.imported_author
.map(|author| author.name)
.or(message.bot_profile.map(|bot| bot.name)),
content: (!deleted).then_some(message.content),
created_at: message.created_at,
edited_at: message.edited_at,
}
}
fn message_error(error: MessageError) -> DocumentError {
match error {
MessageError::Forbidden => DocumentError::Unauthorized,
error => DocumentError::Internal(anyhow::anyhow!(error.to_string())),
}
}