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.

23.5 KB
Raw Blame
//! Bot domain models.

use chrono::{DateTime, Utc};
use macro_user_id::user_id::MacroUserIdStr;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

/// Shared bot id used by bot principals.
pub use bot_id::BotId;
/// Shared harness id used by agent-harness bindings.
pub use harness_id::HarnessId;

/// Owner of a registered harness an agent wants to run on.
///
/// Kept minimal on purpose: the bots domain only needs enough to decide
/// whether a caller may bind an agent to the harness. Mirrors the harnesses
/// domain's `HarnessOwner`, whose table enforces exactly one owner.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HarnessOwner {
    /// User-owned (private) harness.
    User {
        /// Owner user id.
        user_id: String,
    },
    /// Team-owned harness, usable by every team member.
    Team {
        /// Owner team id.
        team_id: Uuid,
    },
}

/// Bot kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum BotKind {
    /// User- or team-owned bot.
    Owned,
    /// First-party system bot.
    System,
}

impl BotKind {
    /// Storage representation.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Owned => "owned",
            Self::System => "system",
        }
    }
}

impl std::str::FromStr for BotKind {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value {
            "owned" => Ok(Self::Owned),
            "system" => Ok(Self::System),
            other => Err(format!("unknown bot kind: {other}")),
        }
    }
}

/// Channel type for a channel containing a bot.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
pub enum BotChannelType {
    /// Public channel.
    Public,
    /// Private channel.
    Private,
    /// Direct message channel.
    DirectMessage,
    /// Team channel.
    Team,
}

impl BotChannelType {
    /// Storage representation.
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::Public => "public",
            Self::Private => "private",
            Self::DirectMessage => "direct_message",
            Self::Team => "team",
        }
    }
}

impl std::str::FromStr for BotChannelType {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value {
            "public" => Ok(Self::Public),
            "private" => Ok(Self::Private),
            "direct_message" => Ok(Self::DirectMessage),
            "team" => Ok(Self::Team),
            other => Err(format!("unknown bot channel type: {other}")),
        }
    }
}

/// Bot owner.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case", tag = "type")]
pub enum BotOwner {
    /// User-owned bot.
    User {
        /// Owner user id.
        user_id: String,
    },
    /// Team-owned bot.
    Team {
        /// Owner team id.
        team_id: Uuid,
    },
}

/// Bot row.
///
/// Clients deserialize this, so both derives are used.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct Bot {
    /// Bot id.
    pub id: BotId,
    /// Bot kind.
    pub kind: BotKind,
    /// Owner for owned bots.
    pub owner: Option<BotOwner>,
    /// Display name.
    pub name: String,
    /// Stable handle.
    pub handle: String,
    /// Optional description.
    pub description: Option<String>,
    /// Optional avatar URL.
    pub avatar_url: Option<String>,
    /// User that created this bot.
    pub created_by: Option<String>,
    /// Creation timestamp.
    pub created_at: DateTime<Utc>,
    /// Update timestamp.
    pub updated_at: DateTime<Utc>,
    /// Soft-delete timestamp.
    pub deleted_at: Option<DateTime<Utc>>,
    /// Whether this bot runs as an AI agent: mentions and DMs start an agent session.
    pub has_agent: bool,
}

/// Minimal bot identity used when another domain presents a bot reference.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BotProfile {
    /// Bot id.
    pub id: BotId,
    /// Display name.
    pub name: String,
    /// Optional avatar URL.
    pub avatar_url: Option<String>,
}

/// Most bot ids one owner-profile request accepts, counting duplicates.
pub const MAX_BOT_OWNER_PROFILE_IDS: usize = 100;

/// Bot identity for rendering, including the sponsor and soft-delete time.
///
/// `owner` is none only for a registry system bot. A persisted row always has
/// a sponsor.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct BotOwnerProfile {
    /// Bot id.
    pub id: BotId,
    /// Display name.
    pub name: String,
    /// Avatar URL. Registry system bots have none.
    pub avatar_url: Option<String>,
    /// Soft-delete time. Absent for an active bot and for a registry system bot.
    pub deleted_at: Option<DateTime<Utc>>,
    /// Sponsor. None only for a registry system bot.
    pub owner: Option<BotOwner>,
}

impl BotOwnerProfile {
    /// Profile of a first-party bot from the registry.
    #[must_use]
    pub fn system(bot: &bot_id::SystemBot) -> Self {
        Self {
            id: bot.id,
            name: bot.name.to_owned(),
            avatar_url: None,
            deleted_at: None,
            owner: None,
        }
    }

    /// Profile of a persisted bot, including one that is soft-deleted.
    #[must_use]
    pub fn persisted(
        id: BotId,
        name: String,
        avatar_url: Option<String>,
        deleted_at: Option<DateTime<Utc>>,
        owner: BotOwner,
    ) -> Self {
        Self {
            id,
            name,
            avatar_url,
            deleted_at,
            owner: Some(owner),
        }
    }
}

impl Bot {
    /// The [`Bot`] view of a first-party bot.
    ///
    /// First-party bots have no row (see [`bot_id::SystemBot`]), so the
    /// row-shaped fields are the honest answers for something that was never
    /// created and cannot be owned, edited, or deleted.
    #[must_use]
    pub fn system(bot: &bot_id::SystemBot) -> Self {
        Self {
            id: bot.id,
            kind: BotKind::System,
            owner: None,
            name: bot.name.to_owned(),
            handle: bot.handle.to_owned(),
            description: None,
            avatar_url: None,
            created_by: None,
            created_at: DateTime::UNIX_EPOCH,
            updated_at: DateTime::UNIX_EPOCH,
            deleted_at: None,
            has_agent: bot.has_agent,
        }
    }
}

/// Whether an agent is available everywhere or only in selected channels.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    Serialize,
    Deserialize,
    strum::EnumString,
    strum::IntoStaticStr,
)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(rename_all = "snake_case")]
#[strum(serialize_all = "snake_case")]
pub enum AgentChannelScope {
    /// The agent is available in every channel its owner can use.
    All,
    /// The agent is available only in its persisted channel memberships.
    Selected,
}

impl AgentChannelScope {
    /// Storage representation.
    pub fn as_str(self) -> &'static str {
        self.into()
    }
}

/// Which Pipedream MCP servers an agent's sessions are handed.
///
/// One value for the whole choice, so a selection can never travel without
/// its scope or a scope without its selection. Serialized with a `scope` tag,
/// which the generated TypeScript sees as a discriminated union.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
#[serde(tag = "scope", rename_all = "snake_case")]
pub enum AgentMcpServers {
    /// Whatever apps the person running the session has connected.
    #[default]
    OwnerConnections,
    /// Exactly these apps, connected or not.
    Selected {
        /// The apps, in the order the agent's author picked them.
        servers: Vec<AgentMcpServer>,
    },
}

impl AgentMcpServers {
    /// Storage representation of the scope.
    pub fn scope_str(&self) -> &'static str {
        match self {
            Self::OwnerConnections => "owner_connections",
            Self::Selected { .. } => "selected",
        }
    }

    /// The selected servers, empty under [`Self::OwnerConnections`].
    pub fn servers(&self) -> &[AgentMcpServer] {
        match self {
            Self::OwnerConnections => &[],
            Self::Selected { servers } => servers,
        }
    }

    /// Rebuilds the value from its two stored columns.
    pub fn from_columns(scope: &str, servers: Vec<AgentMcpServer>) -> anyhow::Result<Self> {
        match scope {
            "owner_connections" => Ok(Self::OwnerConnections),
            "selected" => Ok(Self::Selected { servers }),
            other => anyhow::bail!("unknown mcp scope {other:?}"),
        }
    }
}

/// One Pipedream app an agent lists under [`AgentMcpServers::Selected`].
///
/// Only the catalog identity is stored. Whether a given person has connected
/// the app is theirs, resolved at call time by the egress proxy, never here.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct AgentMcpServer {
    /// Pipedream app slug, e.g. `linear`.
    pub app_slug: String,
    /// Display name, e.g. `Linear`.
    pub server_name: String,
}

/// A persisted user- or team-owned AI agent.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct Agent {
    /// The bot identity used for mentions and channel participation.
    pub bot: Bot,
    /// Instructions supplied to the agent at the start of a conversation.
    pub instructions: String,
    /// Harness used to run the agent.
    pub harness: String,
    /// Registered harness the agent runs on, when `harness` is `macrod`.
    pub harness_id: Option<HarnessId>,
    /// Model selected specifically for this agent.
    pub default_model: String,
    /// Whether the agent is global or channel-specific.
    pub channel_scope: AgentChannelScope,
    /// Selected channel ids. Empty for a global agent.
    pub channel_ids: Vec<Uuid>,
    /// Which MCP servers sessions of this agent are handed.
    pub mcp: AgentMcpServers,
    /// Whether the agent's sessions approve ACP permission requests without
    /// asking. `None` means always prompt. Bypass also requires the harness's opt-in.
    pub auto_accept_permissions: Option<bool>,
    /// Whether the agent works in a repository, which decides how it answers
    /// a channel mention: a coding agent posts a magic chip into its live
    /// session, a chat agent replies in the thread. Chosen in the agent's
    /// settings; the persona's word, not the runtime's.
    pub is_coding: bool,
}

/// Request to create a persisted AI agent.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateAgentRequest {
    /// Team owner. Omit for a private, user-owned agent.
    pub team_id: Option<Uuid>,
    /// Registered harness to run on. Required when `harness` is `macrod`,
    /// forbidden otherwise.
    #[serde(default)]
    pub harness_id: Option<HarnessId>,
    /// Display name.
    pub name: String,
    /// Stable `@` handle.
    pub handle: String,
    /// Optional description.
    pub description: Option<String>,
    /// Optional avatar URL or data URL.
    pub avatar_url: Option<String>,
    /// Instructions supplied to the agent at the start of a conversation.
    pub instructions: String,
    /// Harness used to run the agent.
    pub harness: String,
    /// Model selected specifically for this agent.
    pub default_model: String,
    /// Whether the agent is global or channel-specific.
    pub channel_scope: AgentChannelScope,
    /// Selected channels. Must be non-empty only for `selected` scope.
    #[serde(default)]
    pub channel_ids: Vec<Uuid>,
    /// Which MCP servers sessions of this agent are handed.
    #[serde(default)]
    pub mcp: AgentMcpServers,
    /// Whether the agent's sessions approve ACP permission requests without
    /// asking. Omit to always prompt.
    #[serde(default)]
    pub auto_accept_permissions: Option<bool>,
    /// Whether the agent is a coding agent: a mention is answered with a magic
    /// chip into its live session (`true`) or a reply in the thread (`false`).
    pub is_coding: bool,
}

/// Request to replace the editable configuration of a persisted AI agent.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct UpdateAgentRequest {
    /// Team owner. Omit to make the agent private to the caller.
    pub team_id: Option<Uuid>,
    /// Registered harness to run on. Required when `harness` is `macrod`,
    /// forbidden otherwise.
    #[serde(default)]
    pub harness_id: Option<HarnessId>,
    /// Display name.
    pub name: String,
    /// Stable `@` handle.
    pub handle: String,
    /// Optional description.
    pub description: Option<String>,
    /// Optional avatar URL or data URL.
    pub avatar_url: Option<String>,
    /// Instructions supplied to the agent at the start of a conversation.
    pub instructions: String,
    /// Harness used to run the agent.
    pub harness: String,
    /// Model selected specifically for this agent.
    pub default_model: String,
    /// Whether the agent is global or channel-specific.
    pub channel_scope: AgentChannelScope,
    /// Selected channels. Must be non-empty only for `selected` scope.
    #[serde(default)]
    pub channel_ids: Vec<Uuid>,
    /// Which MCP servers sessions of this agent are handed.
    #[serde(default)]
    pub mcp: AgentMcpServers,
    /// Whether the agent's sessions approve ACP permission requests without
    /// asking. Omit to always prompt.
    #[serde(default)]
    pub auto_accept_permissions: Option<bool>,
    /// Whether the agent is a coding agent: a mention is answered with a magic
    /// chip into its live session (`true`) or a reply in the thread (`false`).
    pub is_coding: bool,
}

#[cfg(test)]
mod test;

/// The runtime an agent runs on: a harness slug and, for `macrod`, the
/// registered harness serving it. Travel together because one without the
/// other is never a valid choice.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AgentHarnessSelection {
    /// Harness slug, e.g. `in-memory`, `cursor`, or `macrod`.
    pub harness: String,
    /// Registered harness to run on. Required when `harness` is `macrod`,
    /// forbidden otherwise.
    pub harness_id: Option<HarnessId>,
}

/// Where an agent can be mentioned: everywhere its owner can use it, or
/// exactly the listed channels.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AgentChannelSelection {
    /// Whether the agent is global or channel-specific.
    pub channel_scope: AgentChannelScope,
    /// Selected channels. Must be non-empty only for `selected` scope.
    pub channel_ids: Vec<Uuid>,
}

/// Request to change part of a persisted agent's instructions or settings.
///
/// Every field is optional; an absent field keeps the agent's current value.
/// Ownership and the bot profile (name, handle, description, avatar) are not
/// patchable here: the profile has [`PatchBotRequest`], and ownership changes
/// go through [`UpdateAgentRequest`].
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct PatchAgentRequest {
    /// Replacement instructions, whole.
    pub instructions: Option<String>,
    /// Replacement runtime.
    pub harness: Option<AgentHarnessSelection>,
    /// Replacement model.
    pub default_model: Option<String>,
    /// Replacement channel availability.
    pub channels: Option<AgentChannelSelection>,
    /// Replacement MCP server selection.
    pub mcp: Option<AgentMcpServers>,
    /// Replacement permission choice: approve without asking (`true`) or
    /// prompt (`false`). A patch cannot clear the choice back to unset; an
    /// explicit `false` prompts exactly as unset does.
    pub auto_accept_permissions: Option<bool>,
    /// Replacement coding choice.
    pub is_coding: Option<bool>,
}

impl PatchAgentRequest {
    /// The full replacement `current` becomes once this patch is applied.
    ///
    /// Keeps the agent under its current owner and profile; only what the
    /// patch names changes.
    #[must_use]
    pub fn apply_to(self, current: &Agent) -> UpdateAgentRequest {
        let (harness, harness_id) = match self.harness {
            Some(selection) => (selection.harness, selection.harness_id),
            None => (current.harness.clone(), current.harness_id),
        };
        let (channel_scope, channel_ids) = match self.channels {
            Some(selection) => (selection.channel_scope, selection.channel_ids),
            None => (current.channel_scope, current.channel_ids.clone()),
        };
        UpdateAgentRequest {
            team_id: match &current.bot.owner {
                Some(BotOwner::Team { team_id }) => Some(*team_id),
                Some(BotOwner::User { .. }) | None => None,
            },
            harness_id,
            name: current.bot.name.clone(),
            handle: current.bot.handle.clone(),
            description: current.bot.description.clone(),
            avatar_url: current.bot.avatar_url.clone(),
            instructions: self
                .instructions
                .unwrap_or_else(|| current.instructions.clone()),
            harness,
            default_model: self
                .default_model
                .unwrap_or_else(|| current.default_model.clone()),
            channel_scope,
            channel_ids,
            mcp: self.mcp.unwrap_or_else(|| current.mcp.clone()),
            auto_accept_permissions: self
                .auto_accept_permissions
                .or(current.auto_accept_permissions),
            is_coding: self.is_coding.unwrap_or(current.is_coding),
        }
    }
}

/// Channel containing a bot.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct BotChannel {
    /// Channel id.
    pub channel_id: Uuid,
    /// Channel display name.
    pub name: Option<String>,
    /// Channel type.
    pub channel_type: BotChannelType,
    /// Timestamp when the bot joined the channel.
    pub joined_at: DateTime<Utc>,
}

/// Authenticated principal asking to list a bot's channels.
#[derive(Debug, Clone)]
pub enum BotChannelListCaller {
    /// A directly authenticated Macro user.
    User(MacroUserIdStr<'static>),
    /// An authenticated bot.
    Bot(BotId),
    /// An authenticated internal service, with or without an acting user.
    Internal,
}

/// Bot token metadata.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct BotToken {
    /// Token id.
    pub id: Uuid,
    /// Owning bot id.
    pub bot_id: BotId,
    /// Display prefix of the bearer token. The raw secret is never stored here.
    pub token_prefix: String,
    /// Optional token label.
    pub label: Option<String>,
    /// Last successful use.
    pub last_used_at: Option<DateTime<Utc>>,
    /// Expiration timestamp.
    pub expires_at: Option<DateTime<Utc>>,
    /// Revocation timestamp.
    pub revoked_at: Option<DateTime<Utc>>,
    /// Creation timestamp.
    pub created_at: DateTime<Utc>,
}

/// Authenticated bot principal.
#[derive(Debug, Clone)]
pub struct AuthenticatedBot {
    /// Bot id.
    pub bot_id: BotId,
    /// Bot kind.
    pub kind: BotKind,
}

/// Candidate token row used during bearer-token authentication.
#[derive(Debug, Clone)]
pub struct BotTokenCandidate {
    /// Token metadata.
    pub token: BotToken,
    /// Authenticated bot principal associated with the token.
    pub bot: AuthenticatedBot,
}

/// Request to create a bot.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateBotRequest {
    /// Team owner. The caller must be a team administrator or owner. Omit for a user-owned bot.
    pub team_id: Option<Uuid>,
    /// Display name.
    pub name: String,
    /// Stable handle.
    pub handle: String,
    /// Optional description.
    pub description: Option<String>,
    /// Optional avatar URL.
    pub avatar_url: Option<String>,
    /// Whether this bot runs as an AI agent: mentions and DMs start an agent session. Defaults to false.
    pub has_agent: Option<bool>,
}

/// Request to patch a bot.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct PatchBotRequest {
    /// Display name.
    pub name: Option<String>,
    /// Stable handle.
    pub handle: Option<String>,
    /// Optional description.
    pub description: Option<String>,
    /// Optional avatar URL.
    pub avatar_url: Option<String>,
    /// Whether this bot runs as an AI agent: mentions and DMs start an agent session. Omit to leave unchanged.
    pub has_agent: Option<bool>,
}

/// Request to create a bot token.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateBotTokenRequest {
    /// Token label.
    pub label: Option<String>,
    /// Optional expiration timestamp.
    pub expires_at: Option<DateTime<Utc>>,
}

/// Request to add a bot to a channel.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct AddChannelBotRequest {
    /// Bot id.
    pub bot_id: BotId,
}

/// Request to create a bot scoped to a channel.
#[derive(Debug, Clone, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateChannelScopedBotRequest {
    /// Team owner. The caller must be a team administrator or owner. Omit for a user-owned bot.
    pub team_id: Option<Uuid>,
    /// Display name.
    pub name: String,
    /// Stable handle.
    pub handle: String,
    /// Optional description.
    pub description: Option<String>,
    /// Optional avatar URL.
    pub avatar_url: Option<String>,
    /// Optional token label.
    pub token_label: Option<String>,
    /// Optional token expiration timestamp.
    pub token_expires_at: Option<DateTime<Utc>>,
    /// Whether this bot runs as an AI agent: mentions and DMs start an agent session. Defaults to false.
    pub has_agent: Option<bool>,
}

/// Response containing a newly minted token.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateBotTokenResponse {
    /// Token metadata.
    pub token: BotToken,
    /// Raw bearer token.
    pub bearer_token: String,
}

/// Response containing a newly created channel-scoped bot and token.
#[derive(Debug, Clone, Serialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct CreateChannelScopedBotResponse {
    /// Created bot.
    pub bot: Bot,
    /// Token metadata.
    pub token: BotToken,
    /// Raw bot token.
    pub bot_token: String,
}

/// Request to post a channel webhook message.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ChannelWebhookRequest {
    /// Message body.
    pub content: String,
}

/// Response returned after posting a channel webhook message.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[cfg_attr(feature = "inbound", derive(utoipa::ToSchema))]
pub struct ChannelWebhookResponse {
    /// Created message id.
    pub message_id: String,
}

/// Facts about a registered harness used to validate a persona.
pub struct HarnessFacts {
    /// Who may use the harness.
    pub owner: HarnessOwner,
    /// Whether the harness operator permits unattended tool approvals.
    pub allow_permission_bypass: bool,
}