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.

10.3 KB
Raw Blame
//! The renderable message vocabulary.
//!
//! These types are the fold's output: what an agent session looks like once
//! its protocol log has been collapsed into something a channel can display.
//! Nothing here is persisted - a [`FoldedMessage`] is derived from
//! `agent_session_log` on every read, so the vocabulary is free to change
//! without a migration.
//!
//! The shapes are deliberately lossy. ACP carries plenty that no reader wants
//! to see (token usage, mode changes, capability handshakes); those frames are
//! dropped rather than modelled. What survives is the material a person would
//! recognize as the story of the session: what they asked, what the agent
//! said, what it ran, and what it wanted permission to do.

use agent_runtime_protocol::domain::action::AgentActionId;
use chrono::{DateTime, Utc};
use macro_user_id::user_id::MacroUserIdStr;
use non_empty::NonEmpty;
use serde::Serialize;
use specta::Type;

/// Questions the agent asks the user, and their answers.
mod elicitation;
/// Per-push change reports.
mod event;
/// Requests currently awaiting a user response.
mod interaction;
/// Session-level metadata.
mod metadata;
/// The parts a message is made of.
mod part;
/// Permission requests and outcomes.
mod permission;
/// The agent's plan.
mod plan;
/// Plain text derived from renderable messages for search.
mod search;
/// How a reply reads as a conversation: prose, activity, interactions.
mod segment;
/// Turn-level facts derived from the fold.
mod signal;
/// Delegated agents.
mod subagent;
/// Tool calls.
mod tool;
/// Macro user tools.
mod user_tool;

pub use agent_runtime_protocol::domain::turn::{FailureLink, FailureNotice, FailureNoticeKind};
pub use elicitation::{
    AnsweredChoice, AnsweredField, AnsweredValue, ElicitationOption, ElicitationOutcome,
    ElicitationProperty, ElicitationPropertySchema, ElicitationRequest, ElicitationRequestId,
    ElicitationSchema, PendingElicitation,
};
pub use event::{FoldEvent, OwnedFoldEvent};
pub use interaction::{PendingInteraction, PendingPermission, PendingToolApproval};
pub use metadata::{
    AvailableCommand, Harness, ModelOption, SessionMetadata, SessionNotification, TurnState,
};
pub use part::{Control, ControlOutcome, MessagePart, StopReason, TaskStatus};
pub use permission::{PermissionOption, PermissionOptionKind, PermissionOutcome};
pub use plan::{PlanEntry, PlanEntryPriority, PlanEntryStatus};
pub use segment::{
    ActivityCard, ActivityRow, ActivityStatus, ProjectedSegment, Segment, SegmentKind, TurnPhase,
    phase, project, prose_text, segments,
};
pub use signal::TurnSignal;
pub use subagent::{SubagentResult, ToolStats};
pub use tool::{AnsiText, FileDiff, ToolDetail, ToolName, ToolStatus};
pub use user_tool::UserToolOutcome;

/// One prompt-to-stop cycle within a session.
///
/// Assigned by the fold in log order starting at zero, so the same log always
/// yields the same ids. This is not the ACP request id - that correlation is
/// internal to the fold.
///
/// A turn is not the unit a channel renders - see [`MessageId`], which is
/// what a comms placeholder stores.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
)]
pub struct TurnId(pub u32);

/// A tool call within a turn, identified by its ACP `toolCallId`.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Type)]
#[serde(transparent)]
#[specta(transparent)]
pub struct ToolUseId(pub String);

/// The JSON-RPC id of a request the agent made, as the agent wrote it.
///
/// Kept in the agent's own shape - a number stays a number - because an
/// answer has to echo it exactly; `"7"` does not answer `7`.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Type)]
#[serde(untagged)]
pub enum AgentRequestId {
    /// A numeric id. Exported as a plain TypeScript number: agents count
    /// requests from zero, nowhere near where an `i64` stops round-tripping.
    Number(#[specta(type = i32)] i64),
    /// A string id.
    Str(String),
}

impl From<&agent_client_protocol::schema::v1::RequestId> for AgentRequestId {
    fn from(id: &agent_client_protocol::schema::v1::RequestId) -> Self {
        use agent_client_protocol::schema::v1::RequestId;
        match id {
            RequestId::Number(number) => Self::Number(*number),
            RequestId::Str(text) => Self::Str(text.clone()),
            // Requests carry an id by definition; a null one is a protocol
            // violation the fold renders rather than rejects.
            RequestId::Null => Self::Str(id.to_string()),
        }
    }
}

/// The natural key of a [`FoldedMessage`] within its session.
///
/// Nothing here is stored, so there is no surrogate row id to hand out.
/// Instead the key falls out of the fold's shape: a turn yields at most one
/// message per side of the conversation, so `(turn, author side)` identifies
/// a message - and because [`TurnId`]s are assigned in log order, the same
/// log always derives the same keys. Queries that pretend the messages are
/// stored address them by this.
///
/// The one exception to "nothing here is persisted": a comms placeholder
/// message stores the message it renders, as these two fields alongside a
/// session id, relying on exactly this stability. They stay two fields
/// everywhere they travel - column, wire, and JSON - so nothing has to format
/// or reparse a composite to get at either half. One placeholder per message,
/// not per turn: a turn's prompt and its reply are separate rows so each can
/// carry its own sender.
#[derive(
    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
)]
pub struct MessageId {
    /// The turn the message belongs to.
    pub turn: TurnId,
    /// Which side of the conversation produced it.
    pub author: AuthorKind,
}

impl MessageId {
    /// The first folded message authored by `author` in a session.
    #[must_use]
    pub const fn first(author: AuthorKind) -> Self {
        Self {
            turn: TurnId(0),
            author,
        }
    }

    /// Address the other side of this turn without changing its turn id.
    #[must_use]
    pub const fn with_author(self, author: AuthorKind) -> Self {
        Self {
            turn: self.turn,
            author,
        }
    }
}

/// Which side of the conversation produced a message.
///
/// The identity-free discriminant of [`Author`], usable in a key where
/// [`Author`] itself carries a payload.
///
/// The wire names a [`MessageId`] is written with and parsed back from are
/// the strum-derived `snake_case` variant names - one source of truth for
/// both directions.
#[derive(
    Debug,
    Clone,
    Copy,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
    Hash,
    strum::Display,
    strum::EnumString,
    strum::IntoStaticStr,
    serde::Serialize,
    serde::Deserialize,
)]
#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
#[strum(serialize_all = "snake_case")]
#[serde(rename_all = "snake_case")]
pub enum AuthorKind {
    /// A person.
    User,
    /// The agent.
    Agent,
}

impl AuthorKind {
    /// The wire name, as it appears in a [`MessageId`]'s string form.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        self.into()
    }
}

/// One renderable message folded out of a session's protocol log.
///
/// A turn produces at most two of these: the user's prompt and the agent's
/// reply. Both carry their content as an ordered part list, so a reader can
/// collapse runs of tool activity or interleave text and tools however it
/// likes.
#[derive(Debug, Clone, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct FoldedMessage {
    /// the id of this message
    #[serde(rename = "turn")]
    pub id: TurnId,
    /// Who produced it.
    pub author: Author,
    /// The ACP request id of the frame that derived this message - the same
    /// string the control endpoint returned, for correlation. `None` on agent
    /// messages and on frames the control plane did not mint (other clients'
    /// requests, notifications).
    pub request_id: Option<AgentActionId>,
    /// Ordered content. Never empty - the fold drops messages with no parts.
    pub parts: NonEmpty<Vec<MessagePart>>,
    /// How the turn ended, on the agent message that closed it.
    ///
    /// `None` while a turn is still in flight, or when the session died
    /// without a response to the prompt.
    pub stop: Option<StopReason>,
    /// Derived from a frame this client issued that the log has not yet
    /// confirmed: a prompt on the wire, a stop just pressed. Cleared when the
    /// confirmed frame folds in its place. Always false on the server's fold.
    pub pending: bool,
    /// When the log stored the prompt this user message came from. `None` on
    /// agent and control messages, on a prompt not stored yet, and on history
    /// a runtime replays on load, whose frames are as old as the load.
    pub posted_at: Option<DateTime<Utc>>,
}

impl FoldedMessage {
    /// The last prose part, trimmed; absent when the message has no prose.
    #[must_use]
    pub fn last_text(&self) -> Option<String> {
        self.parts
            .iter()
            .rev()
            .find_map(|part| match part {
                MessagePart::Text { text } => Some(text.trim()),
                _ => None,
            })
            .filter(|text| !text.is_empty())
            .map(str::to_owned)
    }

    /// This message's natural key within its session.
    #[must_use]
    pub fn id(&self) -> MessageId {
        MessageId {
            turn: self.id,
            author: self.author.kind(),
        }
    }
}

/// Who produced a [`FoldedMessage`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Type)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum Author {
    /// A person, via `session/prompt`.
    ///
    /// The id comes from the log row rather than the ACP payload, and is
    /// absent when the prompt was not attributed to a user.
    User {
        /// The attributed user's id.
        #[serde(rename = "userId")]
        #[specta(type = Option<String>)]
        user_id: Option<MacroUserIdStr<'static>>,
    },
    /// The agent.
    Agent,
}

impl Author {
    /// Which side of the conversation this author is, identity dropped.
    #[must_use]
    pub fn kind(&self) -> AuthorKind {
        match self {
            Self::User { .. } => AuthorKind::User,
            Self::Agent => AuthorKind::Agent,
        }
    }
}