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(agent): emit task mention chips when naming tasks (#8532)

Wolf Mermelstein7cb0959114d5
diff --git a/Cargo.lock b/Cargo.lock
index 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.md
index 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 and
the 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 sidecar
transport 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.md
index 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.rs
index 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.md
index 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 reads
one durable log snapshot including pre-load frames. Keep this separate from the
diff --git a/crates/agent_session/Cargo.toml b/crates/agent_session/Cargo.toml
index 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.rs
index 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 @@ where
if 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 links
These use their own tags — never wrap them in `<m-document-mention>`:
diff --git a/docs/agent-guide/channels.md b/docs/agent-guide/channels.md
index 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 the
PR chip: the task title, or `Task` while loading or without access. Clicking it
opens the task in a new split (in place on touch devices). Linking a different
task 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's
place, cropped and expandable the same way: the prompt, then what is asked - a form's
diff --git a/services/agent_harness_service/src/internal_mcp/test.rs b/services/agent_harness_service/src/internal_mcp/test.rs
index 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,
})
);