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.

10.3 KB
Raw Blame
//! UpdateThreadLabels tool for adding or removing a label from all messages in a thread.

use crate::domain::models::{LinkLabel, UserProvider, mailbox_action::MailboxAction};
use crate::domain::ports::{EmailService, GmailTokenProvider};
use ai_toolset::{AsyncTool, RequestContext, ServiceContext, ToolCallError, ToolResult};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use entity_access::domain::ports::EntityAccessService;
use macro_user_id::user_id::MacroUserIdStr;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

use super::EmailToolContext;

/// Add or remove a label from all messages in an email thread.
#[derive(Debug, Deserialize, JsonSchema, Clone)]
#[schemars(
    title = "UpdateThreadLabels",
    description = "\
Add or remove a single label from every message in a Gmail thread. In Gmail, nearly all \
inbox operations are just label add/remove operations, so this tool is the primitive for \
archiving, marking read/unread, starring, trashing, marking important/spam, and applying \
or removing custom labels.\n\
\n\
Name the label with exactly one of `label` or `label_id`. `label` is a system label \
(INBOX, UNREAD, STARRED, IMPORTANT, TRASH, SPAM) or a custom label's display name, \
matched in the thread's own inbox, so it works across inboxes without a lookup. \
`label_id` is a UUID from ListLabels. Pass `add=true` to apply or `add=false` to remove. \
Each call modifies one label — to do multiple changes on the same thread (e.g. archive \
AND mark read), call this tool once per label.\n\
\n\
Common operations:\n\
- Archive: remove `INBOX` (add=false)\n\
- Move back to inbox: add `INBOX` (add=true)\n\
- Mark as read: remove `UNREAD` (add=false)\n\
- Mark as unread: add `UNREAD` (add=true)\n\
- Star: add `STARRED` (add=true) / Unstar: remove (add=false)\n\
- Move to trash: add `TRASH` (add=true) / Restore: remove (add=false)\n\
- Mark important: add `IMPORTANT` (add=true) / Mark unimportant: remove (add=false)\n\
- Report spam: add `SPAM` (add=true) / Not spam: remove (add=false)\n\
- Apply custom user label: add the label with that display name (add=true) / Remove: (add=false)\n\
\n\
In an Outlook inbox the same system label names set the matching mailbox state (archive, read, \
flag, trash, junk); IMPORTANT has no Outlook equivalent, and other names are Outlook categories.\n\
\n\
`thread_id` is the email thread UUID (the same id returned by ListEntities, search results, \
or GetThread). `label_id` is the UUID returned by ListLabels — NOT the label name; pass a \
name in `label` instead."
)]
pub struct UpdateThreadLabels {
    /// The ID of the email thread to modify. Same UUID returned by ListEntities, search, or GetThread.
    pub thread_id: Uuid,
    /// The UUID of the label to add or remove, from ListLabels. Omit when passing `label`.
    #[serde(default)]
    pub label_id: Option<Uuid>,
    /// The label's name instead of its id: a system label (INBOX, UNREAD, STARRED, IMPORTANT, TRASH, SPAM) or a custom label's display name, matched in the thread's inbox. Omit when passing `label_id`.
    #[serde(default)]
    pub label: Option<String>,
    /// Whether to add (true) or remove (false) the label from every message in the thread.
    pub add: bool,
}

/// The Outlook mailbox state a system label stands for: `None` for other
/// labels (Outlook categories), an error for one Outlook has no equivalent of.
pub(crate) fn outlook_mailbox_state(
    label: &str,
    add: bool,
) -> Option<Result<MailboxAction, ToolCallError>> {
    let state = match label.trim().to_ascii_uppercase().as_str() {
        "INBOX" => MailboxAction::Archived(!add),
        "UNREAD" => MailboxAction::Read(!add),
        "STARRED" => MailboxAction::Flagged(add),
        "TRASH" => MailboxAction::Trashed(add),
        "SPAM" => MailboxAction::Junk(add),
        "IMPORTANT" => {
            return Some(Err(ToolCallError {
                description: "Outlook has no Important label; flag the email instead.".into(),
                internal_error: anyhow::anyhow!("IMPORTANT on an Outlook thread"),
            }));
        }
        _ => return None,
    };
    Some(Ok(state))
}

/// What setting a system label did, for the tool's summary.
/// The one way a call names its label.
#[derive(Clone, Copy)]
enum LabelSelector<'a> {
    Id(Uuid),
    Name(&'a str),
}

fn outlook_done(label: &str, add: bool) -> &'static str {
    match (label.trim().to_ascii_uppercase().as_str(), add) {
        ("INBOX", false) => "Archived",
        ("INBOX", true) => "Moved back to the inbox",
        ("UNREAD", false) => "Marked as read",
        ("UNREAD", true) => "Marked as unread",
        ("STARRED", true) => "Flagged",
        ("STARRED", false) => "Unflagged",
        ("TRASH", true) => "Moved to trash",
        ("SPAM", true) => "Moved to junk",
        _ => "Updated",
    }
}

/// Response from the UpdateThreadLabels tool.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct UpdateThreadLabelsResponse {
    /// The number of messages successfully updated.
    pub successful_count: usize,
    /// The number of messages that failed to update.
    pub failed_count: usize,
    /// A human-readable summary of the operation.
    pub summary: String,
}

impl ToolAnnotated for UpdateThreadLabels {
    const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Update thread labels");
}

#[async_trait]
impl<T, G, E> AsyncTool<EmailToolContext<T, G, E>> for UpdateThreadLabels
where
    T: EmailService,
    G: GmailTokenProvider,
    E: EntityAccessService,
{
    type Output = UpdateThreadLabelsResponse;

    #[tracing::instrument(skip_all, fields(
        user_id=?request_context.user_id,
        thread_id=%self.thread_id,
        label_id=?self.label_id,
        add=%self.add,
    ), err)]
    async fn call(
        &self,
        service_context: ServiceContext<EmailToolContext<T, G, E>>,
        request_context: RequestContext,
    ) -> ToolResult<Self::Output> {
        tracing::info!("Update thread labels");

        // Checked before the thread is resolved, so no provider acts on a
        // call that names its label both ways or not at all.
        let selector = match (self.label_id, self.label.as_deref()) {
            (Some(id), None) => LabelSelector::Id(id),
            (None, Some(name)) => LabelSelector::Name(name),
            _ => {
                return Err(ToolCallError {
                    description: "Pass exactly one of `label` or `label_id`.".to_string(),
                    internal_error: anyhow::anyhow!("label_id and label are exclusive"),
                });
            }
        };

        // Resolve the inbox from the thread itself rather than defaulting to the
        // caller's primary inbox, so label operations work on threads that live
        // in a delegated or secondary inbox.
        let link = service_context
            .service
            .get_owned_link_for_thread(
                MacroUserIdStr((*request_context.user_id).clone()),
                self.thread_id,
            )
            .await
            .map_err(|e| ToolCallError {
                description: format!("Failed to resolve inbox for thread: {e}"),
                internal_error: e.into(),
            })?
            .ok_or_else(|| ToolCallError {
                description: "No accessible inbox owns this thread.".to_string(),
                internal_error: anyhow::anyhow!("no owned link for thread"),
            })?;

        // Outlook has no system labels: archive, read, flag, trash and junk
        // are mailbox states there, so set the state instead.
        if link.provider == UserProvider::Outlook
            && let LabelSelector::Name(name) = selector
            && let Some(state) = outlook_mailbox_state(name, self.add)
        {
            let action = state?;
            let changed = service_context
                .service
                .change_thread_mailbox_state(
                    MacroUserIdStr((*request_context.user_id).clone()),
                    self.thread_id,
                    action,
                )
                .await
                .map_err(|e| ToolCallError {
                    description: format!("Failed to update the thread: {e}"),
                    internal_error: e.into(),
                })?;
            return Ok(UpdateThreadLabelsResponse {
                successful_count: changed,
                failed_count: 0,
                summary: format!("{} the thread.", outlook_done(name, self.add)),
            });
        }

        let label_id = match selector {
            LabelSelector::Id(id) => id,
            LabelSelector::Name(name) => {
                let labels = service_context
                    .service
                    .list_labels(&link)
                    .await
                    .map_err(|e| ToolCallError {
                        description: format!("Failed to list the inbox's labels: {e}"),
                        internal_error: e.into(),
                    })?;
                LinkLabel::find(&labels, name)
                    .map(|label| label.id)
                    .ok_or_else(|| ToolCallError {
                        description: format!(
                            "No label named \"{}\" in this thread's inbox. Call ListLabels to see its labels.",
                            name.trim()
                        ),
                        internal_error: anyhow::anyhow!("unknown label name"),
                    })?
            }
        };

        let result = service_context
            .service
            .update_thread_labels(&link, self.thread_id, label_id, self.add)
            .await
            .map_err(|e| ToolCallError {
                description: format!("Failed to update thread labels: {e}"),
                internal_error: e.into(),
            })?;

        let action = if self.add { "added to" } else { "removed from" };
        let successful_count = result.successful_ids.len();
        let failed_count = result.failed_ids.len();

        let summary = if failed_count == 0 {
            format!("Label successfully {action} {successful_count} message(s).")
        } else {
            format!(
                "Label {action} {successful_count} message(s), but failed for {failed_count} message(s)."
            )
        };

        Ok(UpdateThreadLabelsResponse {
            successful_count,
            failed_count,
            summary,
        })
    }
}