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.

19.0 KB
Raw Blame
//! How an agent's reply reads as a conversation.
//!
//! A reply is an ordered list of parts: prose, tool calls, requests for the
//! user. A conversation surface - a channel message, a typing row, a live
//! tail under the composer - wants them grouped: a passage the agent wrote,
//! the work it did between passages, and what it is waiting on. This module is
//! that grouping, derived from the parts alone.
//!
//! The same function runs on the server, which posts a reply's sealed
//! segments as channel messages, and in the browser through the wasm fold,
//! which renders the segment still being written. Both read the boundaries
//! from here, so a message the server posted and the live view of the same
//! turn never disagree about where one segment ends.
//!
//! Activity rows carry their own wording. A row is stored in a channel
//! message once its segment is posted, so the label a person reads later is
//! the label the live view showed; wording that differed between the two
//! would make a finished turn look like it changed.

use agent_runtime_protocol::domain::tool_approval::ToolApprovalStatus;
use serde::{Deserialize, Serialize};
use specta::Type;

use super::part::MessagePart;
use super::plan::PlanEntryStatus;
use super::tool::{ToolDetail, ToolName, ToolStatus};
use super::user_tool::UserToolOutcome;
use super::{ElicitationOutcome, PermissionOutcome};

#[cfg(test)]
mod test;

mod code_execution;

/// Longest detail a row keeps, in characters.
const DETAIL_MAX_CHARS: usize = 80;

/// What a segment of a reply is.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Type)]
#[serde(rename_all = "snake_case")]
pub enum SegmentKind {
    /// A passage the agent wrote.
    Prose,
    /// A run of tool calls and plan updates.
    Activity,
    /// A permission or a question the agent put to the user.
    Interaction,
}

/// Where one step of work got to.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Type)]
#[serde(rename_all = "snake_case")]
pub enum ActivityStatus {
    /// Started and not finished, including a call waiting on permission.
    Running,
    /// Finished successfully.
    Completed,
    /// Finished unsuccessfully.
    Failed,
    /// Still running when its turn ended: nobody knows whether it finished.
    Interrupted,
}

/// One step of work, worded for a person reading a conversation.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Type)]
#[serde(rename_all = "camelCase")]
pub struct ActivityRow {
    /// The tool call's id, stable across updates; `plan` for a plan update.
    pub id: String,
    /// What happened, as a verb phrase: `Ran`, `Reading`, `Search documents`.
    pub label: String,
    /// What it happened to - a command, a file, a query - when that is safe
    /// to show to everyone who can read the conversation.
    pub detail: Option<String>,
    /// Where it got to.
    pub status: ActivityStatus,
    /// What the step put in front of the person, shown where it ran.
    #[serde(default)]
    pub card: Option<ActivityCard>,
}

/// What a step put in front of the person.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Type)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ActivityCard {
    /// A view the agent presented: the `view` of a presented `PresentView`
    /// call. Its widgets name the items they show, and readers load those
    /// with their own access.
    View {
        /// The dynamic-UI view.
        view: dynamic_ui::View,
    },
}

/// A run of a reply's parts that reads as one unit.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Type)]
#[serde(rename_all = "camelCase")]
pub struct Segment {
    /// Position among the reply's segments, from zero.
    pub index: u32,
    /// What the segment is.
    pub kind: SegmentKind,
    /// Index of the segment's first part.
    pub start: u32,
    /// Index one past the segment's last part.
    pub end: u32,
    /// Whether the segment can still change: false only for the last segment
    /// of a reply that is still being written.
    pub sealed: bool,
    /// The steps, for an activity segment; empty otherwise.
    pub rows: Vec<ActivityRow>,
}

/// What the agent is doing right now, as a typing indicator says it.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Type)]
#[serde(rename_all = "snake_case")]
pub enum TurnPhase {
    /// Nothing to show yet, or between steps.
    Thinking,
    /// Writing prose.
    Writing,
    /// Running a tool.
    Working,
    /// Waiting on the user to answer a permission or a question.
    Waiting,
}

/// A segment with the content a server needs to post it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ProjectedSegment {
    /// The segment's boundaries and rows.
    pub segment: Segment,
    /// The prose, once the segment is sealed. Absent while the agent is
    /// still writing it - an unfinished passage is not posted - and for
    /// every other kind.
    pub text: Option<String>,
}

/// Group a reply's parts into segments.
///
/// `closed` is whether the reply's turn has ended; until it has, the last
/// segment stays open. Thoughts, attachments and controls belong to no
/// segment, and whitespace-only prose is not a passage: a newline the agent
/// emitted between two tool calls must not split their activity in two.
#[must_use]
pub fn segments(parts: &[MessagePart], closed: bool) -> Vec<Segment> {
    let mut out: Vec<Segment> = Vec::new();
    for (index, part) in parts.iter().enumerate() {
        let Some(kind) = part_kind(part) else {
            continue;
        };
        let index = u32::try_from(index).unwrap_or(u32::MAX);
        match out.last_mut() {
            // Each interaction is its own segment: two requests are two
            // things to answer, not one.
            Some(last) if last.kind == kind && kind != SegmentKind::Interaction => {
                last.end = index.saturating_add(1);
            }
            _ => out.push(Segment {
                index: u32::try_from(out.len()).unwrap_or(u32::MAX),
                kind,
                start: index,
                end: index.saturating_add(1),
                sealed: true,
                rows: Vec::new(),
            }),
        }
    }
    if let Some(last) = out.last_mut() {
        last.sealed = closed;
    }
    for segment in &mut out {
        if segment.kind == SegmentKind::Activity {
            segment.rows = activity_rows(slice(parts, segment), closed);
        }
    }
    out
}

/// The segments, with each sealed passage's prose, for a server to post.
#[must_use]
pub fn project(parts: &[MessagePart], closed: bool) -> Vec<ProjectedSegment> {
    segments(parts, closed)
        .into_iter()
        .map(|segment| {
            let text = (segment.kind == SegmentKind::Prose && segment.sealed)
                .then(|| prose_text(parts, &segment));
            ProjectedSegment { segment, text }
        })
        .collect()
}

/// The prose of a segment: its text parts, a blank line apart.
#[must_use]
pub fn prose_text(parts: &[MessagePart], segment: &Segment) -> String {
    slice(parts, segment)
        .iter()
        .filter_map(|part| match part {
            MessagePart::Text { text } if !text.trim().is_empty() => Some(text.trim()),
            _ => None,
        })
        .collect::<Vec<_>>()
        .join("\n\n")
}

/// What an unfinished reply is doing now. `None` once its turn has ended.
///
/// A pending question or approval blocks the turn wherever it sits: the tool
/// that asked can report itself running after its question. Otherwise the
/// phase is read off the last part rather than the last segment: a thought
/// belongs to no segment, and an agent thinking after a passage is not still
/// writing it.
#[must_use]
pub fn phase(parts: &[MessagePart], closed: bool) -> Option<TurnPhase> {
    if closed {
        return None;
    }
    if parts.iter().any(is_pending_request) {
        return Some(TurnPhase::Waiting);
    }
    let phase = match parts.iter().rev().find(|part| !is_blank_text(part)) {
        Some(MessagePart::Text { .. }) => TurnPhase::Writing,
        Some(MessagePart::ToolUse {
            status: ToolStatus::Pending | ToolStatus::Running,
            ..
        }) => TurnPhase::Working,
        _ => TurnPhase::Thinking,
    };
    Some(phase)
}

/// A question or approval the user has not answered yet.
fn is_pending_request(part: &MessagePart) -> bool {
    matches!(
        part,
        MessagePart::Permission {
            outcome: PermissionOutcome::Pending,
            ..
        } | MessagePart::Elicitation {
            outcome: ElicitationOutcome::Pending,
            ..
        } | MessagePart::ToolApproval {
            status: ToolApprovalStatus::Pending,
            ..
        }
    )
}

fn is_blank_text(part: &MessagePart) -> bool {
    matches!(part, MessagePart::Text { text } if text.trim().is_empty())
}

fn part_kind(part: &MessagePart) -> Option<SegmentKind> {
    match part {
        MessagePart::Text { text } if text.trim().is_empty() => None,
        MessagePart::Text { .. } => Some(SegmentKind::Prose),
        MessagePart::ToolUse { .. } | MessagePart::Plan { .. } => Some(SegmentKind::Activity),
        MessagePart::Permission { .. }
        | MessagePart::Elicitation { .. }
        | MessagePart::ToolApproval { .. } => Some(SegmentKind::Interaction),
        MessagePart::Thought { .. }
        | MessagePart::Attachment { .. }
        | MessagePart::Control { .. }
        | MessagePart::TaskNotification { .. } => None,
    }
}

fn slice<'a>(parts: &'a [MessagePart], segment: &Segment) -> &'a [MessagePart] {
    let start = (segment.start as usize).min(parts.len());
    let end = (segment.end as usize).clamp(start, parts.len());
    &parts[start..end]
}

fn activity_rows(parts: &[MessagePart], closed: bool) -> Vec<ActivityRow> {
    parts
        .iter()
        .flat_map(|part| match part {
            MessagePart::ToolUse {
                id,
                name,
                status,
                detail,
            } => code_execution::rows(&id.0, name, detail, closed)
                .unwrap_or_else(|| vec![tool_row(id.0.clone(), name, *status, detail, closed)]),
            MessagePart::Plan { entries } => {
                let done = entries
                    .iter()
                    .filter(|entry| entry.status == PlanEntryStatus::Completed)
                    .count();
                vec![ActivityRow {
                    id: "plan".to_owned(),
                    label: "Updated the plan".to_owned(),
                    detail: Some(format!("{done}/{} done", entries.len())),
                    status: ActivityStatus::Completed,
                    card: None,
                }]
            }
            _ => Vec::new(),
        })
        .collect()
}

/// Verb forms for a step: while it runs, once it finished, and if it failed.
struct Verbs {
    running: &'static str,
    done: &'static str,
    failed: &'static str,
}

const RUN: Verbs = Verbs {
    running: "Running",
    done: "Ran",
    failed: "Command failed",
};
const EDIT: Verbs = Verbs {
    running: "Editing",
    done: "Edited",
    failed: "Edit failed",
};
const READ: Verbs = Verbs {
    running: "Reading",
    done: "Read",
    failed: "Read failed",
};
const DELETE: Verbs = Verbs {
    running: "Deleting",
    done: "Deleted",
    failed: "Delete failed",
};
const MOVE: Verbs = Verbs {
    running: "Moving",
    done: "Moved",
    failed: "Move failed",
};
const SEARCH: Verbs = Verbs {
    running: "Searching",
    done: "Searched",
    failed: "Search failed",
};
const FETCH: Verbs = Verbs {
    running: "Fetching",
    done: "Fetched",
    failed: "Fetch failed",
};
const DELEGATE: Verbs = Verbs {
    running: "Delegating",
    done: "Delegated",
    failed: "Delegation failed",
};

fn tool_row(
    id: String,
    name: &ToolName,
    status: ToolStatus,
    detail: &ToolDetail,
    closed: bool,
) -> ActivityRow {
    let status = match status {
        ToolStatus::Pending | ToolStatus::Running if closed => ActivityStatus::Interrupted,
        ToolStatus::Pending | ToolStatus::Running => ActivityStatus::Running,
        ToolStatus::Completed => ActivityStatus::Completed,
        ToolStatus::Failed => ActivityStatus::Failed,
    };
    let named = humanize(tool_name(name));
    let verbed = |verbs: &Verbs, detail: Option<String>| {
        let label = match status {
            ActivityStatus::Running => verbs.running,
            ActivityStatus::Completed | ActivityStatus::Interrupted => verbs.done,
            ActivityStatus::Failed => verbs.failed,
        };
        (label.to_owned(), detail)
    };
    let card = presented_view(&id, name, status, detail);
    let (label, detail) = match detail {
        ToolDetail::Terminal { command, .. } => {
            verbed(&RUN, command.as_deref().map(command_detail))
        }
        ToolDetail::Edit { diffs } => verbed(
            &EDIT,
            paths_detail(diffs.iter().map(|diff| diff.path.as_path())),
        ),
        ToolDetail::Read { paths } => {
            verbed(&READ, paths_detail(paths.iter().map(|p| p.as_path())))
        }
        ToolDetail::Delete { paths } => {
            verbed(&DELETE, paths_detail(paths.iter().map(|p| p.as_path())))
        }
        ToolDetail::Move { paths } => {
            verbed(&MOVE, paths_detail(paths.iter().map(|p| p.as_path())))
        }
        ToolDetail::Search { paths, .. } => {
            verbed(&SEARCH, paths_detail(paths.iter().map(|p| p.as_path())))
        }
        ToolDetail::Fetch { .. } => verbed(&FETCH, None),
        ToolDetail::Think { .. } => ("Thought it through".to_owned(), None),
        ToolDetail::Other { input, .. } => (
            named_label(&named, status),
            input.as_ref().and_then(input_detail),
        ),
        ToolDetail::Macro { input, .. } => (named_label(&named, status), input_detail(input)),
        ToolDetail::View { .. } => (named_label(&named, status), None),
        ToolDetail::UserTool { outcome, .. } => (user_tool_label(&named, outcome), None),
        ToolDetail::Subagent { title, .. } => verbed(&DELEGATE, Some(truncate(title))),
    };
    let detail = match &card {
        Some(ActivityCard::View { view }) => view.title.as_deref().map(truncate).or(detail),
        None => detail,
    };
    ActivityRow {
        id,
        label,
        detail,
        status,
        card,
    }
}

/// The view a presented `PresentView` call shows. Only the call the harness
/// presents for `execution.views.present`, `view_<id>`, carries one; a view
/// it turned back was never presented.
fn presented_view(
    id: &str,
    name: &ToolName,
    status: ActivityStatus,
    detail: &ToolDetail,
) -> Option<ActivityCard> {
    let ToolName::Mcp { server, tool } = name else {
        return None;
    };
    if server != "macro_internal"
        || tool != "PresentView"
        || !id.starts_with("view_")
        || status != ActivityStatus::Completed
    {
        return None;
    }
    let ToolDetail::View {
        view: Some(view), ..
    } = detail
    else {
        return None;
    };
    Some(ActivityCard::View { view: view.clone() })
}

/// A tool known only by name reads as its name in every state; the status
/// icon says whether it is running.
fn named_label(named: &str, status: ActivityStatus) -> String {
    match status {
        ActivityStatus::Failed => format!("{named} failed"),
        ActivityStatus::Running | ActivityStatus::Completed | ActivityStatus::Interrupted => {
            named.to_owned()
        }
    }
}

fn user_tool_label(named: &str, outcome: &UserToolOutcome) -> String {
    let state = match outcome {
        UserToolOutcome::Pending | UserToolOutcome::Edited => "drafted",
        UserToolOutcome::Sent { .. } => "sent",
        UserToolOutcome::Draft { .. } => "saved as draft",
        UserToolOutcome::Completed { .. } => "done",
        UserToolOutcome::Rejected => "declined",
        UserToolOutcome::Failed { .. } => "failed",
        UserToolOutcome::Unrecognized => "finished",
    };
    format!("{named} {state}")
}

fn tool_name(name: &ToolName) -> &str {
    match name {
        ToolName::Native { name } => name,
        ToolName::Mcp { tool, .. } => tool,
    }
}

/// `ListEntities`, `list_entities` and `list-entities` all read `List entities`.
fn humanize(name: &str) -> String {
    let mut words: Vec<String> = Vec::new();
    let mut current = String::new();
    let mut previous: Option<char> = None;
    for character in name.chars() {
        if matches!(character, '_' | '-' | ' ' | '.') {
            if !current.is_empty() {
                words.push(std::mem::take(&mut current));
            }
        } else {
            let boundary = character.is_uppercase()
                && previous
                    .is_some_and(|previous| previous.is_lowercase() || previous.is_numeric());
            if boundary && !current.is_empty() {
                words.push(std::mem::take(&mut current));
            }
            current.push(character);
        }
        previous = Some(character);
    }
    if !current.is_empty() {
        words.push(current);
    }
    let sentence = words
        .iter()
        .map(|word| {
            // Keep acronyms (`URL`, `PDF`) as written.
            if word.len() > 1 && word.chars().all(|c| c.is_uppercase() || c.is_numeric()) {
                word.clone()
            } else {
                word.to_lowercase()
            }
        })
        .collect::<Vec<_>>()
        .join(" ");
    let mut characters = sentence.chars();
    match characters.next() {
        Some(first) => first.to_uppercase().chain(characters).collect(),
        None => "Tool".to_owned(),
    }
}

fn truncate(text: &str) -> String {
    let line = text.lines().next().unwrap_or_default().trim();
    if line.chars().count() <= DETAIL_MAX_CHARS {
        return line.to_owned();
    }
    let kept: String = line.chars().take(DETAIL_MAX_CHARS - 1).collect();
    format!("{}…", kept.trim_end())
}

/// A command's first line, cut to length.
fn command_detail(command: &str) -> String {
    truncate(command.lines().next().unwrap_or_default())
}

/// A file's name, or how many files.
fn paths_detail<'a>(paths: impl Iterator<Item = &'a std::path::Path>) -> Option<String> {
    let paths: Vec<_> = paths.collect();
    match paths.as_slice() {
        [] => None,
        [path] => Some(truncate(
            &path
                .file_name()
                .map_or_else(|| path.to_string_lossy(), |name| name.to_string_lossy()),
        )),
        many => Some(format!("{} files", many.len())),
    }
}

/// The argument that says what a tool acted on, for tools known by name: a
/// query, a title, a name - of a document or file too - a URL. Only short
/// plain strings qualify.
fn input_detail(input: &serde_json::Value) -> Option<String> {
    const KEYS: [&str; 9] = [
        "query",
        "q",
        "title",
        "name",
        "documentName",
        "fileName",
        "url",
        "path",
        "subject",
    ];
    let object = input.as_object()?;
    KEYS.iter().find_map(|key| {
        object
            .get(*key)
            .and_then(serde_json::Value::as_str)
            .map(str::trim)
            .filter(|value| !value.is_empty())
            .map(truncate)
    })
}