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.

14.2 KB
Raw Blame
//! The Cursor cloud event vocabulary.
//!
//! A run's SSE stream is a sequence of `(event name, JSON payload)` records.
//! This module names every record this crate understands, in the domain's own
//! vocabulary, so the translation ([`crate::domain::translate`]) and the
//! session service never see SSE framing or raw JSON. The shapes are taken
//! from recorded live streams — the Cursor docs name the events but not their
//! payloads — so unrecognized events and unrecognized `interaction_update`
//! subtypes are preserved as [`CursorEvent::Unknown`] and
//! [`InteractionUpdate::Other`] rather than dropped: the stream must survive
//! Cursor adding vocabulary.

#[cfg(test)]
mod test;

use crate::domain::model::{CursorRunId, RunStatus};
use serde::{Deserialize, Serialize};
use serde_json::Value;

/// One decoded event from a run's stream.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum CursorEvent {
    /// The run's lifecycle status changed (also sent once on connect).
    Status {
        /// The run the stream is reporting on.
        run_id: CursorRunId,
        /// Its current status.
        status: RunStatus,
    },
    /// A chunk of the agent's user-facing reply.
    Assistant {
        /// The text delta.
        text: String,
    },
    /// A chunk of the agent's reasoning.
    Thinking {
        /// The text delta.
        text: String,
    },
    /// A tool call was announced or progressed.
    ToolCall(ToolCallEvent),
    /// The undocumented SDK-shaped envelope. Most subtypes duplicate the
    /// documented events one-for-one; the ones that carry anything unique are
    /// modelled in [`InteractionUpdate`].
    Interaction(InteractionUpdate),
    /// The run reached a terminal state.
    Result {
        /// The run that ended.
        run_id: CursorRunId,
        /// The terminal status — `Finished` on success.
        status: RunStatus,
        /// The agent's final reply, when there is one.
        text: Option<String>,
        /// Wall-clock duration of the run.
        duration_ms: Option<u64>,
        /// What the run did to the repositories it was given — the branch it
        /// pushed and, when the agent was asked for one, the pull request it
        /// opened. Absent on runs that touched no repository.
        git: Option<GitState>,
    },
    /// A keepalive; carries nothing.
    Heartbeat,
    /// The server reported a stream-level error.
    Error {
        /// A machine-readable code.
        code: Option<String>,
        /// A human-readable message.
        message: String,
    },
    /// The stream is complete; nothing follows.
    Done,
    /// An event name this crate does not know. Kept whole for logging.
    Unknown {
        /// The SSE event name.
        event: String,
        /// Its raw payload.
        data: Value,
    },
}

/// What a run left behind in the repositories it was given, as reported by
/// the terminal `result` event.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct GitState {
    /// One entry per repository the run pushed to. Stacked agents report
    /// several.
    #[serde(default)]
    pub branches: Vec<GitBranch>,
}

/// One repository's outcome inside a [`GitState`].
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct GitBranch {
    /// The repository, without a scheme — `github.com/macro-inc/macro`.
    pub repo_url: String,
    /// The branch Cursor pushed, when it pushed one.
    #[serde(default)]
    pub branch: Option<String>,
    /// The pull request Cursor opened, present only when the agent was
    /// created with `autoCreatePR`.
    #[serde(default)]
    pub pr_url: Option<String>,
}

/// A `tool_call` event: Cursor sends the same event name for the opening
/// announcement and every later progress report, distinguished only by
/// whether the `callId` has been seen before.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ToolCallEvent {
    /// Cursor's id for the call. May contain a literal newline — see
    /// [`crate::domain::translate`], which collapses it before the id
    /// reaches ACP.
    pub call_id: String,
    /// The tool's name, e.g. `run_terminal_cmd`. The only kind signal
    /// available at announcement time.
    pub name: String,
    /// Cursor's status word (`running`, `completed`, …) — free-form on the
    /// wire, mapped to ACP statuses by the translation.
    #[serde(default)]
    pub status: Option<String>,
    /// Raw tool input, when present.
    #[serde(default)]
    pub args: Option<Value>,
    /// Raw tool output, when present.
    #[serde(default)]
    pub result: Option<Value>,
    /// Which halves of the call Cursor truncated for transport.
    #[serde(default, deserialize_with = "lenient_truncation")]
    pub truncated: Truncation,
}

/// Which halves of a tool call Cursor truncated for transport.
///
/// Observed on the wire as an object — `{"result": true}` in
/// `fixtures/real/list_and_delete.sse`. It was originally modelled as a bare
/// `bool`, which meant that object failed to deserialize and took the entire
/// `tool_call` event down with it: the call degraded to
/// [`CursorEvent::Unknown`] and disappeared from the client, over a field the
/// translation never reads.
///
/// `args` is included because it is the only other half there is to truncate;
/// no recording has shown it yet, so it defaults to false like any absent
/// field.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Truncation {
    /// Cursor truncated the tool's input.
    #[serde(default)]
    pub args: bool,
    /// Cursor truncated the tool's output.
    #[serde(default)]
    pub result: bool,
}

/// Read a [`Truncation`], falling back to "nothing truncated" for any shape
/// this crate does not recognize.
///
/// Deliberately lenient where the rest of this module is strict: everywhere
/// else a shape mismatch costs one event, but here it would cost the whole
/// tool call — and this is the one field on a `tool_call` nothing downstream
/// consumes. A drifted shape should lose the flag, not the call. The corpus
/// sweep is what surfaces the drift.
fn lenient_truncation<'de, D>(deserializer: D) -> Result<Truncation, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let value = Value::deserialize(deserializer)?;
    Ok(Truncation::deserialize(&value).unwrap_or_default())
}

/// The `interaction_update` subtypes that carry information no documented
/// event does. `text-delta` and `thinking-delta` duplicate the `assistant`
/// and `thinking` events one-for-one — consuming both would double every
/// chunk — so they land in [`InteractionUpdate::Other`] and are ignored.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum InteractionUpdate {
    /// The user's prompt echoed back into the stream. The one place the
    /// stream states which prompt opened the turn.
    UserMessage {
        /// The prompt text.
        text: String,
    },
    /// A tool call began, with Cursor's *typed* tool descriptor — richer
    /// than the `tool_call` event's bare name, but it always arrives after
    /// it, so it can only refine later updates.
    ToolCallStarted {
        /// The same call id the `tool_call` event uses.
        call_id: String,
        /// Cursor's tool type, e.g. `shell`.
        tool_type: Option<String>,
    },
    /// A tool call finished, same descriptor.
    ToolCallCompleted {
        /// The same call id the `tool_call` event uses.
        call_id: String,
        /// Cursor's tool type, e.g. `shell`.
        tool_type: Option<String>,
    },
    /// Incremental output token count for the current step.
    TokenDelta {
        /// Tokens since the previous report.
        tokens: u64,
    },
    /// A subtype that carries nothing the documented events do not.
    Other {
        /// The subtype's `type` tag, for logging.
        kind: String,
    },
}

impl CursorEvent {
    /// Decode one SSE record into the vocabulary.
    ///
    /// Malformed payloads for known events degrade to [`CursorEvent::Unknown`]
    /// rather than erroring: a stream that has already cost a run should not
    /// die because one record's shape drifted.
    #[must_use]
    pub fn from_wire(event: &str, data: Value) -> Self {
        match event {
            "status" => match StatusPayload::deserialize(&data) {
                Ok(payload) => Self::Status {
                    run_id: CursorRunId::new(payload.run_id),
                    status: payload.status,
                },
                Err(_) => Self::unknown(event, data),
            },
            "assistant" | "thinking" => match TextPayload::deserialize(&data) {
                Ok(payload) if event == "assistant" => Self::Assistant { text: payload.text },
                Ok(payload) => Self::Thinking { text: payload.text },
                Err(_) => Self::unknown(event, data),
            },
            "tool_call" => match ToolCallEvent::deserialize(&data) {
                Ok(call) => Self::ToolCall(call),
                Err(_) => Self::unknown(event, data),
            },
            "interaction_update" => Self::Interaction(InteractionUpdate::from_payload(&data)),
            "result" => match ResultPayload::deserialize(&data) {
                Ok(payload) => Self::Result {
                    run_id: CursorRunId::new(payload.run_id),
                    status: payload.status,
                    text: payload.text,
                    duration_ms: payload.duration_ms,
                    git: payload.git,
                },
                Err(_) => Self::unknown(event, data),
            },
            "heartbeat" => Self::Heartbeat,
            "error" => match ErrorPayload::deserialize(&data) {
                Ok(payload) => Self::Error {
                    code: payload.code,
                    message: payload.message,
                },
                Err(_) => Self::unknown(event, data),
            },
            "done" => Self::Done,
            _ => Self::unknown(event, data),
        }
    }

    fn unknown(event: &str, data: Value) -> Self {
        Self::Unknown {
            event: event.to_owned(),
            data,
        }
    }
}

impl InteractionUpdate {
    /// Decode the envelope's payload by its `type` tag.
    ///
    /// The tag is *in* the payload here — unlike an SSE record, whose event
    /// name arrives as separate framing — so the dispatch is serde's
    /// [`KnownInteraction`] rather than a hand-written match on strings.
    ///
    /// The fallback stays hand-written for one reason: `#[serde(other)]`
    /// accepts only unit variants, and [`InteractionUpdate::Other`] keeps the
    /// tag it did not recognize, which is the whole point of it.
    fn from_payload(data: &Value) -> Self {
        match KnownInteraction::deserialize(data) {
            Ok(known) => known.into(),
            Err(_) => Self::Other {
                kind: data
                    .get("type")
                    .and_then(Value::as_str)
                    .unwrap_or_default()
                    .to_owned(),
            },
        }
    }
}

/// The `interaction_update` subtypes this crate reads, as serde sees them.
///
/// Separate from [`InteractionUpdate`] because the wire shape and the domain
/// shape disagree on purpose: the wire nests the text under `userMessage` and
/// the tool type under `toolCall`, and the domain wants neither wrapper.
#[derive(Deserialize)]
#[serde(tag = "type", rename_all = "kebab-case")]
enum KnownInteraction {
    #[serde(rename_all = "camelCase")]
    UserMessageAppended {
        #[serde(default)]
        user_message: MessageText,
    },
    /// `partial-tool-call` carries exactly what `tool-call-started` does — a
    /// call id and Cursor's typed descriptor — for a call whose arguments are
    /// still streaming. Nothing on it is unique (the `tool_call` event repeats
    /// the arguments in full, and every recorded call that sends a partial
    /// also sends a started), so it aliases onto the same variant rather than
    /// being dropped as unrecognized.
    #[serde(rename_all = "camelCase", alias = "partial-tool-call")]
    ToolCallStarted {
        #[serde(default)]
        call_id: String,
        #[serde(default)]
        tool_call: ToolDescriptor,
    },
    #[serde(rename_all = "camelCase")]
    ToolCallCompleted {
        #[serde(default)]
        call_id: String,
        #[serde(default)]
        tool_call: ToolDescriptor,
    },
    TokenDelta {
        #[serde(default)]
        tokens: u64,
    },
}

impl From<KnownInteraction> for InteractionUpdate {
    fn from(known: KnownInteraction) -> Self {
        match known {
            KnownInteraction::UserMessageAppended { user_message } => Self::UserMessage {
                text: user_message.text,
            },
            KnownInteraction::ToolCallStarted { call_id, tool_call } => Self::ToolCallStarted {
                call_id,
                tool_type: tool_call.kind,
            },
            KnownInteraction::ToolCallCompleted { call_id, tool_call } => Self::ToolCallCompleted {
                call_id,
                tool_type: tool_call.kind,
            },
            KnownInteraction::TokenDelta { tokens } => Self::TokenDelta { tokens },
        }
    }
}

/// The `userMessage` wrapper, whose only interesting field is the text.
#[derive(Deserialize, Default)]
struct MessageText {
    #[serde(default)]
    text: String,
}

/// The `toolCall` wrapper. `type` is Cursor's typed tool descriptor, richer
/// than the `tool_call` event's bare name; absent on shapes that predate it.
#[derive(Deserialize, Default)]
struct ToolDescriptor {
    #[serde(default, rename = "type")]
    kind: Option<String>,
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct StatusPayload {
    run_id: String,
    status: RunStatus,
}

#[derive(Deserialize)]
struct TextPayload {
    text: String,
}

#[derive(Deserialize)]
#[serde(rename_all = "camelCase")]
struct ResultPayload {
    run_id: String,
    status: RunStatus,
    #[serde(default)]
    text: Option<String>,
    #[serde(default)]
    duration_ms: Option<u64>,
    #[serde(default)]
    git: Option<GitState>,
}

#[derive(Deserialize)]
struct ErrorPayload {
    #[serde(default)]
    code: Option<String>,
    message: String,
}