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.

17.1 KB
Raw Blame
//! The per-session queue of turn-occupying actions.
//!
//! Prompts (and compaction) occupy a whole agent turn, and ACP runs one turn
//! at a time - so while a turn runs, further turn-occupying actions wait here
//! rather than interleaving on the wire. Entries hold the *raw* user text:
//! composition happens at dispatch, which is what makes a queued prompt
//! editable and gives it fresh channel context when it actually runs. The
//! chip is usually announced then too, except a channel follow-up that
//! steers a running turn: it goes to the front and posts its chip when it is
//! accepted, so the reply sits on the follow-up rather than after the
//! cancelled turn or behind work queued earlier.
//!
//! The live replica keeps this working copy beside the session's actor so
//! edits and dispatch stay serialized on the command worker. Every mutation
//! is written through to the session store as it happens; resume (and the
//! first local command after a restart) restores that row. An in-flight
//! turn is still process-local.
//!
//! Callers mutate this only from the session's command worker, which is what
//! serializes an edit against the dispatch that might be claiming the same
//! entry. The structure itself only promises per-call consistency.

use std::collections::VecDeque;

use agent_fold::domain::model::TurnId;
use agent_runtime_protocol::domain::action::{AgentAction, AgentActionId};
use agent_session::domain::events::{InFlightTurnSummary, TurnSummary};
use agent_session::domain::model::AgentSessionId;
use agent_session::domain::model::PrompterKind;
use agent_session::domain::model::StoredQueuedAction;
use agent_session::domain::ports::QueuedControl;
use bot_id::BotId;
use chrono::{DateTime, Utc};
use dashmap::DashMap;
use macro_user_id::user_id::MacroUserIdStr;
use macro_uuid::Uuid;
use trigger_context::TriggerContext;

use super::model::{AnnounceOrigin, HeldToolCall};

#[cfg(test)]
mod test;

/// How many actions one session may hold queued. Far above any real
/// conversation; a backstop against a runaway bot caller, not a product
/// limit.
const QUEUE_CAP: usize = 50;

/// One action waiting to dispatch.
#[derive(Debug, Clone)]
pub struct QueuedEntry {
    /// The id the action was accepted under - the queue's key, the wire's
    /// request id, and the folded message's `request_id` once dispatched.
    pub action_id: AgentActionId,
    /// What to deliver, carrying raw prompt text (see module docs).
    pub action: AgentAction,
    /// The user who queued it, absent when a bot acted on nobody's behalf.
    pub actor: Option<MacroUserIdStr<'static>>,
    /// Where to announce the prompt at dispatch, when it came from somewhere
    /// the session should answer back into.
    pub announce: Option<AnnounceOrigin>,
    /// Why the agent is being asked, composed into the prompt at dispatch.
    pub context: Option<TriggerContext>,
    /// The chip message, once posted. Set by the dispatch that posts it and
    /// carried through a requeue, so a dispatch that fails *after*
    /// announcing retries without posting a second chip.
    pub announced: Option<Uuid>,
    /// When it was accepted.
    pub created_at: DateTime<Utc>,
}

/// The turn a session is running: what the busy mark remembers once the
/// queued entry has been consumed by dispatch.
///
/// In-memory like the queue: a restart mid-turn forgets it, and that turn's
/// end is then observed without a record. `turn` is the fold's next turn id
/// at dispatch, which for a compaction (no user message) is the turn the
/// fold would assign to the next prompt.
#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct InFlightTurn {
    /// The action that opened the turn.
    pub action_id: AgentActionId,
    /// Position in the session's log.
    pub turn: TurnId,
    /// The user who prompted it, absent when a bot acted on nobody's behalf.
    pub actor: Option<MacroUserIdStr<'static>>,
    /// Where the prompt came from, when it came from somewhere the session
    /// answers back into. Kept so the turn's end can speak into the same
    /// thread the announcement did.
    pub announce: Option<AnnounceOrigin>,
    /// The message posted when this turn was announced, when one was. For a
    /// coding agent that is the chip the turn renders into; for a chat agent
    /// it is the pending reply the turn's end resolves (see
    /// [`SessionAnnouncer::resolve`](super::ports::SessionAnnouncer::resolve)).
    /// Downstream events carry it under this name for both.
    pub announcement_message_id: Option<Uuid>,
    /// When delivery named this turn. What a prompt parked behind it, or
    /// an idle check that keeps finding it, reports as the turn's age: a
    /// turn hours old with nothing streaming is the shape of a wedged
    /// session, and without this it looks exactly like a long one.
    pub dispatched_at: DateTime<Utc>,
    /// The bot the session speaks as, for the turn's typing and reply
    /// messages. Absent on a turn recorded before it was kept.
    #[serde(default)]
    pub bot_id: Option<BotId>,
    /// Whether the turn was announced as a session chip (a coding agent or an
    /// assignment), which renders the turn itself: its message is never
    /// rewritten into a reply.
    #[serde(default)]
    pub speaks_as_chip: bool,
    /// The messages a reply shown in segments is posted as, in order. Each id
    /// is allocated, and saved with the turn, before the message is first
    /// posted, so showing the reply again updates the same messages.
    #[serde(default)]
    pub presented: Vec<Uuid>,
    /// Tool calls this turn made that wait on the owner's approval, oldest
    /// first. The reply names the oldest while any wait.
    #[serde(default)]
    pub held_tool_calls: Vec<HeldToolCall>,
}

impl InFlightTurn {
    /// How long this turn has been in flight.
    #[must_use]
    pub fn age(&self) -> chrono::Duration {
        Utc::now().signed_duration_since(self.dispatched_at)
    }

    /// This turn as a session that died underneath it reports it.
    #[must_use]
    pub fn summary(&self) -> InFlightTurnSummary {
        InFlightTurnSummary {
            turn: self.turn,
            action_id: self.action_id,
            actor: self.actor.clone(),
            announcement_message_id: self.announcement_message_id,
        }
    }

    /// This turn as a settled session reports it.
    #[must_use]
    pub fn ended(self, stop_reason: String, excerpt: Option<String>) -> TurnSummary {
        TurnSummary {
            turn: self.turn,
            action_id: self.action_id,
            actor: self.actor,
            announcement_message_id: self.announcement_message_id,
            stop_reason,
            excerpt,
        }
    }
}

impl From<&QueuedEntry> for QueuedControl {
    fn from(entry: &QueuedEntry) -> Self {
        Self {
            action_id: entry.action_id,
            action: entry.action.clone(),
            actor: entry.actor.clone(),
            created_at: entry.created_at,
        }
    }
}

impl QueuedEntry {
    /// Who the turn this entry opens acts for: a system turn acts for nobody,
    /// even when the batch names a user.
    pub fn prompter_kind(&self) -> PrompterKind {
        if matches!(&self.action, AgentAction::Prompt(prompt) if prompt.notifications.as_ref().is_some_and(|input| input.system_turn))
        {
            PrompterKind::System
        } else {
            PrompterKind::User
        }
    }

    /// The person who typed this prompt into the session itself, from the
    /// session view or the API: a human prompt with no thread to announce
    /// into and no trigger behind it. A mention in a channel, document or call
    /// thread carries its origin (`announce`), and a runtime forwarding a
    /// triggered prompt carries its `context`; neither counts. A tool that
    /// prompts on a person's behalf with no trigger counts as theirs.
    /// Following a session is what lists a hidden one for this person.
    pub fn direct_prompter(&self) -> Option<&MacroUserIdStr<'static>> {
        let typed = matches!(self.action, AgentAction::Prompt(_))
            && self.prompter_kind() == PrompterKind::User
            && self.announce.is_none()
            && self.context.is_none();
        self.actor.as_ref().filter(|_| typed)
    }

    /// The durable form written to the session store.
    pub fn to_stored(&self) -> anyhow::Result<StoredQueuedAction> {
        Ok(StoredQueuedAction {
            action_id: self.action_id,
            action: self.action.clone(),
            actor: self.actor.clone(),
            created_at: self.created_at,
            announce: self
                .announce
                .as_ref()
                .map(serde_json::to_value)
                .transpose()?,
            announced_message_id: self.announced,
            context: self.context.clone(),
        })
    }

    /// Rebuild the working-copy entry from a persisted row.
    pub fn from_stored(stored: StoredQueuedAction) -> anyhow::Result<Self> {
        Ok(Self {
            action_id: stored.action_id,
            action: stored.action,
            actor: stored.actor,
            announce: stored.announce.map(serde_json::from_value).transpose()?,
            announced: stored.announced_message_id,
            context: stored.context,
            created_at: stored.created_at,
        })
    }
}

/// Why the queue refused a mutation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum QueueError {
    /// No entry under this id - it dispatched, was removed, or never existed.
    /// One answer for all three: the caller's entry is not waiting anymore,
    /// and which way it left is not knowable from here.
    NotFound,
    /// The entry exists but carries no editable text.
    NotEditable,
    /// The session already holds [`QUEUE_CAP`] entries.
    Full,
}

/// Every session's waiting actions, FIFO per session.
#[derive(Debug, Default)]
pub struct SessionQueues {
    queues: DashMap<AgentSessionId, VecDeque<QueuedEntry>>,
}

impl SessionQueues {
    /// An empty set of queues.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Append an entry to its session's queue.
    pub fn enqueue(&self, session: AgentSessionId, entry: QueuedEntry) -> Result<(), QueueError> {
        self.insert(session, entry, VecDeque::push_back)
    }

    /// Recover a conversation's durable admission order even when broker deliveries arrive out of order.
    pub fn enqueue_chronological(
        &self,
        session: AgentSessionId,
        entry: QueuedEntry,
    ) -> Result<(), QueueError> {
        self.insert(session, entry, |queue, entry| {
            let key = |entry: &QueuedEntry| {
                (
                    entry.created_at,
                    entry.announce.as_ref().map(|origin| origin.message_id),
                )
            };
            let index = queue
                .iter()
                .position(|queued| key(queued) > key(&entry))
                .unwrap_or(queue.len());
            queue.insert(index, entry);
        })
    }

    /// Put an entry ahead of everything already waiting, for a channel
    /// follow-up that steers the running turn: it runs next, not after work
    /// that was queued before it.
    pub fn enqueue_front(
        &self,
        session: AgentSessionId,
        entry: QueuedEntry,
    ) -> Result<(), QueueError> {
        self.insert(session, entry, VecDeque::push_front)
    }

    fn insert(
        &self,
        session: AgentSessionId,
        entry: QueuedEntry,
        push: fn(&mut VecDeque<QueuedEntry>, QueuedEntry),
    ) -> Result<(), QueueError> {
        let mut queue = self.queues.entry(session).or_default();
        if queue.len() >= QUEUE_CAP {
            return Err(QueueError::Full);
        }
        push(&mut queue, entry);
        Ok(())
    }

    /// Take the oldest waiting entry, if any.
    pub fn claim_next(&self, session: AgentSessionId) -> Option<QueuedEntry> {
        let mut queue = self.queues.get_mut(&session)?;
        let entry = queue.pop_front();
        if queue.is_empty() {
            drop(queue);
            // Second look under the map's own lock: an enqueue may have
            // landed between the drop and the removal, and `remove_if` is
            // what keeps this from discarding it.
            self.queues.remove_if(&session, |_, queue| queue.is_empty());
        }
        entry
    }

    /// Put a claimed entry back at the front, for a dispatch that failed
    /// with nobody waiting on it - the entry stays next in line.
    pub fn requeue_front(&self, session: AgentSessionId, entry: QueuedEntry) {
        self.queues.entry(session).or_default().push_front(entry);
    }

    /// Everything waiting for this session, oldest first.
    #[must_use]
    pub fn list(&self, session: AgentSessionId) -> Vec<QueuedControl> {
        self.queues
            .get(&session)
            .map(|queue| queue.iter().map(QueuedControl::from).collect())
            .unwrap_or_default()
    }

    /// Whether this entry is still waiting.
    #[must_use]
    pub fn contains(&self, session: AgentSessionId, action_id: AgentActionId) -> bool {
        self.queues
            .get(&session)
            .is_some_and(|queue| queue.iter().any(|entry| entry.action_id == action_id))
    }

    /// Remember that this entry's chip has been posted, so dispatch does not
    /// announce it a second time.
    pub fn mark_announced(
        &self,
        session: AgentSessionId,
        action_id: AgentActionId,
        message_id: Uuid,
    ) -> Result<(), QueueError> {
        let mut queue = self.queues.get_mut(&session).ok_or(QueueError::NotFound)?;
        let entry = queue
            .iter_mut()
            .find(|entry| entry.action_id == action_id)
            .ok_or(QueueError::NotFound)?;
        entry.announced = Some(message_id);
        Ok(())
    }

    /// Replace a queued prompt's text. The entry keeps its place and its id.
    ///
    /// `actor` becomes the entry's actor: the user who rewrote the text is
    /// who later dispatch announces and logs as, so an edit cannot keep
    /// someone else's name on words they did not type.
    pub fn edit_prompt(
        &self,
        session: AgentSessionId,
        action_id: AgentActionId,
        prompt: String,
        actor: Option<MacroUserIdStr<'static>>,
    ) -> Result<(), QueueError> {
        let mut queue = self.queues.get_mut(&session).ok_or(QueueError::NotFound)?;
        let entry = queue
            .iter_mut()
            .find(|entry| entry.action_id == action_id)
            .ok_or(QueueError::NotFound)?;
        match &mut entry.action {
            AgentAction::Prompt(action) => {
                action.prompt = prompt;
                entry.actor = actor;
                Ok(())
            }
            AgentAction::SetModel(_)
            | AgentAction::SetConfigOption(_)
            | AgentAction::Compact
            | AgentAction::Stop
            | AgentAction::RespondElicitation(_)
            | AgentAction::RespondToPermission(_) => Err(QueueError::NotEditable),
        }
    }

    /// Forget a session's queue wholesale - for a session that is being
    /// deleted, whose entries will never dispatch.
    pub fn drop_session(&self, session: AgentSessionId) {
        self.queues.remove(&session);
    }

    /// Everything waiting, as the working-copy entries.
    #[must_use]
    pub fn snapshot(&self, session: AgentSessionId) -> Vec<QueuedEntry> {
        self.queues
            .get(&session)
            .map(|queue| queue.iter().cloned().collect())
            .unwrap_or_default()
    }

    /// Replace a session's working copy, used when hydrating from the store.
    pub fn replace(&self, session: AgentSessionId, entries: Vec<QueuedEntry>) {
        if entries.is_empty() {
            self.queues.remove(&session);
        } else {
            self.queues.insert(session, entries.into());
        }
    }

    /// Move a waiting entry to the front, so a steer runs it next.
    ///
    /// An entry that is already next is left where it is. Missing entries are
    /// [`QueueError::NotFound`], the same answer as an edit of something that
    /// already dispatched.
    pub fn move_to_front(
        &self,
        session: AgentSessionId,
        action_id: AgentActionId,
    ) -> Result<(), QueueError> {
        let mut queue = self.queues.get_mut(&session).ok_or(QueueError::NotFound)?;
        let position = queue
            .iter()
            .position(|entry| entry.action_id == action_id)
            .ok_or(QueueError::NotFound)?;
        if position == 0 {
            return Ok(());
        }
        let Some(entry) = queue.remove(position) else {
            return Err(QueueError::NotFound);
        };
        queue.push_front(entry);
        Ok(())
    }

    /// Remove a waiting entry.
    pub fn remove(
        &self,
        session: AgentSessionId,
        action_id: AgentActionId,
    ) -> Result<(), QueueError> {
        let mut queue = self.queues.get_mut(&session).ok_or(QueueError::NotFound)?;
        let position = queue
            .iter()
            .position(|entry| entry.action_id == action_id)
            .ok_or(QueueError::NotFound)?;
        queue.remove(position);
        if queue.is_empty() {
            drop(queue);
            self.queues.remove_if(&session, |_, queue| queue.is_empty());
        }
        Ok(())
    }
}