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.

13.6 KB
Raw Blame
//! Start work for newly assigned agents in a task's discussion.

use std::collections::HashSet;

use agent_session::domain::error::{AgentSessionError, Result as AgentResult};
use chrono::{DateTime, Utc};
use trigger_context::origin::{AgentActor, Caller, Lineage};
use trigger_context::{TaskAssignedContext, TaskSnapshot, TriggerContext, TriggerOrigin};

use crate::domain::context::PeopleDirectory;
use agent_session::domain::ports::AgentSessionRepo;
use bot_id::{BotId, BotIdStr};
use macro_event_broker::MacroEventBroker;
use macro_user_id::user_id::MacroUserIdStr;
use macro_uuid::Uuid;
use messages::domain::{
    api::MessageCommands,
    models::{MessageAttribution, MessageParent, PostMessage, PostMessageNotificationPolicy},
    service::MessageWrite,
};
use models_properties::{EntityType, service::property_value::PropertyValue};
use properties::domain::events::EntityPropertyUpdatedMetadata;
use system_properties::SystemPropertyKey;

mod project_context;
pub use project_context::ProjectTaskAssignmentContext;

use super::{
    broker_events::{AgentAssignedToTaskEvent, AgentSessionMacroEvent, NewAgentSessionEvent},
    processing::ProcessMessageEventError,
    service::{
        AgentBotLookup, AgentTriggerService, ChannelParticipationLookup, ExplicitReplyExtractor,
        ImplicitTriggerJudge, TeamMembershipLookup, ThreadHistory,
    },
};

#[cfg(test)]
mod test;

/// Authorized task content supplied to every runtime, including those without tools.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TaskBrief {
    /// Current task title.
    pub title: String,
    /// Current task description in Markdown.
    pub markdown: String,
    /// Current Status option name.
    pub status: Option<String>,
    /// Current Priority option name.
    pub priority: Option<String>,
    /// Current due date.
    pub due: Option<chrono::DateTime<chrono::Utc>>,
    /// User and bot ids in the Assignees property, people and agents alike.
    pub assignee_ids: Vec<String>,
    /// Current project, only when the assigning principal can view it.
    pub project: Option<trigger_context::ProjectRef>,
}

/// Reads the task through its owning service under a verified document capability.
#[cfg_attr(test, mockall::automock)]
pub trait TaskAssignmentContext: Send + Sync + 'static {
    /// Missing or no-longer-task documents yield no work; read failures are retried.
    fn task_brief(
        &self,
        access: entity_access::domain::models::EntityAccessReceipt<MessageWrite>,
    ) -> impl Future<Output = AgentResult<Option<TaskBrief>>> + Send;
}

/// One committed assignment change, with only the newly assigned agents.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TaskAssignment {
    /// The source event id identifies this assignment, including on replay.
    pub event_id: Uuid,
    /// Task document whose discussion receives the agent session link.
    pub parent: MessageParent,
    /// User whose assignment starts the work.
    pub actor: MacroUserIdStr<'static>,
    /// Agents added by this change, in stable order.
    pub bots: Vec<BotId>,
    /// Who made the assignment, and how.
    pub origin: TriggerOrigin,
}

impl TaskAssignment {
    /// Ignore other properties, human assignees, removals, and unchanged saves.
    pub fn from_update(event_id: Uuid, updated: &EntityPropertyUpdatedMetadata) -> Option<Self> {
        if updated.entity_type != EntityType::Task
            || updated.property_definition_id != SystemPropertyKey::Assignees.uuid()
        {
            return None;
        }
        let previous = assigned_bots(updated.previous_value.as_ref());
        let mut bots: Vec<_> = assigned_bots(updated.value.as_ref())
            .difference(&previous)
            .copied()
            .collect();
        bots.sort_by_key(ToString::to_string);
        if bots.is_empty() {
            return None;
        }
        let actor = updated
            .actor_user_id
            .clone()
            .or_else(|| updated.on_behalf_of.clone())?;
        Some(Self {
            event_id,
            parent: MessageParent::parse("document", &updated.entity_id).ok()?,
            origin: assignment_origin(updated, actor.clone()),
            actor,
            bots,
        })
    }
}

/// `actor` is the user behind the change; the event's own `actor` says whether
/// an agent made it for them.
fn assignment_origin(
    updated: &EntityPropertyUpdatedMetadata,
    actor: MacroUserIdStr<'static>,
) -> TriggerOrigin {
    let acting_bot = updated.actor.as_ref().and_then(|actor| actor.as_bot());
    let by = match acting_bot {
        Some(bot) => Caller::Agent(AgentActor {
            bot: bot.bot_id(),
            on_behalf_of: actor,
            lineage: Lineage::Unattributed,
        }),
        None => Caller::Person { user: actor },
    };
    let task = updated.entity_id.clone();
    match updated.inherited_from_project {
        Some(project) => TriggerOrigin::ProjectInherited { by, task, project },
        None => TriggerOrigin::TaskAssigned { by, task },
    }
}

fn assigned_bots(value: Option<&PropertyValue>) -> HashSet<BotId> {
    let Some(PropertyValue::EntityRef(references)) = value else {
        return HashSet::new();
    };
    references
        .iter()
        .filter(|reference| reference.entity_type == EntityType::User)
        .filter_map(|reference| BotIdStr::parse_from_str(&reference.entity_id).ok())
        .map(|id| id.bot_id())
        .collect()
}

/// Open a real discussion before publishing a session trigger. The common
/// harness then links the session here and routes subsequent user replies.
pub async fn process_task_assignment<
    Repo,
    Bots,
    Teams,
    Channels,
    Replies,
    Judge,
    History,
    Broker,
    Context,
    People,
>(
    trigger: &AgentTriggerService<Repo, Bots, Teams, Channels, Replies, Judge, History>,
    publisher: &Broker,
    messages: &dyn MessageCommands,
    context: &Context,
    people: &People,
    assignment: &TaskAssignment,
) -> Result<(), ProcessMessageEventError>
where
    Repo: AgentSessionRepo,
    Bots: AgentBotLookup,
    Teams: TeamMembershipLookup,
    Channels: ChannelParticipationLookup,
    Replies: ExplicitReplyExtractor,
    Judge: ImplicitTriggerJudge,
    History: ThreadHistory,
    Broker: MacroEventBroker,
    Context: TaskAssignmentContext,
    People: PeopleDirectory,
{
    for &bot_id in &assignment.bots {
        let Some(invocation) = trigger
            .authorize_task_assignment(
                &assignment.actor,
                &assignment.parent,
                assignment.event_id,
                bot_id,
            )
            .await?
        else {
            continue;
        };
        let discussion_id = discussion_id(assignment.event_id, bot_id);
        if trigger
            .assignment_has_session(discussion_id, bot_id)
            .await?
        {
            continue;
        }
        let Some(brief) = context.task_brief(invocation.access().clone()).await? else {
            continue;
        };
        let Some(message) = assignment_discussion(
            assignment,
            bot_id,
            discussion_id,
            invocation.access().clone(),
            messages,
        )
        .await?
        else {
            continue;
        };
        let context = assigned_context(assignment, &brief, message.id, people).await?;
        let event = AgentSessionMacroEvent::new_session(NewAgentSessionEvent::AssignedToTask(
            AgentAssignedToTaskEvent {
                bot_id,
                parent: assignment.parent.clone(),
                discussion_id: message.id,
                actor: assignment.actor.clone(),
                prompt: assignment_prompt(assignment, &brief),
                origin: assignment.origin.clone(),
                context: Some(context),
            },
        ));
        publisher
            .send_event(&event)?
            .await
            .map_err(ProcessMessageEventError::PublishTask)??;
    }
    Ok(())
}

/// The task as the agent should see it, with everyone named.
async fn assigned_context(
    assignment: &TaskAssignment,
    brief: &TaskBrief,
    discussion_id: Uuid,
    people: &impl PeopleDirectory,
) -> AgentResult<TriggerContext> {
    let mut named = people
        .people(
            std::iter::once(assignment.actor.as_ref().to_owned())
                .chain(brief.assignee_ids.iter().cloned())
                .collect(),
        )
        .await?
        .into_iter();
    let assigned_by = named.next().ok_or_else(|| {
        AgentSessionError::Unknown(anyhow::anyhow!("the people directory named nobody"))
    })?;
    Ok(TriggerContext::TaskAssigned(TaskAssignedContext {
        task: TaskSnapshot {
            id: assignment.parent.entity_id(),
            title: brief.title.clone(),
            markdown: brief.markdown.clone(),
            status: brief.status.clone(),
            priority: brief.priority.clone(),
            due: brief.due,
            assignees: named.collect(),
            project: brief.project.clone(),
        },
        assigned_by,
        assigned_at: assigned_at(assignment.event_id)?,
        discussion_id,
    }))
}

/// When the assignment was made: its source event id is a UUIDv7, which
/// carries the moment the event was minted.
fn assigned_at(event_id: Uuid) -> AgentResult<DateTime<Utc>> {
    event_id
        .get_timestamp()
        .and_then(|timestamp| {
            let (seconds, nanos) = timestamp.to_unix();
            DateTime::from_timestamp(i64::try_from(seconds).ok()?, nanos)
        })
        .ok_or_else(|| {
            AgentSessionError::Unknown(anyhow::anyhow!(
                "assignment event {event_id} is not a UUIDv7"
            ))
        })
}

/// Derive one replay-stable UUIDv7 per assigned bot, retaining the event timestamp.
/// The hashed random bits keep simultaneous agents in separate discussion threads.
fn discussion_id(event_id: Uuid, bot_id: BotId) -> Uuid {
    use sha2::{Digest, Sha256};
    let hash = Sha256::new()
        .chain_update(event_id.as_bytes())
        .chain_update(bot_id.as_uuid().as_bytes())
        .finalize();
    let mut bytes = *event_id.as_bytes();
    bytes[6..].copy_from_slice(&hash[..10]);
    bytes[6] = (bytes[6] & 0x0f) | 0x70;
    bytes[8] = (bytes[8] & 0x3f) | 0x80;
    Uuid::from_bytes(bytes)
}

fn assignment_prompt(assignment: &TaskAssignment, brief: &TaskBrief) -> String {
    let mut prompt = format!(
        "{}\n\n{}",
        include_str!("task_assignment/prompt.md").trim(),
        task_reference(&assignment.parent, &brief.title),
    );
    if let Some(project_id) = brief.project.as_ref().map(|project| project.id) {
        let project_reference = serde_json::json!({
            "documentId": project_id,
            "documentName": "Task project",
            "blockName": "initiative",
            "blockParams": {},
        });
        prompt.push_str(&format!(
            "\n\nProject: <m-document-mention>{project_reference}</m-document-mention>"
        ));
    }
    prompt.push_str("\n\n");
    prompt.push_str(&brief.markdown);
    prompt
}

/// Persistent task guidance for session system instructions, without snapshotting
/// the mutable task description into the system prompt.
pub fn assignment_instructions(parent: &MessageParent) -> String {
    format!(
        "{}\n\n{}",
        include_str!("task_assignment/prompt.md").trim(),
        task_reference(parent, "Original assigned task"),
    )
}

fn task_reference(parent: &MessageParent, title: &str) -> String {
    // Escape tag delimiters in user-controlled titles and retain the original
    // document ID in both the private opening prompt and system instructions.
    let task_reference = serde_json::json!({
        "documentId": parent.entity_id(),
        "documentName": title,
        "blockName": "task",
        "blockParams": {},
    })
    .to_string()
    .replace('<', "\\u003c")
    .replace('>', "\\u003e");
    format!("<m-document-mention>{task_reference}</m-document-mention>")
}

async fn assignment_discussion(
    assignment: &TaskAssignment,
    bot_id: BotId,
    discussion_id: Uuid,
    access: entity_access::domain::models::EntityAccessReceipt<MessageWrite>,
    commands: &dyn MessageCommands,
) -> Result<Option<messages::domain::models::Message>, ProcessMessageEventError> {
    use entity_access::domain::models::{BotReceiptScope, EntityAccessReceipt};
    // Agent availability and the assigning user's capability were checked by
    // authorize_task_assignment. The response spends that same capability.
    let access = EntityAccessReceipt::try_new_bot(
        bot_id.into(),
        BotReceiptScope::User {
            acting_user: assignment.actor.clone(),
        },
        access.entity().clone(),
        *access.entity_permission(),
    )
    .map_err(|_| {
        ProcessMessageEventError::Discussion(messages::domain::ports::MessageError::Forbidden)
    })?;
    let message = commands
        .post_from_event(
            access,
            discussion_id,
            PostMessage {
                id: None,
                attribution: MessageAttribution::ActingUser,
                notification_policy: PostMessageNotificationPolicy::Silent,
                content: "Working on this task…".to_owned(),
                thread_id: None,
                anchor: None,
                mentions: Vec::new(),
                attachments: Vec::new(),
                nonce: None,
            },
        )
        .await
        .map_err(ProcessMessageEventError::Discussion)?;
    // A replay must not resurrect a response the user deleted.
    if message.deleted_at.is_some()
        || message.parent != assignment.parent
        || message.thread_id.is_some()
        || message.sender_id.as_bot().map(|id| id.bot_id()) != Some(bot_id)
    {
        return Ok(None);
    }
    Ok(Some(message))
}