Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! 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()
}
}