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.

6.5 KB
Raw Blame
//! The seam between the ACP surface and the agentic loop that serves it.

use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};

use agent::ReasoningEffort;
use agent::types::ChatMessage;
use agent::{AgentError, StreamPart};
use agent_api_keys::domain::UsableAgentKey;
use ai_tools::user_tool_review::UserToolReviewer;
use bot_id::BotId;
use mcp_toolset::RemoteMcpToolSet;
use model_owner::Owner;
use tokio::sync::mpsc;
use tokio_util::sync::CancellationToken;

use super::user_input::SharedUserInputRequester;

/// Who the agent is: the bot a session belongs to, by id and by name.
///
/// The name and handle go into the turn's system prompt so the model knows
/// who it is; the id and name also make the turn's tools act as that bot, so
/// what the agent writes is attributed to it - and presented under its name
/// wherever a reader sees the write happen, such as the cursor the editing
/// worker draws - rather than to Macro.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AgentIdentity {
    /// The bot the session belongs to.
    pub bot: BotId,
    /// Display name, e.g. `Grunk`.
    pub name: String,
    /// Stable `@` handle without a leading `@`, e.g. `grunk`.
    pub handle: String,
}

/// Everything one conversational turn needs.
pub struct TurnRequest {
    /// Whether the turn answers the user or condenses their conversation.
    pub purpose: TurnPurpose,
    /// How the session's reader receives the reply.
    pub delivery: ReplyDelivery,
    /// The session the turn belongs to.
    pub session_id: agent_session::domain::model::AgentSessionId,
    /// Counts what the turn is waiting on a person for - a question, or a
    /// tool call held for the owner - so the idle timeout leaves it be.
    pub awaiting: Arc<AwaitingUser>,
    /// The session's owner, whom the turn acts on behalf of: tools run with
    /// their identity and token usage is recorded against them. Both need a
    /// person, which the engine asks of this rather than assumes.
    pub owner: Owner,
    /// Model id the turn runs on. Unknown ids fall back to the loop's
    /// default model rather than failing the turn.
    pub model: String,
    /// Provider-independent effort selected for this session.
    pub reasoning_effort: ReasoningEffort,
    /// Inference speed applied without changing model or reasoning effort.
    pub speed: agent::ModelSpeed,
    /// Who this agent is. Folded into every turn's system prompt so the
    /// model can answer "who are you" even when the session has no
    /// instructions. `None` leaves the standing prompt unnamed.
    pub identity: Option<AgentIdentity>,
    /// The session's instructions, appended to the engine's own system
    /// prompt. `None` runs the engine's default prompt unchanged. For a
    /// [`TurnPurpose::Summary`] call, the whole system prompt.
    pub instructions: Option<String>,
    /// The full conversation, oldest first, ending with the prompt being
    /// answered.
    pub messages: Vec<ChatMessage>,
    /// Tools of the MCP servers the session was handed, composed next to the
    /// native Macro tools. `None` when the session has none.
    pub mcp_tools: Option<RemoteMcpToolSet>,
    /// Cancelling this token stops the turn; the stream ends after the
    /// engine has drained cooperatively.
    pub cancel: CancellationToken,
    /// User-input capability for model-callable tools. Absent when the ACP
    /// client did not advertise form elicitation.
    pub user_input: Option<SharedUserInputRequester>,
    /// Puts a user tool's call (`SendEmail`, `CreateCalendarEvent`) to the
    /// user for review mid-turn, so the tool is finished - run as edited, or
    /// rejected - before the model reads its result. Absent for the same
    /// reason as `user_input`; a pending call then stays pending.
    pub reviewer: Option<Arc<dyn UserToolReviewer>>,
    /// The agent's own key the turn's model calls run on instead of Macro's,
    /// with their usage recorded against it rather than the owner's
    /// allowance. `None` runs on Macro.
    pub agent_key: Option<UsableAgentKey>,
}

/// Whether a model call answers the user or condenses their conversation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TurnPurpose {
    /// A turn of the conversation, with the agent's tools.
    Conversation,
    /// A call that condenses the conversation for its continuation - its
    /// summary, or an image read for it. No tools, no memory, no opening
    /// line, and `instructions` as its whole system prompt.
    Summary,
}

/// How the session's reader receives a reply.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReplyDelivery {
    /// Live, as the model writes it, so a fast model's opening line shows
    /// long before the turn's own first token.
    Streamed,
    /// Only once the turn has finished, as one message (a reply posted to the
    /// thread of the message that mentioned the agent). An opening line would
    /// arrive with the rest, so none is written.
    Whole,
}

/// How many things a turn currently waits on a person for. Shared between
/// whatever is waiting (a question to the user, a tool call held for the
/// owner), which counts itself in, and the turn loop, which reads it to tell
/// "waiting on someone" from "hung".
#[derive(Debug, Default)]
pub struct AwaitingUser(AtomicUsize);

impl AwaitingUser {
    /// Whether anything is being waited on.
    #[must_use]
    pub fn is_waiting(&self) -> bool {
        self.0.load(Ordering::Acquire) > 0
    }

    /// Count one wait until the guard drops - on an answer, an error, or the
    /// waiting future being cancelled.
    pub fn begin(&self) -> AwaitingGuard<'_> {
        self.0.fetch_add(1, Ordering::AcqRel);
        AwaitingGuard(self)
    }
}

/// One wait, counted until dropped.
pub struct AwaitingGuard<'a>(&'a AwaitingUser);

impl Drop for AwaitingGuard<'_> {
    fn drop(&mut self) {
        self.0.0.fetch_sub(1, Ordering::AcqRel);
    }
}

/// Runs one conversational turn and streams its parts back.
///
/// The trait is the testing seam: the ACP surface is exercised against a
/// scripted engine, and production plugs in
/// [`crate::rig_engine::RigTurnEngine`].
pub trait TurnEngine: Send + Sync + 'static {
    /// Model ids this engine deployment can run and therefore advertises over
    /// ACP. The order is the picker order.
    fn supported_models(&self) -> &[&str];

    /// Start the turn. Parts arrive on the returned receiver; the stream
    /// ending is the turn ending, and an `Err` item is a turn-fatal failure.
    fn run_turn(&self, request: TurnRequest) -> mpsc::Receiver<Result<StreamPart, AgentError>>;
}