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.

38.8 KB
Raw Blame
//! GenAI spans projected from a live session's ACP frames.
//!
//! Every harness a session can run on - a sandboxed OpenCode, a Cursor cloud
//! agent, Macro's own in-process agent, an external `macrod` - speaks ACP
//! through the [`SessionActor`](super::actors::SessionActor), and the actor
//! sees every frame in both directions exactly once. So this is the one place
//! a session's turns and tool calls can be traced the same way for all of
//! them, in the OpenTelemetry GenAI vocabulary an evaluation backend reads:
//!
//! - one `invoke_agent` span per prompt turn, from the `session/prompt` going
//!   out to its response coming back: the prompt as `gen_ai.input.messages`,
//!   the agent's streamed prose, reasoning and tool calls as
//!   `gen_ai.output.messages`, the stop reason as the finish reason, the
//!   turn's token usage, the tools the session's MCP servers offered as
//!   `gen_ai.tool.definitions`, the harness as the agent name and the session
//!   as the conversation id;
//! - one `execute_tool` span per tool call, from its `tool_call` to the
//!   `tool_call_update` that finishes it, with the tool's name, arguments and
//!   result read through the harness conventions `agent_fold` knows, and an
//!   error status when the call failed.
//!
//! What ACP does not carry is not invented: there is no `chat` span, because
//! the model calls happen inside the harness and never cross the wire.
//!
//! Content follows the [`ContentPolicy`] and size limits of
//! [`genai_telemetry`]; structure (names, ids, status, usage) is always
//! recorded. Everything here is best-effort and total: a frame the projector
//! cannot read changes nothing, and never the session.
//!
//! Only live frames are projected. The actor feeds this from its effect loop,
//! not from the log writer, so a reconnecting actor catching its fold up on
//! the stored log re-emits nothing.

#[cfg(test)]
mod test;

use std::collections::{HashMap, HashSet};
use std::sync::{Arc, OnceLock};
use std::time::Instant;

use agent_client_protocol::schema::v1::{
    ContentBlock, EmbeddedResourceResource, InitializeRequest, InitializeResponse,
    LoadSessionRequest, NewSessionRequest, PromptRequest, PromptResponse, RequestId, Response,
    ResumeSessionRequest, SessionConfigKind, SessionConfigOption, SessionNotification,
    SessionUpdate, SetSessionConfigOptionRequest, StopReason as AcpStopReason, ToolCall,
    ToolCallUpdate, ToolKind,
};
use agent_client_protocol::{JsonRpcMessage, RawJsonRpcMessage, RawJsonRpcParams};
use agent_fold::domain::harness::{ToolFrame, tool_name};
use agent_fold::domain::model::{Harness, ToolName, ToolStatus};
use agent_runtime_protocol::domain::action::MODEL_CONFIG_ID;
use agent_runtime_protocol::domain::schema::v0::{AcpMessage, ToRuntimeMessage, ToServerMessage};
use genai_telemetry::messages::{self, MediaSource};
use genai_telemetry::{
    ContentPolicy, GenAiSpanExt as _, attr, bound_messages, bound_tool_definitions,
    bounded_json_string, truncate_chars,
};
use serde::Deserialize;
use serde_json::Value;

use crate::domain::model::AgentSessionId;
use crate::domain::ports::SessionToolDefinition;

use super::StopReason;

/// The tools a session's MCP servers advertise, listed once per connection by
/// a task the actor spawns and read by the projector when it records a turn.
///
/// A write-once cell rather than a channel: the listing is one fact, whoever
/// reads it wants the latest and only value, and a turn that opens before the
/// listing lands picks it up when it closes instead.
#[derive(Clone, Default)]
pub(crate) struct SharedToolDefinitions(Arc<OnceLock<Vec<SessionToolDefinition>>>);

impl SharedToolDefinitions {
    /// Publish the listing. A second publish is dropped; the first stands.
    pub(crate) fn publish(&self, definitions: Vec<SessionToolDefinition>) {
        let _ = self.0.set(definitions);
    }

    fn get(&self) -> Option<&[SessionToolDefinition]> {
        self.0.get().map(Vec::as_slice)
    }
}

/// Projects one session connection's ACP frames onto GenAI spans.
pub(crate) struct GenAiProjector {
    session: AgentSessionId,
    policy: ContentPolicy,
    /// The harness producing the frames: announced by `initialize`, or
    /// recognized from the first tool frame of a log with no `initialize`.
    harness: Harness,
    /// The model the session runs on, per the runtime's own config options.
    model: Option<String>,
    tool_definitions: SharedToolDefinitions,
    /// The `initialize` request whose response names the harness.
    initialize: Option<RequestId>,
    /// ACP initialization requests, kept open until their matching response.
    initialization_spans: HashMap<RequestId, tracing::Span>,
    /// Requests whose responses carry the session's config options (and so
    /// its model): `session/new`, `session/load`, `session/resume`, and every
    /// `session/set_config_option`.
    config_requests: HashSet<RequestId>,
    /// The turn in flight, if a `session/prompt` is awaiting its answer.
    turn: Option<Turn>,
    /// Tool calls opened and not yet finished, by ACP tool call id. Under the
    /// turn in flight when there is one; a call streamed outside any turn (a
    /// resumed session whose prompt this connection never sent) gets a root
    /// span of its own.
    tools: HashMap<String, OpenTool>,
    /// The cumulative token totals the last prompt response reported, so
    /// each turn records its own share rather than the running total.
    usage_totals: Option<(u64, u64)>,
}

/// One prompt turn's span and the output it has streamed so far.
struct Turn {
    request_id: RequestId,
    span: tracing::Span,
    /// When the prompt went out, so the first output back dates the turn's
    /// time to first output.
    started: Instant,
    first_output_recorded: bool,
    first_text_recorded: bool,
    first_reasoning_recorded: bool,
    first_tool_call_recorded: bool,
    /// The agent's output, in order: prose, reasoning and tool calls.
    parts: Vec<OutputPart>,
    /// Facts recorded at open so they are not recorded twice at close. Each
    /// is recorded as soon as it is known, which may be at open or at close.
    agent_name_recorded: bool,
    model_recorded: bool,
    definitions_recorded: bool,
}

/// Independent milestones: a tool call must not stop the answer-text clock.
enum OutputKind {
    Text,
    Reasoning,
    ToolCall,
}

enum OutputPart {
    Text(String),
    Reasoning(String),
    ToolCall {
        id: String,
        name: String,
        arguments: Value,
    },
}

impl OutputPart {
    fn into_json(self) -> Value {
        match self {
            Self::Text(text) => messages::text_part(text),
            Self::Reasoning(text) => messages::reasoning_part(text),
            Self::ToolCall {
                id,
                name,
                arguments,
            } => messages::tool_call_part(Some(&id), &name, arguments),
        }
    }
}

/// One tool call's span and what its frames have said so far.
struct OpenTool {
    span: tracing::Span,
    name: ToolName,
    status: ToolStatus,
    /// The latest `rawInput` seen: a harness may stream the arguments over
    /// several patches, and the last complete value is the call's.
    arguments: Option<Value>,
    /// Index of this call's part in the turn's output, when it has one.
    part: Option<usize>,
}

/// How a turn ended.
enum Outcome<'outcome> {
    /// The runtime answered the prompt; the result carries the stop reason.
    Answered(&'outcome Value),
    /// The runtime refused the prompt with a JSON-RPC error.
    Refused(&'outcome str),
    /// Another prompt went out before this one was answered.
    Superseded,
    /// The connection ended with the turn in flight.
    Stopped(&'outcome StopReason),
}

impl GenAiProjector {
    /// A projector for `session`, recording content under `policy` and tool
    /// definitions from `tool_definitions` once they are published.
    pub(crate) fn new(
        session: AgentSessionId,
        policy: ContentPolicy,
        tool_definitions: SharedToolDefinitions,
    ) -> Self {
        Self {
            session,
            policy,
            harness: Harness::Unknown,
            model: None,
            tool_definitions,
            initialize: None,
            initialization_spans: HashMap::new(),
            config_requests: HashSet::new(),
            turn: None,
            tools: HashMap::new(),
            usage_totals: None,
        }
    }

    /// The cell the connection's tool listing is published into.
    pub(crate) fn tool_definitions(&self) -> SharedToolDefinitions {
        self.tool_definitions.clone()
    }

    /// A frame this side is sending to the runtime. A `session/prompt` opens a
    /// turn, as a child of `parent` - the span of the command that carried
    /// the prompt - when there is one.
    pub(crate) fn on_outbound(
        &mut self,
        message: &mut ToRuntimeMessage,
        parent: Option<&tracing::Span>,
    ) {
        let ToRuntimeMessage::Acp(AcpMessage(RawJsonRpcMessage::Request(request))) = message else {
            return;
        };
        let method = &request.method;
        if InitializeRequest::matches_method(method)
            || NewSessionRequest::matches_method(method)
            || LoadSessionRequest::matches_method(method)
            || ResumeSessionRequest::matches_method(method)
        {
            let span = tracing::info_span!(
                parent: parent.and_then(tracing::Span::id),
                "agent.init.acp",
                agent.session.id = %self.session,
                rpc.method = %method,
                outcome = tracing::field::Empty,
            );
            self.initialization_spans.insert(request.id.clone(), span);
        }
        if InitializeRequest::matches_method(method) {
            self.initialize = Some(request.id.clone());
        } else if NewSessionRequest::matches_method(method)
            || LoadSessionRequest::matches_method(method)
            || ResumeSessionRequest::matches_method(method)
            || SetSessionConfigOptionRequest::matches_method(method)
        {
            self.config_requests.insert(request.id.clone());
        } else if PromptRequest::matches_method(method) {
            let prompt: Option<PromptRequest> = deserialize_params(request.params.as_ref());
            self.begin_turn(request.id.clone(), prompt, parent);
            if let Some(turn) = &self.turn
                && let Some(RawJsonRpcParams::Object(params)) = &mut request.params
                && let Some(meta) = params
                    .entry("_meta")
                    .or_insert_with(|| Value::Object(Default::default()))
                    .as_object_mut()
            {
                genai_telemetry::propagation::inject(&turn.span, meta);
            }
        }
    }

    /// A frame the runtime sent.
    pub(crate) fn on_inbound(&mut self, message: &ToServerMessage) {
        let ToServerMessage::Acp(AcpMessage(frame)) = message else {
            return;
        };
        match frame {
            RawJsonRpcMessage::Response(Response::Result { id, result }) => {
                if let Some(span) = self.initialization_spans.remove(id) {
                    span.record("outcome", "success");
                }
                self.on_result(id, result);
            }
            RawJsonRpcMessage::Response(Response::Error { id, error }) => {
                if let Some(span) = self.initialization_spans.remove(id) {
                    span.record("outcome", "error");
                    span.set_error("acp_initialization_failed", "ACP initialization failed");
                }
                if self
                    .turn
                    .as_ref()
                    .is_some_and(|turn| &turn.request_id == id)
                    && let Some(turn) = self.turn.take()
                {
                    self.end_turn(turn, Outcome::Refused(&error.message));
                }
            }
            RawJsonRpcMessage::Notification(notification)
                if SessionNotification::matches_method(&notification.method) =>
            {
                if let Some(notification) =
                    deserialize_params::<SessionNotification>(notification.params.as_ref())
                {
                    self.on_update(notification.update);
                }
            }
            RawJsonRpcMessage::Request(_) | RawJsonRpcMessage::Notification(_) => {}
        }
    }

    /// The connection is over. A turn in flight ends in error; tool calls
    /// still open are marked abandoned.
    pub(crate) fn on_stopped(&mut self, reason: &StopReason) {
        for (_, span) in self.initialization_spans.drain() {
            span.record("outcome", "stopped");
            span.set_error(
                "session_stopped",
                "Session stopped during ACP initialization",
            );
        }
        if let Some(turn) = self.turn.take() {
            self.end_turn(turn, Outcome::Stopped(reason));
        }
        for (_, tool) in self.tools.drain() {
            tool.span.set_error("session_stopped", reason.to_string());
        }
    }

    fn on_result(&mut self, id: &RequestId, result: &Value) {
        if self.initialize.as_ref() == Some(id) {
            self.initialize = None;
            if let Ok(response) = serde_json::from_value::<InitializeResponse>(result.clone())
                && let Some(info) = response.agent_info
            {
                self.harness = Harness::from_agent_info(&info.name);
            }
            return;
        }
        if self.config_requests.remove(id) {
            #[derive(Deserialize)]
            #[serde(rename_all = "camelCase")]
            struct ConfigCarrier {
                #[serde(default)]
                config_options: Vec<SessionConfigOption>,
            }
            if let Ok(carrier) = serde_json::from_value::<ConfigCarrier>(result.clone()) {
                self.apply_config_options(carrier.config_options);
            }
            return;
        }
        if self
            .turn
            .as_ref()
            .is_some_and(|turn| &turn.request_id == id)
            && let Some(turn) = self.turn.take()
        {
            self.end_turn(turn, Outcome::Answered(result));
        }
    }

    fn on_update(&mut self, update: SessionUpdate) {
        match update {
            SessionUpdate::AgentMessageChunk(chunk) => {
                self.note_first_output();
                if let ContentBlock::Text(text) = &chunk.content
                    && !text.text.trim().is_empty()
                {
                    self.note_output_kind(OutputKind::Text);
                }
                self.append_output(&chunk.content, false);
            }
            SessionUpdate::AgentThoughtChunk(chunk) => {
                self.note_first_output();
                if let ContentBlock::Text(text) = &chunk.content
                    && !text.text.trim().is_empty()
                {
                    self.note_output_kind(OutputKind::Reasoning);
                }
                self.append_output(&chunk.content, true);
            }
            SessionUpdate::ToolCall(call) => {
                self.note_first_output();
                self.note_output_kind(OutputKind::ToolCall);
                self.open_tool(call);
            }
            SessionUpdate::ToolCallUpdate(update) => self.patch_tool(update),
            SessionUpdate::ConfigOptionUpdate(update) => {
                self.apply_config_options(update.config_options);
            }
            SessionUpdate::UsageUpdate(usage) => {
                if let Some(turn) = &self.turn {
                    turn.span
                        .set_u64(attr::MACRO_CONTEXT_USED_TOKENS, usage.used);
                    turn.span
                        .set_u64(attr::MACRO_CONTEXT_SIZE_TOKENS, usage.size);
                }
            }
            // Plans, modes, commands, titles and the user's own echoed
            // chunks: nothing a judge of the turn needs.
            _ => {}
        }
    }

    /// Date the turn's first streamed output once; later chunks are the
    /// model talking, not the harness waking up.
    fn note_first_output(&mut self) {
        let Some(turn) = &mut self.turn else {
            return;
        };
        if turn.first_output_recorded {
            return;
        }
        turn.first_output_recorded = true;
        let elapsed_ms = u64::try_from(turn.started.elapsed().as_millis()).unwrap_or(u64::MAX);
        turn.span
            .set_u64(attr::MACRO_TIME_TO_FIRST_OUTPUT_MS, elapsed_ms);
    }

    fn note_output_kind(&mut self, kind: OutputKind) {
        let Some(turn) = &mut self.turn else {
            return;
        };
        let (recorded, attribute, kind) = match kind {
            OutputKind::Text => (
                &mut turn.first_text_recorded,
                attr::MACRO_TIME_TO_FIRST_TEXT_MS,
                "text",
            ),
            OutputKind::Reasoning => (
                &mut turn.first_reasoning_recorded,
                attr::MACRO_TIME_TO_FIRST_REASONING_MS,
                "reasoning",
            ),
            OutputKind::ToolCall => (
                &mut turn.first_tool_call_recorded,
                attr::MACRO_TIME_TO_FIRST_TOOL_CALL_MS,
                "tool_call",
            ),
        };
        if *recorded {
            return;
        }
        *recorded = true;
        let elapsed_ms = u64::try_from(turn.started.elapsed().as_millis()).unwrap_or(u64::MAX);
        turn.span.set_u64(attribute, elapsed_ms);
        // Emit immediately as well: an unfinished turn's span may not be exported yet.
        tracing::info!(parent: &turn.span, output_kind = kind, elapsed_ms, "agent first output milestone");
    }

    fn apply_config_options(&mut self, options: Vec<SessionConfigOption>) {
        let model = options
            .into_iter()
            .find(|option| option.id.to_string() == MODEL_CONFIG_ID);
        if let Some(SessionConfigOption {
            kind: SessionConfigKind::Select(select),
            ..
        }) = model
        {
            self.model = Some(select.current_value.to_string());
        }
    }

    fn begin_turn(
        &mut self,
        request_id: RequestId,
        prompt: Option<PromptRequest>,
        parent: Option<&tracing::Span>,
    ) {
        if let Some(previous) = self.turn.take() {
            self.end_turn(previous, Outcome::Superseded);
        }
        // The literal stays in step with `attr::span_name::INVOKE_AGENT`;
        // `tracing` bakes the name into static metadata.
        let span = match parent {
            Some(parent) => tracing::info_span!(
                parent: parent,
                "invoke_agent",
                gen_ai.operation.name = attr::operation::INVOKE_AGENT,
                gen_ai.conversation.id = %self.session,
                agent.session.id = %self.session,
            ),
            None => tracing::info_span!(
                "invoke_agent",
                gen_ai.operation.name = attr::operation::INVOKE_AGENT,
                gen_ai.conversation.id = %self.session,
                agent.session.id = %self.session,
            ),
        };
        let mut turn = Turn {
            request_id,
            span,
            started: Instant::now(),
            first_output_recorded: false,
            first_text_recorded: false,
            first_reasoning_recorded: false,
            first_tool_call_recorded: false,
            parts: Vec::new(),
            agent_name_recorded: false,
            model_recorded: false,
            definitions_recorded: false,
        };
        self.record_turn_facts(&mut turn);
        if self.policy.capture
            && let Some(prompt) = prompt
        {
            let parts: Vec<Value> = prompt.prompt.iter().filter_map(prompt_part).collect();
            let bounded = bound_messages(
                vec![messages::message(messages::ROLE_USER, parts)],
                &self.policy.limits,
            );
            turn.span.set_str(attr::INPUT_MESSAGES, bounded.json);
            if bounded.truncated {
                turn.span.set_bool(attr::MACRO_CONTENT_TRUNCATED, true);
            }
        }
        self.turn = Some(turn);
    }

    /// Record what is known about the session onto a turn's span: the
    /// harness, the model and the offered tools, each once, as soon as known.
    fn record_turn_facts(&self, turn: &mut Turn) {
        if !turn.agent_name_recorded && self.harness != Harness::Unknown {
            turn.span
                .set_str(attr::AGENT_NAME, harness_name(self.harness));
            turn.agent_name_recorded = true;
        }
        if !turn.model_recorded
            && let Some(model) = &self.model
        {
            turn.span.set_str(attr::REQUEST_MODEL, model.clone());
            turn.model_recorded = true;
        }
        if !turn.definitions_recorded
            && let Some(definitions) = self.tool_definitions.get()
        {
            turn.definitions_recorded = true;
            if !definitions.is_empty() {
                let definitions = definitions
                    .iter()
                    .map(|definition| {
                        messages::tool_definition(
                            &self.definition_name(&definition.name),
                            &definition.description,
                            definition.parameters.clone(),
                        )
                    })
                    .collect();
                let (json, truncated) = bound_tool_definitions(definitions, &self.policy.limits);
                turn.span.set_str(attr::TOOL_DEFINITIONS, json);
                if truncated {
                    turn.span.set_bool(attr::MACRO_CONTENT_TRUNCATED, true);
                }
            }
        }
    }

    /// A listed tool's name as this harness calls it. Macro's in-process agent
    /// calls Macro's tools natively, by their bare names, while the listing
    /// sees them through Macro's MCP server as `mcp__macro__<tool>`; every
    /// other harness calls them by the listed name.
    fn definition_name(&self, listed: &str) -> String {
        let name: ToolName = listed.parse().unwrap_or_else(|never| match never {});
        if self.harness == Harness::Macro
            && let ToolName::Mcp { .. } = &name
            && let Some(tool) = self.harness.reader().macro_tool(&name)
        {
            return tool.to_owned();
        }
        listed.to_owned()
    }

    /// The listed description of the tool behind `name`, if it was listed.
    fn tool_description(&self, name: &ToolName) -> Option<String> {
        let display = name.display();
        let mangled = match name {
            ToolName::Mcp { server, tool } => Some(format!("mcp__{server}__{tool}")),
            ToolName::Native { .. } => None,
        };
        self.tool_definitions.get()?.iter().find_map(|definition| {
            (definition.name == display
                || mangled.as_deref() == Some(definition.name.as_str())
                || self.definition_name(&definition.name) == display)
                .then(|| definition.description.clone())
        })
    }

    fn end_turn(&mut self, mut turn: Turn, outcome: Outcome<'_>) {
        let finish_reason = match outcome {
            Outcome::Answered(result) => {
                self.record_usage(&turn.span, result);
                let stop_reason = serde_json::from_value::<PromptResponse>(result.clone())
                    .ok()
                    .map(|response| response.stop_reason);
                finish_reason(stop_reason)
            }
            Outcome::Refused(message) => {
                turn.span.set_error(
                    "prompt_refused",
                    self.error_description(message, "the runtime refused the prompt"),
                );
                attr::finish_reason::ERROR
            }
            Outcome::Superseded => {
                turn.span.set_error(
                    "superseded",
                    "another prompt was sent before this turn was answered",
                );
                attr::finish_reason::ERROR
            }
            Outcome::Stopped(reason) => {
                turn.span.set_error("session_stopped", reason.to_string());
                attr::finish_reason::ERROR
            }
        };

        // A call this turn opened and the turn ended on is over for the
        // judge's purposes, whatever the harness would have said next: mark
        // it rather than leak its span. A call opened outside any turn (its
        // `part` is `None`) belongs to no turn and stays open for its own
        // finish.
        let abandoned = if finish_reason == attr::finish_reason::CANCELLED {
            "the turn was cancelled before the tool call finished"
        } else {
            "the turn ended before the tool call finished"
        };
        self.tools.retain(|_, tool| {
            if tool.part.is_some() {
                tool.span.set_error("abandoned", abandoned);
                false
            } else {
                true
            }
        });

        self.record_turn_facts(&mut turn);
        if !turn.agent_name_recorded {
            turn.span
                .set_str(attr::AGENT_NAME, harness_name(self.harness));
        }
        turn.span
            .set_str_array(attr::RESPONSE_FINISH_REASONS, [finish_reason]);
        if self.policy.capture {
            let parts = turn.parts.into_iter().map(OutputPart::into_json).collect();
            let bounded = bound_messages(
                vec![messages::output_message(
                    messages::ROLE_ASSISTANT,
                    parts,
                    finish_reason,
                )],
                &self.policy.limits,
            );
            turn.span.set_str(attr::OUTPUT_MESSAGES, bounded.json);
            if bounded.truncated {
                turn.span.set_bool(attr::MACRO_CONTENT_TRUNCATED, true);
            }
        }
        // Dropping the last handle closes the span.
    }

    /// The turn's token usage from the prompt response. ACP reports running
    /// session totals, so each turn records the increase over the previous
    /// response; the first response a connection sees records the total,
    /// which for a resumed session includes earlier turns.
    fn record_usage(&mut self, span: &tracing::Span, result: &Value) {
        let input = result.pointer("/usage/inputTokens").and_then(Value::as_u64);
        let output = result
            .pointer("/usage/outputTokens")
            .and_then(Value::as_u64);
        let (Some(input), Some(output)) = (input, output) else {
            return;
        };
        let (turn_input, turn_output) = match self.usage_totals {
            Some((previous_input, previous_output))
                if input >= previous_input && output >= previous_output =>
            {
                (input - previous_input, output - previous_output)
            }
            _ => (input, output),
        };
        self.usage_totals = Some((input, output));
        span.set_u64(attr::USAGE_INPUT_TOKENS, turn_input);
        span.set_u64(attr::USAGE_OUTPUT_TOKENS, turn_output);
    }

    fn append_output(&mut self, content: &ContentBlock, reasoning: bool) {
        let ContentBlock::Text(text) = content else {
            return;
        };
        let Some(turn) = &mut self.turn else {
            return;
        };
        match (turn.parts.last_mut(), reasoning) {
            (Some(OutputPart::Text(existing)), false)
            | (Some(OutputPart::Reasoning(existing)), true) => existing.push_str(&text.text),
            (_, false) => turn.parts.push(OutputPart::Text(text.text.clone())),
            (_, true) => turn.parts.push(OutputPart::Reasoning(text.text.clone())),
        }
    }

    fn open_tool(&mut self, call: ToolCall) {
        let frame = ToolFrame::of_call(&call);
        self.sniff_harness(&frame);
        let reader = self.harness.reader();
        let name = tool_name(reader, &frame);
        let id = call.tool_call_id.0.to_string();
        let tool_display = name.display().to_owned();

        // The literal stays in step with `attr::span_name::EXECUTE_TOOL`;
        // `otel.name` gives the exported span the semconv `execute_tool
        // {name}` name.
        let otel_name = format!("{} {tool_display}", attr::operation::EXECUTE_TOOL);
        let span = match &self.turn {
            Some(turn) => tracing::info_span!(
                parent: &turn.span,
                "execute_tool",
                otel.name = %otel_name,
                gen_ai.operation.name = attr::operation::EXECUTE_TOOL,
                gen_ai.tool.type = attr::tool_type::FUNCTION,
                gen_ai.tool.name = %tool_display,
                gen_ai.tool.call.id = %id,
                gen_ai.conversation.id = %self.session,
                agent.session.id = %self.session,
            ),
            None => tracing::info_span!(
                "execute_tool",
                otel.name = %otel_name,
                gen_ai.operation.name = attr::operation::EXECUTE_TOOL,
                gen_ai.tool.type = attr::tool_type::FUNCTION,
                gen_ai.tool.name = %tool_display,
                gen_ai.tool.call.id = %id,
                gen_ai.conversation.id = %self.session,
                agent.session.id = %self.session,
            ),
        };
        span.set_str(attr::MACRO_TOOL_KIND, tool_kind_name(call.kind));
        if !call.title.is_empty() {
            span.set_str(attr::MACRO_TOOL_TITLE, call.title.clone());
        }
        if let ToolName::Mcp { server, .. } = &name {
            span.set_str(attr::MACRO_MCP_SERVER, server.clone());
        }
        if let Some(description) = self.tool_description(&name) {
            span.set_str(attr::TOOL_DESCRIPTION, description);
        }

        let arguments = call.raw_input.clone().filter(|input| !input.is_null());
        let part = self.turn.as_mut().map(|turn| {
            turn.parts.push(OutputPart::ToolCall {
                id: id.clone(),
                name: tool_display,
                arguments: arguments.clone().unwrap_or(Value::Null),
            });
            turn.parts.len() - 1
        });
        let status = frame.status.unwrap_or_default();
        if let Some(replaced) = self.tools.insert(
            id.clone(),
            OpenTool {
                span,
                name,
                status,
                arguments,
                part,
            },
        ) {
            replaced
                .span
                .set_error("superseded", "the harness reopened this tool call id");
        }
        if status.is_finished() {
            self.finish_tool(&id, &frame);
        }
    }

    fn patch_tool(&mut self, update: ToolCallUpdate) {
        let id = update.tool_call_id.0.to_string();
        let mut frame = ToolFrame::of_update(&update);
        self.sniff_harness(&frame);
        let Some(tool) = self.tools.get_mut(&id) else {
            // A call this connection never saw open: a resumed session
            // mid-call. Nothing to attach it to.
            return;
        };
        if frame.status.is_none() {
            frame = frame.with_status(tool.status);
        }
        if let Some(status) = frame.status {
            tool.status = status;
        }
        if let Some(input) = frame.raw_input
            && !input.is_null()
        {
            tool.arguments = Some(input.clone());
        }
        // A harness may name the tool only once it knows what it is running.
        if tool.name.is_empty() {
            let named = tool_name(self.harness.reader(), &frame);
            if !named.is_empty() {
                let display = named.display().to_owned();
                tool.span.record("gen_ai.tool.name", display.as_str());
                tool.span.record(
                    "otel.name",
                    format!("{} {display}", attr::operation::EXECUTE_TOOL).as_str(),
                );
                tool.name = named;
            }
        }
        if frame.finished() {
            self.finish_tool(&id, &frame);
        }
    }

    fn finish_tool(&mut self, id: &str, frame: &ToolFrame<'_>) {
        let Some(tool) = self.tools.remove(id) else {
            return;
        };
        let reader = self.harness.reader();
        let (result, mut error) = match frame.raw_output {
            Some(raw) => {
                let (value, error) = reader.unwrap_tool_output(raw);
                (Some(value), error)
            }
            None => (
                frame
                    .content_text()
                    .or_else(|| reader.terminal_output(frame))
                    .map(Value::String),
                None,
            ),
        };
        if error.is_none()
            && let Some(code) = reader.terminal_exit_code(frame)
            && code != 0
        {
            error = Some(format!("the command exited with code {code}"));
        }

        if let Some(result) = &result {
            let bytes = match result {
                Value::String(text) => text.len(),
                other => other.to_string().len(),
            };
            tool.span.set_u64(
                attr::MACRO_TOOL_RESULT_BYTES,
                u64::try_from(bytes).unwrap_or(u64::MAX),
            );
        }
        if self.policy.capture {
            if let Some(arguments) = &tool.arguments {
                let (json, truncated) = bounded_json_string(arguments, &self.policy.limits);
                tool.span.set_str(attr::TOOL_CALL_ARGUMENTS, json);
                if truncated {
                    tool.span.set_bool(attr::MACRO_CONTENT_TRUNCATED, true);
                }
            }
            if let Some(result) = &result {
                let (json, truncated) = bounded_json_string(result, &self.policy.limits);
                tool.span.set_str(attr::TOOL_CALL_RESULT, json);
                if truncated {
                    tool.span.set_bool(attr::MACRO_CONTENT_TRUNCATED, true);
                }
            }
        }
        // The error text is the tool's own output and so content: recorded
        // under the policy, bounded.
        match (tool.status, error) {
            (ToolStatus::Failed, error) => tool.span.set_error(
                "tool_error",
                error.map_or_else(
                    || "the tool call failed".to_owned(),
                    |error| self.error_description(&error, "the tool call failed"),
                ),
            ),
            (_, Some(error)) => tool.span.set_error(
                "tool_error",
                self.error_description(&error, "the tool reported an error"),
            ),
            (_, None) => {}
        }

        // The turn's record of the call gets the final arguments and name.
        if let (Some(turn), Some(index)) = (&mut self.turn, tool.part)
            && let Some(OutputPart::ToolCall {
                name, arguments, ..
            }) = turn.parts.get_mut(index)
        {
            if let Some(final_arguments) = tool.arguments {
                *arguments = final_arguments;
            }
            if name.is_empty() {
                *name = tool.name.display().to_owned();
            }
        }
        // Dropping the last handle closes the span.
    }

    /// An error description fit for a span's status: the detail, bounded,
    /// when content may be recorded; a fixed summary otherwise.
    fn error_description(&self, detail: &str, summary: &'static str) -> String {
        if self.policy.capture {
            truncate_chars(detail, self.policy.limits.max_part_chars).into_owned()
        } else {
            summary.to_owned()
        }
    }

    /// Recognize the harness from a tool frame when no `initialize` named it.
    fn sniff_harness(&mut self, frame: &ToolFrame<'_>) {
        if self.harness == Harness::Unknown
            && let Some(harness) = Harness::sniff(frame)
        {
            self.harness = harness;
        }
    }
}

/// Deserialize a request's or notification's params as a specific ACP type.
/// `None` for positional params or a shape mismatch: less is derived from the
/// frame, nothing fails.
fn deserialize_params<T: serde::de::DeserializeOwned>(
    params: Option<&RawJsonRpcParams>,
) -> Option<T> {
    match params? {
        RawJsonRpcParams::Object(map) => serde_json::from_value(Value::Object(map.clone())).ok(),
        RawJsonRpcParams::Array(_) => None,
    }
}

/// A prompt content block as a semconv message part. Only the user's own text
/// is copied onto a span; attached resources - inline bytes and embedded text
/// alike - are named by their URI, since a document the user attached is not
/// the prompt and can be arbitrarily large.
fn prompt_part(block: &ContentBlock) -> Option<Value> {
    Some(match block {
        ContentBlock::Text(text) => messages::text_part(text.text.clone()),
        ContentBlock::Image(image) => messages::media_part(
            "image",
            Some(&image.mime_type),
            image
                .uri
                .clone()
                .map_or(MediaSource::Inline, MediaSource::Uri),
        ),
        ContentBlock::Audio(audio) => {
            messages::media_part("audio", Some(&audio.mime_type), MediaSource::Inline)
        }
        ContentBlock::ResourceLink(link) => messages::media_part(
            "document",
            link.mime_type.as_deref(),
            MediaSource::Uri(link.uri.clone()),
        ),
        ContentBlock::Resource(embedded) => match &embedded.resource {
            EmbeddedResourceResource::TextResourceContents(text) => messages::media_part(
                "document",
                text.mime_type.as_deref(),
                MediaSource::Uri(text.uri.clone()),
            ),
            EmbeddedResourceResource::BlobResourceContents(blob) => messages::media_part(
                "document",
                blob.mime_type.as_deref(),
                MediaSource::Uri(blob.uri.clone()),
            ),
            // `#[non_exhaustive]`: a resource shape this build does not know.
            _ => return None,
        },
        // `#[non_exhaustive]`: a block this build does not know.
        _ => return None,
    })
}

/// The semconv finish reason for how a turn stopped.
fn finish_reason(stop_reason: Option<AcpStopReason>) -> &'static str {
    match stop_reason {
        Some(AcpStopReason::EndTurn) => attr::finish_reason::STOP,
        Some(AcpStopReason::MaxTokens | AcpStopReason::MaxTurnRequests) => {
            attr::finish_reason::LENGTH
        }
        Some(AcpStopReason::Refusal) => attr::finish_reason::CONTENT_FILTER,
        Some(AcpStopReason::Cancelled) => attr::finish_reason::CANCELLED,
        // `#[non_exhaustive]`, and a response this build cannot read: the
        // turn was answered, which is all that is known.
        Some(_) | None => attr::finish_reason::STOP,
    }
}

/// The harness as the agent name spans carry, in the fold's own snake_case
/// spelling so it matches the `harness` field a session's readers show.
fn harness_name(harness: Harness) -> String {
    serde_json::to_value(harness)
        .ok()
        .and_then(|value| value.as_str().map(str::to_owned))
        .unwrap_or_else(|| "unknown".to_owned())
}

/// ACP's coarse tool kind, in its wire spelling.
fn tool_kind_name(kind: ToolKind) -> String {
    serde_json::to_value(kind)
        .ok()
        .and_then(|value| value.as_str().map(str::to_owned))
        .unwrap_or_else(|| "unknown".to_owned())
}