Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
//! Native capture contract and the shared live/load processing machine.
use super::artifact::{CollectedArtifact, artifact_markdown};
use super::event::{CursorEvent, InteractionUpdate};
use super::inline_image::InlineImageFilter;
use super::model::{CursorRunId, RunOutcome, RunStatus};
use super::translate::TranslateMachine;
use agent_client_protocol::schema::v1::{
ContentBlock, ContentChunk, SessionId, SessionUpdate, TextContent,
};
use futures::future::BoxFuture;
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, HashMap};
/// A complete SSE message, before JSON decoding. IDs are observations, never
/// local sequence numbers or an assumed remote resume token.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NativeRecord {
/// SSE event name.
pub event: String,
/// Original data lines joined by the SSE decoder.
pub data: String,
/// Provider's SSE last-event ID, when supplied.
pub id: Option<String>,
}
impl NativeRecord {
/// Whether this record participates in reconnect prefix matching. This
/// examines framing only; native payload decoding happens after append.
pub(crate) fn is_content(&self) -> bool {
!matches!(self.event.as_str(), "status" | "heartbeat" | "error")
}
/// Decode only after this record is durably captured.
pub fn decode(&self) -> CursorEvent {
CursorEvent::from_wire(
&self.event,
serde_json::from_str(&self.data).unwrap_or_default(),
)
}
}
/// Inputs, not a second ACP transcript. Every synthetic update has an input.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum JournalInput {
/// History is known from its beginning (fresh session or full hydration).
HistoryComplete,
/// Original ACP prompt blocks, associated with the run that accepted them.
Prompt(Vec<ContentBlock>),
/// Links a pre-execution prompt sequence to its accepted provider run.
PromptAccepted(i64),
/// A pre-execution prompt was cancelled/rejected without a run.
PromptAborted(i64),
/// Transport failure, retained without prematurely closing running tools.
TransportError(String),
/// The run's stream broke or went silent and a reconnect was attempted.
///
/// Journaled rather than merely logged because the journal is the durable
/// record of what the transport did: a transcript with a gap in it is only
/// explicable if the gap's cause is in the same ordered record as the
/// content around it, and a later replay of the session has no other way
/// to know a reconnect happened here. Like
/// [`JournalInput::TransportError`] it projects to nothing — it is a fact
/// about the connection, never about the conversation.
StreamInterrupted {
/// What broke, in the transport's own words.
reason: String,
/// The last provider event id captured before the break, if any; what
/// the reconnect resumed from.
last_event_id: Option<String>,
/// Which reconnect attempt this interruption started, from one.
attempt: u32,
},
/// Raw complete provider message, including unknown payloads.
Sse(NativeRecord),
/// Original successful polling response body.
Poll(String),
/// A local terminal decision (e.g. stop during a disconnected poll).
Interrupted(String),
/// The walkthrough files this run produced, re-hosted and durable.
///
/// Journaled before the text announcing them is sent, so a crash between
/// the two re-announces on replay rather than losing files nobody can
/// fetch again — Cursor's own download links last fifteen minutes.
/// Carries the collected list rather than the rendered markdown because
/// the rendering is a pure function of it
/// ([`artifact_markdown`](super::artifact::artifact_markdown)), and one
/// copy of it is the only way live and replay cannot disagree.
ArtifactsCollected(Vec<CollectedArtifact>),
/// Capture has reconciled this run; distinct from ACP delivery checkpoint.
Reconciled,
}
/// One input in explicit session order; run membership uses provider IDs.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct JournalEntry {
/// Monotonically increasing session sequence, starting at one.
pub sequence: i64,
/// Provider run; absent only for session-level facts.
pub run: Option<CursorRunId>,
/// The captured native input.
pub input: JournalInput,
}
/// Session-scoped durable storage. Implementations must reject stale owners
/// and compare `expected` to the current high-water mark atomically with append.
/// Reads and writes are never exposed as a public provider-history endpoint.
pub trait CursorJournal: Send + Sync + std::fmt::Debug {
/// A stable ordered snapshot under the caller's session turn gate.
fn read<'a>(
&'a self,
session: &'a SessionId,
) -> BoxFuture<'a, Result<Vec<JournalEntry>, rootcause::Report>>;
/// Append before processing; failure must leave both progress and output unchanged.
fn append<'a>(
&'a self,
session: &'a SessionId,
expected: i64,
run: Option<&'a CursorRunId>,
input: &'a JournalInput,
) -> BoxFuture<'a, Result<JournalEntry, rootcause::Report>>;
}
#[derive(Debug, Default)]
struct RunState {
prompt: bool,
text: String,
terminal: Option<RunStatus>,
/// What the reader sees of `text`: the same stream minus the `<img>`
/// tags Cursor writes for files only its sandbox can reach.
images: InlineImageFilter,
/// Whether the transport broke after the last content record, so that
/// `text` may be missing its end. Set by an interruption, cleared by
/// the next content record: a resume that continues the stream leaves
/// no gap, and only a run whose outcome then arrives by polling is
/// still behind when its final text is compared.
interrupted: bool,
}
/// Complete live/replay state, including user prompts and terminal tool cleanup.
#[derive(Debug, Default)]
pub struct ReplayMachine {
translator: TranslateMachine,
runs: HashMap<CursorRunId, RunState>,
}
impl ReplayMachine {
/// Latest branches recovered from native results or fallback polling.
pub fn working_branches(&self) -> &BTreeMap<String, String> {
self.translator.working_branches()
}
/// Latest PR recovered from native results or fallback polling.
pub fn pull_request_url(&self) -> Option<&str> {
self.translator.pull_request_url()
}
/// Whether the run's original prompt is reconstructable.
pub fn has_prompt(&self, run: &CursorRunId) -> bool {
self.runs.get(run).is_some_and(|s| s.prompt)
}
/// Whether native history contains a prompt and a terminal fact for a run.
pub fn complete(&self, run: &CursorRunId) -> bool {
self.runs
.get(run)
.is_some_and(|s| s.prompt && s.terminal.is_some())
}
/// The run's answer as this journal captured it, empty string and all.
///
/// Only the final step's text: a new step clears what came before, the
/// same way Cursor's own final text keeps only the last step. That is
/// what makes it comparable with a line of the agent's conversation.
pub fn answer(&self, run: &CursorRunId) -> Option<&str> {
self.runs.get(run).map(|state| state.text.as_str())
}
/// Durable provider terminal status, independent of the reconciliation marker.
pub fn terminal_status(&self, run: &CursorRunId) -> Option<RunStatus> {
self.runs.get(run).and_then(|s| s.terminal.clone())
}
/// Process one journal input, identically during capture and replay.
///
/// Every error here costs the whole session, permanently. Capture appends
/// before it projects, so a payload that reaches this point is already
/// durable: refusing it now refuses it again on every later replay, and a
/// session whose journal cannot be replayed can never be loaded or
/// prompted again. So failing is only right where the alternative is
/// worse than losing the session - reporting an outcome nobody has read
/// as a success, say. Wherever a sound reading of the payload exists,
/// take it and report the surprise instead.
pub fn push(
&mut self,
run: Option<&CursorRunId>,
input: &JournalInput,
) -> Result<Vec<SessionUpdate>, rootcause::Report> {
let Some(run) = run else {
// Original requests also belong to history when they were stopped
// before a remote run existed. Acceptance later only binds state.
return Ok(match input {
JournalInput::Prompt(blocks) => blocks
.iter()
.cloned()
.map(|b| SessionUpdate::UserMessageChunk(ContentChunk::new(b)))
.collect(),
_ => Vec::new(),
});
};
let state = self.runs.entry(run.clone()).or_default();
match input {
JournalInput::Prompt(blocks) => {
if state.prompt {
return Ok(Vec::new());
}
state.prompt = true;
Ok(blocks
.iter()
.cloned()
.map(|b| SessionUpdate::UserMessageChunk(ContentChunk::new(b)))
.collect())
}
JournalInput::Sse(record) => {
if record.is_content() {
state.interrupted = false;
}
self.event(run, record.decode())
}
JournalInput::ArtifactsCollected(artifacts) => {
if artifacts.is_empty() {
return Ok(Vec::new());
}
Ok(vec![SessionUpdate::AgentMessageChunk(ContentChunk::new(
ContentBlock::Text(TextContent::new(artifact_markdown(artifacts))),
))])
}
JournalInput::Poll(raw) => {
let value: serde_json::Value =
serde_json::from_str(raw).map_err(|e| rootcause::report!(e))?;
let status: RunStatus = serde_json::from_value(value["status"].clone())
.map_err(|e| rootcause::report!(e))?;
let text = value
.get("result")
.or_else(|| value.get("text"))
.and_then(|s| s.as_str())
.map(str::to_owned);
let outcome = RunOutcome {
status: status.clone(),
text: text.clone(),
};
if !outcome.is_terminal() {
return Ok(Vec::new());
}
let git = value
.get("git")
.filter(|git| !git.is_null())
.map(|git| serde_json::from_value(git.clone()))
.transpose()
.map_err(|error| rootcause::report!(error))?;
self.event(
run,
CursorEvent::Result {
run_id: run.clone(),
status,
text,
duration_ms: None,
git,
},
)
}
JournalInput::Interrupted(_) => {
// This closes local work, but does not claim remote capture is complete.
Ok(self.translator.close_open_calls())
}
JournalInput::TransportError(_) | JournalInput::StreamInterrupted { .. } => {
state.interrupted = true;
Ok(Vec::new())
}
JournalInput::HistoryComplete
| JournalInput::Reconciled
| JournalInput::PromptAccepted(_)
| JournalInput::PromptAborted(_) => Ok(Vec::new()),
}
}
fn event(
&mut self,
run: &CursorRunId,
event: CursorEvent,
) -> Result<Vec<SessionUpdate>, rootcause::Report> {
let state = self.runs.entry(run.clone()).or_default();
match event {
// A terminal lifecycle frame is a terminal fact here for the same
// reason it is one in the session service: a run whose `result`
// never arrives still ended, and a projection that only learns
// outcomes from `result` leaves such a turn open forever on every
// replay — no `turn_complete`, and tool calls still rendering as
// in progress. Ordinarily `result` follows a frame later and does
// the rest; this is what happens when it does not.
CursorEvent::Status { status, .. } if status.is_terminal() => {
state.terminal = Some(status);
let mut updates = self.translator.push(CursorEvent::Assistant {
text: state.images.flush(),
});
updates.extend(self.translator.close_open_calls());
Ok(updates)
}
CursorEvent::Interaction(InteractionUpdate::Other { kind })
if kind == "step-started" =>
{
// Cursor's final result contains the final step, not earlier
// commentary emitted before tool execution in the same run.
state.text.clear();
Ok(self.translator.push(CursorEvent::Assistant {
text: state.images.flush(),
}))
}
CursorEvent::Interaction(InteractionUpdate::UserMessage { text }) => {
if state.prompt {
return Ok(Vec::new());
}
state.prompt = true;
Ok(vec![SessionUpdate::UserMessageChunk(ContentChunk::new(
ContentBlock::Text(TextContent::new(text)),
))])
}
CursorEvent::Assistant { text } => {
state.text.push_str(&text);
let text = state.images.push(&text);
Ok(self.translator.push(CursorEvent::Assistant { text }))
}
CursorEvent::Result {
run_id,
status,
text,
duration_ms,
git,
} => {
if !matches!(
status,
RunStatus::Finished | RunStatus::Cancelled | RunStatus::Error
) {
return Err(rootcause::report!("nonterminal Cursor result for {run}"));
}
let mut updates = Vec::new();
if let Some(text) = text {
// The final text restates the answer rather than continuing
// it, and the restatement is not the streamed text: Cursor
// drops inline images from it, and nothing promises that is
// the only rewrite. So text that literally continues what
// was captured is the missing suffix of a stream that
// polling overtook, and is appended; anything else is the
// same answer said differently, and the captured stream -
// what the user watched arrive - stays as it is.
match text.strip_prefix(state.text.as_str()) {
Some(suffix) => {
updates.extend(self.translator.push(CursorEvent::Assistant {
text: state.images.push(suffix),
}));
state.text = text;
}
// The stream broke and nothing came after it, so the
// captured text is the front of an answer whose end
// was never streamed. Streamed chunks cannot be taken
// back, so the whole answer follows as its own
// passage: the user sees the fragment and then the
// answer, rather than the fragment alone.
None if state.interrupted => {
tracing::warn!(
%run,
captured = state.text.len(),
restated = text.len(),
"Cursor restated the answer after a stream gap; appending it whole"
);
let separator = if state.text.is_empty() || state.text.ends_with('\n') {
""
} else {
"\n\n"
};
updates.extend(self.translator.push(CursorEvent::Assistant {
text: state.images.push(&format!("{separator}{text}")),
}));
state.text = text;
}
None => tracing::warn!(
%run,
captured = state.text.len(),
restated = text.len(),
"Cursor restated the answer; keeping the streamed text"
),
}
}
updates.extend(self.translator.push(CursorEvent::Assistant {
text: state.images.flush(),
}));
updates.extend(self.translator.push(CursorEvent::Result {
run_id,
status: status.clone(),
text: None,
duration_ms,
git,
}));
state.terminal = Some(status);
updates.extend(self.translator.close_open_calls());
Ok(updates)
}
event => Ok(self.translator.push(event)),
}
}
}
#[cfg(test)]
mod test;