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.

feat(messages): read a comment's mark from the live document (#6827)

gbirman9c1f4c76632b
diff --git a/Cargo.lock b/Cargo.lock
index 1bee9a2d58..ed0446bbd8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3502,6 +3502,7 @@ dependencies = [
"chrono-tz",
"entity_access",
"futures",
+ "lexical_client",
"macro_user_id",
"messages",
"prompt",
diff --git a/crates/agent_harness/src/domain/model.rs b/crates/agent_harness/src/domain/model.rs
index f954f3718a..f0009ef47e 100644
--- a/crates/agent_harness/src/domain/model.rs
+++ b/crates/agent_harness/src/domain/model.rs
@@ -331,6 +331,18 @@ pub struct CommentAnchor {
/// The marked text as it read when the comment was posted. Absent on
/// threads anchored before snapshots were captured.
pub marked_text: Option<String>,
+ /// The mark as the document reads now. Absent when the document no longer
+ /// carries it or the lookup failed, leaving the snapshot as the fallback.
+ pub current: Option<MarkedPassage>,
+}
+
+/// A comment mark resolved against the live document, both fields bounded.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MarkedPassage {
+ /// The text the mark covers.
+ pub marked_text: String,
+ /// The block or blocks containing the mark, windowed around it.
+ pub surrounding_text: String,
}
/// What the conversation an agent was summoned from contributes to its prompt.
diff --git a/crates/agent_harness/src/domain/service/test.rs b/crates/agent_harness/src/domain/service/test.rs
index 4d84dc1aa7..08664f41c4 100644
--- a/crates/agent_harness/src/domain/service/test.rs
+++ b/crates/agent_harness/src/domain/service/test.rs
@@ -907,6 +907,7 @@ async fn open_sends_the_comment_anchor_the_prompt_was_posted_on() {
anchor: Some(CommentAnchor {
mark_id: "0199f3d4-0000-7000-8000-00000000000a".to_owned(),
marked_text: Some("the marked phrase".to_owned()),
+ current: None,
}),
messages: vec![],
};
diff --git a/crates/agent_harness/src/outbound/agent_prompt_composer.rs b/crates/agent_harness/src/outbound/agent_prompt_composer.rs
index 6961474c39..cb892824ed 100644
--- a/crates/agent_harness/src/outbound/agent_prompt_composer.rs
+++ b/crates/agent_harness/src/outbound/agent_prompt_composer.rs
@@ -41,6 +41,8 @@ impl AgentPromptComposer for LexicalAgentPromptComposer {
.map(|anchor| AgentContextAnchor {
mark_id: &anchor.mark_id,
marked_text: anchor.marked_text.as_deref(),
+ current_marked_text: anchor.current.as_ref().map(|c| c.marked_text.as_str()),
+ surrounding_text: anchor.current.as_ref().map(|c| c.surrounding_text.as_str()),
});
self.lexical
diff --git a/crates/agent_harness/src/outbound/agent_prompt_composer/test.rs b/crates/agent_harness/src/outbound/agent_prompt_composer/test.rs
index a6e36c8278..d40a07b4bc 100644
--- a/crates/agent_harness/src/outbound/agent_prompt_composer/test.rs
+++ b/crates/agent_harness/src/outbound/agent_prompt_composer/test.rs
@@ -1,5 +1,5 @@
use super::*;
-use crate::domain::model::{CommentAnchor, PriorMessage};
+use crate::domain::model::{CommentAnchor, MarkedPassage, PriorMessage};
use axum::{Json, Router, routing::post};
use std::sync::{Arc, Mutex};
@@ -57,6 +57,10 @@ async fn the_comment_anchor_reaches_the_lexical_service_beside_the_history() {
anchor: Some(CommentAnchor {
mark_id: "mark-1".to_owned(),
marked_text: Some("the marked phrase".to_owned()),
+ current: Some(MarkedPassage {
+ marked_text: "the edited phrase".to_owned(),
+ surrounding_text: "Around the edited phrase.".to_owned(),
+ }),
}),
messages: vec![PriorMessage {
sender: "alice".to_owned(),
@@ -69,6 +73,11 @@ async fn the_comment_anchor_reaches_the_lexical_service_beside_the_history() {
let body = received.lock().unwrap().clone().unwrap();
assert_eq!(body["anchor"]["markId"], "mark-1");
assert_eq!(body["anchor"]["markedText"], "the marked phrase");
+ assert_eq!(body["anchor"]["currentMarkedText"], "the edited phrase");
+ assert_eq!(
+ body["anchor"]["surroundingText"],
+ "Around the edited phrase."
+ );
assert_eq!(body["messages"][0]["sender"], "alice");
// A thread anchored before snapshots existed still names its mark.
@@ -80,6 +89,7 @@ async fn the_comment_anchor_reaches_the_lexical_service_beside_the_history() {
anchor: Some(CommentAnchor {
mark_id: "mark-2".to_owned(),
marked_text: None,
+ current: None,
}),
messages: vec![],
}),
@@ -89,5 +99,6 @@ async fn the_comment_anchor_reaches_the_lexical_service_beside_the_history() {
let body = received.lock().unwrap().clone().unwrap();
assert_eq!(body["anchor"]["markId"], "mark-2");
assert!(body["anchor"].get("markedText").is_none());
+ assert!(body["anchor"].get("currentMarkedText").is_none());
server.abort();
}
diff --git a/crates/agent_harness/src/outbound/channel_prompt_context.rs b/crates/agent_harness/src/outbound/channel_prompt_context.rs
index 84cd55cad7..ba46befbb3 100644
--- a/crates/agent_harness/src/outbound/channel_prompt_context.rs
+++ b/crates/agent_harness/src/outbound/channel_prompt_context.rs
@@ -5,13 +5,14 @@ mod test;
use crate::domain::{
error::{HarnessError, Result},
- model::{AnnounceOrigin, CommentAnchor, ConversationContext, PriorMessage},
+ model::{AnnounceOrigin, CommentAnchor, ConversationContext, MarkedPassage, PriorMessage},
ports::MessagePromptContext,
};
use entity_access::domain::{
models::{EntityAccessReceipt, EntityType},
ports::EntityAccessService,
};
+use lexical_client::LexicalClient;
use macro_user_id::user_id::MacroUserIdStr;
use messages::domain::{
api::MessageReader,
@@ -48,20 +49,55 @@ impl<Access: EntityAccessService> ContextAuthorizer for Access {
}
}
+/// Reads what a comment mark covers in the live document. It checks no access
+/// of its own: it is only asked after the thread was read under the actor's
+/// capability on that document.
+trait MarkReader: Send + Sync + 'static {
+ fn resolve(
+ &self,
+ document_id: &str,
+ mark_id: &str,
+ ) -> impl Future<Output = anyhow::Result<Option<MarkedPassage>>> + Send;
+}
+
+impl MarkReader for LexicalClient {
+ async fn resolve(
+ &self,
+ document_id: &str,
+ mark_id: &str,
+ ) -> anyhow::Result<Option<MarkedPassage>> {
+ Ok(self
+ .resolve_comment_mark(document_id, mark_id)
+ .await?
+ .map(|mark| MarkedPassage {
+ marked_text: mark.marked_text,
+ surrounding_text: mark.surrounding_text,
+ }))
+ }
+}
+
/// Reads channel and document conversation history with the same access boundary.
-pub struct MessagePromptContextAdapter<Access> {
+pub struct MessagePromptContextAdapter<Access, Marks = LexicalClient> {
messages: Arc<dyn MessageReader>,
access: Arc<Access>,
+ marks: Arc<Marks>,
}
-impl<Access> MessagePromptContextAdapter<Access> {
- /// Compose with the shared message service and current entity permissions.
- pub fn new(messages: Arc<dyn MessageReader>, access: Arc<Access>) -> Self {
- Self { messages, access }
+impl<Access, Marks> MessagePromptContextAdapter<Access, Marks> {
+ /// Compose with the shared message service, current entity permissions,
+ /// and the live documents comment marks are resolved against.
+ pub fn new(messages: Arc<dyn MessageReader>, access: Arc<Access>, marks: Arc<Marks>) -> Self {
+ Self {
+ messages,
+ access,
+ marks,
+ }
}
}
-impl<Access: ContextAuthorizer> MessagePromptContext for MessagePromptContextAdapter<Access> {
+impl<Access: ContextAuthorizer, Marks: MarkReader> MessagePromptContext
+ for MessagePromptContextAdapter<Access, Marks>
+{
async fn authorize_origin(
&self,
actor: &MacroUserIdStr<'static>,
@@ -115,37 +151,55 @@ impl<Access: ContextAuthorizer> MessagePromptContext for MessagePromptContextAda
})
.map_err(|error| HarnessError::PromptContext(rootcause::report!(error).into()))?;
Ok(ConversationContext {
- anchor: anchor(self.messages.as_ref(), access, origin).await?,
+ anchor: anchor(self.messages.as_ref(), self.marks.as_ref(), access, origin).await?,
messages,
})
}
}
/// Where a document discussion sits, read from the thread the prompt was posted
-/// in. Only documents anchor discussions, so a channel prompt never pays for
-/// the lookup.
+/// in, and what that mark covers in the document now. Only documents anchor
+/// discussions, so a channel prompt never pays for the lookup. A failed live
+/// lookup leaves the stored snapshot to stand in rather than failing the prompt.
async fn anchor(
messages: &dyn MessageReader,
+ marks: &impl MarkReader,
access: EntityAccessReceipt<MessageView>,
origin: &AnnounceOrigin,
) -> Result<Option<CommentAnchor>> {
- if !matches!(origin.parent, MessageParent::Document(_)) {
+ let MessageParent::Document(document) = &origin.parent else {
return Ok(None);
- }
+ };
let thread = messages
.get_thread(access, origin.thread_id)
.await
.map_err(|error| HarnessError::PromptContext(rootcause::report!(error).into()))?;
- Ok(match thread.state.anchor {
- // PDF anchors name an annotation the agent cannot read either, but
- // their text is owned by the annotation rather than the thread.
- Some(ThreadAnchor::Markdown {
- mark_id,
- marked_text,
- }) => Some(CommentAnchor {
- mark_id: mark_id.to_string(),
- marked_text,
- }),
- _ => None,
- })
+ // PDF anchors name an annotation the agent cannot read either, but their
+ // text is owned by the annotation rather than the thread.
+ let Some(ThreadAnchor::Markdown {
+ mark_id,
+ marked_text,
+ }) = thread.state.anchor
+ else {
+ return Ok(None);
+ };
+ let mark_id = mark_id.to_string();
+ let current = marks
+ .resolve(&origin.parent.entity_id(), &mark_id)
+ .await
+ .inspect_err(|error| {
+ tracing::warn!(
+ error = ?error,
+ document = ?document,
+ %mark_id,
+ "sending comment anchor without the live marked text"
+ );
+ })
+ .ok()
+ .flatten();
+ Ok(Some(CommentAnchor {
+ mark_id,
+ marked_text,
+ current,
+ }))
}
diff --git a/crates/agent_harness/src/outbound/channel_prompt_context/test.rs b/crates/agent_harness/src/outbound/channel_prompt_context/test.rs
index 88ba2fb5ea..f3b0c0d7dd 100644
--- a/crates/agent_harness/src/outbound/channel_prompt_context/test.rs
+++ b/crates/agent_harness/src/outbound/channel_prompt_context/test.rs
@@ -7,6 +7,24 @@ use messages::domain::{
models::{Message, MessageThread, ThreadState},
};
+/// Live mark lookups, answering one fixed result for the test's document.
+struct Marks(std::result::Result<Option<MarkedPassage>, &'static str>);
+impl Marks {
+ fn none() -> Self {
+ Self(Ok(None))
+ }
+}
+impl MarkReader for Marks {
+ async fn resolve(
+ &self,
+ document_id: &str,
+ _mark_id: &str,
+ ) -> anyhow::Result<Option<MarkedPassage>> {
+ assert_eq!(document_id, "doc");
+ self.0.clone().map_err(|error| anyhow::anyhow!(error))
+ }
+}
+
struct Authorizer {
allowed: bool,
}
@@ -80,8 +98,11 @@ async fn document_origin_checks_its_parent_capability_and_root() {
&& *id == origin().message_id
})
.return_once(|_, _| Ok(message()));
- let adapter =
- MessagePromptContextAdapter::new(Arc::new(source), Arc::new(Authorizer { allowed: true }));
+ let adapter = MessagePromptContextAdapter::new(
+ Arc::new(source),
+ Arc::new(Authorizer { allowed: true }),
+ Arc::new(Marks::none()),
+ );
adapter.authorize_origin(&actor(), &origin()).await.unwrap();
}
@@ -90,6 +111,7 @@ async fn revoked_access_never_reads_message_content() {
let adapter = MessagePromptContextAdapter::new(
Arc::new(MockMessageReader::new()),
Arc::new(Authorizer { allowed: false }),
+ Arc::new(Marks::none()),
);
assert!(adapter.authorize_origin(&actor(), &origin()).await.is_err());
assert!(
@@ -118,6 +140,7 @@ async fn a_claimed_root_or_parent_cannot_link_an_unrelated_session() {
let adapter = MessagePromptContextAdapter::new(
Arc::new(source),
Arc::new(Authorizer { allowed: true }),
+ Arc::new(Marks::none()),
);
assert!(adapter.authorize_origin(&actor(), &origin()).await.is_err());
}
@@ -161,6 +184,7 @@ async fn history_uses_the_shared_authorized_message_reader() {
let adapter = MessagePromptContextAdapter::new(
Arc::new(reader(None)),
Arc::new(Authorizer { allowed: true }),
+ Arc::new(Marks::none()),
);
let context = adapter
.conversation_context(&actor(), &origin())
@@ -182,6 +206,7 @@ async fn a_marked_discussion_names_its_mark_and_the_text_it_covers() {
marked_text: Some("the marked phrase".to_owned()),
}))),
Arc::new(Authorizer { allowed: true }),
+ Arc::new(Marks::none()),
);
let context = adapter
.conversation_context(&actor(), &origin())
@@ -192,6 +217,7 @@ async fn a_marked_discussion_names_its_mark_and_the_text_it_covers() {
Some(CommentAnchor {
mark_id: mark_id.to_string(),
marked_text: Some("the marked phrase".to_owned()),
+ current: None,
})
);
}
@@ -205,6 +231,7 @@ async fn a_discussion_anchored_before_snapshots_still_names_its_mark() {
marked_text: None,
}))),
Arc::new(Authorizer { allowed: true }),
+ Arc::new(Marks::none()),
);
let context = adapter
.conversation_context(&actor(), &origin())
@@ -215,6 +242,7 @@ async fn a_discussion_anchored_before_snapshots_still_names_its_mark() {
Some(CommentAnchor {
mark_id: mark_id.to_string(),
marked_text: None,
+ current: None,
})
);
}
@@ -227,8 +255,11 @@ async fn a_channel_prompt_never_reads_a_thread_for_an_anchor() {
.once()
.return_once(|_, _, _| Ok(vec![]));
source.expect_get_thread().never();
- let adapter =
- MessagePromptContextAdapter::new(Arc::new(source), Arc::new(Authorizer { allowed: true }));
+ let adapter = MessagePromptContextAdapter::new(
+ Arc::new(source),
+ Arc::new(Authorizer { allowed: true }),
+ Arc::new(Marks::none()),
+ );
let channel = AnnounceOrigin {
parent: MessageParent::Channel(Uuid::from_u128(3)),
..origin()
@@ -239,3 +270,57 @@ async fn a_channel_prompt_never_reads_a_thread_for_an_anchor() {
.unwrap();
assert_eq!(context.anchor, None);
}
+
+#[tokio::test]
+async fn a_marked_discussion_reads_the_mark_as_the_document_has_it_now() {
+ let mark_id = Uuid::from_u128(9);
+ let current = MarkedPassage {
+ marked_text: "the edited phrase".to_owned(),
+ surrounding_text: "Before the edited phrase after.".to_owned(),
+ };
+ let adapter = MessagePromptContextAdapter::new(
+ Arc::new(reader(Some(ThreadAnchor::Markdown {
+ mark_id,
+ marked_text: Some("the original phrase".to_owned()),
+ }))),
+ Arc::new(Authorizer { allowed: true }),
+ Arc::new(Marks(Ok(Some(current.clone())))),
+ );
+ let context = adapter
+ .conversation_context(&actor(), &origin())
+ .await
+ .unwrap();
+ assert_eq!(
+ context.anchor,
+ Some(CommentAnchor {
+ mark_id: mark_id.to_string(),
+ marked_text: Some("the original phrase".to_owned()),
+ current: Some(current),
+ })
+ );
+}
+
+#[tokio::test]
+async fn a_failed_live_lookup_falls_back_to_the_snapshot() {
+ let mark_id = Uuid::from_u128(10);
+ let adapter = MessagePromptContextAdapter::new(
+ Arc::new(reader(Some(ThreadAnchor::Markdown {
+ mark_id,
+ marked_text: Some("the original phrase".to_owned()),
+ }))),
+ Arc::new(Authorizer { allowed: true }),
+ Arc::new(Marks(Err("lexical unavailable"))),
+ );
+ let context = adapter
+ .conversation_context(&actor(), &origin())
+ .await
+ .unwrap();
+ assert_eq!(
+ context.anchor,
+ Some(CommentAnchor {
+ mark_id: mark_id.to_string(),
+ marked_text: Some("the original phrase".to_owned()),
+ current: None,
+ })
+ );
+}
diff --git a/crates/channel_bots/Cargo.toml b/crates/channel_bots/Cargo.toml
index cdec5f7728..735816421e 100644
--- a/crates/channel_bots/Cargo.toml
+++ b/crates/channel_bots/Cargo.toml
@@ -18,6 +18,7 @@ entity_access = { path = "../entity_access", default-features = false, features
chrono = { workspace = true }
chrono-tz = { workspace = true }
futures = { workspace = true }
+lexical_client = { path = "../lexical_client" }
macro_user_id = { path = "../macro_user_id" }
messages = { path = "../messages", features = ["ports"] }
prompt = { path = "../prompt" }
diff --git a/crates/channel_bots/src/domain/models.rs b/crates/channel_bots/src/domain/models.rs
index d1d4728c40..bd47a6649f 100644
--- a/crates/channel_bots/src/domain/models.rs
+++ b/crates/channel_bots/src/domain/models.rs
@@ -48,3 +48,12 @@ pub struct TranscriptMessage {
/// Message body.
pub content: String,
}
+
+/// A comment mark resolved against the live document, both fields bounded.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct MarkedPassage {
+ /// The text the mark covers now.
+ pub marked_text: String,
+ /// The block or blocks containing the mark, windowed around it.
+ pub surrounding_text: String,
+}
diff --git a/crates/channel_bots/src/domain/ports.rs b/crates/channel_bots/src/domain/ports.rs
index 429a0b0eee..8619371f96 100644
--- a/crates/channel_bots/src/domain/ports.rs
+++ b/crates/channel_bots/src/domain/ports.rs
@@ -7,7 +7,7 @@ use messages::domain::{
events::MessagePostedMetadata, models::MessageParent, service::MessageWrite,
};
-use super::models::{BotInvocation, TranscriptMessage};
+use super::models::{BotInvocation, MarkedPassage, TranscriptMessage};
/// Produces an assistant response for a posted message.
#[async_trait]
@@ -24,6 +24,19 @@ pub trait UserTimeZones: Send + Sync {
async fn primary_time_zone(&self, user_id: &str) -> Option<String>;
}
+/// Reads what a comment mark covers in the live document.
+#[async_trait]
+pub trait CommentMarks: Send + Sync {
+ /// The mark as the document reads now, `None` when the document no longer
+ /// carries it. Checks no access of its own: it is only asked after the
+ /// thread was read under the invoking user's capability on the document.
+ async fn resolve(
+ &self,
+ document_id: &str,
+ mark_id: uuid::Uuid,
+ ) -> anyhow::Result<Option<MarkedPassage>>;
+}
+
/// Decides whether a committed post should invoke any bots.
#[async_trait]
pub trait TriggerDetector: Send + Sync {
diff --git a/crates/channel_bots/src/domain/service.rs b/crates/channel_bots/src/domain/service.rs
index 83ebe0dac3..d569acf77e 100644
--- a/crates/channel_bots/src/domain/service.rs
+++ b/crates/channel_bots/src/domain/service.rs
@@ -16,8 +16,8 @@ use messages::domain::{
};
use uuid::Uuid;
-use super::models::{BotEvent, BotTrigger};
-use super::ports::{AgentResponder, ConversationAccess, UserTimeZones};
+use super::models::{BotEvent, BotTrigger, MarkedPassage};
+use super::ports::{AgentResponder, CommentMarks, ConversationAccess, UserTimeZones};
use super::sender_label;
/// How many channel messages preceding the trigger to include as local context.
@@ -46,24 +46,27 @@ triggering message.";
const CHANNEL_CONTEXT_INSTRUCTION: &str = "Recent messages in the channel around the mention \
(oldest to newest).";
-const ANCHOR_INSTRUCTION: &str = "The document text this discussion is attached to. It is what \
-the mark covered when the discussion was started, so the document may have changed since — read \
-the document itself if you need its current wording.";
+const LIVE_ANCHOR_INSTRUCTION: &str = "The document text this discussion is attached to, as \
+the document reads now, with the passage around it.";
+
+const SNAPSHOT_ANCHOR_INSTRUCTION: &str = "The document text this discussion is attached to. It \
+is what the mark covered when the discussion was started, so the document may have changed since \
+— read the document itself if you need its current wording.";
/// The thread a mention sits in, read once for everything the prompt needs.
struct ThreadContext {
lines: Vec<PromptLine>,
ids: HashSet<Uuid>,
- /// Present only for a document discussion the author anchored to text,
- /// and only when the anchor carries a snapshot of what it marked.
- marked: Option<MarkedText>,
+ /// Present only for a document discussion the author anchored to text.
+ anchor: Option<MarkAnchor>,
}
-/// The text a markdown discussion marks, with the mark that identifies it —
-/// the same id the comment reads carry, so the two can be matched up.
-struct MarkedText {
+/// The mark a markdown discussion is attached to — the same id the comment
+/// reads carry, so the two can be matched up — and what it covered when the
+/// discussion was started, when that was captured.
+struct MarkAnchor {
mark_id: Uuid,
- text: String,
+ snapshot: Option<String>,
}
/// A single message rendered into the prompt.
@@ -91,16 +94,38 @@ fn trigger_line(event: &BotEvent) -> PromptLine {
/// Write the block naming what a document discussion is anchored to, so a
/// mention that says "this" can be resolved to words rather than to a mark id
-/// the agent has no way to look up.
-fn append_anchor(prompt: &mut String, marked: Option<&MarkedText>) {
- let Some(marked) = marked else {
- return;
- };
- let _ = write!(
- prompt,
- "\n<anchor mark=\"{}\">\n{ANCHOR_INSTRUCTION}\n\n{}\n</anchor>\n",
- marked.mark_id, marked.text
- );
+/// the agent has no way to look up. The live document is preferred; the
+/// snapshot stands in when the mark could not be resolved, and is kept beside
+/// the live text when an edit has changed what the mark covers.
+fn append_anchor(prompt: &mut String, anchor: &MarkAnchor, current: Option<&MarkedPassage>) {
+ let mark_id = anchor.mark_id;
+ match (current, anchor.snapshot.as_deref()) {
+ (Some(current), snapshot) => {
+ let _ = write!(
+ prompt,
+ "\n<anchor mark=\"{mark_id}\">\n{LIVE_ANCHOR_INSTRUCTION}\n\nMarked text: {}\n",
+ current.marked_text
+ );
+ if let Some(snapshot) = snapshot.filter(|s| *s != current.marked_text) {
+ let _ = writeln!(
+ prompt,
+ "When the discussion was started it read: {snapshot}"
+ );
+ }
+ let _ = write!(
+ prompt,
+ "\nSurrounding passage:\n{}\n</anchor>\n",
+ current.surrounding_text
+ );
+ }
+ (None, Some(snapshot)) => {
+ let _ = write!(
+ prompt,
+ "\n<anchor mark=\"{mark_id}\">\n{SNAPSHOT_ANCHOR_INSTRUCTION}\n\n{snapshot}\n</anchor>\n"
+ );
+ }
+ (None, None) => {}
+ }
}
/// Write a tagged context block: an instruction line followed by one message
@@ -173,6 +198,7 @@ pub struct MacroAiHandler<R, Z> {
access: Arc<dyn ConversationAccess>,
responder: Arc<R>,
time_zones: Arc<Z>,
+ marks: Arc<dyn CommentMarks>,
}
impl<R, Z> MacroAiHandler<R, Z>
@@ -186,15 +212,34 @@ where
access: Arc<dyn ConversationAccess>,
responder: Arc<R>,
time_zones: Arc<Z>,
+ marks: Arc<dyn CommentMarks>,
) -> Self {
Self {
messages,
access,
responder,
time_zones,
+ marks,
}
}
+ /// What a mark covers in the document now. Called only after the thread
+ /// was read under the invoking user's access; a failed lookup leaves the
+ /// stored snapshot to stand in rather than failing the reply.
+ async fn current_mark(&self, parent: &MessageParent, mark_id: Uuid) -> Option<MarkedPassage> {
+ let MessageParent::Document(_) = parent else {
+ return None;
+ };
+ self.marks
+ .resolve(&parent.entity_id(), mark_id)
+ .await
+ .inspect_err(|error| {
+ tracing::warn!(error=?error, %mark_id, "prompting without the live marked text");
+ })
+ .ok()
+ .flatten()
+ }
+
/// Load the thread the mention belongs to as prompt lines: the root
/// followed by all replies in order, with the triggering message marked
/// inline. Also returns the ids of every message known to belong to the
@@ -206,11 +251,14 @@ where
root_id: Uuid,
) -> anyhow::Result<ThreadContext> {
let thread = self.messages.get_thread(access, root_id).await?;
- let marked = match thread.state.anchor {
+ let anchor = match thread.state.anchor {
Some(ThreadAnchor::Markdown {
mark_id,
- marked_text: Some(text),
- }) => Some(MarkedText { mark_id, text }),
+ marked_text,
+ }) => Some(MarkAnchor {
+ mark_id,
+ snapshot: marked_text,
+ }),
_ => None,
};
let mut thread_ids = HashSet::new();
@@ -235,7 +283,7 @@ where
Ok(ThreadContext {
lines,
ids: thread_ids,
- marked,
+ anchor,
})
}
@@ -316,9 +364,12 @@ where
let ThreadContext {
lines: thread,
ids: thread_ids,
- marked,
+ anchor,
} = self.thread_lines(event, view, root_id).await?;
- append_anchor(&mut prompt, marked.as_ref());
+ if let Some(anchor) = &anchor {
+ let current = self.current_mark(parent, anchor.mark_id).await;
+ append_anchor(&mut prompt, anchor, current.as_ref());
+ }
append_block(&mut prompt, "thread", thread_instruction, marker, &thread);
let background: Vec<PromptLine> = nearby
diff --git a/crates/channel_bots/src/domain/service/tests.rs b/crates/channel_bots/src/domain/service/tests.rs
index 6256d9c0f8..67422cd53d 100644
--- a/crates/channel_bots/src/domain/service/tests.rs
+++ b/crates/channel_bots/src/domain/service/tests.rs
@@ -52,7 +52,22 @@ fn handler(
access: Arc<Access>,
responder: Arc<Responder>,
) -> MacroAiHandler<Responder, FixedTimeZones> {
- MacroAiHandler::new(Arc::new(api), access, responder, eastern_time_zones())
+ handler_with_marks(api, access, responder, Marks::none())
+}
+
+fn handler_with_marks(
+ api: MockMessageServiceApi,
+ access: Arc<Access>,
+ responder: Arc<Responder>,
+ marks: Arc<Marks>,
+) -> MacroAiHandler<Responder, FixedTimeZones> {
+ MacroAiHandler::new(
+ Arc::new(api),
+ access,
+ responder,
+ eastern_time_zones(),
+ marks,
+ )
}
fn invocation(trigger: &messages::domain::models::Message) -> BotEvent {
@@ -156,7 +171,7 @@ async fn an_anchored_discussion_names_the_text_it_marks() {
async fn a_discussion_with_no_marked_text_claims_no_anchor() {
let trigger = message(1, None, "@macro help with this document");
let mut api = MockMessageServiceApi::new();
- // Both an unanchored discussion and one anchored before snapshots existed.
+ // Anchored before snapshots existed, and the live lookup finds nothing.
configure_reads(&mut api, &trigger, marked_thread(trigger.clone(), None));
let prompt = handler(api, Arc::new(Access::default()), responder("reply"))
.build_prompt(&invocation(&trigger))
@@ -165,6 +180,68 @@ async fn a_discussion_with_no_marked_text_claims_no_anchor() {
assert!(!prompt.contains("<anchor"));
}
+#[tokio::test]
+async fn a_discussion_older_than_snapshots_reads_its_mark_from_the_document() {
+ let trigger = message(1, None, "@macro what is this anchored to?");
+ let mut api = MockMessageServiceApi::new();
+ configure_reads(&mut api, &trigger, marked_thread(trigger.clone(), None));
+ let marks = Arc::new(Marks(Ok(Some(MarkedPassage {
+ marked_text: "backfills the ledger".to_owned(),
+ surrounding_text: "The second stage backfills the ledger from the archive.".to_owned(),
+ }))));
+ let prompt = handler_with_marks(api, Arc::new(Access::default()), responder("reply"), marks)
+ .build_prompt(&invocation(&trigger))
+ .await
+ .unwrap();
+ assert!(prompt.contains("as the document reads now"));
+ assert!(prompt.contains("Marked text: backfills the ledger\n"));
+ assert!(prompt.contains("The second stage backfills the ledger from the archive."));
+ assert!(!prompt.contains("When the discussion was started"));
+}
+
+#[tokio::test]
+async fn an_edited_mark_shows_both_what_it_covers_now_and_what_it_covered() {
+ let trigger = message(1, None, "@macro what is this anchored to?");
+ let mut api = MockMessageServiceApi::new();
+ configure_reads(
+ &mut api,
+ &trigger,
+ marked_thread(trigger.clone(), Some("backfills the ledger")),
+ );
+ let marks = Arc::new(Marks(Ok(Some(MarkedPassage {
+ marked_text: "rebuilds the ledger".to_owned(),
+ surrounding_text: "The second stage rebuilds the ledger.".to_owned(),
+ }))));
+ let prompt = handler_with_marks(api, Arc::new(Access::default()), responder("reply"), marks)
+ .build_prompt(&invocation(&trigger))
+ .await
+ .unwrap();
+ assert!(prompt.contains("Marked text: rebuilds the ledger\n"));
+ assert!(prompt.contains("When the discussion was started it read: backfills the ledger"));
+}
+
+#[tokio::test]
+async fn a_failed_live_lookup_falls_back_to_the_snapshot() {
+ let trigger = message(1, None, "@macro what is this anchored to?");
+ let mut api = MockMessageServiceApi::new();
+ configure_reads(
+ &mut api,
+ &trigger,
+ marked_thread(trigger.clone(), Some("backfills the ledger")),
+ );
+ let prompt = handler_with_marks(
+ api,
+ Arc::new(Access::default()),
+ responder("reply"),
+ Arc::new(Marks(Err("lexical unavailable"))),
+ )
+ .build_prompt(&invocation(&trigger))
+ .await
+ .unwrap();
+ assert!(prompt.contains("backfills the ledger"));
+ assert!(prompt.contains("the document may have changed since"));
+}
+
#[tokio::test]
async fn revoked_document_access_prevents_context_reads_and_agent_work() {
let trigger = message(1, None, "@macro help");
@@ -370,6 +447,7 @@ async fn prompt_says_the_time_zone_is_unknown_without_a_calendar() {
Arc::new(Access::default()),
responder("reply"),
Arc::new(FixedTimeZones(None)),
+ Marks::none(),
)
.build_prompt(&invocation(&trigger))
.await
diff --git a/crates/channel_bots/src/domain/test.rs b/crates/channel_bots/src/domain/test.rs
index af04b8c87c..edd724c04b 100644
--- a/crates/channel_bots/src/domain/test.rs
+++ b/crates/channel_bots/src/domain/test.rs
@@ -1,4 +1,5 @@
-use super::ports::ConversationAccess;
+use super::models::MarkedPassage;
+use super::ports::{CommentMarks, ConversationAccess};
use async_trait::async_trait;
use entity_access::domain::models::{
AccessLevel, BotReceiptScope, EntityAccessReceipt, EntityPermission, EntityType,
@@ -86,6 +87,24 @@ pub(super) fn configure_reads(
Ok(history.clone())
});
}
+/// Live mark lookups answering one fixed result.
+pub(super) struct Marks(pub Result<Option<MarkedPassage>, &'static str>);
+impl Marks {
+ pub fn none() -> Arc<Self> {
+ Arc::new(Self(Ok(None)))
+ }
+}
+#[async_trait]
+impl CommentMarks for Marks {
+ async fn resolve(
+ &self,
+ document_id: &str,
+ _mark_id: Uuid,
+ ) -> anyhow::Result<Option<MarkedPassage>> {
+ assert_eq!(document_id, "discussion-document");
+ self.0.clone().map_err(|error| anyhow::anyhow!(error))
+ }
+}
#[derive(Default)]
pub(super) struct Access {
pub revoked: Arc<AtomicBool>,
diff --git a/crates/channel_bots/src/inbound/bot_trigger_router.rs b/crates/channel_bots/src/inbound/bot_trigger_router.rs
index 8dbf2badde..17f59953f7 100644
--- a/crates/channel_bots/src/inbound/bot_trigger_router.rs
+++ b/crates/channel_bots/src/inbound/bot_trigger_router.rs
@@ -8,7 +8,7 @@ use tracing::Instrument as _;
use crate::domain::{
models::BotEvent,
- ports::{AgentResponder, ConversationAccess, TriggerDetector, UserTimeZones},
+ ports::{AgentResponder, CommentMarks, ConversationAccess, TriggerDetector, UserTimeZones},
service::MacroAiHandler,
};
@@ -50,9 +50,12 @@ where
responder: Arc<R>,
detector: Arc<D>,
time_zones: Arc<Z>,
+ marks: Arc<dyn CommentMarks>,
) -> Self {
Self {
- macro_ai: Arc::new(MacroAiHandler::new(messages, access, responder, time_zones)),
+ macro_ai: Arc::new(MacroAiHandler::new(
+ messages, access, responder, time_zones, marks,
+ )),
detector,
}
}
diff --git a/crates/channel_bots/src/outbound/lexical_comment_marks.rs b/crates/channel_bots/src/outbound/lexical_comment_marks.rs
new file mode 100644
index 0000000000..44db24e03b
--- /dev/null
+++ b/crates/channel_bots/src/outbound/lexical_comment_marks.rs
@@ -0,0 +1,36 @@
+//! Lexical-service lookup of the live text a comment mark covers.
+
+use async_trait::async_trait;
+use lexical_client::LexicalClient;
+
+use crate::domain::{models::MarkedPassage, ports::CommentMarks};
+
+/// [`CommentMarks`] resolved by the lexical service from the synced document.
+pub struct LexicalCommentMarks {
+ lexical: LexicalClient,
+}
+
+impl LexicalCommentMarks {
+ /// Resolve marks through `lexical`.
+ pub fn new(lexical: LexicalClient) -> Self {
+ Self { lexical }
+ }
+}
+
+#[async_trait]
+impl CommentMarks for LexicalCommentMarks {
+ async fn resolve(
+ &self,
+ document_id: &str,
+ mark_id: uuid::Uuid,
+ ) -> anyhow::Result<Option<MarkedPassage>> {
+ Ok(self
+ .lexical
+ .resolve_comment_mark(document_id, &mark_id.to_string())
+ .await?
+ .map(|mark| MarkedPassage {
+ marked_text: mark.marked_text,
+ surrounding_text: mark.surrounding_text,
+ }))
+ }
+}
diff --git a/crates/channel_bots/src/outbound/mod.rs b/crates/channel_bots/src/outbound/mod.rs
index 7269c95e9f..1117329d23 100644
--- a/crates/channel_bots/src/outbound/mod.rs
+++ b/crates/channel_bots/src/outbound/mod.rs
@@ -4,8 +4,10 @@ mod agent_loop_responder;
/// Current parent capabilities for built-in agent replies.
pub mod conversation;
mod fast_model_trigger_classifier;
+mod lexical_comment_marks;
mod primary_calendar_time_zones;
pub use agent_loop_responder::AgentLoopResponder;
pub use fast_model_trigger_classifier::FastModelTriggerClassifier;
+pub use lexical_comment_marks::LexicalCommentMarks;
pub use primary_calendar_time_zones::PrimaryCalendarTimeZones;
diff --git a/crates/lexical_client/src/parse_markdown.rs b/crates/lexical_client/src/parse_markdown.rs
index 2494d15b2a..43cb755a64 100644
--- a/crates/lexical_client/src/parse_markdown.rs
+++ b/crates/lexical_client/src/parse_markdown.rs
@@ -228,6 +228,12 @@ pub struct AgentContextAnchor<'a> {
/// The marked text when the comment was posted, when it was captured.
#[serde(skip_serializing_if = "Option::is_none")]
pub marked_text: Option<&'a str>,
+ /// The text the mark covers in the document now, when it was resolved.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub current_marked_text: Option<&'a str>,
+ /// The passage around the mark now, when it was resolved.
+ #[serde(skip_serializing_if = "Option::is_none")]
+ pub surrounding_text: Option<&'a str>,
}
#[derive(Debug, serde::Serialize)]
@@ -247,6 +253,22 @@ struct AgentContextResponse {
markdown: String,
}
+/// The live text of a comment mark, resolved from the current document by the
+/// lexical service `/comment-mark` endpoint. Both fields are bounded there.
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct CommentMarkContext {
+ /// The text the mark covers now.
+ pub marked_text: String,
+ /// The block or blocks containing the mark, windowed around it.
+ pub surrounding_text: String,
+}
+
+#[derive(Debug, Clone, serde::Deserialize)]
+struct CommentMarkResponse {
+ data: Option<CommentMarkContext>,
+}
+
/// Rendering target supported by the lexical service `/markdown` endpoint.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MarkdownTarget {
@@ -370,6 +392,20 @@ impl LexicalClient {
Ok(EmbeddingMarkdown(markdown))
}
+ /// Resolve a comment mark against the live document: `None` when the
+ /// document no longer carries it. Performs no access check of its own, so
+ /// callers must already hold access to the document.
+ #[tracing::instrument(skip(self), err)]
+ pub async fn resolve_comment_mark(
+ &self,
+ document_id: &str,
+ mark_id: &str,
+ ) -> Result<Option<CommentMarkContext>> {
+ let url = format!("{}/comment-mark/{}/{}", self.url, document_id, mark_id);
+ let response: CommentMarkResponse = self.get_json(&url).await?;
+ Ok(response.data)
+ }
+
#[tracing::instrument(skip(self), err)]
pub async fn parse_markdown_for_ai(&self, document_id: &str) -> Result<CognitionResponseData> {
let url = format!("{}/cognition/{}", self.url, document_id);
@@ -717,6 +753,23 @@ mod tests {
assert_eq!(value["parent"]["id"], "doc-1");
}
+ #[test]
+ fn comment_mark_response_reads_a_resolved_or_missing_mark() {
+ let found: CommentMarkResponse = serde_json::from_str(
+ r#"{"data":{"markedText":"the phrase","surroundingText":"all of the phrase here"}}"#,
+ )
+ .unwrap();
+ assert_eq!(
+ found.data,
+ Some(CommentMarkContext {
+ marked_text: "the phrase".to_owned(),
+ surrounding_text: "all of the phrase here".to_owned(),
+ })
+ );
+ let missing: CommentMarkResponse = serde_json::from_str(r#"{"data":null}"#).unwrap();
+ assert_eq!(missing.data, None);
+ }
+
#[test]
fn extract_reply_response_deserializes_null() {
let response: ExtractReplyResponse = serde_json::from_str(r#"{ "reply": null }"#).unwrap();
diff --git a/packages/lexical-core/nodes/CommentNode.ts b/packages/lexical-core/nodes/CommentNode.ts
index 34d6ceacc2..be3c5732f6 100644
--- a/packages/lexical-core/nodes/CommentNode.ts
+++ b/packages/lexical-core/nodes/CommentNode.ts
@@ -3,8 +3,10 @@ import { $dfs } from '@lexical/utils';
import {
$applyNodeReplacement,
$getRoot,
+ $isRootOrShadowRoot,
type EditorConfig,
type ElementNode,
+ type LexicalNode,
type LexicalUpdateJSON,
type NodeKey,
type RangeSelection,
@@ -56,6 +58,95 @@ export function $getCommentMarkText(markId: string): string {
return blocks.join('\n').trim();
}
+/** Where a comment mark sits in a document, bounded for an agent prompt. */
+export type CommentMarkContext = {
+ /** The text the mark covers. */
+ markedText: string;
+ /** The block or blocks containing the mark, windowed around it. */
+ surroundingText: string;
+};
+
+const ELLIPSIS = '\u2026';
+
+function clip(text: string, limit: number): string {
+ return text.length > limit ? text.slice(0, limit) + ELLIPSIS : text;
+}
+
+/** A window of `text` at most `limit` long, centred on `focus` starting at `at`. */
+function windowAround(
+ text: string,
+ at: number,
+ focusLength: number,
+ limit: number
+): string {
+ if (text.length <= limit) return text;
+ const pad = Math.floor((limit - Math.min(focusLength, limit)) / 2);
+ const start = Math.max(0, Math.min(at - pad, text.length - limit));
+ const end = start + limit;
+ return (
+ (start > 0 ? ELLIPSIS : '') +
+ text.slice(start, end) +
+ (end < text.length ? ELLIPSIS : '')
+ );
+}
+
+/**
+ * The length of the text that precedes `node` within its top-level block,
+ * found from the node's own position so a phrase repeated elsewhere in the
+ * block cannot be mistaken for the marked one.
+ */
+function $textBefore(node: LexicalNode): number {
+ let length = 0;
+ let current: LexicalNode | null = node;
+ while (current && !$isRootOrShadowRoot(current.getParent())) {
+ for (
+ let sibling = current.getPreviousSibling();
+ sibling;
+ sibling = sibling.getPreviousSibling()
+ ) {
+ length += sibling.getTextContent().length;
+ }
+ current = current.getParent();
+ }
+ return length;
+}
+
+/**
+ * The live text a comment mark covers and the blocks around it, or null when
+ * no node in the document carries the mark. Both are bounded so that one
+ * highlight over a long section cannot dominate an agent prompt. Must run
+ * inside an editor read or update.
+ */
+export function $getCommentMarkContext(
+ markId: string,
+ { markedLimit = 1000, surroundingLimit = 2000 } = {}
+): CommentMarkContext | null {
+ const blocks = new Map<NodeKey, ElementNode>();
+ let offset: number | undefined;
+ for (const { node } of $dfs($getRoot())) {
+ if (!$isCommentNode(node) || !node.getIDs().includes(markId)) continue;
+ offset ??= $textBefore(node);
+ const block = node.getTopLevelElement();
+ if (block && !blocks.has(block.getKey())) blocks.set(block.getKey(), block);
+ }
+ if (blocks.size === 0) return null;
+ const markedText = $getCommentMarkText(markId);
+ const joined = [...blocks.values()]
+ .map((block) => block.getTextContent())
+ .join('\n');
+ const leading = joined.length - joined.trimStart().length;
+ const surrounding = joined.trim();
+ return {
+ markedText: clip(markedText, markedLimit),
+ surroundingText: windowAround(
+ surrounding,
+ Math.max(0, (offset ?? 0) - leading),
+ markedText.length,
+ surroundingLimit
+ ),
+ };
+}
+
export class CommentNode extends MarkNode {
__threadId: number | undefined;
__isDraft: boolean;
diff --git a/packages/lexical-core/tests/agent-context.test.ts b/packages/lexical-core/tests/agent-context.test.ts
index 76f7f23ff4..4a3c4da84f 100644
--- a/packages/lexical-core/tests/agent-context.test.ts
+++ b/packages/lexical-core/tests/agent-context.test.ts
@@ -191,6 +191,44 @@ describe('composeAgentContextPrompt', () => {
});
});
+ it('prefers the live text and keeps the snapshot to show an edit', () => {
+ const composed = composeAgentContextPrompt({
+ promptMarkdown: 'what does this mean?',
+ anchor: {
+ markId: 'mark-1',
+ markedText: 'the old phrase',
+ currentMarkedText: 'the new phrase',
+ surroundingText: 'Before the new phrase after.',
+ },
+ });
+ const state = markdownToSerializedEditorStateWithIds(composed);
+
+ expect(state.root.children[0]).toMatchObject({
+ type: 'agent-context',
+ text:
+ 'Comment anchor: {"markId":"mark-1","markedText":"the old phrase","currentMarkedText":"the new phrase","surroundingText":"Before the new phrase after."}\n' +
+ 'currentMarkedText is what the mark covers in the document now and surroundingText the passage around it. markedText is what it covered when the comment was posted; if the two differ, the text was edited since.',
+ });
+ });
+
+ it('describes a live mark on a thread that predates snapshots', () => {
+ const composed = composeAgentContextPrompt({
+ promptMarkdown: 'what does this mean?',
+ anchor: {
+ markId: 'mark-1',
+ currentMarkedText: 'the phrase',
+ surroundingText: 'All of the phrase.',
+ },
+ });
+ const state = markdownToSerializedEditorStateWithIds(composed);
+
+ expect(state.root.children[0]).toMatchObject({
+ text:
+ 'Comment anchor: {"markId":"mark-1","currentMarkedText":"the phrase","surroundingText":"All of the phrase."}\n' +
+ 'currentMarkedText is what the mark covers in the document now and surroundingText the passage around it.',
+ });
+ });
+
it('names a mark with no snapshot without claiming one', () => {
const composed = composeAgentContextPrompt({
promptMarkdown: 'what does this mean?',
diff --git a/packages/lexical-core/tests/comment-mark-text.test.ts b/packages/lexical-core/tests/comment-mark-text.test.ts
index cbc3626645..fbb1ef0b27 100644
--- a/packages/lexical-core/tests/comment-mark-text.test.ts
+++ b/packages/lexical-core/tests/comment-mark-text.test.ts
@@ -8,6 +8,7 @@ import {
import { describe, expect, it } from 'vitest';
import {
$createCommentNode,
+ $getCommentMarkContext,
$getCommentMarkText,
CommentNode,
} from '../nodes/CommentNode';
@@ -82,3 +83,67 @@ describe('$getCommentMarkText', () => {
expect(editor.read(() => $getCommentMarkText('mark'))).toBe('');
});
});
+
+describe('$getCommentMarkContext', () => {
+ it('returns the marked text and the block it sits in', () => {
+ const editor = editorWith(() =>
+ markedParagraph('mark', 'the marked phrase', ' and the rest')
+ );
+
+ expect(editor.read(() => $getCommentMarkContext('mark'))).toEqual({
+ markedText: 'the marked phrase',
+ surroundingText: 'the marked phrase and the rest',
+ });
+ });
+
+ it('is null when the document no longer carries the mark', () => {
+ const editor = editorWith(() => markedParagraph('other', 'unrelated'));
+
+ expect(editor.read(() => $getCommentMarkContext('mark'))).toBeNull();
+ });
+
+ it('centres on the marked copy of a phrase repeated in the block', () => {
+ const editor = editorWith(() => {
+ const mark = $createCommentNode({ ids: ['mark'], isDraft: false });
+ mark.append($createTextNode('needle'));
+ $getRoot().append(
+ $createParagraphNode().append(
+ $createTextNode(`needle ${'a'.repeat(100)} `),
+ mark,
+ $createTextNode(` ${'b'.repeat(100)}`)
+ )
+ );
+ });
+
+ const context = editor.read(() =>
+ $getCommentMarkContext('mark', { surroundingLimit: 20 })
+ );
+ expect(context?.surroundingText).toBe(
+ `\u2026${'a'.repeat(6)} needle ${'b'.repeat(6)}\u2026`
+ );
+ });
+
+ it('windows a long block around the mark and bounds the marked text', () => {
+ const before = 'a'.repeat(500);
+ const after = 'b'.repeat(500);
+ const editor = editorWith(() => {
+ const mark = $createCommentNode({ ids: ['mark'], isDraft: false });
+ mark.append($createTextNode('needle'));
+ $getRoot().append(
+ $createParagraphNode().append(
+ $createTextNode(before),
+ mark,
+ $createTextNode(after)
+ )
+ );
+ });
+
+ const context = editor.read(() =>
+ $getCommentMarkContext('mark', { markedLimit: 3, surroundingLimit: 20 })
+ );
+ expect(context?.markedText).toBe('nee…');
+ expect(context?.surroundingText).toBe(
+ `…${'a'.repeat(7)}needle${'b'.repeat(7)}…`
+ );
+ });
+});
diff --git a/packages/lexical-core/utils/agent-context.ts b/packages/lexical-core/utils/agent-context.ts
index 16bacbe241..6d8d6c2eb0 100644
--- a/packages/lexical-core/utils/agent-context.ts
+++ b/packages/lexical-core/utils/agent-context.ts
@@ -23,8 +23,12 @@ export type AgentContextParent = {
/** Where in a document the comment thread a prompt was posted in sits. */
export type AgentContextAnchor = {
markId: string;
- /** Absent on threads anchored before marked text was captured. */
+ /** What the mark covered when the comment was posted; absent on threads anchored before it was captured. */
markedText?: string;
+ /** What the mark covers in the document now, when it could be resolved. */
+ currentMarkedText?: string;
+ /** The passage around the mark now, when it could be resolved. */
+ surroundingText?: string;
};
/** Input used to compose an agent prompt with private conversation context. */
@@ -38,12 +42,20 @@ export type AgentContextPrompt = {
/**
* Name the document range a comment marks. The mark id identifies it, but
- * nothing the agent can read maps that id back onto text, so the text the
- * comment covered travels with it — as a snapshot, since the document is free
- * to change after the comment is written.
+ * nothing the agent can read maps that id back onto text, so the text travels
+ * with it: as the document reads now when it could be resolved, and as it read
+ * when the comment was posted, which is all there is when the live lookup
+ * failed or the text has since been removed.
*/
function describeAnchor(anchor: AgentContextAnchor): string {
const location = `Comment anchor: ${JSON.stringify(anchor)}`;
+ if (anchor.currentMarkedText !== undefined) {
+ const snapshot =
+ anchor.markedText === undefined
+ ? ''
+ : ' markedText is what it covered when the comment was posted; if the two differ, the text was edited since.';
+ return `${location}\ncurrentMarkedText is what the mark covers in the document now and surroundingText the passage around it.${snapshot}`;
+ }
if (anchor.markedText === undefined) return location;
return `${location}\nmarkedText is what the mark covered when the comment was posted; the document may have changed since.`;
}
diff --git a/services/agent_harness_service/src/main.rs b/services/agent_harness_service/src/main.rs
index c147bc5976..573dc80560 100644
--- a/services/agent_harness_service/src/main.rs
+++ b/services/agent_harness_service/src/main.rs
@@ -763,9 +763,12 @@ async fn run() -> anyhow::Result<()> {
);
let prompt_mentions =
LexicalPromptMentions::new(lexical.clone(), PgSessionAccess::new(pool.clone()));
+ let prompt_context = MessagePromptContextAdapter::new(
+ message_service,
+ Arc::clone(&entity_access),
+ Arc::new(lexical.clone()),
+ );
let prompt_composer = LexicalAgentPromptComposer::new(lexical);
- let prompt_context =
- MessagePromptContextAdapter::new(message_service, Arc::clone(&entity_access));
// One connection per harness, shared by every session of every agent
// bound to it. Held here because the gateway puts dialed-in sockets into
diff --git a/services/document_storage_service/src/main.rs b/services/document_storage_service/src/main.rs
index fc98463742..39ec992b2c 100644
--- a/services/document_storage_service/src/main.rs
+++ b/services/document_storage_service/src/main.rs
@@ -1165,6 +1165,9 @@ async fn run() -> anyhow::Result<()> {
calendar_events::outbound::pg::PgCalendarRepository::new(readonly_db.clone()),
)),
)),
+ Arc::new(channel_bots::outbound::LexicalCommentMarks::new(
+ (*lexical_client).clone(),
+ )),
);
bot_trigger_router.spawn(bot_trigger_receiver);
diff --git a/services/lexical-service/src/endpoints/agent-context.ts b/services/lexical-service/src/endpoints/agent-context.ts
index 89c7773f6b..25a4ccfef8 100644
--- a/services/lexical-service/src/endpoints/agent-context.ts
+++ b/services/lexical-service/src/endpoints/agent-context.ts
@@ -13,6 +13,8 @@ const messageParent = z.object({
const commentAnchor = z.object({
markId: z.string().min(1),
markedText: z.string().optional(),
+ currentMarkedText: z.string().optional(),
+ surroundingText: z.string().optional(),
});
const agentContextRequest = z.object({
diff --git a/services/lexical-service/src/endpoints/comment-mark.ts b/services/lexical-service/src/endpoints/comment-mark.ts
new file mode 100644
index 0000000000..403da942a1
--- /dev/null
+++ b/services/lexical-service/src/endpoints/comment-mark.ts
@@ -0,0 +1,73 @@
+import { OpenAPIRoute } from 'chanfana';
+import type { Context } from 'hono';
+import { z } from 'zod';
+import { toCommentMarkContext } from '../lib/convsersions';
+import {
+ ConversionError,
+ createSyncError,
+ handleEndpointError,
+ validateEnvironment,
+} from '../lib/error-handler';
+import { docIdParam, standardErrorResponses } from '../lib/schemas';
+import { createSyncClient } from '../lib/sync-service';
+
+const commentMarkContext = z.object({
+ markedText: z.string(),
+ surroundingText: z.string(),
+});
+
+export class CommentMarkEndpoint extends OpenAPIRoute {
+ schema = {
+ summary: 'Resolve a comment mark to the text it covers',
+ description:
+ 'Reads the live document from the sync service and returns the text a comment mark covers with a bounded window of its surrounding blocks, or null when the document no longer carries the mark. Callers must have checked access to the document.',
+ request: {
+ params: docIdParam.extend({
+ markId: z.string().min(1, 'Mark ID is required'),
+ }),
+ },
+ responses: {
+ 200: {
+ description: 'The mark, or null when it is no longer in the document',
+ content: {
+ 'application/json': {
+ schema: z.object({ data: commentMarkContext.nullable() }),
+ },
+ },
+ },
+ ...standardErrorResponses,
+ },
+ };
+
+ async handle(c: Context) {
+ let docId = 'unknown';
+ try {
+ const { params } = await this.getValidatedData<typeof this.schema>();
+ docId = params.docId;
+
+ validateEnvironment(c, ['SYNC_SERVICE_AUTH_KEY', 'SYNC_SERVICE_URL']);
+
+ const syncClient = createSyncClient({
+ baseUrl: c.env.SYNC_SERVICE_URL,
+ internalAuthKey: c.env.SYNC_SERVICE_AUTH_KEY,
+ serviceFetcher: c.env.SYNC_SERVICE,
+ });
+
+ const rawDocument = await syncClient.raw(docId);
+ if (!rawDocument.success) {
+ throw createSyncError(
+ rawDocument as { success: false; error: Error; status?: number }
+ );
+ }
+ try {
+ return c.json({
+ data: toCommentMarkContext(rawDocument.data, params.markId),
+ });
+ } catch {
+ throw new ConversionError('Failed to parse document snapshot');
+ }
+ } catch (error) {
+ return handleEndpointError(error, c, docId);
+ }
+ }
+}
diff --git a/services/lexical-service/src/index.ts b/services/lexical-service/src/index.ts
index 23ed14e162..b593715494 100644
--- a/services/lexical-service/src/index.ts
+++ b/services/lexical-service/src/index.ts
@@ -1,80 +1,83 @@
-import "./polyfills/prism";
+import './polyfills/prism';
-import { fromHono } from "chanfana";
-import { Hono, type MiddlewareHandler } from "hono";
-import { AgentAnnouncementEndpoint } from "./endpoints/agent-announcement";
-import { AgentContextEndpoint } from "./endpoints/agent-context";
-import { CognitionPresignedEndpoint } from "./endpoints/cognition-presigned";
-import { CognitionTextEndpoint } from "./endpoints/cognition-text";
-import { CognitionV2Endpoint } from "./endpoints/cognition-v2";
-import { MarkdownEndpoint } from "./endpoints/markdown";
-import { MarkdownSnapshotEndpoint } from "./endpoints/markdown-snapshot";
-import { MentionsEndpoint } from "./endpoints/mentions";
-import { PlaintextEndpoint } from "./endpoints/plaintext";
-import { ExtractReplyEndpoint } from "./endpoints/extract-reply";
-import { HtmlEndpoint } from "./endpoints/html";
-import { SearchTextEndpoint } from "./endpoints/search-text";
-import { XmlEndpoint } from "./endpoints/xml";
+import { fromHono } from 'chanfana';
+import { Hono, type MiddlewareHandler } from 'hono';
+import { AgentAnnouncementEndpoint } from './endpoints/agent-announcement';
+import { AgentContextEndpoint } from './endpoints/agent-context';
+import { CognitionPresignedEndpoint } from './endpoints/cognition-presigned';
+import { CognitionTextEndpoint } from './endpoints/cognition-text';
+import { CognitionV2Endpoint } from './endpoints/cognition-v2';
+import { CommentMarkEndpoint } from './endpoints/comment-mark';
+import { ExtractReplyEndpoint } from './endpoints/extract-reply';
+import { HtmlEndpoint } from './endpoints/html';
+import { MarkdownEndpoint } from './endpoints/markdown';
+import { MarkdownSnapshotEndpoint } from './endpoints/markdown-snapshot';
+import { MentionsEndpoint } from './endpoints/mentions';
+import { PlaintextEndpoint } from './endpoints/plaintext';
+import { SearchTextEndpoint } from './endpoints/search-text';
+import { XmlEndpoint } from './endpoints/xml';
type Bindings = {
- INTERNAL_AUTH_KEY: string;
- SYNC_SERVICE_AUTH_KEY: string;
- SYNC_SERVICE_URL: string;
- SYNC_SERVICE: Fetcher;
+ INTERNAL_AUTH_KEY: string;
+ SYNC_SERVICE_AUTH_KEY: string;
+ SYNC_SERVICE_URL: string;
+ SYNC_SERVICE: Fetcher;
};
const app = new Hono<{ Bindings: Bindings }>();
// Apply internal auth middleware only to API endpoints
const internalAuth: MiddlewareHandler<{ Bindings: Bindings }> = async (
- c,
- next,
+ c,
+ next
) => {
- const authKey = c.req.header("x-internal-auth-key");
- if (!authKey || authKey !== c.env.INTERNAL_AUTH_KEY) {
- return c.json({ error: "Unauthorized" }, 401);
- }
- await next();
+ const authKey = c.req.header('x-internal-auth-key');
+ if (!authKey || authKey !== c.env.INTERNAL_AUTH_KEY) {
+ return c.json({ error: 'Unauthorized' }, 401);
+ }
+ await next();
};
-app.use("/plaintext/*", internalAuth);
-app.use("/cognition/*", internalAuth);
-app.use("/cognitionv2/*", internalAuth);
-app.use("/search/*", internalAuth);
-app.use("/xml/*", internalAuth);
-app.use("/markdown/*", internalAuth);
-app.use("/snapshot/*", internalAuth);
-app.use("/mentions", internalAuth);
-app.use("/extract-reply", internalAuth);
-app.use("/agent-announcement", internalAuth);
-app.use("/agent-context", internalAuth);
-app.use("/internal/health", internalAuth);
+app.use('/plaintext/*', internalAuth);
+app.use('/cognition/*', internalAuth);
+app.use('/cognitionv2/*', internalAuth);
+app.use('/search/*', internalAuth);
+app.use('/xml/*', internalAuth);
+app.use('/markdown/*', internalAuth);
+app.use('/comment-mark/*', internalAuth);
+app.use('/snapshot/*', internalAuth);
+app.use('/mentions', internalAuth);
+app.use('/extract-reply', internalAuth);
+app.use('/agent-announcement', internalAuth);
+app.use('/agent-context', internalAuth);
+app.use('/internal/health', internalAuth);
const openapi = fromHono(app, {
- docs_url: "/",
- schema: {
- info: {
- title: "Lexical Service API",
- version: "1.0.0",
- description: "API for converting Lexical documents to various formats",
- },
- },
+ docs_url: '/',
+ schema: {
+ info: {
+ title: 'Lexical Service API',
+ version: '1.0.0',
+ description: 'API for converting Lexical documents to various formats',
+ },
+ },
});
-openapi.get("/health", (c) => c.json({ message: "Healthy" }));
-openapi.get("/plaintext/:docId", PlaintextEndpoint);
-openapi.get("/cognition/presigned", CognitionPresignedEndpoint);
-openapi.get("/cognition/:docId", CognitionTextEndpoint);
-openapi.get("/cognitionv2/:docId", CognitionV2Endpoint);
-openapi.get("/search/:docId", SearchTextEndpoint);
-openapi.get("/markdown/:docId", MarkdownEndpoint);
-openapi.get("/xml/:docId", XmlEndpoint);
-openapi.post("/snapshot/markdown", MarkdownSnapshotEndpoint);
-openapi.post("/html", HtmlEndpoint);
-openapi.post("/mentions", MentionsEndpoint);
-openapi.post("/extract-reply", ExtractReplyEndpoint);
-openapi.post("/agent-announcement", AgentAnnouncementEndpoint);
-openapi.post("/agent-context", AgentContextEndpoint);
-openapi.get("/internal/health", (c) => c.json({ status: "healthy" }));
+openapi.get('/health', (c) => c.json({ message: 'Healthy' }));
+openapi.get('/plaintext/:docId', PlaintextEndpoint);
+openapi.get('/cognition/presigned', CognitionPresignedEndpoint);
+openapi.get('/cognition/:docId', CognitionTextEndpoint);
+openapi.get('/cognitionv2/:docId', CognitionV2Endpoint);
+openapi.get('/search/:docId', SearchTextEndpoint);
+openapi.get('/markdown/:docId', MarkdownEndpoint);
+openapi.get('/comment-mark/:docId/:markId', CommentMarkEndpoint);
+openapi.get('/xml/:docId', XmlEndpoint);
+openapi.post('/snapshot/markdown', MarkdownSnapshotEndpoint);
+openapi.post('/html', HtmlEndpoint);
+openapi.post('/mentions', MentionsEndpoint);
+openapi.post('/extract-reply', ExtractReplyEndpoint);
+openapi.post('/agent-announcement', AgentAnnouncementEndpoint);
+openapi.post('/agent-context', AgentContextEndpoint);
+openapi.get('/internal/health', (c) => c.json({ status: 'healthy' }));
export default app;
diff --git a/services/lexical-service/src/lib/comment-mark.test.ts b/services/lexical-service/src/lib/comment-mark.test.ts
new file mode 100644
index 0000000000..ace501311d
--- /dev/null
+++ b/services/lexical-service/src/lib/comment-mark.test.ts
@@ -0,0 +1,63 @@
+import '../polyfills/prism';
+import { describe, expect, it } from 'bun:test';
+import { toCommentMarkContext } from './convsersions';
+
+const text = (value: string) => ({
+ type: 'text',
+ version: 1,
+ text: value,
+ format: 0,
+ detail: 0,
+ mode: 'normal',
+ style: '',
+});
+
+const document = {
+ root: {
+ type: 'root',
+ version: 1,
+ format: '',
+ indent: 0,
+ direction: null,
+ children: [
+ {
+ type: 'paragraph',
+ version: 1,
+ format: '',
+ indent: 0,
+ direction: null,
+ textFormat: 0,
+ textStyle: '',
+ children: [
+ text('The second stage '),
+ {
+ type: 'comment-mark',
+ version: 1,
+ format: '',
+ indent: 0,
+ direction: null,
+ ids: ['mark-1'],
+ threadId: undefined,
+ isDraft: false,
+ children: [text('backfills the ledger')],
+ },
+ text(' from the archive.'),
+ ],
+ },
+ ],
+ },
+};
+
+describe('toCommentMarkContext', () => {
+ it('resolves a mark in a stored document to its text and block', () => {
+ expect(toCommentMarkContext(document as never, 'mark-1')).toEqual({
+ markedText: 'backfills the ledger',
+ surroundingText:
+ 'The second stage backfills the ledger from the archive.',
+ });
+ });
+
+ it('is null for a mark the document no longer carries', () => {
+ expect(toCommentMarkContext(document as never, 'gone')).toBeNull();
+ });
+});
diff --git a/services/lexical-service/src/lib/convsersions.ts b/services/lexical-service/src/lib/convsersions.ts
index 65482ba8bf..10a70572be 100644
--- a/services/lexical-service/src/lib/convsersions.ts
+++ b/services/lexical-service/src/lib/convsersions.ts
@@ -1,8 +1,10 @@
import { $convertToMarkdownString } from '@lexical/markdown';
import { $dfsIterator } from '@lexical/utils';
import {
+ $getCommentMarkContext,
$getId,
$isImageNode,
+ type CommentMarkContext,
EXTERNAL_TRANSFORMERS,
type ImageNode,
INTERNAL_TRANSFORMERS,
@@ -31,6 +33,16 @@ export function toPlaintext(raw: SerializedEditorState) {
}
}
+/** The live text of a comment mark and its surrounding blocks, if still present. */
+export function toCommentMarkContext(
+ raw: SerializedEditorState,
+ markId: string
+): CommentMarkContext | null {
+ const editor = createEditor();
+ editor.setEditorState(editor.parseEditorState(raw));
+ return editor.read(() => $getCommentMarkContext(markId));
+}
+
export function toSearchText(raw: SerializedEditorState) {
const editor = createEditor();
try {