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.3 KB
Raw Blame
//! The pure Cursor→ACP translation.
//!
//! [`TranslateMachine`] takes one [`CursorEvent`] at a time and reports the
//! ACP [`SessionUpdate`]s it implies — usually one, often none. It is a state
//! machine rather than a function because some provider facts need memory:
//!
//! - Cursor sends the same `tool_call` event for the opening announcement and
//!   every later progress report; ACP distinguishes `tool_call` from
//!   `tool_call_update`, so the machine remembers which call ids it has
//!   announced.
//! - Cursor's typed tool descriptor (`interaction_update.toolCall.type`)
//!   always arrives *after* the bare-named `tool_call` event it describes, so
//!   the machine records it per call id to refine later updates — the opening
//!   announcement can only ever rely on the tool's name.
//!
//! - Result events retain repository branches and pull request identity for
//!   the host's durable session metadata, independently of ACP updates.
//!
//! Everything else is stateless mapping. Notably, `interaction_update`'s
//! `text-delta`/`thinking-delta` subtypes duplicate the `assistant` and
//! `thinking` events one-for-one on real streams — consuming both would
//! double every chunk — so the envelope is ignored except for the subtypes
//! that carry something unique.
//!
//! Cursor reports incremental output tokens (`token-delta`) but never a
//! context-window size, while ACP's `usage_update` reports context used out
//! of a sized window. Inventing a size would misrender in any client that
//! shows a percentage, so usage is deliberately not translated.

#[cfg(test)]
mod test;

use crate::domain::event::{CursorEvent, GitState, InteractionUpdate, ToolCallEvent};
use crate::domain::model::RepoUrl;
use agent_client_protocol::schema::v1::{
    ContentBlock, ContentChunk, Diff, SessionUpdate, TextContent, ToolCall, ToolCallContent,
    ToolCallLocation, ToolCallStatus, ToolCallUpdate, ToolCallUpdateFields, ToolKind,
};
use std::collections::{BTreeMap, HashMap, HashSet};

/// Translates a run's event stream into ACP session updates, one event at a
/// time.
#[derive(Debug, Default)]
pub struct TranslateMachine {
    /// Call ids announced and not yet terminal, so repeats become
    /// `tool_call_update` and a turn that ends early knows what it left
    /// open. A call id leaves this set the moment it reports `Completed` or
    /// `Failed` — it re-entering would mean Cursor reused a finished id,
    /// which has never been observed.
    open: HashSet<String>,
    /// Kinds learned from Cursor's typed tool descriptor, keyed by call id.
    learned_kinds: HashMap<String, ToolKind>,
    /// The pull request last announced to the client. Every run's result
    /// restates the agent's pushed branches, so without this the same url
    /// would be announced once per turn.
    pull_request_url: Option<String>,
    /// Latest authoritative branch for each repository reported by Cursor.
    working_branches: BTreeMap<String, String>,
}

impl TranslateMachine {
    /// A machine with no memory of any tool call.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Advance by one event, returning the updates it implies in order.
    pub fn push(&mut self, event: CursorEvent) -> Vec<SessionUpdate> {
        match event {
            CursorEvent::Assistant { text } => chunk(&text, SessionUpdate::AgentMessageChunk),
            CursorEvent::Thinking { text } => chunk(&text, SessionUpdate::AgentThoughtChunk),
            CursorEvent::ToolCall(call) => vec![self.tool_call(call)],
            CursorEvent::Interaction(update) => {
                self.interaction(&update);
                Vec::new()
            }
            CursorEvent::Result { git, .. } => self.git_state(git.as_ref()),
            // Lifecycle and keepalives: the session service consumes these as
            // the turn's boundary; they have no ACP counterpart.
            CursorEvent::Status { .. }
            | CursorEvent::Heartbeat
            | CursorEvent::Error { .. }
            | CursorEvent::Done => Vec::new(),
            CursorEvent::Unknown { event, .. } => {
                tracing::debug!(event, "ignoring unrecognized cursor event");
                Vec::new()
            }
        }
    }

    /// Retain repository facts independently of ACP presentation and PR creation.
    fn git_state(&mut self, git: Option<&GitState>) -> Vec<SessionUpdate> {
        if let Some(git) = git {
            for repository in &git.branches {
                if let Some(branch) = &repository.branch {
                    // One fact per repository identity: replay must not apply an
                    // older HTTPS spelling after a newer scheme-less result.
                    let identity = RepoUrl::from_git_state(&repository.repo_url)
                        .map(|repository| repository.as_str().to_owned())
                        .unwrap_or_else(|| repository.repo_url.clone());
                    self.working_branches.insert(identity, branch.clone());
                }
            }
            if let Some(url) = pull_request_url(git) {
                self.pull_request_url = Some(url.to_owned());
            }
        }
        Vec::new()
    }

    /// Latest branch facts keyed by provider repository identity.
    pub fn working_branches(&self) -> &BTreeMap<String, String> {
        &self.working_branches
    }

    /// Latest PR reported by the provider, for the host's session operation.
    pub fn pull_request_url(&self) -> Option<&str> {
        self.pull_request_url.as_deref()
    }

    /// One `tool_call` event: an announcement the first time a call id is
    /// seen, an update after.
    fn tool_call(&mut self, call: ToolCallEvent) -> SessionUpdate {
        // Cursor call ids embed a literal newline (`call-…-0\nfc_…_0`) —
        // legal JSON, but it corrupts anything that renders an id on one
        // line, so it is collapsed before the id reaches ACP.
        let call_id = collapse_whitespace(&call.call_id);
        let kind = self
            .learned_kinds
            .get(&call_id)
            .copied()
            .unwrap_or_else(|| kind_from_tool_name(&call.name));
        let status = map_status(call.status.as_deref(), call.result.as_ref());
        // The path a client needs to label the row, from wherever this frame
        // happens to carry it: an in-flight edit names it in `args`, a finished
        // call in its result envelope. `locations` is ACP's own field for this
        // and Cursor fills in nothing there, so read and delete rows arrive
        // with no path at all today. Left unset rather than empty when there
        // is no path — a shell command touches no file, and an empty array is
        // payload that says nothing.
        let locations = touched_path(call.args.as_ref(), call.result.as_ref())
            .map(|path| vec![ToolCallLocation::new(path)]);
        // A finished edit reports the file whole, before and after, which is
        // exactly an ACP diff. Only on the finished frame: an in-flight edit's
        // `streamContent` is the changed *region*, and rendering that as the
        // new file would claim everything else was deleted.
        let diff = call.result.as_ref().and_then(edit_diff);

        // Captured before the status below can remove it: a call id is only
        // ever a fresh announcement the first time it is seen, even when
        // that first frame already reports it terminal.
        let is_new = self.open.insert(call_id.clone());
        if matches!(status, ToolCallStatus::Completed | ToolCallStatus::Failed) {
            self.open.remove(&call_id);
        }

        if is_new {
            let mut announcement = ToolCall::new(call_id, call.name)
                .kind(kind)
                .status(status)
                .raw_input(call.args);
            if let Some(locations) = locations {
                announcement = announcement.locations(locations);
            }
            if let Some(diff) = diff {
                announcement = announcement.content(vec![ToolCallContent::Diff(diff)]);
            }
            if let Some(result) = call.result {
                announcement = announcement.raw_output(wrap_result(result));
            }
            SessionUpdate::ToolCall(announcement)
        } else {
            let mut fields = ToolCallUpdateFields::new()
                .kind(kind)
                .status(status)
                .title(call.name)
                .locations(locations)
                .raw_input(call.args);
            if let Some(diff) = diff {
                fields = fields.content(vec![ToolCallContent::Diff(diff)]);
            }
            if let Some(result) = call.result {
                fields = fields.raw_output(wrap_result(result));
            }
            SessionUpdate::ToolCallUpdate(ToolCallUpdate::new(call_id, fields))
        }
    }

    /// Force every call still open to a terminal status, for a turn that
    /// ended without Cursor ever reporting one.
    ///
    /// A cancelled run's `result` frame is the turn's terminal signal; it
    /// does not always carry a completed `tool_call` for work that was
    /// mid-flight. A call still running at that moment would otherwise never
    /// receive one — the client is left rendering it in progress forever.
    /// `Failed` is the honest status to close it with: ACP v1 has no
    /// `cancelled` tool-call status, and Cursor never actually reported an
    /// outcome for these, so `Completed` would claim a success nobody
    /// witnessed.
    pub fn close_open_calls(&mut self) -> Vec<SessionUpdate> {
        let mut open: Vec<_> = self.open.drain().collect();
        open.sort();
        open.into_iter()
            .map(|call_id| {
                SessionUpdate::ToolCallUpdate(ToolCallUpdate::new(
                    call_id,
                    ToolCallUpdateFields::new().status(ToolCallStatus::Failed),
                ))
            })
            .collect()
    }

    /// Record what the envelope teaches; it never emits an update itself.
    fn interaction(&mut self, update: &InteractionUpdate) {
        match update {
            InteractionUpdate::ToolCallStarted { call_id, tool_type }
            | InteractionUpdate::ToolCallCompleted { call_id, tool_type } => {
                if let Some(kind) = tool_type.as_deref().and_then(kind_from_cursor_type) {
                    self.learned_kinds
                        .insert(collapse_whitespace(call_id), kind);
                }
            }
            InteractionUpdate::UserMessage { .. }
            | InteractionUpdate::TokenDelta { .. }
            | InteractionUpdate::Other { .. } => {}
        }
    }
}

/// A text delta as the given chunk variant; empty deltas produce nothing.
/// The first branch with a pull request. Stacked agents can push several
/// branches, but this session opened one agent against one repository, so
/// the first is the session's own.
fn pull_request_url(git: &GitState) -> Option<&str> {
    git.branches
        .iter()
        .find_map(|branch| branch.pr_url.as_deref())
        .filter(|url| !url.is_empty())
}

fn chunk(text: &str, variant: impl Fn(ContentChunk) -> SessionUpdate) -> Vec<SessionUpdate> {
    if text.is_empty() {
        return Vec::new();
    }
    let content = ContentBlock::Text(TextContent::new(text));
    vec![variant(ContentChunk::new(content))]
}

/// Cursor's own typed tool descriptor mapped to an ACP kind.
///
/// Exhaustive over what real streams send: every arm below was read off a
/// recording, and a type that has not been observed returns `None` so the
/// name table decides instead. The previous version also mapped `write`,
/// `search`, `fetch` and `web`, none of which Cursor has ever sent — they were
/// guesses that would have answered confidently for types that do not exist.
///
/// Two arms are judgement rather than transcription, because ACP has no kind
/// that fits:
///
/// - `task` delegates to a subagent, which is not read, write, search or
///   execute. [`ToolKind::Other`] is what ACP has for "none of these".
/// - `mcp` invokes an arbitrary MCP tool, so its kind is genuinely unknown at
///   this layer — the call could do anything the server offers.
fn kind_from_cursor_type(tool_type: &str) -> Option<ToolKind> {
    Some(match tool_type {
        "shell" => ToolKind::Execute,
        "read" => ToolKind::Read,
        "edit" => ToolKind::Edit,
        "delete" => ToolKind::Delete,
        "glob" | "grep" => ToolKind::Search,
        // The closest ACP kind for a todo-list update. ACP models a plan
        // properly as `SessionUpdate::Plan`, which is where Cursor's
        // `todo_write` calls really belong; translating them there instead is
        // a change to the shape of a turn, not a kind mapping, so it is left
        // as follow-up.
        "updateTodos" => ToolKind::Think,
        "task" | "mcp" => ToolKind::Other,
        _ => return None,
    })
}

/// Every tool name a real Cursor stream has sent, and its ACP kind.
///
/// Cursor's documented `tool_call` event carries a name and nothing else, so
/// the opening announcement — the one a client renders first — can only be
/// classified from this. The typed descriptor that would refine it always
/// arrives afterwards, and for three of these tools (`get_mcp_tools`,
/// `web_fetch`, `web_search`) it never arrives at all, so for those the name
/// is the only signal there will ever be.
///
/// This used to be token matching: names were split on separators and
/// camelCase humps and looked up in a hand-written vocabulary. That answered
/// for tools that do not exist and quietly mis-answered for ones that do —
/// `todo_write` matched the `write` token and classified a todo update as a
/// file edit. An exact table cannot do that. The cost is that a genuinely new
/// Cursor tool lands in [`ToolKind::Other`] until it is added here, which is
/// the honest answer rather than a lucky one, and the corpus sweep's pinned
/// tool-call snapshot is what surfaces the new name.
const KIND_BY_TOOL_NAME: &[(&str, ToolKind)] = &[
    ("run_terminal_cmd", ToolKind::Execute),
    ("read_file", ToolKind::Read),
    ("edit_file", ToolKind::Edit),
    ("delete_file", ToolKind::Delete),
    ("file_search", ToolKind::Search),
    ("grep_search", ToolKind::Search),
    // Both retrieve data from outside the workspace, which is what ACP's
    // Fetch means. Neither carries a typed descriptor, so this is the only
    // classification they will ever get.
    ("web_fetch", ToolKind::Fetch),
    ("web_search", ToolKind::Fetch),
    ("todo_write", ToolKind::Think),
    // See `kind_from_cursor_type` for why these three are `Other`.
    ("task", ToolKind::Other),
    ("mcp", ToolKind::Other),
    ("get_mcp_tools", ToolKind::Other),
];

/// The ACP kind for a Cursor tool name, or [`ToolKind::Other`] for a name no
/// recording has produced.
#[must_use]
pub fn kind_from_tool_name(name: &str) -> ToolKind {
    KIND_BY_TOOL_NAME
        .iter()
        .find_map(|(candidate, kind)| (*candidate == name).then_some(*kind))
        .unwrap_or(ToolKind::Other)
}

/// Cursor's tool status mapped to an ACP status.
///
/// The two signals answer different questions, and both recorded failures
/// prove it:
///
/// - The **status word** says whether the call is *done*. It never says
///   whether it succeeded — no recorded stream has ever used the word
///   "failed", so a call that failed still arrives as `"completed"`
///   (`fixtures/real/read_and_search.sse`, whose `get_mcp_tools` call failed
///   with `status: "completed"`).
/// - The **result envelope** says whether the outcome was a success, but only
///   once there is an outcome. An error envelope on a still-running frame is
///   transient: `fixtures/real/mcp_servers.sse` has a call whose first frame
///   is `"running"` with `result: {"error": …}` and which then completes
///   successfully. Reading that as failure flickers the call to Failed and
///   back.
///
/// So the word decides *whether* the call is finished and the envelope decides
/// *how* — and neither is trusted for the other's question. Unknown words are
/// treated as in-flight: a status the crate cannot read is still progress.
fn map_status(status: Option<&str>, result: Option<&serde_json::Value>) -> ToolCallStatus {
    match status {
        Some("completed" | "success") => {
            if result.is_some_and(is_error_envelope) {
                ToolCallStatus::Failed
            } else {
                ToolCallStatus::Completed
            }
        }
        Some("failed" | "error") => ToolCallStatus::Failed,
        Some("pending") => ToolCallStatus::Pending,
        _ => ToolCallStatus::InProgress,
    }
}

/// Whether Cursor's result envelope reports a failure.
///
/// Results arrive as a single-key envelope — `{"success": …}` or
/// `{"error": …}`. Only the latter is a failure; a result that is neither
/// (a bare scalar, say) says nothing about the outcome.
fn is_error_envelope(result: &serde_json::Value) -> bool {
    result.get("error").is_some()
}

/// The success payload of Cursor's single-key result envelope.
///
/// Everything worth reading out of a finished call lives under `success`; an
/// `{"error": …}` envelope has nothing to offer here, and is left to
/// [`map_status`] to turn into a failed call.
fn success(result: &serde_json::Value) -> Option<&serde_json::Value> {
    result.get("success")
}

/// A finished file edit as an ACP diff.
///
/// Recognized by the shape of the payload rather than the tool's name, so a
/// `write`-style sibling reporting the same fields gets a diff too and a
/// renamed tool does not silently lose one. `afterFullFileContent` is the
/// discriminator: `read_file` also reports a `path` and must not be mistaken
/// for an edit.
///
/// `beforeFullFileContent` is absent exactly when the file is new — the
/// corpus pairs that with a `--- /dev/null` header — which is what ACP's
/// `old_text: None` means, so the absence maps across directly.
///
/// Cursor's own `diffString` goes unread: ACP renders from the two full texts,
/// and there is nowhere in the protocol to put a unified patch.
fn edit_diff(result: &serde_json::Value) -> Option<Diff> {
    let success = success(result)?;
    let path = success.get("path")?.as_str()?;
    let after = success.get("afterFullFileContent")?.as_str()?;
    let before = success
        .get("beforeFullFileContent")
        .and_then(serde_json::Value::as_str);
    Some(Diff::new(path, after).old_text(before.map(str::to_owned)))
}

/// The file a call touched, from the result envelope or, while it is still
/// running, from its input.
///
/// Deliberately not restricted to edits: `read_file` and `delete_file` name a
/// path the same way, and the fold reads `locations` for those rows too.
fn touched_path(
    args: Option<&serde_json::Value>,
    result: Option<&serde_json::Value>,
) -> Option<String> {
    let from_result = result
        .and_then(success)
        .and_then(|success| success.get("path"))
        .and_then(serde_json::Value::as_str);
    let from_args = args
        .and_then(|args| args.get("path"))
        .and_then(serde_json::Value::as_str);
    from_result.or(from_args).map(str::to_owned)
}

/// Cursor's raw result under a `result` key, so `rawOutput` is always an
/// object even when Cursor returns a bare scalar.
fn wrap_result(result: serde_json::Value) -> serde_json::Value {
    serde_json::json!({ "result": result })
}

/// All whitespace runs collapsed to single spaces, trimmed.
fn collapse_whitespace(id: &str) -> String {
    id.split_whitespace().collect::<Vec<_>>().join(" ")
}