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.

37.5 KB
Raw Blame
//! 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,
    }
}