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
feat(agent): emit task mention chips when naming tasks (#8532)
Wolf Mermelstein7cb0959114d5
diff --git a/Cargo.lock b/Cargo.lockindex bd07e2eb75..1d46fa56ca 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -843,6 +843,7 @@ dependencies = ["macro_tower_layers","macro_user_id","macro_uuid",+ "mention_utils","messages","mockall","model-entity",diff --git a/crates/agent_harness/AGENTS.md b/crates/agent_harness/AGENTS.mdindex 4cce8e994e..cc447217bb 100644--- a/crates/agent_harness/AGENTS.md+++ b/crates/agent_harness/AGENTS.md@@ -11,6 +11,9 @@ between the sandbox and the rest of the product.- `src/domain/service.rs` + `src/domain/ports.rs`: the harness service andthe ports every runtime/container provider implements.+- `src/domain/model/coding_preferences/`: workflows injected into coding+ sessions (create-tasks, open-pull-requests). Task mentions use the lexical+ `<m-document-mention>` chip.- `src/domain/codex.rs`: per-runtime session setup.- `src/outbound/sidecar.rs` + `sidecar_pump.rs`: the container sidecartransport that speaks `agent_runtime_protocol`.diff --git a/crates/agent_harness/src/domain/model/coding_preferences/create_tasks.md b/crates/agent_harness/src/domain/model/coding_preferences/create_tasks.mdindex 090c686e4f..bf0887f084 100644--- a/crates/agent_harness/src/domain/model/coding_preferences/create_tasks.md+++ b/crates/agent_harness/src/domain/model/coding_preferences/create_tasks.md@@ -5,6 +5,6 @@ The user tracks coding work with Macro tasks. Before changing code:1. If this session was started from a Macro task, it is already linked: skip to step 4.2. Search the user's Macro workspace (macro.NameSearch, macro.ContentSearch) for related tasks, documents and discussions. For each related task, call macro_internal.task_pull_requests to see its pull requests and whether they merged.3. If related work exists or already shipped, stop and ask the user how to proceed before writing code.-4. Link the session with macro_internal.link_task, creating the task with macro.CreateDocument (isTask true) when none fits. Tell the user which task you are working from.+4. Link the session with macro_internal.link_task, creating the task with macro.CreateDocument (isTask true) when none fits. Tell the user which task you are working from by pasting the `mention` chip link_task returns — an `<m-document-mention>` tag with `"blockName":"task"`. Whenever you name a task, emit that same chip. Never a Markdown URL, MACRO- id, or bare title. This overrides any instruction to link Macro items as plain URLs: session transcripts render the chip.When you open a pull request, put the task reference link_task returns in its description.diff --git a/crates/agent_harness/src/domain/model/coding_preferences/test.rs b/crates/agent_harness/src/domain/model/coding_preferences/test.rsindex 1fa85ba8ba..5e8a95e3ff 100644--- a/crates/agent_harness/src/domain/model/coding_preferences/test.rs+++ b/crates/agent_harness/src/domain/model/coding_preferences/test.rs@@ -77,6 +77,14 @@ fn tasks_put_their_reference_in_any_pull_request() {));}+#[test]+fn tasks_are_stated_as_a_mention_chip() {+ assert!(CREATE_TASKS_INSTRUCTIONS.contains("mention"));+ assert!(CREATE_TASKS_INSTRUCTIONS.contains(r#""blockName":"task""#));+ assert!(CREATE_TASKS_INSTRUCTIONS.contains("<m-document-mention>"));+ assert!(CREATE_TASKS_INSTRUCTIONS.contains("Whenever you name a task"));+}+#[test]fn pull_requests_are_registered_with_the_session() {assert!(OPEN_PULL_REQUESTS_INSTRUCTIONS.contains("macro_internal.set_pull_request"));diff --git a/crates/agent_session/AGENTS.md b/crates/agent_session/AGENTS.mdindex c0bb56192a..89a3d6fa0d 100644--- a/crates/agent_session/AGENTS.md+++ b/crates/agent_session/AGENTS.md@@ -50,7 +50,7 @@ consumer talks to.## Tool contracts-- `src/inbound/toolset/`: session reads, creation, lifecycle actions, and sharing. Mutations preserve acting-user identity and existing owner/edit receipts; internal controls accept only prompt/stop, never human approvals.+- `src/inbound/toolset/`: session reads, creation, lifecycle actions, and sharing. Mutations preserve acting-user identity and existing owner/edit receipts; internal controls accept only prompt/stop, never human approvals. `link_task` returns a `mention` chip to paste when naming the task.Internal action recovery uses `AgentSessionService::recorded_action`, which readsone durable log snapshot including pre-load frames. Keep this separate from thediff --git a/crates/agent_session/Cargo.toml b/crates/agent_session/Cargo.tomlindex 620184cb4f..9f63c19f84 100644--- a/crates/agent_session/Cargo.toml+++ b/crates/agent_session/Cargo.toml@@ -97,6 +97,7 @@ chrono = { workspace = true }thiserror = { workspace = true }anyhow = { workspace = true }bot_id = { path = "../bot_id" }+mention_utils = { path = "../mention_utils" }trigger_context = { path = "../trigger_context" }serde = { workspace = true }serde_json = { workspace = true }diff --git a/crates/agent_session/src/domain/session_task.rs b/crates/agent_session/src/domain/session_task.rsindex 22926f5ee4..101a424bf3 100644--- a/crates/agent_session/src/domain/session_task.rs+++ b/crates/agent_session/src/domain/session_task.rs@@ -109,6 +109,8 @@ pub struct LinkedTask {pub url: String,/// Put this in the pull request description so GitHub activity reaches the task.pub reference: String,+ /// Paste this `<m-document-mention>` chip whenever you name the task.+ pub mention: String,/// The session's pull request, now linked to the task, if it has one.pub pull_request: Option<String>,}@@ -321,11 +323,17 @@ whereif let Some(url) = &pull_request {self.link_pull_request(url, &facts).await?;}+ let mention =+ mention_utils::serialize::task_mention(facts.id.as_str(), &facts.title)+ .map_err(|error| {+ SessionTaskError::Unavailable(rootcause::report!("{error}"))+ })?;Ok(LinkedTask {url: format!("{}/{}", self.task_url_base, facts.id.as_str()),task_id: facts.id.0,title: facts.title,reference: facts.reference,+ mention,pull_request,})}diff --git a/crates/agent_session/src/domain/session_task/test.rs b/crates/agent_session/src/domain/session_task/test.rsindex 283c48baa5..e290eec44f 100644--- a/crates/agent_session/src/domain/session_task/test.rs+++ b/crates/agent_session/src/domain/session_task/test.rs@@ -218,6 +218,9 @@ async fn links_a_task_and_answers_its_link_and_reference() {title: "Task 6f".to_owned(),url: format!("https://macro.com/app/task/{TASK}"),reference: "ENG-6f".to_owned(),+ mention: format!(+ r#"<m-document-mention>{{"documentId":"{TASK}","blockName":"task","documentName":"Task 6f","blockParams":{{}},"collapsed":false}}</m-document-mention>"#+ ),pull_request: None,});diff --git a/crates/agent_session/src/inbound/toolset/link_task.rs b/crates/agent_session/src/inbound/toolset/link_task.rsindex 8eef6b6057..ac8d19afd2 100644--- a/crates/agent_session/src/inbound/toolset/link_task.rs+++ b/crates/agent_session/src/inbound/toolset/link_task.rs@@ -16,7 +16,7 @@ use crate::domain::session_task::LinkedTask;#[serde(deny_unknown_fields)]#[schemars(title = "link_task",- description = "Link this coding session to the Macro task it works on, replacing any earlier link. The session's pull request, now or later, is linked to the task. Returns the task's id, title, link, and the reference to put in the pull request description."+ description = "Link this coding session to the Macro task it works on, replacing any earlier link. The session's pull request, now or later, is linked to the task. Returns the task's id, title, link, mention chip to paste when naming the task, and the reference to put in the pull request description.")]pub struct LinkTask {/// The task to link.diff --git a/crates/mention_utils/src/serialize.rs b/crates/mention_utils/src/serialize.rsindex 053722c85b..5fe5f6f98b 100644--- a/crates/mention_utils/src/serialize.rs+++ b/crates/mention_utils/src/serialize.rs@@ -137,6 +137,20 @@ struct DocumentMention<'a, P> {collapsed: bool,}+/// Serialize a task as an in-app task chip; the title is untrusted.+pub fn task_mention(task_id: &str, title: &str) -> Result<String, serde_json::Error> {+ let payload = tag_json(&DocumentMention {+ document_id: task_id,+ block_name: "task",+ document_name: title,+ block_params: serde_json::Map::new(),+ collapsed: false,+ })?;+ Ok(format!(+ "<m-document-mention>{payload}</m-document-mention>"+ ))+}+/// Serialize a markdown document as an in-app document mention node.pub fn document_mention(document_id: &str,diff --git a/crates/mention_utils/src/serialize/test.rs b/crates/mention_utils/src/serialize/test.rsindex 845bb9f777..37e3b4cb4a 100644--- a/crates/mention_utils/src/serialize/test.rs+++ b/crates/mention_utils/src/serialize/test.rs@@ -26,6 +26,11 @@ fn native_links_and_channels_round_trip_untrusted_labels() {let (rest, parsed) = ParsedDocumentMention::parse(&channel).unwrap();assert!(rest.is_empty());assert_eq!(parsed.document_name, label);+ let task = task_mention("task-id", label).unwrap();+ assert!(task.contains(r#""blockName":"task""#));+ let (rest, parsed) = ParsedDocumentMention::parse(&task).unwrap();+ assert!(rest.is_empty());+ assert_eq!(parsed.document_name, label);let bot = bot_mention(bot_id::MACRO_AI_BOT_ID, label).unwrap();let (rest, parsed) = ParsedUserMention::parse(&bot).unwrap();assert!(rest.is_empty());diff --git a/crates/prompt/src/mentions.rs b/crates/prompt/src/mentions.rsindex cf20d01ba4..29793e1fcb 100644--- a/crates/prompt/src/mentions.rs+++ b/crates/prompt/src/mentions.rs@@ -53,6 +53,8 @@ Exact `blockName`s, since any other value renders a broken or deleted chip:- An email thread is `email`, never `thread` or `email_thread`. A calendar event is `calendar`, never `calendar_event`, with the `eventId` as `documentId`; add a recurring event's `recurrenceId` as `occurrenceKey` to target one occurrence. Channel members without the event see a read-only preview. Private and confidential events are never shared.- When a tool returns a channel message id, mention that message, not just its channel.+Whenever you name a task — one you created, linked, searched, or were assigned — emit the task mention chip. Do not use a Markdown URL, MACRO- id, or bare title, and do not repeat the title beside the chip. Use the `mention` field a task tool returned when you have it.+### People, groups, dates, agent sessions, pull requests, and booking linksThese use their own tags — never wrap them in `<m-document-mention>`:diff --git a/docs/agent-guide/channels.md b/docs/agent-guide/channels.mdindex 707dc9a711..8f06c6b17f 100644--- a/docs/agent-guide/channels.md+++ b/docs/agent-guide/channels.md@@ -574,6 +574,9 @@ session header (and the side panel's **Task** row) shows a task chip before thePR chip: the task title, or `Task` while loading or without access. Clicking itopens the task in a new split (in place on touch devices). Linking a differenttask sends the same session-update notification, so mounted headers refresh.+When the agent names that task in a reply — after creating or linking it, or+later — the reply includes an `<m-document-mention>` task chip, not a URL or+`MACRO-` id.When the agent stops to ask a question the question takes the area in the passage'splace, cropped and expandable the same way: the prompt, then what is asked - a form'sdiff --git a/services/agent_harness_service/src/internal_mcp/test.rs b/services/agent_harness_service/src/internal_mcp/test.rsindex 38b3974fe4..10e2cbeb52 100644--- a/services/agent_harness_service/src/internal_mcp/test.rs+++ b/services/agent_harness_service/src/internal_mcp/test.rs@@ -74,6 +74,9 @@ impl SessionTasks for FixedTasks {title: "Fix the thing".into(),url: format!("https://macro.com/app/task/{task}"),reference: "ENG-42".into(),+ mention: format!(+ r#"<m-document-mention>{{"documentId":"{task}","blockName":"task","documentName":"Fix the thing","blockParams":{{}},"collapsed":false}}</m-document-mention>"#+ ),pull_request: None,})})@@ -293,6 +296,7 @@ async fn each_harness_gets_only_internal_tools_and_writes_only_its_session() {"title": "Fix the thing","url": "https://macro.com/app/task/MACRO-abc","reference": "ENG-42",+ "mention": "<m-document-mention>{\"documentId\":\"MACRO-abc\",\"blockName\":\"task\",\"documentName\":\"Fix the thing\",\"blockParams\":{},\"collapsed\":false}</m-document-mention>","pull_request": null,}));