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 imperative shell around [`SessionMachine`]: executes one input's
//! effects at a time.
//!
//! [`SessionActor`] owns the machine, the transport, and the log handle for
//! one connection. It never decides anything - it pulls one input, hands it
//! to the machine, and executes the returned effects in order. An effect that
//! fails to execute voids the rest of its batch and feeds [`Input::Closed`]
//! back into the machine, so a `Complete` never fires for an action that was
//! not sent.
//!
//! Stepping is the caller's choice: production spawns a "step until stopped"
//! loop (see [`super::super::service`]), while tests exercise its input and
//! dispatch halves directly.
use std::{collections::VecDeque, sync::Arc, time::Duration};
use agent_client_protocol::RawJsonRpcMessage;
use agent_client_protocol::schema::v1::{McpServer, SessionId};
use agent_runtime_protocol::domain::action::{AgentAction, AgentActionId};
use agent_runtime_protocol::domain::schema::v0::{
AcpMessage, SystemEvent, ToRuntimeMessage, ToServerMessage,
};
use macro_user_id::user_id::MacroUserIdStr;
use tokio::sync::{mpsc, oneshot, watch};
use tokio::time::Instant;
use tracing::Instrument as _;
use crate::domain::error::{AgentSessionError, Result};
use crate::domain::model::{AgentSessionId, AgentSessionLog, Message};
use agent_runtime_protocol::domain::ports::{TransportReceiver, TransportSender};
use crate::domain::ports::{
AgentConnector, AgentSessionLogWriter, AgentSessionRepo, SessionToolCatalog,
SessionTurnObserver,
};
use agent_fold::domain::model::TurnSignal;
use super::telemetry::GenAiProjector;
use super::{
CloseReason, Effect, HandshakeStatus, Input, PermissionPolicy, RuntimeStatus, SessionMachine,
StopReason,
};
/// How long the ACP handshake has to finish before the session is declared dead.
const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(60);
/// How long one caller's action has to reach the runtime.
const COMMAND_DELIVERY_TIMEOUT: Duration = Duration::from_secs(60);
/// How long the session's MCP servers have to list their tools for telemetry
/// before the listing is given up on. Off the actor's own path, so generous.
const TOOL_LISTING_TIMEOUT: Duration = Duration::from_secs(60);
/// A caller's request to deliver one action, and the wire back to them.
pub(crate) struct SessionCommand {
pub(crate) user_id: Option<MacroUserIdStr<'static>>,
pub(crate) action: AgentAction,
pub(crate) action_id: AgentActionId,
pub(crate) completed: oneshot::Sender<Result<()>>,
pub(crate) span: tracing::Span,
pub(crate) enqueued_at: Instant,
}
/// What reaches a session's actor through its command channel. One channel,
/// so a server change and the prompt behind it arrive in the order sent.
pub(crate) enum SessionMessage {
/// Persist a tool card without waiting for the current turn to complete.
PresentTool {
presentation: crate::domain::model::SessionToolPresentation,
completed: oneshot::Sender<Result<()>>,
},
/// Deliver an action.
Action(SessionCommand),
/// Hand the agent these MCP servers from now on.
ReplaceMcpServers(Vec<McpServer>),
/// Answer the agent's permission requests this way from now on.
SetPermissionPolicy(PermissionPolicy),
}
/// An actor-owned operation or an input to the runtime protocol machine.
pub(crate) enum ActorInput {
Protocol(Input<SessionCompletion>),
PresentTool {
presentation: crate::domain::model::SessionToolPresentation,
completed: oneshot::Sender<Result<()>>,
},
}
pub(crate) struct SessionCompletion {
completed: oneshot::Sender<Result<()>>,
span: tracing::Span,
/// When the command was dequeued, if the runtime was not live yet.
dequeued_before_live: Option<Instant>,
}
/// Whether a [`SessionActor`] has more steps to take.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum Stepped {
/// Keep stepping.
Continue,
/// The machine stopped for this reason; clean up.
Stopped(StopReason),
}
/// One session connection's imperative shell: pulls one input, runs the
/// machine, and executes the effects - nothing else.
pub(crate) struct SessionActor<Connector: AgentConnector, Logs> {
machine: SessionMachine<SessionCompletion>,
initialization_request: Option<ToRuntimeMessage>,
initialization_response: Option<ToServerMessage>,
/// The carrier's halves. Sending is shared with whoever else is on the
/// same connection; receiving is this actor's alone, which is why it can
/// be read with `&mut` and needs no lock.
outbound: Connector::Sender,
inbound: Connector::Receiver,
logs: Logs,
commands: mpsc::Receiver<SessionMessage>,
/// This connection's handshake gate: published to when this session runs
/// the handshake, watched for when another session runs it.
handshake: watch::Sender<HandshakeStatus>,
handshake_seen: watch::Receiver<HandshakeStatus>,
/// The span covering the handshake, dropped once the runtime is live or
/// dead. Every effect run before then hangs off it.
handshake_span: Option<tracing::Span>,
handshake_deadline: Instant,
/// Told when the machine reports a turn over, so the harness can dispatch
/// its next queued prompt, and when the runtime reports its session
/// deliberately closed.
turn_observer: Arc<dyn SessionTurnObserver>,
/// GenAI spans for the turns and tool calls this connection carries, fed
/// every frame the effects below send or log. See [`super::telemetry`].
telemetry: GenAiProjector,
/// Lists the session's MCP tools once the connection is live, for the
/// projector's `gen_ai.tool.definitions`.
tool_catalog: Arc<dyn SessionToolCatalog>,
/// The servers to list, as the machine sends them on `session/new`.
mcp_servers: Vec<McpServer>,
/// Whether the listing has been started; it runs once per connection.
tools_listed: bool,
}
impl<Connector, Logs> SessionActor<Connector, Logs>
where
Connector: AgentConnector,
Logs: AgentSessionLogWriter + AgentSessionRepo,
{
// One argument per fact the actor owns; a struct here would only move the
// same list one level down.
#[allow(clippy::too_many_arguments)]
pub(crate) fn new(
id: AgentSessionId,
acp_session_id: Option<SessionId>,
workspace: String,
mcp_servers: Vec<McpServer>,
permission_policy: PermissionPolicy,
connector: Connector,
logs: Logs,
commands: mpsc::Receiver<SessionMessage>,
handshake: watch::Sender<HandshakeStatus>,
turn_observer: Arc<dyn SessionTurnObserver>,
tool_catalog: Arc<dyn SessionToolCatalog>,
) -> Self {
// Marked unseen so the first wait reports the *current* state rather
// than only later changes: a session binding after the handshake
// finished would otherwise wait for an announcement already made.
let mut handshake_seen = handshake.subscribe();
handshake_seen.mark_changed();
let (outbound, inbound) = connector.split();
let handshake_span = tracing::info_span!(
"agent.acp.handshake",
agent.session.id = %id,
otel.status_code = tracing::field::Empty,
otel.status_description = tracing::field::Empty,
);
Self {
initialization_request: None,
initialization_response: None,
outbound,
inbound,
handshake_seen,
handshake,
machine: match acp_session_id {
None => SessionMachine::new(id, workspace, mcp_servers.clone(), permission_policy),
Some(session_id) => SessionMachine::resume(
id,
session_id,
workspace,
mcp_servers.clone(),
permission_policy,
),
}
.with_connection_context(macro_uuid::generate_uuid_v7()),
logs,
commands,
handshake_span: Some(handshake_span),
handshake_deadline: Instant::now() + HANDSHAKE_TIMEOUT,
turn_observer,
telemetry: GenAiProjector::new(
id,
genai_telemetry::ContentPolicy::from_env(),
Default::default(),
),
tool_catalog,
mcp_servers,
tools_listed: false,
}
}
/// Apply an explicit starting model before a new session becomes live.
pub(crate) fn with_initial_model(mut self, model: Option<String>) -> Self {
self.machine = self.machine.with_initial_model(model);
self
}
/// The session this actor's connection belongs to.
pub(crate) fn id(&self) -> AgentSessionId {
self.machine.id()
}
/// Refuse further commands, so a caller cannot enqueue into an actor that
/// will never step again.
pub(crate) fn close(&mut self) {
self.commands.close();
}
/// Wait for the next input without mutating protocol state. Keeping this
/// separate from dispatch lets shutdown cancel the wait, never an effect
/// batch after the machine has already advanced.
pub(crate) async fn next_input(&mut self) -> ActorInput {
loop {
let handshake_deadline = self.handshake_deadline;
let handshake_timeout = async {
if matches!(
self.machine.status(),
RuntimeStatus::Booting | RuntimeStatus::Handshaking
) {
tokio::time::sleep_until(handshake_deadline).await;
} else {
std::future::pending::<()>().await;
}
};
let log_flush_deadline = self.logs.flush_deadline();
let log_flush_due = async {
match log_flush_deadline {
Some(deadline) => tokio::time::sleep_until(deadline).await,
None => std::future::pending().await,
}
};
let input = tokio::select! {
() = handshake_timeout => Input::Closed(CloseReason::HandshakeTimedOut),
// Buffered log frames have waited long enough; write them out. A
// failed flush is a failed log write, and the machine decides
// what that means, same as a failed append.
() = log_flush_due => match self.logs.flush().await {
Ok(()) => continue,
Err(error) => {
tracing::error!(
error = ?error,
id = %self.machine.id(),
"agent session failed to flush buffered log frames"
);
Input::Closed(CloseReason::LogFailed)
}
},
command = self.commands.recv() => match command {
Some(SessionMessage::PresentTool { presentation, completed }) => {
return ActorInput::PresentTool { presentation, completed };
},
Some(SessionMessage::ReplaceMcpServers(servers)) => Input::ReplaceMcpServers(servers),
Some(SessionMessage::SetPermissionPolicy(policy)) => Input::SetPermissionPolicy(policy),
Some(SessionMessage::Action(SessionCommand { user_id, action, action_id, completed, span, enqueued_at })) => {
span.record(
"agent.command.queue_wait_ms",
elapsed_ms(enqueued_at),
);
let status = self.machine.status();
span.record("agent.session.runtime_phase_at_dequeue", status.as_ref());
let dequeued_before_live = (!matches!(status, RuntimeStatus::Live { .. }))
.then(Instant::now);
Input::Command {
from: user_id,
action,
action_id,
token: SessionCompletion { completed, span, dequeued_before_live },
}
},
// The service dropped every handle; nobody can reach us.
None => Input::Closed(CloseReason::Abandoned),
},
// A handshake somebody else ran. The machine ignores it unless it
// is still booting, which is what makes the session that ran the
// handshake ignore its own result coming back.
Ok(()) = self.handshake_seen.changed() => match self.handshake_seen.borrow_and_update().clone() {
HandshakeStatus::ReadyWithContext { restore, context } => Input::SharedReady { restore, context },
// Nothing to act on yet, but the wait must resume.
HandshakeStatus::Pending | HandshakeStatus::InFlight => continue,
},
inbound = self.inbound.recv() => match inbound {
Ok(Some(message)) => Input::Inbound(message),
Ok(None) => Input::Closed(CloseReason::TransportClosed),
Err(error) => {
tracing::error!(error = ?error, id = %self.machine.id(), "agent session transport failed");
Input::Closed(CloseReason::TransportFailed)
}
},
};
return ActorInput::Protocol(input);
}
}
/// Complete actor-owned writes outside the cancellable input wait.
pub(crate) async fn dispatch_input(&mut self, input: ActorInput) -> Stepped {
match input {
ActorInput::Protocol(input) => self.dispatch(input).await,
ActorInput::PresentTool {
presentation,
completed,
} => {
let RuntimeStatus::Live { session_id, .. } = self.machine.status() else {
let _ = completed.send(Err(AgentSessionError::Disconnected(self.machine.id())));
return Stepped::Continue;
};
let result = self
.logs
.present_tool(self.machine.id(), session_id, presentation)
.await
.inspect_err(|error| {
tracing::error!(
error = ?error,
id = %self.machine.id(),
"agent session failed to persist a tool presentation"
);
});
let failed = result.is_err();
let _ = completed.send(result);
if failed {
self.dispatch(Input::Closed(CloseReason::LogFailed)).await
} else {
Stepped::Continue
}
}
}
}
/// Run the machine and execute its effects in order. An effect that fails
/// to execute voids the rest of its batch and feeds [`Input::Closed`]
/// back in - so a `Complete` never fires for an action that was not sent,
/// and the machine (not this loop) decides what failure means.
pub(crate) async fn dispatch(&mut self, input: Input<SessionCompletion>) -> Stepped {
let was_live = matches!(self.machine.status(), RuntimeStatus::Live { .. });
let mut handshake_span = self.handshake_span.clone();
let produced = match &handshake_span {
Some(span) => span.in_scope(|| self.machine.handle(input)),
None => self.machine.handle(input),
};
let mut effects = VecDeque::from(produced);
if was_live && matches!(self.machine.status(), RuntimeStatus::Handshaking) {
self.handshake_deadline = Instant::now() + HANDSHAKE_TIMEOUT;
}
let handshake_deadline = self.handshake_deadline;
self.finish_handshake_if_complete();
if self.handshake_span.is_none() {
handshake_span = None;
}
let mut stepped = Stepped::Continue;
while let Some(effect) = effects.pop_front() {
match effect {
Effect::Send { from, mut message } => {
let command_span = effects.front().and_then(|effect| match effect {
Effect::Complete { token, .. } => {
token.span.record(
"agent.command.handshake_wait_ms",
token.dequeued_before_live.map_or(0, elapsed_ms),
);
Some(token.span.clone())
}
_ => None,
});
// Before delivery, so the turn's span starts when the
// prompt leaves. A delivery that fails closes the
// connection, which ends the turn in error below.
self.telemetry
.on_outbound(&mut message, command_span.as_ref());
let delivery = self.deliver(from, message);
let (result, close_reason) =
match (command_span.as_ref(), handshake_span.as_ref()) {
(Some(span), _) => match tokio::time::timeout(
COMMAND_DELIVERY_TIMEOUT,
delivery.instrument(span.clone()),
)
.await
{
Ok(result) => (result, CloseReason::SendFailed),
Err(_) => (
Err(AgentSessionError::DeliveryTimedOut(self.machine.id())),
CloseReason::SendFailed,
),
},
(None, Some(span)) => match tokio::time::timeout_at(
handshake_deadline,
delivery.instrument(span.clone()),
)
.await
{
Ok(result) => (result, CloseReason::SendFailed),
Err(_) => (
Err(AgentSessionError::Handshake(format!(
"timed out after {} seconds",
HANDSHAKE_TIMEOUT.as_secs()
))),
CloseReason::HandshakeTimedOut,
),
},
(None, None) => {
match tokio::time::timeout(COMMAND_DELIVERY_TIMEOUT, delivery).await
{
Ok(result) => (result, CloseReason::SendFailed),
Err(_) => (
Err(AgentSessionError::DeliveryTimedOut(self.machine.id())),
CloseReason::SendFailed,
),
}
}
};
if let Err(error) = result {
if let Some(span) = command_span {
span.record("otel.status_code", "ERROR");
span.record("otel.status_description", tracing::field::display(&error));
}
tracing::error!(
error = ?error,
id = %self.machine.id(),
"agent session failed to deliver an action"
);
self.fail_remaining_completions(&mut effects, error);
effects.extend(self.machine.handle(Input::Closed(close_reason)));
self.finish_handshake_if_complete();
}
}
Effect::Log { message, boundary } => {
self.telemetry.on_inbound(&message);
if let Some(ToRuntimeMessage::Acp(AcpMessage(RawJsonRpcMessage::Request(
request,
)))) = &self.initialization_request
&& let ToServerMessage::Acp(AcpMessage(frame)) = &message
&& frame.response_id() == Some(&request.id)
{
self.initialization_response = Some(message.clone());
}
let log = self.logs.append_with_boundary(
AgentSessionLog {
agent_session_id: self.machine.id(),
user_id: None,
content: Message::ToServer(message),
logged_at: None,
},
boundary,
);
let (result, close_reason) = match handshake_span.as_ref() {
Some(span) => match tokio::time::timeout_at(
handshake_deadline,
log.instrument(span.clone()),
)
.await
{
Ok(result) => (result, CloseReason::LogFailed),
Err(_) => (
Err(AgentSessionError::Handshake(format!(
"timed out after {} seconds",
HANDSHAKE_TIMEOUT.as_secs()
))),
CloseReason::HandshakeTimedOut,
),
},
None => match tokio::time::timeout(COMMAND_DELIVERY_TIMEOUT, log).await {
Ok(result) => (result, CloseReason::LogFailed),
Err(_) => (
Err(AgentSessionError::LogTimedOut(self.machine.id())),
CloseReason::LogFailed,
),
},
};
match result {
Ok(appended) => self.forward_signals(appended.signals),
Err(error) => {
tracing::error!(
error = ?error,
id = %self.machine.id(),
"agent session failed to persist an inbound message"
);
self.fail_remaining_completions(&mut effects, error);
effects.extend(self.machine.handle(Input::Closed(close_reason)));
self.finish_handshake_if_complete();
}
}
}
Effect::EstablishInitialization { context } => {
let establish = async {
let id = self
.logs
.append(AgentSessionLog {
agent_session_id: self.machine.id(),
user_id: None,
content: Message::ToRuntime(context.request.clone()),
logged_at: None,
})
.await?
.log_id;
self.machine.initialization_persisted(id);
self.log(None, Message::ToServer(context.response.clone()))
.await
};
let result = tokio::time::timeout_at(handshake_deadline, establish)
.await
.unwrap_or_else(|_| Err(AgentSessionError::LogTimedOut(self.machine.id())));
if let Err(error) = result {
tracing::error!(
error = ?error,
id = %self.machine.id(),
"agent session failed to persist its shared initialization"
);
self.fail_remaining_completions(&mut effects, error);
effects.extend(self.machine.handle(Input::Closed(CloseReason::LogFailed)));
}
}
Effect::PersistAcpSession { session_id } => {
let result = tokio::time::timeout(
COMMAND_DELIVERY_TIMEOUT,
self.persist_acp_session(session_id),
)
.await
.unwrap_or_else(|_| Err(AgentSessionError::LogTimedOut(self.machine.id())));
if let Err(error) = result {
tracing::error!(
error = ?error,
id = %self.machine.id(),
"agent session failed to persist its ACP session id"
);
effects.clear();
effects.extend(self.machine.handle(Input::Closed(CloseReason::LogFailed)));
}
}
Effect::Initialized { restore } => {
let request = self
.initialization_request
.as_ref()
.expect("initialization request persisted before its response");
let response = self
.initialization_response
.as_ref()
.expect("Initialized follows logging the matching response");
// The actor retains a receiver, so publication cannot fail.
let _ = self.handshake.send(HandshakeStatus::ReadyWithContext {
restore,
context: std::sync::Arc::new(super::InitializationContext {
request: request.clone(),
response: response.clone(),
}),
});
}
Effect::Complete { token, result } => {
if let Err(error) = &result {
token.span.record("otel.status_code", "ERROR");
token
.span
.record("otel.status_description", tracing::field::display(error));
}
let _ = token.completed.send(result);
}
Effect::RuntimeClosed => {
let _closed = tracing::info_span!(
"agent.session.runtime_closed",
agent.session.id = %self.machine.id(),
)
.entered();
tracing::info!(
id = %self.machine.id(),
"agent session runtime was deliberately closed"
);
self.turn_observer.runtime_closed(self.machine.id());
}
Effect::Stop { reason } => {
self.telemetry.on_stopped(&reason);
// The one place a session's `disconnected` event is
// written. The frame itself carries no cause, so a
// routine idle teardown and a runtime lost mid-turn are
// indistinguishable downstream - in the log, in the
// status projection, and in the composer that reads it.
// Recording the close reason here is what tells them
// apart after the fact.
let span = tracing::info_span!(
"agent.session.disconnect",
agent.session.id = %self.machine.id(),
agent.session.close_reason = %reason,
agent.session.disconnect_persisted = tracing::field::Empty,
);
let terminal_log = self.log(
None,
Message::ToServer(ToServerMessage::Event {
event: SystemEvent::Disconnected,
}),
);
let result = tokio::time::timeout(COMMAND_DELIVERY_TIMEOUT, terminal_log)
.instrument(span.clone())
.await;
match result {
Ok(Ok(())) => {
span.record("agent.session.disconnect_persisted", "yes");
}
Ok(Err(error)) => {
span.record("agent.session.disconnect_persisted", "failed");
tracing::error!(
error = ?error,
id = %self.machine.id(),
"agent session failed to persist its disconnect"
);
}
Err(_) => {
span.record("agent.session.disconnect_persisted", "timed_out");
tracing::error!(
id = %self.machine.id(),
"agent session timed out persisting its disconnect"
);
}
}
tracing::info!(id = %self.machine.id(), %reason, "agent session stopped");
stepped = Stepped::Stopped(reason);
}
}
}
stepped
}
/// Log then send: the log entry is written first so the session's history
/// never lacks a message its agent received.
#[tracing::instrument(
name = "agent.acp.deliver",
err,
skip(self, from, message),
fields(
agent.session.id = %self.machine.id(),
rpc.system.name = tracing::field::Empty,
rpc.method = tracing::field::Empty,
)
)]
async fn deliver(
&mut self,
from: Option<MacroUserIdStr<'static>>,
message: ToRuntimeMessage,
) -> Result<()> {
if let Some(method) = acp_method(&message) {
tracing::Span::current().record("rpc.system.name", "jsonrpc");
tracing::Span::current().record("rpc.method", method);
}
let appended = self
.logs
.append(AgentSessionLog {
agent_session_id: self.machine.id(),
user_id: from,
content: if agent_runtime_protocol::domain::notification::input_from_runtime(
&message,
)
.is_some_and(|input| input.system_turn)
{
Message::Notification(message.clone())
} else {
Message::ToRuntime(message.clone())
},
logged_at: None,
})
.await?;
if acp_method(&message) == Some("initialize") {
self.machine.initialization_persisted(appended.log_id);
self.initialization_request = Some(message.clone());
}
self.outbound.send(message).await?;
// After the send, so a signal never describes a frame the runtime has
// not seen: an answer to a question clears it once it is on the wire.
self.forward_signals(appended.signals);
Ok(())
}
async fn log(
&mut self,
user_id: Option<MacroUserIdStr<'static>>,
content: Message,
) -> Result<()> {
let appended = self
.logs
.append(AgentSessionLog {
agent_session_id: self.machine.id(),
user_id,
content,
logged_at: None,
})
.await?;
self.forward_signals(appended.signals);
Ok(())
}
/// Hand the fold's turn signals to the observer, one span per turn end.
///
/// The counterpart to `agent.session.disconnect`: a turn that ended here
/// reached its stop reason, so a session whose last turn has this span
/// and no disconnect after it finished cleanly.
fn forward_signals(&self, signals: Vec<TurnSignal>) {
for signal in signals {
match &signal {
TurnSignal::TurnEnded {
turn,
action_id,
stop,
..
} => {
let _ended = tracing::info_span!(
"agent.session.turn_ended",
agent.session.id = %self.machine.id(),
agent.turn.id = turn.0,
agent.action.id = action_id.map(tracing::field::display),
agent.turn.stop_reason = ?stop,
)
.entered();
tracing::info!(id = %self.machine.id(), "agent session turn ended");
}
TurnSignal::ElicitationRaised { request_id, .. } => {
tracing::info!(
id = %self.machine.id(),
?request_id,
"agent session is waiting for input"
);
}
TurnSignal::ElicitationCleared { request_id, .. } => {
tracing::info!(
id = %self.machine.id(),
?request_id,
"agent session elicitation cleared"
);
}
// A reply's shape changes several times a turn; the turn's
// own span already covers it, so this is not logged.
TurnSignal::Progressed { .. } => {}
}
self.turn_observer.signal(self.machine.id(), signal);
}
}
async fn persist_acp_session(&self, acp_session_id: SessionId) -> Result<()> {
self.logs
.set_acp_session_id(self.machine.id(), acp_session_id)
.await
}
fn finish_handshake_if_complete(&mut self) {
match self.machine.status() {
RuntimeStatus::Live { .. } => {
self.handshake_span.take();
self.list_tools_once();
}
RuntimeStatus::Dead => {
if let Some(span) = self.handshake_span.take() {
span.record("otel.status_code", "ERROR");
span.record("otel.status_description", "ACP handshake failed");
}
}
RuntimeStatus::Booting | RuntimeStatus::Handshaking => {}
}
}
/// List the session's MCP tools for its telemetry, once, off this actor's
/// path: the listing dials the same servers the agent was just handed and
/// must never hold up a prompt. Whatever it finds is published for the
/// projector to pick up on the next turn it records.
fn list_tools_once(&mut self) {
if self.tools_listed {
return;
}
self.tools_listed = true;
if self.mcp_servers.is_empty() {
return;
}
let catalog = Arc::clone(&self.tool_catalog);
let servers = self.mcp_servers.clone();
let definitions = self.telemetry.tool_definitions();
let id = self.machine.id();
tokio::spawn(
async move {
match tokio::time::timeout(TOOL_LISTING_TIMEOUT, catalog.tool_definitions(servers))
.await
{
Ok(listed) => {
tracing::debug!(%id, tools = listed.len(), "listed an agent session's tools");
definitions.publish(listed);
}
Err(_) => {
tracing::warn!(%id, "timed out listing an agent session's tools");
}
}
}
.in_current_span(),
);
}
/// The failing effect's own caller gets `cause` itself; anything still
/// queued behind it never reached the runtime, so it gets `Disconnected`.
fn fail_remaining_completions(
&self,
effects: &mut VecDeque<Effect<SessionCompletion>>,
cause: AgentSessionError,
) {
let mut stop = None;
let mut cause = Some(cause);
while let Some(effect) = effects.pop_front() {
match effect {
Effect::Complete { token, .. } => {
let error = cause
.take()
.unwrap_or_else(|| AgentSessionError::Disconnected(self.machine.id()));
token.span.record("otel.status_code", "ERROR");
token
.span
.record("otel.status_description", tracing::field::display(&error));
let _ = token.completed.send(Err(error));
}
effect @ Effect::Stop { .. } => stop = Some(effect),
Effect::Send { .. }
| Effect::Log { .. }
| Effect::EstablishInitialization { .. }
| Effect::PersistAcpSession { .. }
| Effect::Initialized { .. }
| Effect::RuntimeClosed => {}
}
}
if let Some(stop) = stop {
effects.push_back(stop);
}
}
}
/// Milliseconds as i64: a u64 reaches OTel as a string.
fn elapsed_ms(since: Instant) -> i64 {
i64::try_from(since.elapsed().as_millis()).unwrap_or(i64::MAX)
}
fn acp_method(message: &ToRuntimeMessage) -> Option<&str> {
let ToRuntimeMessage::Acp(AcpMessage(frame)) = message else {
return None;
};
match frame {
RawJsonRpcMessage::Request(request) => Some(request.method.as_ref()),
RawJsonRpcMessage::Notification(notification) => Some(notification.method.as_ref()),
RawJsonRpcMessage::Response(_) => None,
}
}