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.

22.8 KB
Raw Blame
//! Commands use the scheduler's existing cron engine, including single-year
//! one-off schedules, and its program model for steps.
use anyhow::{Result, ensure};
use async_trait::async_trait;
use chrono::{DateTime, Datelike, Timelike, Utc};
use macro_user_id::user_id::MacroUserIdStr;
use routine_program::{RoutineProgram, Step};
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::Value;
use uuid::Uuid;

#[cfg(test)]
mod test;

/// A recurring or one-off schedule, as the scheduler's cron trigger.
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum RoutineSchedule {
    /// Execute once at a future timestamp, even if the creating session has ended.
    Once {
        /// RFC3339 timestamp including UTC offset.
        at: DateTime<Utc>,
    },
    /// Repeat using a six-field cron expression and an IANA time zone.
    Cron {
        /// Seconds, minutes, hours, day-of-month, month, weekday (optional year).
        expression: String,
        /// IANA time zone, e.g. America/New_York.
        timezone: String,
    },
}
impl RoutineSchedule {
    /// Validate and translate to the existing scheduler contract.
    pub fn cron(&self, now: DateTime<Utc>) -> Result<(String, String)> {
        let (schedule, timezone) = match self {
            Self::Once { at } => {
                ensure!(*at > now, "Choose a one-off time in the future.");
                (
                    format!(
                        "{} {} {} {} {} * {}",
                        at.second(),
                        at.minute(),
                        at.hour(),
                        at.day(),
                        at.month(),
                        at.year()
                    ),
                    "UTC".to_owned(),
                )
            }
            Self::Cron {
                expression,
                timezone,
            } => {
                let cron = expression.parse::<cron::Schedule>().map_err(|_| {
                    anyhow::anyhow!(
                        "Use a six-field cron: seconds minutes hours day-of-month month weekday."
                    )
                })?;
                let zone = timezone.parse::<chrono_tz::Tz>().map_err(|_| {
                    anyhow::anyhow!("Use an IANA timezone such as America/New_York.")
                })?;
                ensure!(
                    cron.after(&now.with_timezone(&zone)).next().is_some(),
                    "This schedule has no future runs."
                );
                (expression.clone(), timezone.clone())
            }
        };
        Ok((schedule, timezone))
    }
}
/// When a routine runs. Combine any schedules with any activity triggers.
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum RoutineTrigger {
    /// Execute once at a future timestamp, even if the creating session has ended.
    Once {
        /// RFC3339 timestamp including UTC offset.
        at: DateTime<Utc>,
    },
    /// Repeat using a six-field cron expression and an IANA time zone.
    Cron {
        /// Seconds, minutes, hours, day-of-month, month, weekday (optional year).
        expression: String,
        /// IANA time zone, e.g. America/New_York.
        timezone: String,
    },
    /// Run when matching activity happens in Macro. Only people's actions
    /// trigger routines; changes made by routines and agents never do.
    Event {
        /// Any of these events starts a run.
        events: Vec<RoutineEvent>,
        /// Limit to these items: channel ids for channel events, task or
        /// document ids for task and document events. Omit to match every
        /// item; `*_created`, `channel.mentioned` and `email.message_received`
        /// usually omit it.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        ids: Option<Vec<Uuid>>,
        /// Optional yes/no question the triggering content must answer with
        /// yes, e.g. "Is this email from a customer?". Runs where the answer
        /// is no are skipped before any step runs.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        condition: Option<String>,
    },
}

/// Activity that can trigger a routine.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
pub enum RoutineEvent {
    /// New mail arrives in the owner's inbox (not spam, trash, drafts or imports).
    #[serde(rename = "email.message_received")]
    EmailMessageReceived,
    /// A task the owner can access is created.
    #[serde(rename = "task.created")]
    TaskCreated,
    /// A selected task's status changes.
    #[serde(rename = "task.status_changed")]
    TaskStatusChanged,
    /// A selected task's priority changes.
    #[serde(rename = "task.priority_changed")]
    TaskPriorityChanged,
    /// Any property of a selected task changes.
    #[serde(rename = "task.property_changed")]
    TaskPropertyChanged,
    /// A document the owner can access is created.
    #[serde(rename = "document.created")]
    DocumentCreated,
    /// A selected document is deleted.
    #[serde(rename = "document.deleted")]
    DocumentDeleted,
    /// A channel the owner can access is created.
    #[serde(rename = "channel.created")]
    ChannelCreated,
    /// Someone sends a message in a selected channel.
    #[serde(rename = "channel.message_posted")]
    ChannelMessagePosted,
    /// The owner is @-mentioned in a channel.
    #[serde(rename = "channel.mentioned")]
    ChannelMentioned,
    /// A call the owner can access starts.
    #[serde(rename = "call.started")]
    CallStarted,
    /// A call the owner can access ends.
    #[serde(rename = "call.ended")]
    CallEnded,
}

/// Bounds the scheduler enforces as well; checked here for clearer errors.
const MAX_TRIGGERS: usize = 16;
const MAX_EVENT_FILTERS: usize = 32;

/// Complete user-editable configuration, independent of execution bookkeeping.
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct RoutineConfiguration {
    /// Short descriptive name.
    pub name: String,
    /// When it runs: one or more schedules and activity triggers.
    pub triggers: Vec<RoutineTrigger>,
    /// What it does each run, in order: a JSON array of steps, encoded as a
    /// string (see the tool description for the step format).
    #[serde(with = "steps_json")]
    #[schemars(with = "String")]
    pub steps: Vec<Step>,
    /// Apps its agent step needs, on top of the agent's own. The user must
    /// already have each one connected (offer a connect link via
    /// DiscoverConnectors if not). On update, omit it to keep the routine's
    /// current apps; a list replaces them, and an empty list removes them.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub required_apps: Option<Vec<RoutineApp>>,
}
/// A Pipedream app a routine requires.
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct RoutineApp {
    /// Pipedream app slug, e.g. `linear`.
    pub app_slug: String,
    /// Display name, e.g. `Linear`.
    pub name: String,
}

/// A configuration in the current shape, or in the single-agent shape callers
/// used before steps (`instructions`, `target`, `schedule`), which becomes one
/// agent step on that schedule. The advertised schema is the current one.
pub fn deserialize_configuration<'de, D: serde::Deserializer<'de>>(
    deserializer: D,
) -> Result<RoutineConfiguration, D::Error> {
    use serde::de::Error;
    let mut value = Value::deserialize(deserializer)?;
    if let Value::Object(fields) = &mut value
        && !fields.contains_key("steps")
        && let Some(instructions) = fields.remove("instructions")
    {
        let mut agent = serde_json::json!({ "type": "agent", "instructions": instructions });
        if let Some(Value::Object(target)) = fields.remove("target") {
            match target.get("type").and_then(Value::as_str) {
                Some("model") => {
                    agent["model"] = target.get("model").cloned().unwrap_or(Value::Null);
                }
                Some("agent") => {
                    agent["agent"] = serde_json::json!({ "bot_id": target.get("agentId") });
                }
                _ => {}
            }
        }
        fields.insert("steps".into(), Value::Array(vec![agent]));
        if !fields.contains_key("triggers")
            && let Some(schedule) = fields.remove("schedule")
        {
            fields.insert("triggers".into(), Value::Array(vec![schedule]));
        }
    }
    RoutineConfiguration::deserialize(value).map_err(D::Error::custom)
}

/// Steps travel as a JSON string so the tool's input schema stays flat: some
/// providers reject recursive or free-form schemas. An array is accepted too.
mod steps_json {
    use routine_program::Step;
    use serde::{Deserialize, Deserializer, Serializer, de::Error};
    use serde_json::Value;

    pub fn serialize<S: Serializer>(steps: &[Step], serializer: S) -> Result<S::Ok, S::Error> {
        let text = serde_json::to_string(steps).map_err(serde::ser::Error::custom)?;
        serializer.serialize_str(&text)
    }

    pub fn deserialize<'de, D: Deserializer<'de>>(deserializer: D) -> Result<Vec<Step>, D::Error> {
        let value = match Value::deserialize(deserializer)? {
            Value::String(text) => serde_json::from_str(&text).map_err(|error| {
                D::Error::custom(format!("steps must be a JSON array of steps: {error}"))
            })?,
            value => value,
        };
        serde_json::from_value(value)
            .map_err(|error| D::Error::custom(format!("invalid steps: {error}")))
    }
}

/// A saved routine whose configuration these tools can't express without
/// losing part of it, so it is only edited on its page in Macro.
#[derive(Debug, Clone)]
pub struct NotEditableHere(String);

impl std::fmt::Display for NotEditableHere {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{} Edit it on the routine's page in Macro.", self.0)
    }
}

impl std::error::Error for NotEditableHere {}

impl RoutineConfiguration {
    /// The saved routine in the shape CreateRoutine and UpdateRoutine take, so
    /// it can be sent back with only the intended change.
    pub fn from_saved(name: &str, trigger: &Value, task: &Value) -> Result<Self, NotEditableHere> {
        let program = RoutineProgram::from_task(task)
            .map_err(|_| NotEditableHere("Its steps can't be read here.".into()))?;
        Ok(Self {
            name: name.to_owned(),
            triggers: saved_triggers(trigger)?,
            steps: program.steps,
            required_apps: Some(
                program
                    .mcp_servers
                    .into_iter()
                    .map(|app| RoutineApp {
                        app_slug: app.app_slug,
                        name: app.server_name,
                    })
                    .collect(),
            ),
        })
    }

    /// Validate the user's intent independently of its transport representation.
    pub fn validate(&self, now: DateTime<Utc>) -> Result<()> {
        ensure!(!self.name.trim().is_empty(), "A routine name is required.");
        self.trigger(now)?;
        // Validate as a program, so a lone agent step gets every check too.
        let apps: Vec<Value> = self
            .required_apps
            .iter()
            .flatten()
            .map(|app| serde_json::json!({ "app_slug": app.app_slug, "server_name": app.name }))
            .collect();
        let program = serde_json::json!({ "steps": self.steps, "mcp_servers": apps });
        RoutineProgram::from_task(&program)
            .map_err(|error| anyhow::anyhow!("Invalid steps: {error}."))?
            .validate()
            .map_err(|error| anyhow::anyhow!("Invalid steps: {error}."))?;
        Ok(())
    }

    /// The scheduler's task, replacing `saved` when updating. Apps are always
    /// stated: the listed ones, or the saved ones when the caller omitted them.
    /// A lone agent step is stored as the single agent task routines had
    /// before steps, as the app does, so every scheduler version can run it;
    /// a saved program stays a program.
    pub fn task(&self, saved: Option<&Value>) -> Value {
        let mcp_servers: Vec<Value> = match &self.required_apps {
            Some(apps) => apps
                .iter()
                .map(|app| serde_json::json!({ "app_slug": app.app_slug, "server_name": app.name }))
                .collect(),
            None => saved
                .and_then(|task| task.get("mcp_servers"))
                .and_then(Value::as_array)
                .cloned()
                .unwrap_or_default(),
        };
        let saved_program = saved.is_some_and(|task| task.get("steps").is_some());
        if !saved_program && let [Step::Agent(agent)] = self.steps.as_slice() {
            let (prompt, user_prompt) = split_instructions(saved, &agent.instructions);
            let mut task = serde_json::json!({
                "mcp_servers": mcp_servers,
                "prompt": prompt,
                "user_prompt": user_prompt,
            });
            if let Some(model) = &agent.model {
                task["model"] = model.clone().into();
            }
            if let Some(selection) = &agent.agent {
                task["agent"] = serde_json::json!({ "bot_id": selection.bot_id });
            }
            return task;
        }
        serde_json::json!({ "steps": self.steps, "mcp_servers": mcp_servers })
    }

    /// The scheduler's trigger: schedules as they are, activity filters combined.
    pub fn trigger(&self, now: DateTime<Utc>) -> Result<Value> {
        ensure!(
            !self.triggers.is_empty(),
            "Add a trigger: a schedule or an activity event."
        );
        let mut schedules = Vec::new();
        let mut filters = Vec::new();
        for trigger in &self.triggers {
            match trigger {
                RoutineTrigger::Once { at } => {
                    schedules.push(cron_trigger(RoutineSchedule::Once { at: *at }.cron(now)?))
                }
                RoutineTrigger::Cron {
                    expression,
                    timezone,
                } => schedules.push(cron_trigger(
                    RoutineSchedule::Cron {
                        expression: expression.clone(),
                        timezone: timezone.clone(),
                    }
                    .cron(now)?,
                )),
                RoutineTrigger::Event {
                    events,
                    ids,
                    condition,
                } => {
                    ensure!(
                        !events.is_empty(),
                        "Activity triggers need at least one event."
                    );
                    let mut filter = serde_json::json!({ "events": events });
                    if let Some(ids) = ids {
                        filter["ids"] = serde_json::json!(ids);
                    }
                    if let Some(condition) = condition.as_deref().map(str::trim)
                        && !condition.is_empty()
                    {
                        filter["condition"] = condition.into();
                    }
                    filters.push(filter);
                }
            }
        }
        ensure!(
            schedules.len() + usize::from(!filters.is_empty()) <= MAX_TRIGGERS,
            "Use at most {MAX_TRIGGERS} schedules."
        );
        ensure!(
            filters.len() <= MAX_EVENT_FILTERS,
            "Use at most {MAX_EVENT_FILTERS} activity triggers."
        );
        if !filters.is_empty() {
            schedules.push(serde_json::json!({ "type": "events", "filters": filters }));
        }
        Ok(match <[Value; 1]>::try_from(schedules) {
            Ok([single]) => single,
            Err(triggers) => serde_json::json!({ "type": "multiple", "triggers": triggers }),
        })
    }
}

fn cron_trigger((schedule, timezone): (String, String)) -> Value {
    serde_json::json!({ "type": "cron", "schedule": schedule, "timezone": timezone })
}

/// The saved scheduler trigger as these tools' triggers: schedules stay cron
/// expressions; each activity filter becomes one event trigger.
fn saved_triggers(trigger: &Value) -> Result<Vec<RoutineTrigger>, NotEditableHere> {
    let unreadable = || NotEditableHere("Its triggers can't be read here.".into());
    match trigger.get("type").and_then(Value::as_str) {
        Some("cron") => Ok(vec![RoutineTrigger::Cron {
            expression: string_field(trigger, "schedule").ok_or_else(unreadable)?,
            timezone: string_field(trigger, "timezone").ok_or_else(unreadable)?,
        }]),
        Some("events") => trigger
            .get("filters")
            .and_then(Value::as_array)
            .ok_or_else(unreadable)?
            .iter()
            .map(saved_filter)
            .collect(),
        Some("multiple") => {
            let mut triggers = Vec::new();
            for trigger in trigger
                .get("triggers")
                .and_then(Value::as_array)
                .ok_or_else(unreadable)?
            {
                triggers.extend(saved_triggers(trigger)?);
            }
            Ok(triggers)
        }
        _ => Err(unreadable()),
    }
}

/// One activity filter, refused when it holds what an event trigger here
/// can't state (GitHub selectors, payload tests, older event kinds), since
/// sending it back would drop them.
fn saved_filter(filter: &Value) -> Result<RoutineTrigger, NotEditableHere> {
    let Value::Object(fields) = filter else {
        return Err(NotEditableHere("Its triggers can't be read here.".into()));
    };
    if let Some(key) = fields
        .keys()
        .find(|key| !matches!(key.as_str(), "events" | "ids" | "condition"))
    {
        return Err(NotEditableHere(match key.as_str() {
            "github" | "match" => {
                "It has GitHub or payload filters these tools can't state.".into()
            }
            _ => format!("Its trigger has a `{key}` setting these tools can't state."),
        }));
    }
    let events: Vec<RoutineEvent> = serde_json::from_value(fields["events"].clone())
        .map_err(|_| NotEditableHere("It uses events these tools can't state.".into()))?;
    let ids = match fields.get("ids") {
        None | Some(Value::Null) => None,
        Some(ids) => Some(
            serde_json::from_value(ids.clone())
                .map_err(|_| NotEditableHere("Its trigger's items can't be read here.".into()))?,
        ),
    };
    Ok(RoutineTrigger::Event {
        events,
        ids,
        condition: fields
            .get("condition")
            .and_then(Value::as_str)
            .map(str::to_owned),
    })
}

fn string_field(value: &Value, key: &str) -> Option<String> {
    value.get(key).and_then(Value::as_str).map(str::to_owned)
}

/// Compact routine details returned to the caller.
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct RoutineInfo {
    /// Routine identifier.
    pub id: Uuid,
    /// Display name.
    pub name: String,
    /// Whether automatic runs are enabled.
    pub enabled: bool,
    /// The saved configuration in the shape CreateRoutine and UpdateRoutine
    /// take. To change it, send it back with only the intended change.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub configuration: Option<RoutineConfiguration>,
    /// Why `configuration` is absent: part of this routine can only be
    /// edited on its page in Macro, so UpdateRoutine refuses to replace it.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub not_editable_here: Option<String>,
    /// Next scheduled firing, absent after a one-off completes.
    pub next_run_at: Option<DateTime<Utc>>,
}
/// A bounded list with the full matching count.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct RoutineList {
    /// Matching routines (most recent first).
    pub routines: Vec<RoutineInfo>,
    /// Total matches before the response limit.
    pub total: usize,
}
/// Routine configuration and recent execution history.
#[derive(Debug, Serialize, JsonSchema)]
pub struct RoutineDetails {
    /// Current saved configuration.
    pub routine: RoutineInfo,
    /// Most recent runs, up to fifty, including status and transcript references.
    pub runs: Vec<serde_json::Value>,
}
/// A run started on demand; it continues after the call returns.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct RoutineRunStarted {
    /// The routine that is running.
    pub routine_id: Uuid,
    /// The chat or agent session the run writes to, when the scheduler reports one.
    pub resource: Option<serde_json::Value>,
}
/// Owning-service capability: authorization remains in the scheduler, never the tools.
#[async_trait]
pub trait RoutineService: Send + Sync {
    /// Create for the authenticated user; target accessibility is checked server-side.
    async fn create(
        &self,
        user: &MacroUserIdStr<'static>,
        config: &RoutineConfiguration,
    ) -> Result<RoutineInfo>;
    /// List the authenticated user's routines, including routines targeting agents.
    async fn list(&self, user: &MacroUserIdStr<'static>) -> Result<Vec<RoutineInfo>>;
    /// Read an accessible routine and its history.
    async fn read(&self, user: &MacroUserIdStr<'static>, id: Uuid) -> Result<RoutineDetails>;
    /// Replace configuration of an owned routine; activation is preserved.
    async fn update(
        &self,
        user: &MacroUserIdStr<'static>,
        id: Uuid,
        config: &RoutineConfiguration,
    ) -> Result<RoutineInfo>;
    /// Pause/resume an owned routine independently of its configuration.
    async fn set_enabled(
        &self,
        user: &MacroUserIdStr<'static>,
        id: Uuid,
        enabled: bool,
    ) -> Result<RoutineInfo>;
    /// Permanently delete an owned routine and its schedule.
    async fn delete(&self, user: &MacroUserIdStr<'static>, id: Uuid) -> Result<()>;
    /// Start an owned routine now, outside its schedule.
    async fn run_now(&self, user: &MacroUserIdStr<'static>, id: Uuid) -> Result<RoutineRunStarted>;
}

/// A saved single agent task keeps its routine instructions (`prompt`) apart
/// from the user task, and reads back as the two joined by a blank line. While
/// the joined text still starts with the saved instructions, keep them apart,
/// so the agent is told them the same way as before the edit.
fn split_instructions(saved: Option<&Value>, instructions: &str) -> (String, String) {
    let base = saved
        .and_then(|task| task.get("prompt"))
        .and_then(Value::as_str)
        .map(str::trim)
        .unwrap_or_default();
    match instructions
        .strip_prefix(base)
        .and_then(|rest| rest.strip_prefix("\n\n"))
    {
        Some(user_prompt) if !base.is_empty() => (base.to_owned(), user_prompt.to_owned()),
        _ => (String::new(), instructions.to_owned()),
    }
}