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.

16.3 KB
Raw Blame
//! Bot ports.

use super::models::{
    Agent, AuthenticatedBot, Bot, BotChannel, BotChannelListCaller, BotId, BotOwner,
    BotOwnerProfile, BotProfile, BotToken, BotTokenCandidate, CreateAgentRequest, CreateBotRequest,
    CreateBotTokenRequest, CreateBotTokenResponse, CreateChannelScopedBotRequest,
    CreateChannelScopedBotResponse, HarnessFacts, HarnessId, PatchAgentRequest, PatchBotRequest,
    UpdateAgentRequest,
};
use bot_token::HashedBotToken;
use entity_access::domain::models::{EntityAccessReceipt, MemberParticipantRole};
use macro_user_id::user_id::MacroUserIdStr;
use rootcause::Report;
use std::{collections::HashMap, future::Future};
use uuid::Uuid;

/// Bot repository.
#[cfg_attr(feature = "test-utils", mockall::automock(type Err = anyhow::Error;))]
pub trait BotRepo: Send + Sync + 'static {
    /// Repository error.
    type Err: Into<anyhow::Error> + Send;

    /// Create an owned agent and its selected channel memberships atomically,
    /// with `has_agent` enabled.
    fn create_agent(
        &self,
        owner: BotOwner,
        created_by: MacroUserIdStr<'static>,
        req: CreateAgentRequest,
    ) -> impl Future<Output = Result<Agent, Self::Err>> + Send;

    /// Replace an owned agent and its selected channel memberships atomically,
    /// enabling `has_agent` even if it was previously disabled.
    /// The direct agent conversations it takes part in are not among them and
    /// are left as they are.
    fn update_agent(
        &self,
        bot_id: BotId,
        owner: BotOwner,
        req: UpdateAgentRequest,
    ) -> impl Future<Output = Result<Option<Agent>, Self::Err>> + Send;

    /// List active agents the caller can manage or start a managed session as.
    ///
    /// Own and team-owned agents are included, plus selected-channel agents
    /// installed in a channel the caller belongs to — the same personas they
    /// can `@` mention there. A direct agent conversation is not such a
    /// channel.
    fn list_manageable_agents(
        &self,
        caller: MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<Vec<Agent>, Self::Err>> + Send;

    /// Check whether the caller is an active member of every supplied channel.
    /// A direct agent conversation never counts: it is not a channel to select.
    fn user_has_channels(
        &self,
        caller: MacroUserIdStr<'static>,
        channel_ids: &[Uuid],
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Create an owned bot.
    fn create_owned_bot(
        &self,
        owner: BotOwner,
        created_by: MacroUserIdStr<'static>,
        req: CreateBotRequest,
    ) -> impl Future<Output = Result<Bot, Self::Err>> + Send;

    /// Create an owned bot, add it to a channel, and persist a hashed token atomically.
    fn create_channel_scoped_bot(
        &self,
        owner: BotOwner,
        created_by: MacroUserIdStr<'static>,
        channel_id: Uuid,
        token: HashedBotToken,
        req: CreateChannelScopedBotRequest,
    ) -> impl Future<Output = Result<(Bot, BotToken), Self::Err>> + Send;

    /// List active bots manageable by a caller.
    fn list_manageable_bots(
        &self,
        caller: MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<Vec<Bot>, Self::Err>> + Send;

    /// Get an active bot by id.
    fn get_bot(&self, bot_id: BotId)
    -> impl Future<Output = Result<Option<Bot>, Self::Err>> + Send;

    /// Get presentation profiles for the requested bots.
    ///
    /// Historical profiles remain available after a bot is soft-deleted.
    fn get_bot_profiles(
        &self,
        bot_ids: &[BotId],
    ) -> impl Future<Output = Result<HashMap<BotId, BotProfile>, Self::Err>> + Send;

    /// Load owner profiles, including soft-deleted rows.
    fn get_owner_profiles(
        &self,
        bot_ids: &[BotId],
    ) -> impl Future<Output = Result<HashMap<BotId, BotOwnerProfile>, Self::Err>> + Send;

    /// Get an active persisted agent by bot id. Its channels are the ones it
    /// was put in, without the direct agent conversations it takes part in.
    fn get_agent(
        &self,
        bot_id: BotId,
    ) -> impl Future<Output = Result<Option<Agent>, Self::Err>> + Send;

    /// Check team membership.
    fn user_has_team(
        &self,
        caller: MacroUserIdStr<'static>,
        team_id: Uuid,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Get ownership and permission capabilities of an active registered harness.
    fn get_harness_facts(
        &self,
        harness_id: HarnessId,
    ) -> impl Future<Output = Result<Option<HarnessFacts>, Self::Err>> + Send;

    /// Check whether a bot is an active channel participant. A direct agent
    /// conversation counts: a mention in one of its threads still reaches
    /// the persona.
    fn bot_active_in_channel(
        &self,
        channel_id: Uuid,
        bot_id: BotId,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Check whether a bot may post in a channel on its own: it is an active
    /// participant, and the channel is not a direct agent conversation. Its
    /// owner or any member of its team holds the bot's tokens, not just the
    /// person a direct conversation is with.
    fn bot_may_post_in_channel(
        &self,
        channel_id: Uuid,
        bot_id: BotId,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Whether the user and bot share at least one active channel, other than a
    /// direct agent conversation: only the people a persona already serves
    /// have one, so it never makes the persona available.
    fn user_shares_channel_with_bot(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Check whether a user is an administrator or owner of a team.
    fn user_can_administer_team(
        &self,
        caller: MacroUserIdStr<'static>,
        team_id: Uuid,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Check whether a user owns a team.
    fn user_owns_team(
        &self,
        caller: MacroUserIdStr<'static>,
        team_id: Uuid,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Patch an active bot.
    fn patch_bot(
        &self,
        bot_id: BotId,
        req: PatchBotRequest,
    ) -> impl Future<Output = Result<Option<Bot>, Self::Err>> + Send;

    /// Soft-delete an active bot.
    fn delete_bot(&self, bot_id: BotId) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Add bot reach to a channel.
    fn add_bot_to_channel(
        &self,
        channel_id: Uuid,
        bot_id: BotId,
    ) -> impl Future<Output = Result<(), Self::Err>> + Send;

    /// Remove bot reach from a channel. A direct agent conversation keeps its
    /// persona, so removing it from one finds nothing to remove.
    fn remove_bot_from_channel(
        &self,
        channel_id: Uuid,
        bot_id: BotId,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// List active channels containing a bot, without the direct agent
    /// conversations it takes part in.
    fn list_bot_channels(
        &self,
        bot_id: BotId,
    ) -> impl Future<Output = Result<Vec<BotChannel>, Self::Err>> + Send;

    /// List active bots in a channel.
    fn list_channel_bots(
        &self,
        channel_id: Uuid,
    ) -> impl Future<Output = Result<Vec<Bot>, Self::Err>> + Send;

    /// Persist a hashed token. The raw secret must not be passed here.
    fn create_token(
        &self,
        bot_id: BotId,
        token: HashedBotToken,
        req: CreateBotTokenRequest,
    ) -> impl Future<Output = Result<BotToken, Self::Err>> + Send;

    /// List active token metadata.
    fn list_tokens(
        &self,
        bot_id: BotId,
    ) -> impl Future<Output = Result<Vec<BotToken>, Self::Err>> + Send;

    /// Revoke a token.
    fn revoke_token(
        &self,
        bot_id: BotId,
        token_id: Uuid,
    ) -> impl Future<Output = Result<bool, Self::Err>> + Send;

    /// Lookup a token candidate by hashing the presented raw token.
    fn token_candidate(
        &self,
        token: &str,
    ) -> impl Future<Output = Result<Option<BotTokenCandidate>, Self::Err>> + Send;

    /// Lookup a channel-scoped token candidate by hashing the presented raw token.
    /// A direct agent conversation accepts no token.
    fn channel_token_candidate(
        &self,
        channel_id: Uuid,
        token: &str,
    ) -> impl Future<Output = Result<Option<BotTokenCandidate>, Self::Err>> + Send;

    /// Mark a token as used.
    fn mark_token_used(&self, token_id: Uuid)
    -> impl Future<Output = Result<(), Self::Err>> + Send;
}

/// Eligibility for private conversations with an agent persona.
pub trait AgentDmEligibility: Send + Sync + 'static {
    /// Require a runnable persona owned by the caller or their current team.
    /// Channel placement does not confer or restrict private DM eligibility.
    fn authorize_agent_dm(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
    ) -> impl Future<Output = Result<(), BotError>> + Send;
}

/// Bot service.
#[cfg_attr(feature = "test-utils", mockall::automock)]
pub trait BotService: Send + Sync + 'static {
    /// Create an agent owned by the caller or a team they administer.
    fn create_agent(
        &self,
        caller: MacroUserIdStr<'static>,
        req: CreateAgentRequest,
    ) -> impl Future<Output = Result<Agent, BotError>> + Send;

    /// Replace the editable configuration of a manageable agent.
    fn update_agent(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
        req: UpdateAgentRequest,
    ) -> impl Future<Output = Result<Agent, BotError>> + Send;

    /// A live agent the caller may change: their own, or their team's. For
    /// settings kept beside the agent, such as its API key.
    fn manageable_agent(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
    ) -> impl Future<Output = Result<Agent, BotError>> + Send;

    /// Change part of a manageable agent's instructions or settings, keeping
    /// everything the patch leaves unnamed - owner and profile included.
    fn patch_agent(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
        req: PatchAgentRequest,
    ) -> impl Future<Output = Result<Agent, BotError>> + Send;

    /// List agents the caller can manage or start a managed session as.
    fn list_agents(
        &self,
        caller: MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<Vec<Agent>, BotError>> + Send;

    /// Create a bot owned by the caller or a team they administer.
    fn create_bot(
        &self,
        caller: MacroUserIdStr<'static>,
        req: CreateBotRequest,
    ) -> impl Future<Output = Result<Bot, BotError>> + Send;

    /// Create a bot owned by the caller or a team they administer and scoped to a channel.
    fn create_channel_scoped_bot(
        &self,
        caller: MacroUserIdStr<'static>,
        channel_id: Uuid,
        req: CreateChannelScopedBotRequest,
    ) -> impl Future<Output = Result<CreateChannelScopedBotResponse, BotError>> + Send;

    /// List bots manageable by the caller.
    fn list_bots(
        &self,
        caller: MacroUserIdStr<'static>,
    ) -> impl Future<Output = Result<Vec<Bot>, BotError>> + Send;

    /// Get a manageable bot.
    fn get_bot(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
    ) -> impl Future<Output = Result<Bot, BotError>> + Send;

    /// Load owner profiles in request order.
    fn get_owner_profiles(
        &self,
        ids: &[BotId],
    ) -> impl Future<Output = Result<Vec<BotOwnerProfile>, BotError>> + Send;

    /// Get the authenticated bot's own record.
    fn get_self(&self, bot_id: BotId) -> impl Future<Output = Result<Bot, BotError>> + Send;

    /// Patch a manageable bot.
    fn patch_bot(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
        req: PatchBotRequest,
    ) -> impl Future<Output = Result<Bot, BotError>> + Send;

    /// Delete a manageable bot.
    fn delete_bot(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
    ) -> impl Future<Output = Result<(), BotError>> + Send;

    /// Add an owned/team-available bot to a channel.
    fn add_bot_to_channel(
        &self,
        access: EntityAccessReceipt<MemberParticipantRole>,
        bot_id: BotId,
    ) -> impl Future<Output = Result<(), BotError>> + Send;

    /// Remove a bot from a channel.
    fn remove_bot_from_channel(
        &self,
        caller: MacroUserIdStr<'static>,
        channel_id: Uuid,
        bot_id: BotId,
    ) -> impl Future<Output = Result<(), BotError>> + Send;

    /// List active channels containing a manageable bot, the calling bot itself,
    /// or a bot requested by an authenticated internal service.
    fn list_bot_channels(
        &self,
        caller: BotChannelListCaller,
        bot_id: BotId,
    ) -> impl Future<Output = Result<Vec<BotChannel>, BotError>> + Send;

    /// List channel bots.
    fn list_channel_bots(
        &self,
        channel_id: Uuid,
    ) -> impl Future<Output = Result<Vec<Bot>, BotError>> + Send;

    /// Create a token for a manageable bot.
    fn create_token(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
        req: CreateBotTokenRequest,
    ) -> impl Future<Output = Result<CreateBotTokenResponse, BotError>> + Send;

    /// List token metadata for a manageable bot.
    fn list_tokens(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
    ) -> impl Future<Output = Result<Vec<BotToken>, BotError>> + Send;

    /// Revoke a token for a manageable bot.
    fn revoke_token(
        &self,
        caller: MacroUserIdStr<'static>,
        bot_id: BotId,
        token_id: Uuid,
    ) -> impl Future<Output = Result<(), BotError>> + Send;

    /// Ensure that a bot may post in a channel on its own: it is an active
    /// participant, and the channel is not a direct agent conversation.
    fn ensure_bot_in_channel(
        &self,
        bot_id: BotId,
        channel_id: Uuid,
    ) -> impl Future<Output = Result<(), BotError>> + Send;

    /// Authorize an autonomous bot's channel messages using its active channel
    /// membership alone. The receipt names no acting user and reaches no other entity.
    /// A direct agent conversation authorizes none, and is refused as a
    /// channel the bot is not in.
    fn channel_message_access(
        &self,
        bot_id: BotId,
        channel_id: Uuid,
    ) -> impl Future<
        Output = Result<EntityAccessReceipt<messages::domain::service::MessageWrite>, BotError>,
    > + Send;

    /// Authenticate a raw bearer token.
    fn authenticate_token(
        &self,
        token: &str,
    ) -> impl Future<Output = Result<AuthenticatedBot, BotError>> + Send;

    /// Authenticate a raw bot token scoped to a channel.
    fn authenticate_channel_token(
        &self,
        channel_id: Uuid,
        token: &str,
    ) -> impl Future<Output = Result<AuthenticatedBot, BotError>> + Send;
}

/// Whether a Pipedream app slug is one an agent may pin.
///
/// The directory is Pipedream's. `Ok(false)` is a definite miss. `Err` means
/// the directory could not be asked, and the slug must not be stored.
pub trait McpAppCatalog: Send + Sync + 'static {
    /// `true` when `slug` is a connectable Pipedream app.
    fn is_connectable_app(&self, slug: &str)
    -> impl Future<Output = Result<bool, BotError>> + Send;
}

/// Every bot a team has owned, for removing the team.
///
/// `bots.team_id` is the only link from a team bot to its team, and it
/// cascades when the team row is deleted, so ask before deleting the team.
pub trait TeamBotRoster: Send + Sync + 'static {
    /// The bots of `team_id` in id order, soft-deleted bots included. An
    /// unknown team has none.
    fn team_bot_ids(
        &self,
        team_id: Uuid,
    ) -> impl Future<Output = Result<Vec<BotId>, Report>> + Send;
}

/// Bot service error.
#[derive(Debug, thiserror::Error)]
pub enum BotError {
    /// Bad request.
    #[error("{0}")]
    BadRequest(String),
    /// Not found.
    #[error("{0}")]
    NotFound(String),
    /// Unauthorized.
    #[error("unauthorized")]
    Unauthorized,
    /// The MCP app directory could not answer, so a slug was not stored.
    #[error("{0}")]
    Unavailable(String),
    /// Repository error.
    #[error(transparent)]
    Repo(#[from] anyhow::Error),
}