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.

20.6 KB
Raw Blame
//! Agent session lifecycle facts, published to
//! [`MacroAgentSessionLifecycleTopic`] and keyed by session id.
//!
//! These are facts about a session after the fact - opened, a turn started or
//! ended, nothing left to do, asking its owner something, gone - for anyone
//! downstream to react to: webhooks, notifications, observability. Commands
//! that *drive* a session travel on `macro.agent_sessions` instead.
//!
//! Consumers that only decode these events depend on this crate with
//! `default-features = false`: the domain compiles without the inbound and
//! outbound adapters' axum, sqlx, and client dependencies.

#[cfg(test)]
mod test;

use agent_runtime_protocol::domain::action::AgentActionId;
use bots::domain::models::BotId;
use macro_event_broker::{Event, MacroEvent, TopicEvent};
use macro_event_topics::MacroAgentSessionLifecycleTopic;
use macro_user_id::user_id::MacroUserIdStr;
use macro_uuid::Uuid;
use messages::domain::models::MessageParent;
use serde::{Deserialize, Serialize};

use super::model::{
    AgentSessionId, AgentSessionLog, LogAppended, Message, SessionSource, StoredAgentSessionLog,
    TurnId,
};

/// The thread a session was opened from, when it was.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct ThreadOrigin {
    /// Entity owning the thread: the channel or document it was posted in.
    pub parent: MessageParent,
    /// Channel the thread lives in, for channel parents only. Kept beside
    /// `parent` for consumers written when every origin was a channel.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub channel_id: Option<Uuid>,
    /// Root message of the thread.
    pub thread_id: Uuid,
    /// The message whose mention opened the session.
    pub originating_message_id: Uuid,
}

impl ThreadOrigin {
    /// An origin on `parent`, with `channel_id` derived from it.
    #[must_use]
    pub fn new(parent: MessageParent, thread_id: Uuid, originating_message_id: Uuid) -> Self {
        let channel_id = match &parent {
            MessageParent::Channel(channel_id) => Some(*channel_id),
            MessageParent::Document(_)
            | MessageParent::Call(_)
            | MessageParent::Initiative(_)
            | MessageParent::CrmCompany(_)
            | MessageParent::CrmContact(_) => None,
        };
        Self {
            parent,
            channel_id,
            thread_id,
            originating_message_id,
        }
    }
}

/// Wire shape of [`ThreadOrigin`]: events published before parents existed
/// carry only `channel_id`, and still decode as channel origins.
#[derive(Deserialize)]
struct ThreadOriginWire {
    #[serde(default)]
    parent: Option<MessageParent>,
    #[serde(default)]
    channel_id: Option<Uuid>,
    thread_id: Uuid,
    originating_message_id: Uuid,
}

impl<'de> Deserialize<'de> for ThreadOrigin {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let wire = ThreadOriginWire::deserialize(deserializer)?;
        let parent = wire
            .parent
            .or(wire.channel_id.map(MessageParent::Channel))
            .ok_or_else(|| serde::de::Error::missing_field("parent"))?;
        Ok(Self::new(
            parent,
            wire.thread_id,
            wire.originating_message_id,
        ))
    }
}

/// Who and what a session is; carried by every lifecycle event so a
/// consumer never has to look the session up.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct SessionIdentity {
    /// The session.
    #[cfg_attr(feature = "schema", schema(value_type = String, format = Uuid))]
    pub session_id: AgentSessionId,
    /// User-facing session name at the time of the event.
    pub session_name: String,
    /// Bot the session runs for.
    pub bot_id: BotId,
    /// The bot's display name at the time of the event.
    pub bot_name: String,
    /// User who owns the session.
    pub owner_id: MacroUserIdStr<'static>,
    /// Thread the session was opened from, when it was.
    pub origin: Option<ThreadOrigin>,
    /// Everyone with a stake in what happens next: the owner plus every user
    /// who has prompted or answered this session. Resolved by the emitter so
    /// a consumer fanning out never has to read the session's log.
    #[serde(default)]
    pub audience: Vec<MacroUserIdStr<'static>>,
    /// Who started the session. Events from before it was recorded say
    /// nothing and read as a person.
    #[serde(default)]
    pub source: SessionSource,
}

/// A turn the runtime answered.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct TurnSummary {
    /// Position in the session's log.
    #[cfg_attr(feature = "schema", schema(value_type = u32))]
    pub turn: TurnId,
    /// The action that opened the turn.
    pub action_id: AgentActionId,
    /// User who prompted it, absent when a bot acted on nobody's behalf.
    pub actor: Option<MacroUserIdStr<'static>>,
    /// The magic-chip message posted for this turn, when one was.
    pub announcement_message_id: Option<Uuid>,
    /// The ACP stop reason, or `"error"` when the runtime refused the prompt.
    pub stop_reason: String,
    /// The agent's last text in the turn, whole; what the magic chip shows
    /// once the turn ends. `None` when the turn produced no prose.
    pub excerpt: Option<String>,
}

/// A turn the runtime never answered: the session stopped underneath it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct InFlightTurnSummary {
    /// Position in the session's log.
    #[cfg_attr(feature = "schema", schema(value_type = u32))]
    pub turn: TurnId,
    /// The action that opened the turn.
    pub action_id: AgentActionId,
    /// User who prompted it, absent when a bot acted on nobody's behalf.
    pub actor: Option<MacroUserIdStr<'static>>,
    /// The magic-chip message posted for this turn, when one was.
    pub announcement_message_id: Option<Uuid>,
}

/// A session was created.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct SessionOpenedMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// Model slug the session runs with.
    pub model: String,
    /// Harness slug the session runs on.
    pub harness: String,
}

/// A prompt was delivered to the runtime.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct TurnStartedMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// Position in the session's log.
    #[cfg_attr(feature = "schema", schema(value_type = u32))]
    pub turn: TurnId,
    /// The action that opened the turn.
    pub action_id: AgentActionId,
    /// User who prompted it, absent when a bot acted on nobody's behalf.
    pub actor: Option<MacroUserIdStr<'static>>,
    /// The magic-chip message posted for this turn, when one was.
    pub announcement_message_id: Option<Uuid>,
}

/// The runtime answered a turn. Another prompt may follow at once; see
/// [`SessionSettledMetadata`] for "nothing left to do".
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct TurnEndedMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// Position in the session's log.
    #[cfg_attr(feature = "schema", schema(value_type = u32))]
    pub turn: TurnId,
    /// The action that opened the turn.
    pub action_id: AgentActionId,
    /// User who prompted it, absent when a bot acted on nobody's behalf.
    pub actor: Option<MacroUserIdStr<'static>>,
    /// The magic-chip message posted for this turn, when one was.
    pub announcement_message_id: Option<Uuid>,
    /// The ACP stop reason, or `"error"` when the runtime refused the prompt.
    pub stop_reason: String,
    /// Prompts still waiting behind this turn.
    pub queued_remaining: usize,
}

/// Sanitized public details of a command refused before runtime execution.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct CommandFailure {
    /// Stable public denial or unavailability code.
    pub code: String,
    /// Public explanation, never an internal error report.
    pub message: String,
    /// Whether retrying later may succeed without a policy change.
    pub retryable: bool,
}

#[cfg(feature = "admission")]
impl From<ai_billing::AiAdmissionError> for CommandFailure {
    fn from(error: ai_billing::AiAdmissionError) -> Self {
        Self {
            code: error.code().to_owned(),
            message: error.to_string(),
            retryable: error.is_retryable(),
        }
    }
}

/// An accepted command was refused before it could start a runtime turn.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct CommandRejectedMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// The command that will not execute.
    pub action_id: AgentActionId,
    /// Who submitted the command, if acting on a user's behalf.
    pub actor: Option<MacroUserIdStr<'static>>,
    /// The command's thread announcement, when one was created.
    pub announcement_message_id: Option<Uuid>,
    /// Safe details for clients and downstream consumers.
    pub failure: CommandFailure,
}

/// A turn ended and nothing is queued: the agent has stopped working.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct SessionSettledMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// The turn that just ended, when the emitter still had its record.
    pub last_turn: Option<TurnSummary>,
}

/// The agent asked its owner a question and is blocked on the answer.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct WaitingForInputMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// The turn asking.
    #[cfg_attr(feature = "schema", schema(value_type = u32))]
    pub turn: TurnId,
    /// The action that opened the turn.
    pub action_id: AgentActionId,
    /// The magic-chip message posted for this turn, when one was.
    pub announcement_message_id: Option<Uuid>,
    /// The question, as the agent phrased it.
    pub question: String,
}

/// The pending question was answered or withdrawn.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct InputReceivedMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// The turn that was asking.
    #[cfg_attr(feature = "schema", schema(value_type = u32))]
    pub turn: TurnId,
    /// The action that opened the turn.
    pub action_id: AgentActionId,
}

/// A prompt named other users who can open the session. Published when the
/// prompt is accepted, not when it is answered: "come look at this" should
/// not wait for the turn.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct SessionMentionedMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// The action carrying the prompt.
    pub action_id: AgentActionId,
    /// Who wrote the prompt, absent when a bot acted on nobody's behalf.
    pub mentioned_by: Option<MacroUserIdStr<'static>>,
    /// The users named, already narrowed to those who can open the session
    /// and never including the author.
    pub mentioned: Vec<MacroUserIdStr<'static>>,
    /// The channel or document message the prompt was posted as, when it
    /// arrived from a thread rather than the session view. That message
    /// already notified the users it named when it was posted.
    #[serde(default)]
    pub origin_message_id: Option<Uuid>,
}

/// The session's live actor is gone: idle teardown, transport loss, or crash.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct SessionStoppedMetadata {
    /// The session.
    pub identity: SessionIdentity,
    /// Why it stopped, as the session machine reported it.
    pub reason: String,
    /// The turn that was running when it stopped, if any.
    pub turn_in_flight: Option<InFlightTurnSummary>,
}

/// The session was renamed; `identity` carries the new name.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct SessionRenamedMetadata {
    /// The session, with its new name.
    pub identity: SessionIdentity,
}

/// The session was deleted.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
pub struct SessionDeletedMetadata {
    /// The session as it was.
    pub identity: SessionIdentity,
}

/// Events publishable to [`MacroAgentSessionLifecycleTopic`].
///
/// The serde tag and [`AgentSessionLifecycleEventName`] spell the same wire
/// names: subscribers filter on them, so they are API. The
/// `event_names_match_the_wire` test holds the two in step. Exhaustive on
/// purpose: a consumer's match should break when a variant is added.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, strum::EnumDiscriminants)]
#[cfg_attr(feature = "schema", derive(utoipa::ToSchema))]
#[serde(tag = "event_type", content = "metadata")]
#[strum_discriminants(
    name(AgentSessionLifecycleEventName),
    derive(strum::Display, strum::EnumIter, strum::IntoStaticStr),
    doc = "The wire name of an [`AgentSessionLifecycleEvent`], as subscribers filter on it."
)]
pub enum AgentSessionLifecycleEvent {
    /// A session was created.
    #[serde(rename = "agent_session.opened")]
    #[strum_discriminants(strum(serialize = "agent_session.opened"))]
    Opened(SessionOpenedMetadata),
    /// A prompt was delivered to the runtime.
    #[serde(rename = "agent_session.turn_started")]
    #[strum_discriminants(strum(serialize = "agent_session.turn_started"))]
    TurnStarted(TurnStartedMetadata),
    /// The runtime answered a turn.
    #[serde(rename = "agent_session.turn_ended")]
    #[strum_discriminants(strum(serialize = "agent_session.turn_ended"))]
    TurnEnded(TurnEndedMetadata),
    /// An accepted command was refused before runtime execution.
    #[serde(rename = "agent_session.command_rejected")]
    #[strum_discriminants(strum(serialize = "agent_session.command_rejected"))]
    CommandRejected(CommandRejectedMetadata),
    /// A turn ended with nothing queued behind it.
    #[serde(rename = "agent_session.settled")]
    #[strum_discriminants(strum(serialize = "agent_session.settled"))]
    Settled(SessionSettledMetadata),
    /// The agent is blocked on a question to its owner.
    #[serde(rename = "agent_session.waiting_for_input")]
    #[strum_discriminants(strum(serialize = "agent_session.waiting_for_input"))]
    WaitingForInput(WaitingForInputMetadata),
    /// The question was answered or withdrawn.
    #[serde(rename = "agent_session.input_received")]
    #[strum_discriminants(strum(serialize = "agent_session.input_received"))]
    InputReceived(InputReceivedMetadata),
    /// A prompt named other users who can open the session.
    #[serde(rename = "agent_session.mentioned")]
    #[strum_discriminants(strum(serialize = "agent_session.mentioned"))]
    Mentioned(SessionMentionedMetadata),
    /// The session's live actor is gone.
    #[serde(rename = "agent_session.stopped")]
    #[strum_discriminants(strum(serialize = "agent_session.stopped"))]
    Stopped(SessionStoppedMetadata),
    /// The session was renamed.
    #[serde(rename = "agent_session.renamed")]
    #[strum_discriminants(strum(serialize = "agent_session.renamed"))]
    Renamed(SessionRenamedMetadata),
    /// The session was deleted.
    #[serde(rename = "agent_session.deleted")]
    #[strum_discriminants(strum(serialize = "agent_session.deleted"))]
    Deleted(SessionDeletedMetadata),
}

impl AgentSessionLifecycleEvent {
    /// The session this event is about.
    #[must_use]
    pub fn identity(&self) -> &SessionIdentity {
        match self {
            Self::Opened(metadata) => &metadata.identity,
            Self::TurnStarted(metadata) => &metadata.identity,
            Self::TurnEnded(metadata) => &metadata.identity,
            Self::CommandRejected(metadata) => &metadata.identity,
            Self::Settled(metadata) => &metadata.identity,
            Self::WaitingForInput(metadata) => &metadata.identity,
            Self::InputReceived(metadata) => &metadata.identity,
            Self::Mentioned(metadata) => &metadata.identity,
            Self::Stopped(metadata) => &metadata.identity,
            Self::Renamed(metadata) => &metadata.identity,
            Self::Deleted(metadata) => &metadata.identity,
        }
    }

    /// The session's id.
    #[must_use]
    pub fn session_id(&self) -> AgentSessionId {
        self.identity().session_id
    }

    /// The wire name subscribers filter on.
    #[must_use]
    pub fn name(&self) -> &'static str {
        AgentSessionLifecycleEventName::from(self).into()
    }
}

impl TopicEvent for AgentSessionLifecycleEvent {
    type Topic = MacroAgentSessionLifecycleTopic;

    const SCHEMA_VERSION: u8 = 1;
}

/// Publishable event for [`MacroAgentSessionLifecycleTopic`].
///
/// Keyed by session id: one session's facts land on one partition, in order,
/// so a consumer sees `turn_started` before `turn_ended` before `settled`.
#[derive(Debug, Clone)]
pub struct AgentSessionLifecycleMacroEvent {
    key: String,
    event: Event<AgentSessionLifecycleEvent>,
}

impl AgentSessionLifecycleMacroEvent {
    /// Wrap a lifecycle fact for publication.
    #[must_use]
    pub fn new(event: AgentSessionLifecycleEvent) -> Self {
        Self {
            key: event.session_id().to_string(),
            event: Event::new(event),
        }
    }
}

impl MacroEvent for AgentSessionLifecycleMacroEvent {
    type EventPayload = AgentSessionLifecycleEvent;

    fn key(&self) -> &str {
        &self.key
    }

    fn event(&self) -> &Event<Self::EventPayload> {
        &self.event
    }

    fn from_event(key: String, event: Event<Self::EventPayload>) -> Self {
        Self { key, event }
    }
}

/// The frames one flush appended, as the log stored them: what the harness
/// hands to a process serving viewers of its own, such as the GraphQL
/// subscription in document storage. Each entry is exactly the stored row, so
/// a subscriber folds the same bytes a reader of the durable log does.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LogAppendedMetadata {
    /// The session the frames belong to.
    pub agent_session_id: AgentSessionId,
    /// The frames, in the order the log holds them.
    pub entries: Vec<LogAppendedEntry>,
}

/// One stored frame: the row's identity and time beside the frame itself.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LogAppendedEntry {
    /// Durable row identity.
    pub id: Uuid,
    /// When the log recorded the frame.
    pub created_at: chrono::DateTime<chrono::Utc>,
    /// The user whose action produced the frame, absent when no user did.
    pub user_id: Option<MacroUserIdStr<'static>>,
    /// The frame, with its direction.
    pub content: Message,
}

impl From<&LogAppended> for LogAppendedMetadata {
    fn from(event: &LogAppended) -> Self {
        Self {
            agent_session_id: event.agent_session_id,
            entries: event
                .entries
                .iter()
                .map(|stored| LogAppendedEntry {
                    id: stored.id,
                    created_at: stored.created_at,
                    user_id: stored.entry.user_id.clone(),
                    content: stored.entry.content.clone(),
                })
                .collect(),
        }
    }
}

impl LogAppendedMetadata {
    /// The frames as stored rows again, for a consumer that reads them the
    /// way it reads the durable log.
    #[must_use]
    pub fn into_stored(self) -> Vec<StoredAgentSessionLog> {
        let agent_session_id = self.agent_session_id;
        self.entries
            .into_iter()
            .map(|entry| StoredAgentSessionLog {
                id: entry.id,
                created_at: entry.created_at,
                entry: AgentSessionLog {
                    agent_session_id,
                    user_id: entry.user_id,
                    content: entry.content,
                    logged_at: Some(entry.created_at),
                },
            })
            .collect()
    }
}