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
//! 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(())
}
}