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.

51.5 KB
Raw Blame
//! Commands and values used by the harness domain.

use std::collections::HashSet;

use agent_client_protocol::schema::v1::{HttpHeader, McpServer as AcpMcpServer, McpServerHttp};
use agent_egress::domain::model::{
    CUSTOM_MCP_PATH_PREFIX, CustomMcpServerKey, CustomMcpServerListing, McpServerSlug, RepoSlug,
};
use agent_fold::domain::model::{StopReason, TurnSignal};
use agent_runtime_protocol::domain::action::{AgentAction, AgentActionId, PromptAttachment};
use agent_session::domain::model::{AgentMcpServers, AgentSessionId, MessageId, SandboxSize};
use agent_session::domain::ports::ControlEvent;
use agent_session::domain::session::PermissionPolicy;

#[cfg(test)]
mod test;
use bot_id::BotId;
use macro_user_id::user_id::MacroUserIdStr;
use macro_uuid::Uuid;
use messages::domain::events::MessageEventAttachment;
use trigger_context::TriggerContext;
mod current_time;
pub use current_time::CurrentTime;
mod session_origin;
pub use session_origin::{MentionOrigin, SessionOrigin, TaskAssignmentOrigin};
mod coding_preferences;
pub use coding_preferences::{
    CREATE_TASKS_INSTRUCTIONS, OPEN_PULL_REQUESTS_INSTRUCTIONS, with_coding_preferences,
};

/// How a channel message's attached files are named to an agent.
///
/// Channel attachments are stored by static file id; the agent needs a URL it
/// can fetch. The base URL is deployment configuration handed in by the
/// composition root, so this stays a pure translation.
#[derive(Debug, Clone)]
pub struct StaticFileLinks {
    base_url: String,
}

impl StaticFileLinks {
    /// Channel attachment entity type for an image stored as a static file.
    const STATIC_IMAGE: &str = "static/image";
    /// Channel attachment entity type for a video stored as a static file.
    const STATIC_VIDEO: &str = "static/video";
    /// How many files ride a prompt as ACP resource links. Matches the MCP
    /// channel-image budget so a long thread cannot flood the first turn.
    const MAX_PROMPT_ATTACHMENTS: usize = 8;

    /// Links under the static file service at `base_url`.
    #[must_use]
    pub fn new(base_url: impl Into<String>) -> Self {
        let mut base_url = base_url.into();
        while base_url.ends_with('/') {
            base_url.pop();
        }
        Self { base_url }
    }

    /// The prompt attachment for a static file, or `None` for one that is not
    /// a static file - documents reach the agent through mentions, and have
    /// no URL an agent could fetch unauthenticated.
    ///
    /// Channel rows record only that a file is an image or a video, not its
    /// exact type, so the media type is the matching wildcard range.
    #[must_use]
    fn file_link(&self, entity_type: &str, entity_id: &str) -> Option<PromptAttachment> {
        let (kind, mime_type) = match entity_type {
            Self::STATIC_IMAGE => ("image", "image/*"),
            Self::STATIC_VIDEO => ("video", "video/*"),
            _ => return None,
        };
        let uri = format!("{}/file/{}", self.base_url, entity_id);
        Some(PromptAttachment::new(uri, kind).mime_type(mime_type))
    }

    /// Files to send with a prompt: the mentioning message first, then the
    /// rest of its thread. Deduped by entity id and capped so a long thread
    /// cannot flood the first turn.
    #[must_use]
    pub fn prompt_attachments_for(
        &self,
        mention: &[MessageEventAttachment],
        context: Option<&TriggerContext>,
    ) -> Vec<PromptAttachment> {
        let mut seen = HashSet::new();
        let mut out = Vec::new();
        for attachment in mention {
            self.push_prompt_attachment(
                &mut out,
                &mut seen,
                &attachment.entity_type,
                &attachment.entity_id,
            );
        }
        if let Some(discussion) = context.and_then(TriggerContext::discussion) {
            for attachment in discussion.prompt_thread_attachments() {
                self.push_prompt_attachment(
                    &mut out,
                    &mut seen,
                    &attachment.entity_type,
                    &attachment.entity_id,
                );
            }
        }
        out
    }

    /// Give every static file in the trigger's discussion the URL the agent
    /// fetches it from, so the prompt XML can name it.
    pub fn link_context_attachments(&self, context: Option<&mut TriggerContext>) {
        let Some(discussion) = context.and_then(TriggerContext::discussion_mut) else {
            return;
        };
        for attachment in discussion.attachments_mut() {
            attachment.url = self
                .file_link(&attachment.entity_type, &attachment.entity_id)
                .map(|link| link.uri);
        }
    }

    fn push_prompt_attachment(
        &self,
        out: &mut Vec<PromptAttachment>,
        seen: &mut HashSet<String>,
        entity_type: &str,
        entity_id: &str,
    ) {
        if out.len() >= Self::MAX_PROMPT_ATTACHMENTS || seen.contains(entity_id) {
            return;
        }
        let Some(link) = self.file_link(entity_type, entity_id) else {
            return;
        };
        seen.insert(entity_id.to_owned());
        out.push(link);
    }
}

/// Open a new session for a mention or task assignment.
///
/// Only for managed sessions - the ones whose sandbox this deployment
/// provisions. External sessions are opened through
/// [`agent_session::domain::ports::SessionOpener`] instead: they
/// need no provisioning, no announcement, and no first prompt, so they are
/// a plain create rather than a harness command.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct OpenSession {
    /// The bot selected by the triggering event.
    pub bot_id: BotId,
    /// Runtime configuration resolved for this bot when the trigger arrived.
    pub runtime: AgentRuntimeConfig,
    /// The mention or assignment that requested the session.
    pub origin: SessionOrigin,
}

/// How a bot's sessions get a runtime — the closed set of first-party
/// providers, one name per member.
///
/// Legacy system bots derive this from their stable IDs. User and team agents
/// derive it from their persisted harness slug, which is also copied onto each
/// session so resume and teardown keep routing correctly after a restart.
///
/// A session's instructions are stored on its row whichever kind serves it.
/// [`Self::InMemory`] builds its system prompt from them in this process; every other
/// kind talks ACP or a prompt-only API, neither of which has a system prompt, so
/// they ride in the first prompt's hidden agent-context node instead. See
/// [`Self::folds_instructions`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum AgentKind {
    /// A sandbox this deployment provisions (Daytona, or local Docker when
    /// a developer has opted in).
    SandboxedCoder,
    /// A Cursor cloud agent, served over an in-process ACP pipe.
    Cursor,
    /// A per-owner Codex cloud conversation served over ACP.
    CodexCloud,
    /// The in-process (in-memory) Macro agent bot, served by `agent_inmem`.
    InMemory,
    /// The bot's operator hosts the runtime and dials the gateway; no
    /// deployment here provisions anything for it.
    External,
}

impl AgentKind {
    /// The kind of runtime serving `bot`'s sessions.
    #[must_use]
    pub fn of(bot: BotId) -> Self {
        if bot == bot_id::MACRO_CODER_BOT_ID {
            Self::SandboxedCoder
        } else if bot == bot_id::CURSOR_BOT_ID {
            Self::Cursor
        } else if bot == bot_id::CODEX_BOT_ID {
            Self::CodexCloud
        } else if bot == bot_id::MACRO_NEW_BOT_ID {
            Self::InMemory
        } else {
            Self::External
        }
    }

    /// Resolve a database-backed agent's runtime from its persisted harness.
    #[must_use]
    pub fn from_harness(harness: &str) -> Self {
        match harness {
            "cursor" => Self::Cursor,
            "codex-cloud" => Self::CodexCloud,
            "in-memory" | "macro-inmem" => Self::InMemory,
            // Registered macrod harnesses are the deliberate external case:
            // the agent's `harness_id` names whose daemon serves it.
            harness_id::MACROD_HARNESS_SLUG => Self::External,
            _ => Self::External,
        }
    }

    /// Resolve a persisted session's runtime without losing fixed system-bot
    /// identities that predate per-agent harness configuration.
    #[must_use]
    pub fn for_session(bot: BotId, harness: &str) -> Self {
        match Self::of(bot) {
            Self::External => Self::from_harness(harness),
            fixed => fixed,
        }
    }

    /// Fixed harness slug for kinds that map one-to-one onto one.
    ///
    /// Inverse of [`Self::from_harness`] for Cursor and Codex — a
    /// session of those bots is always stored under that slug, even when the
    /// open path fell through to a deployment default (`opencode`). The
    /// sandboxed coder's slug is deployment configuration, in-memory accepts
    /// both `in-memory` and `macro-inmem`, and an external runtime is whoever
    /// dialed in; those keep the slug the open path already chose.
    #[must_use]
    pub const fn harness_slug(self) -> Option<&'static str> {
        match self {
            Self::Cursor => Some("cursor"),
            Self::CodexCloud => Some("codex-cloud"),
            Self::SandboxedCoder | Self::InMemory | Self::External => None,
        }
    }

    /// Whether a session's instructions travel in its first prompt, for kinds
    /// whose runtime has no system prompt to put them in.
    #[must_use]
    pub const fn folds_instructions(self) -> bool {
        !matches!(self, Self::InMemory)
    }

    /// Whether this kind's runtime starts on the session row's model by itself.
    /// The others are sent a model chosen at creation over ACP, before their
    /// first prompt.
    #[must_use]
    pub const fn starts_on_session_model(self) -> bool {
        matches!(self, Self::InMemory | Self::Cursor)
    }

    /// Whether a deployment provisions this kind's runtimes itself.
    ///
    /// Membership is about who provisions, not whether *this* deployment is
    /// armed to — an unarmed deployment refuses a managed bot's sessions
    /// rather than waiting for a dial-in that can never come.
    #[must_use]
    pub fn is_managed(self) -> bool {
        !matches!(self, Self::External)
    }

    /// Whether this kind's agent is handed the session's whole egress server
    /// list ([`SandboxEgress::acp_servers`]) when it attaches - the list a
    /// live session is refreshed to when the owner's connections change.
    /// Codex Cloud is handed none. External runtimes receive the whole list
    /// through `SandboxEgressProvisioner::external_mcp_servers` when they bind,
    /// but do not participate in live refresh.
    #[must_use]
    pub fn takes_egress_mcp_servers(self) -> bool {
        !matches!(self, Self::CodexCloud | Self::External)
    }

    /// Whether this kind's sessions work in a repository.
    ///
    /// The runtime's nature, and what a persona is taken to be for until it
    /// says otherwise: how a mention is answered in its thread is the
    /// persona's choice ([`is_coding_agent`]), and this is the default for
    /// one that has not chosen and the answer for the fixed system bots. A
    /// coding runtime runs for minutes and produces diffs, so its turn is
    /// announced as a magic chip - a live portal into the session. The
    /// in-memory runtime has no repository and chats, so its thread gets a
    /// pending reply that becomes the answer when the turn ends, the way the
    /// original Macro bot replied.
    #[must_use]
    pub const fn is_coding(self) -> bool {
        !matches!(self, Self::InMemory)
    }

    /// How this kind's sessions answer permission requests without a registered
    /// local harness.
    ///
    /// Managed runtimes act inside sandboxes this deployment owns (or, for
    /// Cursor, never ask), so approving on arrival costs nothing. An external
    /// runtime is somebody's own machine, where a bot approving its own tool
    /// calls is exactly what a person should be asked about.
    #[must_use]
    pub fn default_permission_policy(self) -> PermissionPolicy {
        match self {
            Self::SandboxedCoder | Self::Cursor | Self::CodexCloud | Self::InMemory => {
                PermissionPolicy::AutoAccept
            }
            Self::External => PermissionPolicy::Prompt,
        }
    }
}

/// Whether a session's turns are announced as a coding agent's.
///
/// A persona's setting is the source of truth. The fixed system bots have no
/// persona and so no setting; `choice` is `None` for them alone, and the
/// runtime's nature ([`AgentKind::is_coding`]) decides.
#[must_use]
pub const fn is_coding_agent(choice: Option<bool>, kind: AgentKind) -> bool {
    match choice {
        Some(chosen) => chosen,
        None => kind.is_coding(),
    }
}

/// The persona a session's thread replies speak as, read from its bot at
/// the moment of speaking.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReplyPersona {
    /// The bot's display name, what a link to the session is labelled.
    pub name: String,
    /// Whether the turn is announced as a magic chip (coding) or answered
    /// as a reply in the thread (chat); see [`is_coding_agent`].
    pub is_coding: bool,
}

/// Stored facts used by the domain to choose a session permission policy.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum PermissionPolicyConfig {
    /// A fixed system bot with no editable persona configuration.
    Fixed(AgentKind),
    /// An editable persona and its harness operator's limit.
    Persona {
        /// The runtime serving this persona.
        kind: AgentKind,
        /// A registered harness's opt-in. `None` denotes a built-in runtime.
        harness_allows_bypass: Option<bool>,
        /// The agent owner's choice for a local harness; absent means prompt.
        auto_accept_permissions: Option<bool>,
    },
}

impl PermissionPolicyConfig {
    /// Apply local harness consent and agent choice, or the built-in policy.
    #[must_use]
    pub fn resolve(self) -> PermissionPolicy {
        match self {
            Self::Fixed(kind) => kind.default_permission_policy(),
            Self::Persona {
                kind,
                harness_allows_bypass,
                auto_accept_permissions,
            } => match harness_allows_bypass {
                Some(allowed) => resolve_permission_policy(allowed, auto_accept_permissions),
                None => kind.default_permission_policy(),
            },
        }
    }
}

/// Resolve a persona's choice within the harness operator's permission limit.
#[must_use]
pub fn resolve_permission_policy(
    allow_bypass: bool,
    auto_accept: Option<bool>,
) -> PermissionPolicy {
    if allow_bypass && auto_accept == Some(true) {
        PermissionPolicy::AutoAccept
    } else {
        PermissionPolicy::Prompt
    }
}

/// Runtime settings used to open one database-backed or fixed agent.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct AgentRuntimeConfig {
    /// Which runtime implementation serves the agent.
    pub kind: AgentKind,
    /// Model stamped onto the new session.
    pub model: String,
    /// Harness slug stamped onto the new session.
    pub harness: String,
    /// Configured agent instructions, snapshotted onto each new session's row
    /// so a mention opens with the same system prompt the create menu does.
    pub instructions: String,
    /// Which Pipedream MCP servers the agent's sessions are handed.
    pub mcp_servers: AgentMcpServers,
}

/// Whether a user belongs to the Macro staff domain - the egress crate's
/// predicate, reused so the harness's staff gates and the proxy's can never
/// disagree about who staff is.
pub(crate) use agent_egress::domain::model::is_macro_staff;

/// Where a prompt came from, when it came from somewhere the session should
/// answer back into.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ReplyPlacement {
    /// Answer inside the source discussion, the behavior of existing mentions.
    #[default]
    Thread,
    /// Answer in the channel's main timeline, as an agent conversing there does.
    Timeline,
}

impl ReplyPlacement {
    /// Whether this is the default placement used by existing serialized origins.
    pub fn is_thread(&self) -> bool {
        *self == Self::Thread
    }

    /// Convert a source root to the message API's optional reply target.
    pub fn thread_id(self, root: Uuid) -> Option<Uuid> {
        match self {
            Self::Thread => Some(root),
            Self::Timeline => None,
        }
    }

    /// How a turn answered here is shown.
    pub fn voice_style(self) -> VoiceStyle {
        match self {
            Self::Thread => VoiceStyle::Turn,
            Self::Timeline => VoiceStyle::Segments,
        }
    }
}

/// How an agent's reply is shown where it was asked.
///
/// The same turn reads either way; what differs is how many messages it
/// takes. A thread carries one reply per mention, so the reply is one message
/// that grows. A private conversation reads like talking to a teammate, so
/// each passage the agent writes is its own message as soon as it is
/// finished, with the steps it took to get there; while it works, its typing
/// row says what it is doing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum VoiceStyle {
    /// One message per turn, posted when the turn starts and updated in place.
    Turn,
    /// One message per passage, posted when the passage is finished; nothing
    /// is posted until the agent has something to say.
    Segments,
}

/// One message of an agent's reply, as it should read now.
///
/// The domain decides which segments a message shows and whether it is
/// news; the announcer chooses the words around them and composes the
/// nodes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReplyPresentation {
    /// The session the reply speaks for.
    pub session_id: AgentSessionId,
    /// The bot the session speaks as; the message is posted as it.
    pub bot_id: BotId,
    /// Who prompted the turn; the bot writes on their current capability.
    pub triggered_by: MacroUserIdStr<'static>,
    /// Where the reply is shown.
    pub parent: messages::domain::models::MessageParent,
    /// The thread it is shown in; `None` for a timeline.
    pub thread_id: Option<Uuid>,
    /// The message's id, allocated before it is first posted so posting it
    /// again finds the same message.
    pub message_id: Uuid,
    /// The turn the segments belong to.
    pub turn: agent_fold::domain::model::TurnId,
    /// The segments the message shows, in order.
    pub segments: Vec<agent_fold::domain::model::ProjectedSegment>,
    /// Lead with a link to the session.
    pub link: bool,
    /// Show that the turn is still running after the segments.
    pub pending: bool,
    /// How the turn ended, on the reply's last message once it has.
    pub outcome: Option<ReplyOutcome>,
    /// Whether this update is news: the reply's last message, once the turn
    /// has ended.
    pub notify: bool,
}

/// An agent session typing through the bot that speaks for it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AgentTypingUpdate {
    /// The session whose turn is running.
    pub session_id: AgentSessionId,
    /// The bot the session speaks as.
    pub bot_id: BotId,
    /// Who prompted the turn; the bot types on their current capability.
    pub triggered_by: MacroUserIdStr<'static>,
    /// Where the reply will appear.
    pub parent: messages::domain::models::MessageParent,
    /// The thread it will appear in; `None` for a timeline.
    pub thread_id: Option<Uuid>,
    /// Whether the agent is typing.
    pub active: bool,
    /// What the agent is doing.
    pub phase: agent_fold::domain::model::TurnPhase,
}

/// Source message and placement of one agent response.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct AnnounceOrigin {
    /// Ordinary mentions reply in a thread; agent conversations answer in the timeline.
    #[serde(default, skip_serializing_if = "ReplyPlacement::is_thread")]
    pub reply_placement: ReplyPlacement,
    /// Update the existing agent response instead of posting a reply.
    #[serde(default)]
    pub reuse_origin_message: bool,
    /// Channel or document the prompt was posted in.
    pub parent: messages::domain::models::MessageParent,
    /// Thread the announcement replies into.
    pub thread_id: Uuid,
    /// The message that triggered the prompt.
    pub message_id: Uuid,
}

/// Whose access a session runs with, and who sent the prompt being composed.
///
/// Named to the agent on every prompt so it can tell the session's owner
/// from anyone else who may drive it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PromptPeople {
    /// The session's owner.
    pub owner: MacroUserIdStr<'static>,
    /// The prompt's sender; absent when a bot sent it on nobody's behalf.
    pub sender: Option<MacroUserIdStr<'static>>,
}

/// Do something in a session that already exists.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct DeliverAction {
    /// The id the action carries onto the wire, minted when it was accepted.
    /// A reconnect-and-retry resends under the same id.
    pub id: AgentActionId,
    /// What the agent is being asked to do.
    pub action: AgentAction,
    /// The user responsible, absent when nobody in particular is.
    pub actor: Option<MacroUserIdStr<'static>>,
    /// Where to announce this, for prompts that arrived from elsewhere.
    ///
    /// `None` means "do not announce": either the caller drove the session
    /// directly, so there is nowhere else to answer, or the action is not the
    /// kind anyone announces. A prompt posted into the session's own dedicated
    /// channel passes `Some`, and is still suppressed - the harness only
    /// learns the session's channel when it runs.
    pub announce: Option<AnnounceOrigin>,
    /// Why the agent is being asked, rendered ahead of a prompt. Absent for
    /// prompts driven from the session itself.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub context: Option<TriggerContext>,
}

/// One operation executed by the harness for an agent session.
///
/// Create, act, destroy. Everything that happens *within* a session's life is
/// a [`DeliverAction`], because the differences that used to justify separate
/// commands - whether to reconnect a dead session, whether to announce - are
/// properties of the action and its origin, not of the request that carried
/// it.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub enum HarnessCommand {
    /// Drain durable system events when this session is idle.
    DrainNotifications,
    /// Open or continue the durably reserved session of an agent's conversation.
    ConversationMessage(OpenSession),
    /// Persist a nonblocking tool card on the replica owning this session.
    PresentTool {
        /// Authenticated session owner.
        actor: MacroUserIdStr<'static>,
        /// Stable component identity and presentation payload.
        presentation: agent_session::domain::model::SessionToolPresentation,
    },
    /// Open a new session.
    Open(OpenSession),
    /// Act on a session that already exists.
    Deliver(DeliverAction),
    /// Replace a queued prompt's text before it dispatches.
    EditQueued {
        /// The queue entry to edit.
        action_id: AgentActionId,
        /// The new raw prompt text.
        prompt: String,
        /// The user responsible, judged by the same gates as sending: whoever
        /// may not prompt a session may not rewrite what it is about to be
        /// prompted with.
        actor: Option<MacroUserIdStr<'static>>,
    },
    /// Remove a queued action before it dispatches.
    RemoveQueued {
        /// The queue entry to remove.
        action_id: AgentActionId,
        /// The user responsible, as on [`Self::EditQueued`].
        actor: Option<MacroUserIdStr<'static>>,
    },
    /// Run a queued action next: move it to the front and, when a turn is in
    /// flight, cancel that turn so this entry flushes ahead of the rest.
    SteerQueued {
        /// The queue entry to run next.
        action_id: AgentActionId,
        /// The user responsible, as on [`Self::EditQueued`].
        actor: Option<MacroUserIdStr<'static>>,
    },
    /// The session's fold reported a turn fact: an ended turn clears the
    /// busy mark and dispatches the next queued action; a raised or cleared
    /// question is published as is. Internal - enqueued by the turn observer
    /// on the managing replica, never forwarded.
    Turn(TurnSignal),
    /// The session's live actor stopped: clear the busy mark and nothing
    /// more - resuming a dead runtime stays the next user action's job.
    /// Internal, like [`Self::Turn`].
    SessionStopped {
        /// Why the actor stopped.
        reason: String,
    },
    /// A tool call in the session's running turn started or stopped waiting
    /// for the owner's approval. Sent by the approval service from whichever
    /// replica held the call, and forwarded to the one managing the session,
    /// since that is where the turn's reply is known.
    ToolApproval(ToolApprovalChange),
    /// Change the session's sandbox size and the owner's default.
    SetSandboxSize(SandboxSize),
    /// Release a session's live resources and delete it.
    Delete,
    /// Load an external session whose agent is still running on a runtime
    /// that dialed in again, so its local activity reaches Macro without a
    /// prompt. Internal: the runtime registry asks for these on each dial.
    Reattach,
}

/// What executing a command did with it, beyond succeeding.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CommandOutcome {
    /// The command ran to completion - for a deliver, the action reached the
    /// runtime.
    Completed,
    /// The action waits in the session's queue for the running turn to end.
    Queued,
}

impl DeliverAction {
    /// A prompt from a user, arriving from a channel that may need answering.
    ///
    /// Takes the action rather than its text so a prompt's attached files
    /// ride along; `AgentAction::prompt(text)` is the plain-text form.
    pub fn prompt(
        action: AgentAction,
        actor: Option<MacroUserIdStr<'static>>,
        announce: Option<AnnounceOrigin>,
    ) -> Self {
        Self {
            id: AgentActionId::mint(),
            action,
            actor,
            announce,
            context: None,
        }
    }

    /// A control request under a caller-visible id: the caller's own id when
    /// it named one, so its optimistic entry is confirmed in place, and a
    /// freshly minted id otherwise. Names no origin: control is "deliver this
    /// to the session", and announcing a prompt into its channel is the
    /// trigger pipeline's job, keyed on what it observed rather than anything
    /// a caller claims.
    pub fn control(event: ControlEvent) -> Self {
        Self {
            id: event.action_id.unwrap_or_else(AgentActionId::mint),
            action: event.action,
            actor: event.actor,
            announce: None,
            context: event.context,
        }
    }
}

/// Announce a prompt an external runtime delivers itself.
///
/// For a mention in an external session's thread, the trigger pipeline fans
/// out twice: the bot's runtime gets the webhook and sends the prompt through
/// the control endpoint, and this posts the magic-chip message the replies
/// render into. Split that way because each side is the only one that can
/// do its half honestly: only the runtime can reach its harness, and only
/// the observed trigger event can vouch for the conversation context.
#[derive(Debug, Clone)]
pub struct AnnouncePrompt {
    /// The bot the trigger named; must match the session row before posting.
    pub bot_id: BotId,
    /// Where the mention was posted.
    pub origin: AnnounceOrigin,
    /// The mention's text, shown in the announcement's reply target.
    pub content: String,
    /// Who mentioned the bot.
    pub sender: MacroUserIdStr<'static>,
}

/// Facts required to announce one prompt into its originating context.
#[derive(Debug, Clone)]
pub struct SessionAnnouncement {
    /// Preallocated reply id for a durably journaled conversation turn.
    pub reply_message_id: Option<Uuid>,
    /// Whether the answer is a thread reply or a top-level channel message.
    pub reply_placement: ReplyPlacement,
    /// Update the existing agent response instead of posting a reply.
    pub reuse_origin_message: bool,
    /// Agent session represented by the announcement.
    pub session_id: AgentSessionId,
    /// The bot the session runs for; the announcement posts as it.
    pub bot_id: BotId,
    /// Whether the bot is a coding agent (see [`is_coding_agent`]). Assignment
    /// announcements always use a session link, regardless of the bot's kind.
    pub is_coding: bool,
    /// Channel or document containing the mention that opened the session.
    pub origin_parent: messages::domain::models::MessageParent,
    /// Thread where the announcement should be posted.
    pub origin_thread_id: Uuid,
    /// Channel message targeted by the announcement.
    pub origin_message_id: Uuid,
    /// Folded user message that prompts the anchored agent response.
    pub prompted_message_id: MessageId,
    /// Text of the prompting message, shown in the reply target.
    pub prompted_content: String,
    /// User whose mention triggered the announcement.
    pub triggered_by: MacroUserIdStr<'static>,
}

impl SessionAnnouncement {
    /// Assignments and coding agents link to the session; only a chat mention
    /// starts a pending reply that will copy the answer into the discussion.
    pub(crate) const fn shows_session_link(&self) -> bool {
        self.is_coding || self.reuse_origin_message
    }
}

/// Something the mentioner has to set up before their provider will open a
/// session for them - the one class of refusal that is theirs to fix, so
/// it is answered in the thread rather than logged.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SessionBlocker {
    /// `@cursor` runs on the mentioner's own Cursor account, and they have
    /// not registered a key in settings yet.
    CursorNotConnected,
    /// The mentioner has not connected their ChatGPT account for Codex.
    CodexNotConnected,
    /// Codex is connected, but no cloud environment has been selected.
    CodexEnvironmentNotConfigured,
}

/// A mention that opened no session, and why. Posted back into the mention's
/// thread as the bot, so the person who asked learns what to do next instead
/// of watching a chip that never answers.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DeclinedMention {
    /// The bot that was mentioned; the reply posts as it.
    pub bot_id: BotId,
    /// Where the mention was posted, and so where the reply goes.
    pub origin: AnnounceOrigin,
    /// Who mentioned the bot.
    pub triggered_by: MacroUserIdStr<'static>,
    /// What stands between them and a session.
    pub blocker: SessionBlocker,
}

/// The message an announcement became.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AnnouncedMessage {
    /// The posted message: a coding agent's magic chip, or a chat agent's
    /// pending reply.
    pub message_id: Uuid,
}

/// What a turn's reply in the thread that prompted it should say now.
///
/// Mostly how the turn ended. Text wins whenever there is any: an agent that
/// wrote something and was then cancelled or cut off still said it, and the
/// thread would rather read that than a notice. The rest distinguish the
/// silences a reader can act on differently - try again, or not.
///
/// Three are not ends at all. A turn that asks the user something through an
/// ACP elicitation is held open until someone answers it in the session
/// view, and one whose tool call waits on the owner's approval is held until
/// the owner answers; a thread showing a spinner has no way of knowing
/// either. So the reply says so ([`Self::NeedsInput`],
/// [`Self::AwaitingApproval`]) and returns to pending once nothing is
/// waiting ([`Self::Resumed`]).
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ReplyOutcome {
    /// The agent answered; its last message, whole.
    Answered(String),
    /// The turn ran to its end without saying anything.
    Empty,
    /// The turn was cancelled before it finished: a stop, or a follow-up in
    /// the thread that steered the session onto a new prompt.
    Cancelled,
    /// The runtime refused the prompt or died underneath the turn.
    Failed,
    /// The turn is waiting on a question only the session view can answer.
    NeedsInput {
        /// What the agent is asking, in prose.
        question: String,
    },
    /// A tool call is held until the session's owner approves it.
    AwaitingApproval(HeldToolCall),
    /// The question was answered or withdrawn, or every held tool call was
    /// settled, and the turn is running again.
    Resumed,
}

/// A tool call held for the session owner's approval, as far as the thread
/// is told about it.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct HeldToolCall {
    /// The approval row; what its settling names.
    pub approval_id: String,
    /// `macro`, or the connected app's slug.
    pub server_slug: String,
    /// What a person calls the server the tool is on.
    pub server_name: String,
    /// The tool called.
    pub tool_name: String,
}

/// How a session's held tool calls changed.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum ToolApprovalChange {
    /// A call started waiting for the owner.
    Held(HeldToolCall),
    /// The call was approved, denied, cancelled, or expired.
    Settled {
        /// The approval that settled.
        approval_id: String,
    },
}

impl ReplyOutcome {
    /// The outcome of a turn the fold closed with `stop`, whose last text
    /// part was `last_text`.
    #[must_use]
    pub fn of_turn(stop: &StopReason, last_text: Option<String>) -> Self {
        match last_text.filter(|text| !text.trim().is_empty()) {
            Some(text) => Self::Answered(text),
            None => match stop {
                StopReason::Cancelled => Self::Cancelled,
                StopReason::Failed { .. } => Self::Failed,
                StopReason::EndTurn
                | StopReason::MaxTokens
                | StopReason::MaxTurnRequests
                | StopReason::Refusal
                | StopReason::Other { .. } => Self::Empty,
            },
        }
    }
}

/// Facts required to replace a turn's pending reply with what it should say.
///
/// Modelled on [`SessionAnnouncement`], which posted the message this
/// resolves: the same bot posts, on the same person's current capability
/// to the same parent, so a mentioner who has since lost access to the
/// thread gets nothing patched in their name either.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedReply {
    /// The session whose turn the reply speaks for; what the reply links to.
    pub session_id: AgentSessionId,
    /// The bot the session runs for; the patch is made as it.
    pub bot_id: BotId,
    /// Whether the session's bot is a coding agent. A coding agent's chip
    /// renders the turn itself, so there is nothing to resolve for one.
    pub is_coding: bool,
    /// The pending reply posted when the turn was announced.
    pub message_id: Uuid,
    /// Channel or document the mention was posted in.
    pub origin_parent: messages::domain::models::MessageParent,
    /// Who prompted the turn.
    pub triggered_by: MacroUserIdStr<'static>,
    /// What the reply should say now.
    pub outcome: ReplyOutcome,
    /// The turn the reply answers.
    pub turn: agent_fold::domain::model::TurnId,
    /// The reply's segments, when this replica watched the turn run: the
    /// passages and steps the reply shows. Empty when it did not, and the
    /// reply is then told from `outcome` alone.
    pub segments: Vec<agent_fold::domain::model::ProjectedSegment>,
}

/// Values required to provision a new session container.
#[derive(Debug, Clone)]
pub struct SpawnContainer {
    /// Session that will own the container transport.
    pub session_id: AgentSessionId,
    /// Which provider serves this session — the routing decision itself,
    /// resolved by the emitter from the session's bot. Routing is the only
    /// thing spawn ever consumed the bot for; resume and teardown re-derive
    /// the same kind from the session row's bot.
    pub kind: AgentKind,
    /// Compute tier to request from the provider.
    pub size: SandboxSize,
    /// How the sandbox reaches anything outside itself.
    ///
    /// Carries the repository implicitly: the sandbox clones from the proxy,
    /// which reads the repository off the session's own grant, so no provider
    /// needs to be told what it is.
    pub egress: SandboxEgress,
}

/// Everything a sandbox needs to make an authenticated outbound call, and
/// nothing more.
///
/// The sandbox runs model-authored code with every permission allowed, so
/// whatever is in here has been handed to the model. That is why it is one
/// short-lived session token and a URL rather than any upstream credential:
/// the credentials stay in the egress proxy, which stamps them on as requests
/// pass through.
///
/// The MCP servers are carried as data rather than any provider's rendered
/// config, because two consumers speak two dialects of it: an ACP agent gets
/// them in `session/new` through [`SandboxEgress::acp_servers`], and a Cursor
/// cloud agent gets the same servers through Cursor's own API. One source,
/// two renderings, nothing to drift.
#[derive(Clone)]
pub struct SandboxEgress {
    /// Base URL of the egress proxy, as the sandbox should dial it.
    pub base_url: String,
    /// The session token, presented on every proxied call.
    pub session_token: String,
    /// The MCP servers to advertise, by the slug the proxy resolves: the
    /// owner's connected apps, or the agent's selected apps whether or not
    /// the owner has connected them. Macro's own server is not listed: every
    /// session has it, on its own route.
    pub mcp_servers: Vec<McpServerSlug>,
    /// The owner's own MCP servers - the ones added by URL under "Custom
    /// MCP" - by the key the proxy resolves. The sandbox never sees a
    /// server's URL or credential; both stay behind the key.
    pub custom_servers: Vec<CustomMcpServerListing>,
}

/// Where the sandbox finds the egress proxy.
///
/// Named here rather than written inline because the name is shared knowledge
/// with the container: `container/ensure_ready.sh` reads it to build the git
/// remote it clones from. Like `provision::SIDECAR_PORT`, the agreement between
/// the two is held by a test rather than by comment.
pub const EGRESS_URL_VARIABLE: &str = "MACRO_EGRESS_URL";

/// The session token the sandbox presents on every proxied call. Shared with
/// `container/ensure_ready.sh` on the same terms as [`EGRESS_URL_VARIABLE`].
pub const SESSION_TOKEN_VARIABLE: &str = "MACRO_SESSION_TOKEN";

/// The name every session's server list gives Macro's own MCP server.
///
/// Purely a display name now - resolution happens by route, not by name - but
/// kept short and stable because agents namespace tool names under it.
pub const MACRO_MCP_NAME: &str = "macro";

/// Harness-owned session tools, separate from the workspace MCP catalog.
pub const INTERNAL_MCP_NAME: &str = "macro_internal";

impl SandboxEgress {
    /// Where the proxy serves `slug` - the URL a client dials to reach that
    /// server, whichever client it is.
    pub fn mcp_url(&self, slug: &McpServerSlug) -> String {
        format!("{}/mcp/{slug}", self.base_url)
    }

    /// Where the proxy serves Macro's own MCP server: its own route, so no
    /// connected app's slug can ever name it.
    pub fn macro_mcp_url(&self) -> String {
        format!("{}/mcp-macro", self.base_url)
    }

    /// Where the proxy serves the owner's custom server behind `key`.
    pub fn custom_mcp_url(&self, key: &CustomMcpServerKey) -> String {
        format!("{}{CUSTOM_MCP_PATH_PREFIX}{key}", self.base_url)
    }

    /// The `Authorization` value presented on every proxied call.
    pub fn authorization_header(&self) -> String {
        format!("Bearer {}", self.session_token)
    }

    /// The session token [`Self::acp_servers`] stamped on `servers`, read
    /// back off the internal server every rendering of the list carries.
    pub fn session_token_in(servers: &[AcpMcpServer]) -> Option<String> {
        servers.iter().find_map(|server| match server {
            AcpMcpServer::Http(server) if server.name == INTERNAL_MCP_NAME => server
                .headers
                .iter()
                .find(|header| header.name.eq_ignore_ascii_case("authorization"))
                .and_then(|header| header.value.strip_prefix("Bearer "))
                .map(str::to_owned),
            _ => None,
        })
    }

    /// The sandbox environment this becomes.
    ///
    /// Unsized on purpose: a third variable should be one more line here and
    /// nothing at any call site.
    pub fn environment(&self) -> impl IntoIterator<Item = (String, String)> {
        [
            (EGRESS_URL_VARIABLE.to_owned(), self.base_url.clone()),
            (
                SESSION_TOKEN_VARIABLE.to_owned(),
                self.session_token.clone(),
            ),
        ]
    }

    /// The workspace and internal MCP servers, followed by the owner's apps
    /// and then the owner's custom servers, as `(name, url)` pairs.
    ///
    /// The one enumeration behind both renderings - [`Self::acp_servers`] and
    /// the Cursor API's - so the two can never advertise different sets.
    ///
    /// Every name is unique and non-empty, because the runtimes key servers
    /// by name and refuse a list that repeats one. App slugs already are; a
    /// custom server's name is whatever the owner typed, so it is reduced to
    /// the characters tool namespaces tolerate and, if that still collides
    /// with an earlier entry, suffixed with a piece of its key.
    pub fn server_entries(&self) -> impl Iterator<Item = (String, String)> + '_ {
        let mut entries: Vec<(String, String)> = vec![
            (MACRO_MCP_NAME.to_owned(), self.macro_mcp_url()),
            (
                INTERNAL_MCP_NAME.to_owned(),
                format!("{}/mcp/internal", self.base_url),
            ),
            (
                "macro-preview".to_owned(),
                format!("{}/mcp-preview", self.base_url),
            ),
        ];
        entries.extend(
            self.mcp_servers
                .iter()
                .map(|slug| (slug.as_str().to_owned(), self.mcp_url(slug))),
        );
        for listing in &self.custom_servers {
            let name = unique_server_name(&listing.name, &listing.key, &entries);
            entries.push((name, self.custom_mcp_url(&listing.key)));
        }
        entries.into_iter()
    }

    /// Session-scoped internal tools, also supplied to external runtimes.
    pub fn internal_mcp_server(&self) -> AcpMcpServer {
        AcpMcpServer::Http(
            McpServerHttp::new(INTERNAL_MCP_NAME, format!("{}/mcp/internal", self.base_url))
                .headers(vec![HttpHeader::new(
                    "Authorization",
                    self.authorization_header(),
                )]),
        )
    }

    /// Preview-only MCP endpoint, authenticated by the same session credential.
    pub fn preview_mcp_server(&self) -> AcpMcpServer {
        AcpMcpServer::Http(
            McpServerHttp::new("macro-preview", format!("{}/mcp-preview", self.base_url)).headers(
                vec![HttpHeader::new(
                    "Authorization",
                    self.authorization_header(),
                )],
            ),
        )
    }

    /// The MCP servers an ACP agent is handed in `session/new`, `session/load`
    /// and `session/resume`.
    ///
    /// Every server is HTTP transport pointed at the egress proxy, never at
    /// the server itself, and carries the session token - the sandbox holds
    /// no upstream credential to point anywhere with.
    pub fn acp_servers(&self) -> Vec<AcpMcpServer> {
        self.server_entries()
            .map(|(name, url)| {
                AcpMcpServer::Http(McpServerHttp::new(name, url).headers(vec![HttpHeader::new(
                    "Authorization",
                    self.authorization_header(),
                )]))
            })
            .collect()
    }
}

/// A minted egress environment and the hash that has to be stored for it to
/// work.
///
/// The two halves go to different places and must not be confused: the raw
/// token in [`ProvisionedEgress::sandbox`] is handed to the container, and
/// [`ProvisionedEgress::session_token_hash`] is what the session row keeps so
/// the proxy can recognize it. Returned together because the row has to be
/// written before the container that holds the token exists.
#[derive(Debug, Clone)]
pub struct ProvisionedEgress {
    /// SHA-256 hex of the session token, for the session row.
    pub session_token_hash: String,
    /// The environment the sandbox is spawned with, carrying the raw token.
    pub sandbox: SandboxEgress,
}

/// The name a custom server is advertised under among `taken` entries.
///
/// Owner-typed names are reduced to `[A-Za-z0-9_-]`, which is what agents
/// accept in a tool namespace, and an empty result reads as `custom`. A name
/// that then matches an earlier entry gets a key suffix, so two servers the
/// owner named alike stay distinguishable and neither can shadow Macro's own.
fn unique_server_name(name: &str, key: &CustomMcpServerKey, taken: &[(String, String)]) -> String {
    const DEFAULT_NAME: &str = "custom";
    const KEY_SUFFIX_LEN: usize = 8;

    let mut sanitized: String = name
        .trim()
        .chars()
        .map(|character| {
            if character.is_ascii_alphanumeric() || matches!(character, '_' | '-') {
                character
            } else {
                '_'
            }
        })
        .collect();
    if sanitized.is_empty() {
        sanitized = DEFAULT_NAME.to_owned();
    }
    let is_taken = |candidate: &str| taken.iter().any(|(existing, _)| existing == candidate);
    if !is_taken(&sanitized) {
        return sanitized;
    }
    let key = key.as_str();
    let suffixed = format!("{sanitized}_{}", &key[..KEY_SUFFIX_LEN.min(key.len())]);
    if !is_taken(&suffixed) {
        return suffixed;
    }
    format!("{sanitized}_{key}")
}

impl std::fmt::Debug for SandboxEgress {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
            .debug_struct("SandboxEgress")
            .field("base_url", &self.base_url)
            .field("session_token", &"[REDACTED]")
            .field("mcp_servers", &self.mcp_servers)
            .field("custom_servers", &self.custom_servers)
            .finish()
    }
}

/// The repository a deployment's sessions work in, valid by construction.
///
/// Held as the URL a session's row carries, not as the [`RepoSlug`] it was
/// read as: the row is what the egress proxy re-reads to decide which
/// repository a sandbox's git traffic may reach, so the URL is the value
/// that has to survive. Parsing is what makes it a repository rather than a
/// string - a URL that names no repository could only fail later, at a clone
/// nobody is watching - and the parse is the proxy's own.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionRepository(String);

impl SessionRepository {
    /// Read a configured GitHub URL as the repository it names.
    ///
    /// [`None`] for a URL that names no repository. That is a deployment
    /// misconfiguration, and the composition root is where it should be
    /// refused: every session this deployment would go on to open carries it.
    #[must_use]
    pub fn parse(repository_url: &str) -> Option<Self> {
        RepoSlug::parse_github_url(repository_url)?;
        Some(Self(repository_url.to_owned()))
    }

    /// The URL, as a session's row carries it.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

/// One repository a user can reach through Macro's GitHub App.
///
/// What a chooser offers and what the open path authorizes against: the url
/// is the value a session's row is pinned to, and the default branch is where
/// a session starts when its caller selected the repository but no branch.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ReachableRepository {
    /// The canonical `https://github.com/owner/name` url.
    pub url: String,
    /// The branch a clone checks out, absent for a repository with no commits.
    pub default_branch: Option<String>,
}

/// Session-row values that remain deployment configuration for now.
#[derive(Debug, Clone)]
pub struct SessionDefaults {
    /// The bot managed sessions run as.
    ///
    /// Configuration rather than a constant for the same reason as the
    /// trigger path's: `@claude` and `@codex` are separate deployments of one
    /// binary, differing only in the bot they answer for.
    pub bot_id: BotId,
    /// Model slug, e.g. `claude`.
    pub model: String,
    /// Harness slug, e.g. `opencode`.
    pub harness: String,
    /// Repository this bot's sessions open against, or [`None`] for a bot
    /// whose sessions do not learn one until they run.
    ///
    /// A Codex cloud session is the latter: it works in whatever repository
    /// its cloud environment holds, which is not known until the environment
    /// resolves, and the row is written then (see
    /// `CodexRuntime::resolve_target`). Seeding the row with a deployment
    /// default would make it briefly claim a repository the session will
    /// never touch.
    pub repo_url: Option<SessionRepository>,
}

/// Session defaults for every bot a deployment answers for.
///
/// One deployment can serve more than one managed bot (the sandboxed coder
/// bot and the in-process Macro bot), and each stamps different defaults onto
/// the sessions it opens.
#[derive(Debug, Clone)]
pub struct HarnessDefaults {
    default: SessionDefaults,
    per_bot: Vec<(BotId, SessionDefaults)>,
    managed_bot: Option<BotId>,
}

impl HarnessDefaults {
    /// Defaults every bot shares until one is given its own.
    #[must_use]
    pub fn new(default: SessionDefaults) -> Self {
        Self {
            default,
            per_bot: Vec::new(),
            managed_bot: None,
        }
    }

    /// Stamp `bot`'s sessions with `defaults` instead of the shared ones.
    #[must_use]
    pub fn with_bot(mut self, bot: BotId, defaults: SessionDefaults) -> Self {
        self.per_bot.push((bot, defaults));
        self
    }

    /// Open managed sessions - the ones nothing names a bot for, like the
    /// create menu's - as `bot` instead of the deployment's own.
    #[must_use]
    pub fn with_managed_bot(mut self, bot: BotId) -> Self {
        self.managed_bot = Some(bot);
        self
    }

    /// The defaults a session opens with when no particular bot is named -
    /// the `with_managed_bot` override when one is set, the deployment's own
    /// bot otherwise.
    #[must_use]
    pub fn managed(&self) -> &SessionDefaults {
        match self.managed_bot {
            Some(bot) => self.for_bot(bot),
            None => &self.default,
        }
    }

    /// The defaults `bot`'s sessions are stamped with.
    #[must_use]
    pub fn for_bot(&self, bot: BotId) -> &SessionDefaults {
        self.per_bot
            .iter()
            .find(|(candidate, _)| *candidate == bot)
            .map_or(&self.default, |(_, defaults)| defaults)
    }
}

impl From<SessionDefaults> for HarnessDefaults {
    fn from(default: SessionDefaults) -> Self {
        Self::new(default)
    }
}