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
//! The session service: the use cases an ACP client can drive.
//!
//! One ACP session maps to one Cursor agent, created lazily on the first
//! prompt (Cursor mints an agent and its first run together). Each later
//! prompt opens a follow-up run on the same agent, so the conversation
//! accumulates server-side. A turn is: create the run, stream its events,
//! translate each into session updates, deliver them through the notifier,
//! and answer with the ACP stop reason once the stream ends.
//!
//! Concurrency: ACP turns are strictly sequential per session, and the
//! service enforces that — a second prompt while one is streaming is an
//! error, not a queue. `session/cancel` is the exception: it must land *while*
//! a turn is streaming, so cancellation state lives behind a lock the
//! streaming loop never holds across an await.
//!
//! `session/cancel` is a notification we pump into Cursor: `POST
//! /v1/agents/{id}/runs/{runId}/cancel`. The turn itself keeps reading the
//! run's stream until Cursor's terminal `result` frame (then `done`) — the
//! same way a finished run ends. Cancellation is terminal on Cursor's side;
//! that `result` is what closes the ACP prompt.
//!
//! The cancellation token never cuts a live stream short — that is the whole
//! point of the paragraph above. It ends the waits where there is nothing to
//! read: a prompt queued behind `agent_busy`, and the fallback poll, which
//! only runs because the stream is gone. Reading `GET …/runs/{run}` once more
//! after the user has stopped buys nothing a stopped turn reports anyway, so
//! the poll's wait is where a stop lands.
//!
//! The remote cancel still needs a run id, and this process only remembers
//! one for a turn it is itself streaming. A session restored after a restart,
//! or one whose run started from cursor.com, has no such memory — cancelling
//! it falls back to asking Cursor which run is current rather than silently
//! skipping the remote call. A stop that beats the run into existence has
//! nothing to fall back to, so [`CursorSessionService::prompt`] re-sends it
//! the moment the run has an id; otherwise the stop would be swallowed and
//! the turn would run to the agent's own natural end.
#[cfg(test)]
mod test;
use crate::domain::artifact::{ArtifactListing, CollectedArtifact, inline_text, mime_type};
use crate::domain::error::{PromptRefusal, RunFailed, SessionError};
use crate::domain::event::CursorEvent;
use crate::domain::journal::{CursorJournal, JournalEntry, JournalInput, ReplayMachine};
use crate::domain::model::{
ConversationLine, ConversationSpeaker, CursorAgentId, CursorModel, CursorRunId, McpServer,
ModelChoice, RepoUrl, RunStatus,
};
use crate::domain::ports::{
ArtifactStore, CursorAgents, CursorArtifacts, NoPromptImageFetcher, PromptImageFetcher,
RepositoryChooser, RunStream, SessionIntent, SessionNotifier, StreamConnectError,
};
use crate::domain::prompt_image::{self, CursorPromptImage};
use agent_client_protocol::schema::v1::{
ContentBlock, SessionId, SessionUpdate, StopReason, TextContent,
};
use futures::StreamExt as _;
use futures::pin_mut;
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use std::sync::{Arc, Mutex};
/// How often a wait that is not about the run's outcome asks again: the
/// busy-agent queue, and a poll retried after a transport error.
const POLL_INTERVAL: std::time::Duration = std::time::Duration::from_secs(2);
/// The fallback poll's cadence: quick at first, when a run that has just gone
/// quiet is most likely about to end, then settling at [`POLL_INTERVAL_CEILING`].
///
/// Two facts from the journals set the shape. `GET /v1/agents/{id}/runs/{run}`
/// is limited to 300 requests a minute per API key, shared by every session
/// this deployment drives, and a two-second poll from a dozen stalled
/// sessions was enough to draw a 429 (dev, 2026-09-19). And a run's record
/// carries no liveness signal while it is `RUNNING` — `updatedAt` moves only
/// on status transitions — so asking more often learns nothing sooner.
const POLL_DELAYS: [std::time::Duration; 11] = [
std::time::Duration::from_secs(2),
std::time::Duration::from_secs(2),
std::time::Duration::from_secs(2),
std::time::Duration::from_secs(2),
std::time::Duration::from_secs(2),
std::time::Duration::from_secs(3),
std::time::Duration::from_secs(5),
std::time::Duration::from_secs(8),
std::time::Duration::from_secs(12),
std::time::Duration::from_secs(20),
std::time::Duration::from_secs(30),
];
/// Where the poll cadence settles: two requests a minute per waiting session.
const POLL_INTERVAL_CEILING: std::time::Duration = std::time::Duration::from_secs(30);
/// Polls before a turn stops waiting — about two hours along [`POLL_DELAYS`].
///
/// This is a ceiling for a run that Cursor still calls `RUNNING`, not an
/// estimate of how long one takes. The old fifteen-minute budget was sized
/// to a recorded corpus of short runs; live, a run that opened its pull
/// request at 19:55 had its turn abandoned at 19:54, and every "gave up
/// waiting" in three days of production logs was a run that was merely
/// slow. A turn that stops waiting cannot be resumed, so the budget errs
/// long: the chip shows the session working the whole time.
const POLL_ATTEMPTS: usize = 250;
/// How long the fallback poll sleeps before its `attempt`-th ask.
fn poll_delay(attempt: usize) -> std::time::Duration {
POLL_DELAYS
.get(attempt)
.copied()
.unwrap_or(POLL_INTERVAL_CEILING)
}
/// Consecutive poll failures tolerated before the turn takes the error.
const POLL_ERROR_TOLERANCE: usize = 5;
/// A stream this quiet gets its run's record checked. Observed live: the
/// final text arrives and the stream then hangs open, its terminal `result`
/// minutes behind — and the client shows a turn still "writing" long after
/// the answer is on screen. Long enough to never fire during ordinary
/// streaming; short enough that a finished run closes its turn promptly.
const STREAM_QUIET_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(10);
/// How long a stream that has already been found quiet waits between the
/// next checks of its run's record. Slower than the first check on purpose:
/// the record endpoint's rate limit is shared by every session (see
/// [`POLL_DELAYS`]), and a run that was still going ten seconds ago is most
/// likely still going now.
const STREAM_QUIET_RECHECK: std::time::Duration = std::time::Duration::from_secs(30);
/// Silence on an open stream before its connection is replaced.
///
/// Cursor does not heartbeat an open stream: the journals show runs saying
/// nothing for many minutes while their record stays `RUNNING` — a tool call
/// waiting on CI (`await`, `blockUntilMs: 120000`), a long build — and every
/// reconnect in that window resumed zero records. So silence on a run the
/// record still calls live is the agent working, and the connection is
/// kept. Only silence this long buys a fresh connection, as insurance
/// against a socket that died without saying so, and it costs nothing
/// from the reconnect budget: that budget is for a transport that is
/// failing, and this one merely has nothing to say.
const STREAM_SILENCE_BEFORE_RECONNECT: std::time::Duration = std::time::Duration::from_secs(120);
/// Backoff before each reconnect of an interrupted stream.
///
/// Observed twice in production: the SSE body fails mid-run during a long tool
/// call while the run itself carries on fine, and everything Cursor says
/// between the drop and the run's end — tool results, prose, the images it
/// writes into prose — never reaches the transcript. Resuming from the last
/// event id gets that back; the ramp keeps a provider that is actually down
/// from being hammered.
const STREAM_RECONNECT_DELAYS: [std::time::Duration; 5] = [
std::time::Duration::from_millis(500),
std::time::Duration::from_secs(1),
std::time::Duration::from_secs(2),
std::time::Duration::from_secs(4),
std::time::Duration::from_secs(8),
];
/// Reconnects before a run gives up on its stream and polls instead. Counted
/// since the last reconnect that delivered content and then stayed up (see
/// [`STREAM_HEALTHY_RESUME`]), so a long run that drops repeatedly but
/// recovers each time is never rationed.
const STREAM_RECONNECT_ATTEMPTS: usize = 5;
/// How long a resumed connection has to stay up, once it has delivered,
/// before it counts as the transport working again and refills the budget.
///
/// Every resume in one day's incidents (prod, 2026-09-26, eight runs)
/// delivered its whole backlog in a burst and failed within the second, from
/// the very id it had just advanced to. Refilling on delivery alone made
/// each of those a fresh first attempt: the budget never ran down, the
/// attempt counter in every log line read `1`, and nothing could say "this
/// transport has been failing for an hour". A connection that outlives this
/// after delivering is one the provider is genuinely streaming on.
const STREAM_HEALTHY_RESUME: std::time::Duration = std::time::Duration::from_secs(5);
/// Connects that stall before their headers, on a run whose stream never
/// opened, before the turn stops trying and polls the record instead.
///
/// Once a stream has opened, stalls are not counted against anything: the
/// run's record is checked on each, so a finished run ends its turn within
/// a stall of finishing, and a run still going is still worth the stream.
/// Before it has ever opened there is nothing to resume, and a connect that
/// stalls three times running is a stream that is not going to open.
const STALLED_CONNECTS_BEFORE_POLLING: u32 = 3;
/// How long a prompt waits behind a run something else started (the same
/// agent is drivable from cursor.com) before giving up, in poll intervals.
const BUSY_ATTEMPTS: usize = 450;
/// How soon after the mirror's last live frame a prompt is taken to have been
/// sent while that frame was still on its way.
///
/// The client opens a prompt's turn when it sends the prompt; the request
/// reaches this service a pipe hop later, in milliseconds. Mirror frames sent
/// in between land inside that turn, and nothing here can tell which, so such
/// a prompt asks for a reload that puts the mirrored run back in its place.
/// Generous on purpose: a false positive costs one reload.
const MIRROR_PROMPT_OVERLAP: std::time::Duration = std::time::Duration::from_secs(2);
/// How long a prompt waits for the turn gate while a background mirror is
/// following a run started elsewhere, before giving up.
///
/// The same budget as [`BUSY_ATTEMPTS`], because it is the same wait seen
/// from one step earlier: the mirror follows exactly the run that Cursor
/// would answer `agent_busy` for. Observed live (prod, 2026-09-27): a mirror
/// following a run Cursor never ended held the gate for hours, the prompt
/// behind it never started, and everything queued after it never sent. The
/// wait has to end somewhere the person can see.
const GATE_WAIT_BUDGET: std::time::Duration =
std::time::Duration::from_secs(BUSY_ATTEMPTS as u64 * POLL_INTERVAL.as_secs());
/// How long a turn that saw no new artifacts waits before listing once more.
///
/// Cursor uploads a run's artifacts as the run finishes, so the listing can
/// still be empty a moment after the terminal frame that ended the turn. The
/// trade is plain: every turn that produced nothing pays this before it
/// answers, and without it a walkthrough's screenshots are silently missing
/// from the turn that took them. Five seconds is long enough to cover the
/// upload lag seen in practice and short enough to read as the turn ending.
const ARTIFACT_LISTING_RETRY_DELAY: std::time::Duration = std::time::Duration::from_secs(5);
/// The largest artifact this service will pull into memory, 64 MiB.
///
/// Read from the listing's `sizeBytes`, so an oversized recording is declined
/// before a byte of it is fetched. Well past any screenshot and past most
/// screen recordings; a run that produces something bigger loses that one
/// file, loudly, rather than the process losing its memory.
const MAX_ARTIFACT_BYTES: u64 = 64 * 1024 * 1024;
/// Whether a captured frame reaches the client as it is journaled.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Emit {
/// Published as captured: the frames of this session's own turn.
Live,
/// Journaled only, for a load to show.
Silent,
/// A run started on cursor.com, mirrored into an idle session: published
/// as captured, exactly like a turn, unless a prompt is waiting behind
/// the mirror. That prompt's turn is already open on the client, and the
/// run's frames would render inside it, so they are withheld instead and
/// the sweep asks for a reload.
Mirror,
}
#[derive(Clone, Copy)]
struct IngestMode {
emit: Emit,
strict: bool,
attempt: usize,
}
impl IngestMode {
const LIVE: Self = Self {
emit: Emit::Live,
strict: false,
attempt: 0,
};
const HYDRATE: Self = Self {
emit: Emit::Silent,
strict: true,
attempt: 0,
};
}
/// Wait out `duration`, unless the client cancels first. `true` means it did.
///
/// Every wait a turn can be parked in goes through this, so a cancel is felt
/// within a scheduler tick rather than at the end of whatever interval happened
/// to be running.
async fn sleep_unless_cancelled(
cancel: &tokio_util::sync::CancellationToken,
duration: std::time::Duration,
) -> bool {
tokio::select! {
biased;
() = cancel.cancelled() => true,
() = tokio::time::sleep(duration) => false,
}
}
/// Why a stream connection ended without the run's outcome.
struct Interruption {
reason: String,
/// Whether a fresh connection could still deliver the run.
recoverable: bool,
/// The connection was replaced for saying nothing, not for failing.
quiet: bool,
}
impl Interruption {
fn failed(reason: String) -> Self {
Self {
reason,
recoverable: true,
quiet: false,
}
}
}
/// The run's content records already durable in this session's journal.
///
/// What a stream read from the beginning is reconciled against: every record
/// here must arrive again, in order, before anything new is appended. Recomputed
/// rather than captured once, because a reconnect that restarts the stream has
/// to account for what the interrupted connection already appended.
fn captured_content(
session: &Session,
run: &CursorRunId,
) -> Vec<crate::domain::journal::NativeRecord> {
session
.state
.lock()
.expect("session state poisoned")
.journal_entries
.iter()
.filter(|entry| entry.run.as_ref() == Some(run))
.filter_map(|entry| match &entry.input {
JournalInput::Sse(record) if record.is_content() => Some(record.clone()),
_ => None,
})
.collect()
}
/// The turn's failure for a run Cursor ended in neither finished nor
/// cancelled.
///
/// The span and the log keep everything Cursor said about the run: its
/// terminal status and the last `error` event journaled for it. The person
/// gets a notice pointing at the run's page, the only place the reason is.
/// Read from the journal rather than the stream loop so a run whose terminal
/// status was recovered after a restart is reported the same way.
fn run_failure(
session: &Session,
agent: &CursorAgentId,
run: &CursorRunId,
status: RunStatus,
) -> SessionError {
let reported = session
.state
.lock()
.expect("session state poisoned")
.journal_entries
.iter()
.rev()
.filter(|entry| entry.run.as_ref() == Some(run))
.find_map(|entry| match &entry.input {
JournalInput::Sse(record) => match record.decode() {
CursorEvent::Error { code, message } => Some((code, message)),
_ => None,
},
_ => None,
});
let (code, message) = reported.unzip();
let code = code.flatten();
let span = tracing::Span::current();
span.record("cursor.run.error.code", code.as_deref());
span.record("cursor.run.error.message", message.as_deref());
tracing::warn!(
%agent,
cursor.run.id = %run,
cursor.run.status = ?status,
cursor.run.error.code = code.as_deref(),
cursor.run.error.message = message.as_deref(),
"Cursor ended the run in failure"
);
SessionError::Rejected(
RunFailed {
agent: agent.clone(),
status,
}
.refusal(),
)
}
/// Restate a rejection the person who prompted can act on - a repository
/// Cursor cannot reach, a Cursor account out of budget - in their terms,
/// leaving every other failure exactly as it arrived.
///
/// The result is a [`SessionError::Rejected`], so it takes the same path a
/// [`PromptRejected`](crate::domain::error::PromptRejected) already takes:
/// the prompt is journalled as aborted and the refusal travels to the client
/// as the `session/prompt` error. Cursor's own body stays in the tracing event —
/// it names codes and ids that mean nothing to a reader of the chip.
fn explain_rejection(error: SessionError) -> SessionError {
let SessionError::Cursor(report) = &error else {
return error;
};
if let Some(unavailable) =
report.downcast_current_context::<crate::domain::error::RepositoryUnavailable>()
{
tracing::warn!(
repo = %unavailable.repo,
reason = %unavailable.reason,
detail = %unavailable.detail,
"cursor rejected the prompt: it could not use the session's repository"
);
return SessionError::Rejected(PromptRefusal::plain(unavailable.user_message()));
}
if let Some(exceeded) =
report.downcast_current_context::<crate::domain::error::UsageLimitExceeded>()
{
tracing::warn!(
code = %exceeded.code,
detail = %exceeded.detail,
"cursor rejected the prompt: the account's usage limit is exhausted"
);
return SessionError::Rejected(exceeded.refusal());
}
error
}
/// A user chunk that restates the prompt the client already sent.
///
/// An image frame does not: it was fetched from a pasted link, and the live
/// transcript learns the picture from this update.
fn restates_the_prompt(update: &SessionUpdate) -> bool {
matches!(
update,
SessionUpdate::UserMessageChunk(chunk)
if !matches!(chunk.content, ContentBlock::Image(_))
)
}
/// Whether a failed create is a definite refusal — the prompt never ran, so
/// it is journalled as aborted rather than left as an accepted turn.
fn is_prompt_rejection(error: &SessionError) -> bool {
match error {
SessionError::Rejected(_) => true,
#[cfg(feature = "postgres")]
SessionError::Admission(_) => true,
SessionError::Cursor(report) => report
.downcast_current_context::<crate::domain::error::PromptRejected>()
.is_some(),
_ => false,
}
}
/// A prompt Cursor refused before the session had an agent, and why.
#[derive(Debug, Clone, PartialEq, Eq)]
struct RejectedPrompt {
/// What the person asked, as it would have gone to Cursor.
text: String,
/// The refusal as it was shown to them, when there was a readable one.
reason: Option<String>,
}
/// The prompt that finally mints an agent, carrying the ones Cursor refused
/// before it so the agent reads the whole conversation the person had.
///
/// The framing tells the agent which message is current and that the earlier
/// ones were never acted on, so it neither re-does nor ignores them. Images
/// travel beside this text, on the prompt that is actually sent.
fn prompt_with_rejected(rejected: &[RejectedPrompt], prompt: &str) -> String {
if rejected.is_empty() {
return prompt.to_owned();
}
let mut text = String::from(
"The following earlier message(s) in this conversation never reached an agent: \
each attempt to start one was refused by Cursor. They are included so nothing the \
person asked is lost. The message under \"Latest message\" is the one to respond to.\n",
);
for earlier in rejected {
text.push_str("\n--- Earlier message ---\n");
text.push_str(&earlier.text);
if let Some(reason) = &earlier.reason {
text.push_str("\n(Refused with: ");
text.push_str(reason);
text.push(')');
}
text.push('\n');
}
text.push_str("\n--- Latest message ---\n");
text.push_str(prompt);
text
}
/// One session's mutable state. Guarded by a std mutex: every critical
/// section is a handful of field reads/writes, never an await.
#[derive(Debug, Default)]
struct SessionState {
/// The repository this session works on, once the first prompt chose one.
///
/// Mutable, and that is the point: a fresh session has no repository until
/// its first prompt is read, and a restored one carries back whatever that
/// prompt chose. Still needed after the agent exists - Cursor fixed the
/// repository at creation, and a restore has to hand the same one back.
repo: Option<RepoUrl>,
/// The first prompt's repository decision, kept until an agent exists.
///
/// Cursor can reject the create that follows the decision — a branch it
/// could not verify, a repository the account has not connected — and the
/// next prompt is then usually "what happened?", which is no evidence of
/// where the work belongs. So the decision is made once, on the prompt
/// that carried the evidence, and reused by every create attempt until
/// one succeeds. Cleared with the process: a restored session re-decides.
intent: Option<SessionIntent>,
/// Prompts Cursor refused before any agent existed, oldest first.
///
/// A refused prompt is journaled as aborted and never reaches Cursor; if
/// the next one alone minted the agent, the agent would answer a question
/// about a message it never saw. So they ride along with the prompt that
/// finally creates it. Cancelled prompts are deliberately not here — the
/// person withdrew those. Cleared once a prompt is accepted.
rejected_prompts: Vec<RejectedPrompt>,
/// The Cursor agent, once the first prompt has minted it.
agent: Option<CursorAgentId>,
/// The run currently streaming, so cancel knows what to cancel.
active_run: Option<CursorRunId>,
/// The last run this session itself drove to an end. The backfill
/// watermark: runs newer than this were driven from cursor.com and are
/// delivered before the next prompt. `None` means no watermark — a fresh
/// or restored session, whose history is already rendered or unknowable —
/// so nothing is backfilled rather than everything replayed.
last_run: Option<CursorRunId>,
/// Whether the ACP client has opened or loaded this session on the current
/// connection. Restored sessions must not emit recovered updates before
/// `session/load` re-establishes the host's routing for their session id.
ready_for_sync: bool,
/// Pause background capture while the host loads, without refusing prompts
/// it already dispatched before observing the recovery requirement.
reload_pending: bool,
/// Prompts parked behind a mirror's hold on the turn gate. Each one's
/// turn is already open on the client, so the mirror stops publishing
/// once one arrives.
prompts_waiting: usize,
/// Something journaled since the last load projected updates the client
/// was never sent. Until a load shows them, the mirror cannot deliver a
/// run by streaming it: the client would be missing whatever came
/// before, so the sweep captures silently and asks for a reload instead.
unshown: bool,
/// When the mirror last published a frame live; see
/// [`MIRROR_PROMPT_OVERLAP`].
mirror_published_at: Option<tokio::time::Instant>,
/// Set by cancel; read by the turn when its stream ends.
///
/// The *verdict*, not the mechanism: a cancel that raced the stream's own
/// ending still has to report `Cancelled`, so this outlives the token
/// below and is what the turn consults once it has stopped.
cancelled: bool,
/// Fired by cancel; awaited by every wait a turn can be sitting in.
///
/// The mechanism, and the reason a cancel is felt at once rather than
/// whenever Cursor happens to end the stream. Replaced per turn, so a
/// cancel can never carry into the next one.
cancel: tokio_util::sync::CancellationToken,
/// Fired by cancel; awaited by the background mirror of a run started
/// elsewhere ([`CursorSessionService::sync_foreign_runs`]).
///
/// Separate from `cancel`, which belongs to the turn: a mirror holds the
/// turn gate while a prompt may already be waiting behind it with its own
/// token installed, and a stop has to reach both. Replaced per mirror
/// sweep, so a stop can never carry into the next one. A stop is the only
/// thing that fires it — a prompt arriving behind the mirror waits for
/// it instead, because giving up on a run started from cursor.com would
/// leave that conversation's run marked abandoned and cancel it.
mirror_cancel: tokio_util::sync::CancellationToken,
/// The model this session's next run will use.
///
/// `None` means "whatever this user's own Cursor settings resolve to" —
/// Cursor falls back user default, then team, then system — which is the
/// right answer until a client says otherwise.
model: Option<ModelChoice>,
/// MCP servers the client named, applied when the first prompt creates
/// the agent. Mutable because they re-enter over the protocol: a
/// `session/load` carries the client's current list, which is the truth a
/// restored process has no other way to learn.
mcp_servers: Vec<McpServer>,
/// Carried across turns so tool-call ids stay deduplicated for the whole
/// session.
machine: ReplayMachine,
journal_entries: Vec<JournalEntry>,
journal_loaded: bool,
fresh: bool,
capture_failed: bool,
}
/// Counts a prompt as parked behind the mirror for as long as it is held.
struct WaitingPrompt<'session>(&'session Session);
impl<'session> WaitingPrompt<'session> {
/// The client opened this prompt's turn when it sent the prompt, before
/// it got here, so whatever the mirror streamed in between may already
/// sit inside that turn. Nothing can tell those frames apart, so the
/// mirror's run is left for a reload to put in its place.
fn new(session: &'session Session) -> Self {
let mut state = session.state.lock().expect("session state poisoned");
state.prompts_waiting += 1;
state.unshown = true;
drop(state);
Self(session)
}
}
impl Drop for WaitingPrompt<'_> {
fn drop(&mut self) {
self.0
.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.prompts_waiting -= 1;
}
}
/// A session shared between a streaming turn and a concurrent cancel.
#[derive(Debug)]
struct Session {
/// ACP working directory, used by the standalone repository chooser.
cwd: PathBuf,
/// Serializes turns against background foreign-run syncs, so a mirror of
/// cursor.com activity never interleaves its frames with a live turn's.
/// A prompt waits on it; a sync skips its tick instead. Never held by
/// `cancel`, which must land while a turn is streaming.
turn_gate: Arc<tokio::sync::Mutex<()>>,
state: Mutex<SessionState>,
}
/// The service behind the ACP handlers.
#[derive(Debug)]
pub struct CursorSessionService<Cursor, Notifier, Chooser, Store> {
journal: Arc<dyn CursorJournal>,
cursor: Cursor,
notifier: Notifier,
chooser: Chooser,
/// Where a turn's walkthrough files are re-hosted. A store that reports
/// itself unavailable turns artifact collection off entirely.
artifacts: Store,
sessions: Mutex<HashMap<SessionId, Arc<Session>>>,
/// Monotonic counter for minting session ids without a clock or RNG.
next_session: Mutex<u64>,
/// A model id this deployment pins, applied to every new session. `None`
/// leaves the choice to Cursor's own default resolution.
default_model_id: Option<String>,
/// The model this one session runs on, from the host's own session record:
/// what its owner picked for it, or the slug the host seeded it with.
/// Outranks [`Self::default_model_id`], which is only what a session gets
/// when nobody said otherwise.
///
/// A whole service per session is how the hosted deployment serves them,
/// so this sits beside the deployment default rather than on [`Session`].
host_model_id: Option<String>,
/// `GET /v1/models`, fetched once. The table is static for the life of a
/// process and every `session/new` would otherwise re-fetch it.
models: tokio::sync::Mutex<Option<Vec<CursorModel>>>,
/// Resolves pasted links into prompt images. Absent means links stay text.
images: Arc<dyn PromptImageFetcher>,
}
impl<Cursor, Notifier, Chooser, Store> CursorSessionService<Cursor, Notifier, Chooser, Store>
where
Cursor: CursorAgents + CursorArtifacts + RunStream,
Notifier: SessionNotifier,
Chooser: RepositoryChooser,
Store: ArtifactStore,
{
/// Wire the service to its ports.
pub fn new(
cursor: Cursor,
notifier: Notifier,
chooser: Chooser,
journal: Arc<dyn CursorJournal>,
artifacts: Store,
) -> Self {
Self {
journal,
cursor,
notifier,
chooser,
artifacts,
sessions: Mutex::new(HashMap::new()),
next_session: Mutex::new(0),
default_model_id: None,
host_model_id: None,
models: tokio::sync::Mutex::new(None),
images: Arc::new(NoPromptImageFetcher),
}
}
/// Fetch pasted links and attach the ones that are images.
#[must_use]
pub fn with_image_fetcher(mut self, images: Arc<dyn PromptImageFetcher>) -> Self {
self.images = images;
self
}
/// Pin the model every new session starts on, by id.
///
/// The id alone, because a caller configuring this has only ever had an id
/// to give (`CURSOR_MODEL`); its params are resolved from Cursor's own
/// default variant, since Cursor rejects an id whose params are not a
/// variant it knows.
#[must_use]
pub fn with_default_model(mut self, model_id: Option<String>) -> Self {
self.default_model_id = model_id;
self
}
/// Pin the model this session runs on, by id, ahead of the deployment
/// default.
///
/// The host's session record, which holds the model its owner chose for
/// this session - before it ever ran, or by selecting one mid-session -
/// and otherwise whatever slug the host seeded the record with. Resolved
/// like any other id, so a value that is not a Cursor model is no opinion
/// and the deployment default still answers.
#[must_use]
pub fn with_host_model(mut self, model_id: Option<String>) -> Self {
self.host_model_id = model_id;
self
}
/// Open a session.
///
/// No repository is chosen here: a session's repository follows from what
/// its first prompt asks for, and there is no prompt yet. `session/new`
/// carries a `cwd`, which the standalone chooser uses to resolve its checkout.
/// Hosted sessions choose from the prompt and ignore that path.
pub fn new_session(&self, cwd: &Path, mcp_servers: Vec<McpServer>) -> SessionId {
let session = Arc::new(Session {
cwd: cwd.to_path_buf(),
turn_gate: Arc::new(tokio::sync::Mutex::new(())),
state: Mutex::new(SessionState {
mcp_servers,
ready_for_sync: true,
fresh: true,
..SessionState::default()
}),
});
let mut sessions = self.sessions.lock().expect("session map poisoned");
// Counter-minted ids restart at 1 each process, but restored sessions
// carry ids minted by earlier processes — skip over those rather than
// silently replacing a live session with a fresh one.
let id = loop {
let candidate = {
let mut next = self.next_session.lock().expect("session counter poisoned");
*next += 1;
SessionId::new(format!("cursor-acp-{next}"))
};
if !sessions.contains_key(&candidate) {
break candidate;
}
};
sessions.insert(id.clone(), session);
id
}
/// The models this account may choose from, fetched once and reused.
pub async fn models(&self) -> Result<Vec<CursorModel>, SessionError> {
let mut cached = self.models.lock().await;
if let Some(models) = cached.as_ref() {
return Ok(models.clone());
}
let models = self
.cursor
.list_models()
.await
.map_err(SessionError::Cursor)?;
*cached = Some(models.clone());
Ok(models)
}
/// The model a session's next run will use, by id.
///
/// This is what *we* last asked for, not what Cursor ran: no API surface
/// reports a run's model back — not the run record, not the run list, not
/// the stream — so our own record is the only answer available.
pub async fn session_model_id(
&self,
session_id: &SessionId,
) -> Result<Option<String>, SessionError> {
Ok(self.session_model(session_id).await?.map(|model| model.id))
}
/// The concrete model variant the session's next run will use.
pub async fn session_model(
&self,
session_id: &SessionId,
) -> Result<Option<ModelChoice>, SessionError> {
self.effective_model(session_id).await
}
/// Choose the model a session's next run will use.
///
/// Takes effect on the next run rather than the one streaming now, which
/// Cursor fixes at creation. Resolved against `GET /v1/models` so an id
/// Cursor would reject is refused here, with the list, instead of failing
/// at the next prompt.
pub async fn set_model(
&self,
session_id: &SessionId,
model_id: &str,
) -> Result<(), SessionError> {
let session = self.session(session_id)?;
let models = self.models().await?;
let model = models
.iter()
.find(|model| model.id == model_id)
.ok_or_else(|| {
SessionError::Cursor(rootcause::report!(
"no cursor model with id {model_id}; this account offers {}",
models
.iter()
.map(|model| model.id.as_str())
.collect::<Vec<_>>()
.join(", ")
))
})?;
session.state.lock().expect("session state poisoned").model = Some(model.default_choice());
Ok(())
}
/// Choose the reasoning effort for the session's next run.
///
/// Cursor accepts only combinations returned by `GET /v1/models`, so the
/// selected effort is resolved to a variant that preserves every other
/// parameter of the current choice.
pub async fn set_reasoning_effort(
&self,
session_id: &SessionId,
effort: &str,
) -> Result<(), SessionError> {
use crate::domain::model_options::REASONING_PARAMETER_IDS;
let session = self.session(session_id)?;
let current = self.effective_model(session_id).await?.ok_or_else(|| {
SessionError::Cursor(rootcause::report!(
"choose a concrete cursor model before setting reasoning effort"
))
})?;
let models = self.models().await?;
let model = models
.iter()
.find(|model| model.id == current.id)
.ok_or_else(|| {
SessionError::Cursor(rootcause::report!(
"current cursor model is no longer offered"
))
})?;
let parameter_id = current
.params
.iter()
.find(|param| REASONING_PARAMETER_IDS.contains(¶m.id.as_str()))
.map(|param| param.id.as_str())
.ok_or_else(|| {
SessionError::Cursor(rootcause::report!(
"cursor model {} has no reasoning effort parameter",
current.id
))
})?;
let choice = model
.variants
.iter()
.find(|variant| {
variant
.params
.iter()
.any(|param| param.id == parameter_id && param.value == effort)
&& super::model_options::model_params_match_except(
&variant.params,
¤t.params,
parameter_id,
)
})
.map(|variant| ModelChoice {
id: model.id.clone(),
params: variant.params.clone(),
})
.ok_or_else(|| {
SessionError::Cursor(rootcause::report!(
"cursor model {} has no compatible reasoning effort {effort}",
current.id
))
})?;
session.state.lock().expect("session state poisoned").model = Some(choice);
Ok(())
}
/// The session's explicit choice, or the deployment's pinned default
/// resolved to a variant Cursor will accept.
///
/// The default is resolved on first use rather than at `session/new`, which
/// is synchronous and cannot reach the API, and then stored so the lookup
/// happens once per session.
async fn effective_model(
&self,
session_id: &SessionId,
) -> Result<Option<ModelChoice>, SessionError> {
let session = self.session(session_id)?;
if let Some(model) = session
.state
.lock()
.expect("session state poisoned")
.model
.clone()
{
return Ok(Some(model));
}
// Session before deployment: the session's own id is what its owner
// chose for it (or was using before a restart), and the default is
// what a session gets when nobody ever said otherwise. Each is only a
// preference, so one that resolves to nothing hands the question to
// the next rather than answering it with silence.
for fallback_id in [
self.host_model_id.as_deref(),
self.default_model_id.as_deref(),
]
.into_iter()
.flatten()
{
// A failure to *fetch* the model table degrades like a failed
// lookup in it: the fallback is a preference, and Cursor being
// unreachable for `GET /v1/models` must cost the preference, never
// the prompt — the run itself may well still work.
let choice = match self.resolve_model_id(fallback_id).await {
Ok(choice) => choice,
Err(error) => {
tracing::warn!(
fallback_id,
%error,
"could not resolve the fallback model; using Cursor's default"
);
None
}
};
let Some(choice) = choice else {
continue;
};
session.state.lock().expect("session state poisoned").model = Some(choice.clone());
return Ok(Some(choice));
}
Ok(None)
}
/// The id resolved to a choice Cursor will accept, or `None` for an id
/// this account is not offered.
///
/// The miss is tolerated by design, not defensively. Both fallback ids
/// come from places that can legitimately hold non-Cursor values: the
/// deployment default is operator configuration, and the restored id is a
/// persisted column the harness seeds with its own deployment slug
/// (`claude`) before any real choice overwrites it. For either, "not a
/// Cursor model" means "no opinion" — Cursor's own default resolution is a
/// working answer — never a failed prompt.
async fn resolve_model_id(&self, model_id: &str) -> Result<Option<ModelChoice>, SessionError> {
let models = self.models().await?;
let Some(model) = models.iter().find(|model| model.id == model_id) else {
tracing::warn!(
model_id,
"not a cursor model this account is offered; using Cursor's default"
);
return Ok(None);
};
Ok(Some(model.default_choice()))
}
/// Replace the session's MCP servers with the client's current list.
///
/// Driven by `session/load`: the list belongs to the client and the
/// protocol restates it there, which is how a restored process — whose
/// host never persisted it — learns it again.
pub fn set_mcp_servers(&self, session_id: &SessionId, mcp_servers: Vec<McpServer>) {
if let Ok(session) = self.session(session_id) {
session
.state
.lock()
.expect("session state poisoned")
.mcp_servers = mcp_servers;
}
}
/// Mark a restored session safe for background updates after load replies.
#[cfg(test)]
fn loaded(&self, session_id: &SessionId) -> Result<(), SessionError> {
let session = self.session(session_id)?;
session
.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.ready_for_sync = true;
Ok(())
}
/// Run one prompt to completion, delivering updates as they stream.
///
/// Resolves with the turn's ACP stop reason once the run's stream ends.
#[tracing::instrument(skip(self, prompt), err)]
pub async fn prompt(
&self,
session_id: &SessionId,
prompt: &str,
) -> Result<StopReason, SessionError> {
self.prompt_content(
session_id,
prompt,
vec![ContentBlock::Text(TextContent::new(prompt))],
)
.await
}
/// Run a prompt retaining its original ACP blocks in the native journal.
///
/// This is the whole of a Cursor turn, and the ACP path calls straight
/// through here rather than through [`Self::prompt`] - so an
/// uninstrumented body leaves a turn with no span at all.
///
/// The outcome is recorded on the way out rather than left to `err`.
/// A turn whose future is dropped - a pipe torn down under it - still
/// closes its span, with no error and no recorded outcome, which is
/// otherwise indistinguishable from a turn that ended normally. An unset
/// `agent.turn.outcome` is what tells those two apart.
#[tracing::instrument(
name = "agent.turn",
skip_all,
fields(
agent.acp.session_id = ?session_id,
cursor.agent.id = tracing::field::Empty,
cursor.run.id = tracing::field::Empty,
agent.turn.stop_reason = tracing::field::Empty,
agent.turn.outcome = tracing::field::Empty,
agent.turn.gate_wait_ms = tracing::field::Empty,
),
err,
)]
pub async fn prompt_content(
&self,
session_id: &SessionId,
prompt: &str,
blocks: Vec<ContentBlock>,
) -> Result<StopReason, SessionError> {
let outcome = self.run_turn(session_id, prompt, blocks).await;
let span = tracing::Span::current();
match &outcome {
Ok(stop_reason) => {
span.record("agent.turn.stop_reason", tracing::field::debug(stop_reason));
span.record("agent.turn.outcome", "completed");
}
Err(_) => {
span.record("agent.turn.outcome", "failed");
}
}
outcome
}
/// Fetch links in `blocks` and keep the ones that are images.
///
/// Returns new ACP image frames to append to the original blocks and all
/// images to send to Cursor. A failed fetch leaves the link as text.
#[tracing::instrument(name = "cursor.prompt_images.resolve", skip_all, fields(image.count = tracing::field::Empty))]
async fn resolve_prompt_images(
&self,
blocks: &[ContentBlock],
) -> (Vec<ContentBlock>, Vec<CursorPromptImage>) {
let mut images = prompt_image::images_in_blocks(blocks);
if images.len() == prompt_image::MAX_PROMPT_IMAGES {
return (Vec::new(), images);
}
let mut fetched = Vec::new();
let deadline = tokio::time::Instant::now() + std::time::Duration::from_secs(10);
let urls = prompt_image::linked_image_urls(blocks);
let fetcher = Arc::clone(&self.images);
let fetches = futures::stream::iter(urls)
.map(move |url| {
let fetcher = Arc::clone(&fetcher);
async move { fetcher.fetch_image(&url).await }
})
.buffered(prompt_image::MAX_PROMPT_IMAGES);
futures::pin_mut!(fetches);
while images.len() + fetched.len() < prompt_image::MAX_PROMPT_IMAGES {
let Ok(Some(image)) = tokio::time::timeout_at(deadline, fetches.next()).await else {
break;
};
if let Some(image) = image {
fetched.push(image);
}
}
tracing::Span::current().record("image.count", images.len() + fetched.len());
let blocks = fetched
.iter()
.map(CursorPromptImage::to_content_block)
.collect();
images.extend(fetched);
(blocks, images)
}
async fn run_turn(
&self,
session_id: &SessionId,
prompt: &str,
blocks: Vec<ContentBlock>,
) -> Result<StopReason, SessionError> {
let session = self.session(session_id)?;
// Wait behind an in-flight foreign-run mirror, so its frames and
// this turn's never interleave — but never behind another turn: ACP
// makes a concurrent prompt the client's error, not a queue. The
// holder is told apart by active_run, which only turns set.
let gate = session.turn_gate.try_lock().ok();
if gate.is_none()
&& session
.state
.lock()
.expect("session state poisoned")
.active_run
.is_some()
{
return Err(SessionError::TurnAlreadyActive(session_id.clone()));
}
// This pending prompt owns cancellation before any wait it can be
// parked in — the gate, the model lookup, historical recovery. A stop
// has to land while the prompt is waiting behind a mirror, and the
// mirror can hold the gate for as long as the run it follows lives;
// installing the token after the gate would have that stop fire an
// old token and then be erased by the reset here. Only after the
// active-turn check, which must never clobber a live turn's token.
let cancel = {
let mut state = session.state.lock().expect("session state poisoned");
state.cancelled = false;
state.cancel = tokio_util::sync::CancellationToken::new();
state.cancel.clone()
};
let _turn = match gate {
Some(guard) => guard,
None => {
// The wait is on the turn span, not only in a log line: it
// is the one place a turn's time goes that no Cursor call
// accounts for, and a trace of a slow turn has to show it.
let waiting_since = std::time::Instant::now();
let _waiting = WaitingPrompt::new(&session);
let span = tracing::Span::current();
tracing::info!(
"waiting for the turn gate behind a mirror of a run started elsewhere"
);
tokio::select! {
biased;
() = cancel.cancelled() => {
// Nothing to journal: the prompt never reached the
// gate, so it never became part of this session's
// record. The client's own transcript has it.
let waited_ms = waiting_since.elapsed().as_millis() as u64;
span.record("agent.turn.gate_wait_ms", waited_ms);
tracing::info!(waited_ms, "stopped while waiting for the turn gate");
return Ok(StopReason::Cancelled);
}
guard = session.turn_gate.lock() => {
let waited_ms = waiting_since.elapsed().as_millis() as u64;
span.record("agent.turn.gate_wait_ms", waited_ms);
tracing::info!(waited_ms, "acquired the turn gate");
guard
}
() = tokio::time::sleep(GATE_WAIT_BUDGET) => {
span.record("agent.turn.gate_wait_ms", GATE_WAIT_BUDGET.as_millis() as u64);
tracing::warn!(
waited_secs = GATE_WAIT_BUDGET.as_secs(),
"gave up waiting for the turn gate; a mirror is still following a run started elsewhere"
);
return Err(SessionError::Rejected(PromptRefusal::plain(
"Cursor is still busy with a run started outside Macro, and Macro \
stopped waiting for it. Send another message once that run has \
finished, or stop the session to interrupt it.",
)));
}
}
}
};
// A mirror that finished streaming just before this prompt arrived
// may have streamed its last frames into this prompt's turn.
let overlapped = session
.state
.lock()
.expect("session state poisoned")
.mirror_published_at
.is_some_and(|at| at.elapsed() < MIRROR_PROMPT_OVERLAP);
if overlapped {
tracing::info!("prompt arrived as a mirrored run finished streaming; reloading");
self.require_reload(session_id, &session).await?;
}
if !session
.state
.lock()
.expect("session state poisoned")
.ready_for_sync
{
return Err(SessionError::Cursor(rootcause::report!(
"Cursor session must load successfully before prompting"
)));
}
// A failed model lookup proves no prompt was executed. Do it before
// reserving the durable intent, so load does not see false ambiguity.
let model = self.effective_model(session_id).await?;
self.ensure_journal(session_id, &session).await?;
let prior_agent = session
.state
.lock()
.expect("session state poisoned")
.agent
.clone();
if let Some(agent) = &prior_agent {
self.backfill_foreign_runs(session_id, &session, agent, None, &cancel, Emit::Silent)
.await?;
}
// Links are fetched before the prompt is journaled, so the record
// holds the image frames and not only the URLs they came from.
let (fetched, images) = tokio::select! {
biased;
() = cancel.cancelled() => (Vec::new(), Vec::new()),
resolved = self.resolve_prompt_images(&blocks) => resolved,
};
let mut blocks = blocks;
blocks.extend(fetched);
// Preserve original content before the provider creates remote work.
self.capture(
session_id,
&session,
None,
JournalInput::Prompt(blocks.clone()),
Emit::Silent,
)
.await?;
let prompt_sequence = session
.state
.lock()
.expect("session state poisoned")
.journal_entries
.last()
.expect("captured prompt")
.sequence;
if cancel.is_cancelled() {
self.capture(
session_id,
&session,
None,
JournalInput::PromptAborted(prompt_sequence),
Emit::Silent,
)
.await?;
return Ok(StopReason::Cancelled);
}
let creating_agent = prior_agent.is_none();
let created = match prior_agent {
Some(agent) => {
// Queue behind any run still going (the same agent advances
// from cursor.com too) instead of failing the prompt.
self.create_run_when_free(
&session,
&agent,
prompt,
model.as_ref(),
&images,
&cancel,
)
.await
.map(|run| (agent, run))
}
None => {
// Snapshotted out of the lock: `create_agent` is a network
// call, and the state mutex must never be held across an await.
let (mcp_servers, decided, rejected) = {
let state = session.state.lock().expect("session state poisoned");
(
state.mcp_servers.clone(),
state.intent.clone(),
state.rejected_prompts.clone(),
)
};
// The first prompt is the only evidence there is for which
// repository this session belongs to, and Cursor fixes an
// agent's repository at creation - so the decision is made
// here, before the agent exists, and never revisited: a
// create Cursor refused leaves the decision standing for the
// next attempt rather than re-reading a prompt that is now
// about the refusal.
let intent = match decided {
Some(intent) => {
tracing::info!(
repo = ?intent.repository.as_ref().map(RepoUrl::as_str),
"reusing the repository decided by this session's first prompt"
);
Ok(intent)
}
None => self.chooser.choose(prompt, &session.cwd).await,
};
match intent {
Ok(intent) => {
{
let mut state = session.state.lock().expect("session state poisoned");
state.repo = intent.repository.clone();
state.intent = Some(intent.clone());
}
if intent.repository.is_none() {
tracing::warn!(
"no repository chosen - this session will not appear in the Cursor sessions list"
);
}
self.cursor
.create_agent(
&prompt_with_rejected(&rejected, prompt),
intent.repository.as_ref(),
intent.open_pull_request,
&mcp_servers,
model.as_ref(),
&images,
)
.await
.map_err(SessionError::from)
}
// A chooser that cannot answer fails the prompt rather
// than falling back to some default repository: an agent
// minted against the wrong repository would open its pull
// request there, which no later correction undoes.
Err(error) => {
tracing::warn!(error = ?error, "could not choose a repository for this session");
let error = SessionError::from(error);
match error {
#[cfg(feature = "postgres")]
SessionError::Admission(_) => Err(error),
_ => Err(SessionError::Rejected(PromptRefusal::plain(
"Couldn't prepare repository access for this session. Please retry; if this persists, check your GitHub connection.",
))),
}
}
}
}
};
let (agent, run) = match created.map_err(explain_rejection) {
Ok(created) => created,
Err(error) => {
if is_prompt_rejection(&error) {
self.capture(
session_id,
&session,
None,
JournalInput::PromptAborted(prompt_sequence),
Emit::Silent,
)
.await?;
if cancel.is_cancelled() {
return Ok(StopReason::Cancelled);
}
// Quota-refused prompts must not be silently bundled into a later run.
#[cfg(feature = "postgres")]
if matches!(error, SessionError::Admission(_)) {
return Err(error);
}
// Only a create's refusal is carried: a follow-up run
// refused on an existing agent is already in a conversation
// the agent can see.
if creating_agent {
let reason = match &error {
SessionError::Rejected(refusal) => Some(refusal.message.clone()),
_ => None,
};
session
.state
.lock()
.expect("session state poisoned")
.rejected_prompts
.push(RejectedPrompt {
text: prompt.to_owned(),
reason,
});
}
}
return Err(error);
}
};
self.capture(
session_id,
&session,
Some(&run),
JournalInput::PromptAccepted(prompt_sequence),
Emit::Silent,
)
.await?;
{
let mut state = session.state.lock().expect("session state poisoned");
state.agent = Some(agent.clone());
state.rejected_prompts.clear();
}
// Acceptance is durable even if recovery of an older run fails. Do
// not observe/project the new run until every older run is reconciled.
self.backfill_foreign_runs(
session_id,
&session,
&agent,
Some(&run),
&cancel,
Emit::Silent,
)
.await?;
// The turn span is the only place all three identities meet, and it
// is what makes a Macro session joinable to the cursor.com run that
// served it.
let span = tracing::Span::current();
span.record("cursor.agent.id", tracing::field::display(&agent));
span.record("cursor.run.id", tracing::field::display(&run));
tracing::info!(%agent, %run, "cursor run started");
let cancelled_before_the_run = {
let mut state = session.state.lock().expect("session state poisoned");
state.agent = Some(agent.clone());
state.active_run = Some(run.clone());
state.cancelled
};
// A stop this run did not exist to receive. `cancel` had no run id to
// POST — a first prompt spends ten seconds creating the agent, and a
// session with no agent yet cannot name one — so the remote work was
// left going and the stream below would have read it to the agent's
// own natural end. Ask now, and the same stream ends on Cursor's
// cancelled `result` a second or two later.
if cancelled_before_the_run {
tracing::info!(%agent, %run, "stop arrived before this run existed; cancelling it now");
if let Err(error) = self.cursor.cancel_run(&agent, &run).await {
// Best-effort, exactly as in `cancel`: the turn still ends on
// whatever the stream reports.
tracing::warn!(%agent, %run, %error, "could not cancel a run stopped before it existed");
}
}
let outcome = self
.stream_turn(session_id, &session, &agent, &run, &cancel)
.await;
let cancelled = {
let mut state = session.state.lock().expect("session state poisoned");
state.active_run = None;
state.cancelled
};
// Both variants are a turn that stopped without a terminal fact, and
// both have to leave that record: a `Rejected` here is the turn giving
// up on a run still going, not a prompt refused before it ran.
let interrupted = match &outcome {
Err(SessionError::Cursor(error)) => Some(error.to_string()),
Err(SessionError::Rejected(refusal)) => Some(refusal.message.clone()),
_ => None,
};
if let Some(interrupted) = interrupted {
self.capture(
session_id,
&session,
Some(&run),
JournalInput::Interrupted(interrupted),
Emit::Live,
)
.await?;
}
if cancelled && outcome.is_ok() {
self.capture(
session_id,
&session,
Some(&run),
JournalInput::Interrupted("user cancelled the turn".into()),
Emit::Live,
)
.await?;
}
// The run's walkthrough files, collected once its outcome is known
// and before the turn answers, so the fold appends their markdown to
// this turn's reply like any other streamed text. A failed turn
// collects nothing: there is no reply for the text to land in.
if outcome.is_ok() {
self.collect_artifacts(session_id, &session, &agent, &run, &cancel)
.await?;
}
let reconciled = session
.state
.lock()
.expect("session state poisoned")
.journal_entries
.iter()
.any(|e| e.run.as_ref() == Some(&run) && e.input == JournalInput::Reconciled);
if outcome.is_ok() && reconciled {
self.notifier
.checkpoint(session_id, &run)
.await
.map_err(SessionError::Cursor)?;
session
.state
.lock()
.expect("session state poisoned")
.last_run = Some(run.clone());
}
// A cancel that raced the stream's own ending still reports
// Cancelled: ACP requires it once the client sent `session/cancel`.
// `Rejected` included, because giving up on a run still going takes
// that variant now — a stop landing near the end of the poll budget
// must still answer Cancelled, not "Cursor is still working". Journal
// failures stay unmasked by cancellation, as ever.
match outcome {
Ok(_) | Err(SessionError::Cursor(_) | SessionError::Rejected(_)) if cancelled => {
Ok(StopReason::Cancelled)
}
Ok(stop_reason) => Ok(stop_reason),
Err(error) => Err(error),
}
}
/// Cancel the session's active turn, if any. Idempotent; a session with
/// no active turn is a no-op rather than an error, because the turn may
/// have ended while the cancel was in flight.
///
/// `active_run` is this process's own memory of what it started, so it is
/// empty for a session restored after a restart — or one whose run this
/// process never drove at all (started from cursor.com). Either way the
/// agent may still have a run going, so a miss falls back to asking
/// Cursor which run, if any, is current before giving up on the remote
/// cancel.
#[tracing::instrument(skip(self), err)]
pub async fn cancel(&self, session_id: &SessionId) -> Result<(), SessionError> {
let session = self.session(session_id)?;
let (agent, active_run) = {
let mut state = session.state.lock().expect("session state poisoned");
state.cancelled = true;
// Unblocks a prompt still queued behind `agent_busy`. The live
// stream is not abandoned — Cursor's `result` frame is what ends
// the turn. The POST below is the notification that asks for that
// frame.
state.cancel.cancel();
// And the background mirror, if one is following a run started
// elsewhere: that run is cancelled below like any other, and a
// mirror left waiting for a `result` Cursor never sends would
// hold the turn gate — and every prompt behind it — for good.
state.mirror_cancel.cancel();
(state.agent.clone(), state.active_run.clone())
};
// No agent yet: the session's first prompt is still creating one, so
// there is nothing to name in a remote cancel. `cancelled` is set,
// and `prompt` sends it as soon as the run has an id.
let Some(agent) = agent else {
return Ok(());
};
let runs = match active_run {
Some(run) => vec![run],
None => self.current_runs(&agent).await,
};
// Concurrent rather than sequential so one failing cancel does not
// skip the rest — every run found gets its own attempt regardless of
// how the others land.
let results =
futures::future::join_all(runs.iter().map(|run| self.cursor.cancel_run(&agent, run)))
.await;
for result in results {
result?;
}
Ok(())
}
/// The agent's runs still in progress, per Cursor's own record.
///
/// The fallback [`Self::cancel`] takes when this process has no memory of
/// one: best-effort, like the remote cancel itself, so a lookup failure
/// costs the remote cancel, never the local one that already fired.
/// Cursor documents one active run per agent (see
/// [`Self::create_run_when_free`]), but that is a server-side invariant
/// this client does not enforce, so every match is cancelled rather than
/// just the first — cheap insurance against it ever slipping.
async fn current_runs(&self, agent: &CursorAgentId) -> Vec<CursorRunId> {
let listings = match self.cursor.list_runs(agent, None).await {
Ok(listings) => listings,
Err(error) => {
tracing::warn!(%agent, %error, "could not list runs to find one to cancel");
return Vec::new();
}
};
let runs: Vec<CursorRunId> = listings
.into_iter()
.filter(|listing| matches!(listing.status, RunStatus::Creating | RunStatus::Running))
.map(|listing| listing.id)
.collect();
if runs.len() > 1 {
tracing::warn!(
%agent,
count = runs.len(),
"more than one run in progress for an agent; Cursor documents one active run per agent"
);
}
runs
}
/// Drop a session, reporting whether it existed. Any active run keeps
/// running server-side; closing the ACP session does not imply
/// cancelling the work.
///
/// The bool is what lets `session/close` answer a client that named a
/// session this agent never had, rather than acknowledging a no-op.
pub fn close(&self, session_id: &SessionId) -> bool {
self.sessions
.lock()
.expect("session map poisoned")
.remove(session_id)
.is_some()
}
/// Seed a session a previous process created, so a `session/load` naming
/// it finds it live.
///
/// The host restores provider identity; the Cursor-owned journal restores
/// conversation state when the client subsequently loads the session. With
/// `Some(agent)` the next prompt opens a follow-up run on that agent;
/// with `None` it mints a fresh one — the state of a session that died
/// after `session/new` but before its first prompt, which must still
/// load rather than refuse (seen live: a restart in that window left a
/// session no follow-up could ever reach). Replaces any session already
/// under `id`: the restored fact wins, and the id space cannot collide
/// with fresh ids because [`Self::new_session`] skips occupied ids.
pub fn restore_session(
&self,
id: SessionId,
agent: Option<CursorAgentId>,
repo: Option<RepoUrl>,
) {
self.restore_session_with_watermark(id, agent, repo, None);
}
/// Restore a session together with its durable run-delivery checkpoint.
pub fn restore_session_with_watermark(
&self,
id: SessionId,
agent: Option<CursorAgentId>,
repo: Option<RepoUrl>,
last_run: Option<CursorRunId>,
) {
// No MCP servers here on purpose: the host never had the truth to
// hand over — the list belongs to the ACP client, and the client
// restates it on `session/load`, which is where it re-enters.
let session = Arc::new(Session {
cwd: PathBuf::new(),
turn_gate: Arc::new(tokio::sync::Mutex::new(())),
state: Mutex::new(SessionState {
repo,
agent,
last_run,
..SessionState::default()
}),
});
self.sessions
.lock()
.expect("session map poisoned")
.insert(id, session);
}
/// Whether a session is live in this process. What `session/load` checks:
/// loading is a lookup, not a fetch, because restoring state into the
/// process is [`Self::restore_session`]'s job and happens before serving.
#[must_use]
pub fn has_session(&self, session_id: &SessionId) -> bool {
self.sessions
.lock()
.expect("session map poisoned")
.contains_key(session_id)
}
/// Stream one run, translating and delivering as events arrive.
///
/// Streaming is the good path, not the only one. Cursor's stream endpoint
/// has been observed refusing connects for seconds after a run's creation
/// and dying mid-run, while the run itself finishes fine server-side — so
/// any streaming failure here degrades to the polling fallback rather than
/// failing the turn. A turn may lose its liveness; it must not lose its
/// answer.
async fn stream_turn(
&self,
session_id: &SessionId,
session: &Session,
agent: &CursorAgentId,
run: &CursorRunId,
cancel: &tokio_util::sync::CancellationToken,
) -> Result<StopReason, SessionError> {
self.ingest_run(session_id, session, agent, run, cancel, IngestMode::LIVE)
.await
}
/// One ordered path for live, foreign, and hydration ingestion. Reconnect
/// starts at the beginning and verifies the captured content prefix. No
/// local sequence is sent to Cursor as a remote resume token.
///
/// One span per ingestion attempt: this is where a turn or a replay spends
/// its time between the run being listed and its records being journaled,
/// and the Cursor stream and poll calls inside it are what a stalled
/// handshake or turn was otherwise waiting on invisibly.
#[tracing::instrument(
name = "cursor.run.ingest",
skip_all,
fields(
agent.acp.session_id = ?session_id,
cursor.agent.id = %agent,
cursor.run.id = %run,
cursor.ingest.emit = ?mode.emit,
cursor.ingest.strict = mode.strict,
cursor.ingest.attempt = mode.attempt,
cursor.run.status = tracing::field::Empty,
cursor.run.error.code = tracing::field::Empty,
cursor.run.error.message = tracing::field::Empty,
cursor.stream.reconnects = tracing::field::Empty,
cursor.stream.fell_back_to_poll = tracing::field::Empty,
),
err,
)]
async fn ingest_run(
&self,
session_id: &SessionId,
session: &Session,
agent: &CursorAgentId,
run: &CursorRunId,
cancel: &tokio_util::sync::CancellationToken,
mode: IngestMode,
) -> Result<StopReason, SessionError> {
let IngestMode {
emit,
strict,
attempt,
} = mode;
// A crash can leave a terminal SSE/Poll durable but its following
// marker absent. Its text and terminal tool cleanup were reconstructed
// already; reconnecting the stream would append that suffix twice.
let terminal = session
.state
.lock()
.expect("session state poisoned")
.machine
.terminal_status(run);
if let Some(status) = terminal {
tracing::Span::current().record("cursor.run.status", tracing::field::debug(&status));
if strict
&& !session
.state
.lock()
.expect("session state poisoned")
.machine
.has_prompt(run)
{
return Err(
rootcause::report!("original Cursor prompt unavailable for {run}").into(),
);
}
self.capture(
session_id,
session,
Some(run),
JournalInput::Reconciled,
Emit::Silent,
)
.await?;
return match status {
RunStatus::Cancelled => Ok(StopReason::Cancelled),
RunStatus::Finished => Ok(StopReason::EndTurn),
_ if strict => Ok(StopReason::EndTurn),
status => Err(run_failure(session, agent, run, status)),
};
}
let mut captured = captured_content(session, run);
let mut matched = 0;
let mut terminal = None;
let mut saw_content = false;
// The provider's most recent event id. Opaque: it is handed back
// verbatim as a resume position or not used at all.
let mut last_event_id: Option<String> = None;
// Reconnects since the last one that produced new records.
let mut reconnects: u32 = 0;
let mut fell_back_to_poll = false;
let mut ever_connected = false;
let mut resume_from: Option<String> = None;
// Cursor rejecting a resume position buys exactly one connect without
// one; a second rejection means something is wrong with the run, not
// with the id we sent.
let mut blind_reconnect_available = true;
// The run's latest `status` frame, kept to recognize the sticky copy
// Cursor re-sends at the top of every reconnect.
let mut last_status: Option<crate::domain::journal::NativeRecord> = None;
// Connects in a row that stalled before their headers; a connection
// that opens resets it.
let mut stalled_connects: u32 = 0;
// Whether the record was found terminal behind a stalled stream and
// the one connect allowed to drain that stream has been spent.
let mut drained_after_terminal = false;
// When the transport last broke, and when a record last arrived on
// any connection: together they say how long the transcript has
// been behind, which is the figure a person watching a frozen chip
// needs from the logs.
let started_at = tokio::time::Instant::now();
let mut interrupted_at: Option<tokio::time::Instant> = None;
let mut last_record_at: Option<tokio::time::Instant> = None;
loop {
// The connected stream borrows the position it resumed from, so
// the position this iteration sends is its own owned copy.
let resuming = resume_from.clone();
let interruption = match self
.cursor
.raw_stream(agent, run, resuming.as_deref())
.await
{
// The stream said nothing, but the record still answers: a
// run that finished behind a wedged stream must not wait on
// another stall to end its turn. Hydration takes the strict
// arm below; it has no record to fall back on.
Err(StreamConnectError::Stalled(detail)) if !strict => {
stalled_connects += 1;
let raw = self
.fetch_run_record(session_id, agent, run, cancel)
.await?;
let outcome = Self::run_outcome(&raw)?;
if outcome.is_terminal()
&& !std::mem::replace(&mut drained_after_terminal, true)
{
// Observed: what a stalled stream held back arrives
// the instant the run ends, so the stream gets one
// more connect to deliver it - and its terminal
// frame - itself. The record is deliberately not
// captured yet: its final text would reach the
// transcript now and then again from the stream.
tracing::info!(
cursor.run.id = %run,
cursor.stream.stalled_connects = stalled_connects,
cursor.stream.last_event_id = last_event_id,
"Cursor run ended behind a stalled stream; connecting once more to drain it"
);
} else {
self.capture(
session_id,
session,
Some(run),
JournalInput::Poll(raw),
emit,
)
.await?;
if outcome.is_terminal() {
// A second stall past the run's end: the
// record's account stands.
terminal = Some(outcome.status);
tracing::warn!(
cursor.run.id = %run,
cursor.stream.stalled_connects = stalled_connects,
cursor.stream.last_event_id = last_event_id,
"Cursor stream still stalled after the run ended; keeping the record's account"
);
break;
}
}
if cancel.is_cancelled() {
break;
}
Some(Interruption {
reason: format!("{detail} (stalled connect {stalled_connects})"),
recoverable: ever_connected
|| stalled_connects < STALLED_CONNECTS_BEFORE_POLLING,
quiet: true,
})
}
Err(StreamConnectError::Stalled(detail)) => Some(Interruption {
reason: detail,
recoverable: false,
quiet: false,
}),
Err(StreamConnectError::InvalidResumePosition(detail))
if blind_reconnect_available && resuming.is_some() =>
{
// Reading the run from the top still beats polling: the
// prefix logic below matches what is already captured
// instead of duplicating it. It has to be recomputed
// first, because this ingestion has appended to it.
blind_reconnect_available = false;
tracing::warn!(
cursor.run.id = %run,
cursor.stream.last_event_id = resuming,
cursor.stream.reason = %detail,
"Cursor rejected the stream resume position; reconnecting from the start"
);
resume_from = None;
captured = captured_content(session, run);
matched = 0;
continue;
}
// Past the retention window there is no stream left to resume,
// so the run record is the only remaining account of the run.
Err(StreamConnectError::Expired(detail)) => Some(Interruption {
reason: detail,
recoverable: false,
quiet: false,
}),
Err(error) => Some(Interruption::failed(error.to_string())),
Ok(connected) => {
let resumed = resuming.is_some();
ever_connected = true;
stalled_connects = 0;
let opened_at = tokio::time::Instant::now();
let mut first_record_at: Option<tokio::time::Instant> = None;
let retention_seconds = connected.retention_seconds;
let records = connected.records;
pin_mut!(records);
let mut received = 0usize;
let mut received_content = 0usize;
let mut sticky_status_pending = resumed;
// How long this connection has said nothing, across the
// record checks that found its run still going.
let mut silence = std::time::Duration::ZERO;
let interruption = loop {
let quiet_timeout = if silence.is_zero() {
STREAM_QUIET_TIMEOUT
} else {
STREAM_QUIET_RECHECK
};
let record = match tokio::time::timeout(quiet_timeout, records.next()).await
{
Ok(Some(Ok(record))) => {
silence = std::time::Duration::ZERO;
let now = tokio::time::Instant::now();
first_record_at.get_or_insert(now);
last_record_at = Some(now);
record
}
Ok(Some(Err(error))) => {
break Some(Interruption::failed(error.to_string()));
}
// Cursor closes the stream after `done`, which
// breaks below with an outcome. Reaching here
// without one is a close mid-run.
Ok(None) if terminal.is_some() => break None,
Ok(None) => {
break Some(Interruption::failed("stream closed".to_owned()));
}
Err(_) if strict => break None,
Err(_) => {
// Quiet streams are checked through the exact same raw
// polling/capture path as disconnected streams.
let status = self
.poll_once(session_id, session, agent, run, cancel, emit)
.await?;
if status.is_terminal() {
terminal = Some(status.status);
break None;
}
if cancel.is_cancelled() {
break None;
}
silence += quiet_timeout;
if silence < STREAM_SILENCE_BEFORE_RECONNECT {
// The run is going and the connection is
// open: an agent at work, not a stream
// that stopped delivering.
continue;
}
break Some(Interruption {
reason: format!("no records for {} seconds", silence.as_secs()),
recoverable: true,
quiet: true,
});
}
};
if let Some(id) = &record.id {
last_event_id = Some(id.clone());
}
// Cursor re-sends the run's `status` frame, without an
// id, at the top of every reconnect. It is framing, not
// a new fact: journaling it again would put the same
// lifecycle event in the record twice.
if std::mem::take(&mut sticky_status_pending)
&& record.id.is_none()
&& last_status.as_ref() == Some(&record)
{
continue;
}
if record.event == "status" {
last_status = Some(record.clone());
}
received += 1;
let content = record.is_content();
if content && matched < captured.len() {
if captured[matched] != record {
return Err(rootcause::report!("Cursor stream prefix cannot be reconciled for {run}; refusing incomplete history").into());
}
matched += 1;
if let CursorEvent::Result { status, .. } = record.decode() {
terminal = Some(status);
}
continue;
}
self.capture(
session_id,
session,
Some(run),
JournalInput::Sse(record.clone()),
emit,
)
.await?;
saw_content |= content;
received_content += usize::from(content);
match record.decode() {
CursorEvent::Error { code, .. }
if code.as_deref() == Some("stream_unavailable")
&& !saw_content
&& attempt < 4 =>
{
if !sleep_unless_cancelled(
cancel,
std::time::Duration::from_millis(400),
)
.await
{
return Box::pin(self.ingest_run(
session_id,
session,
agent,
run,
cancel,
IngestMode {
attempt: attempt + 1,
..mode
},
))
.await;
}
break None;
}
CursorEvent::Result { status, .. } => terminal = Some(status),
// The stream's own account of the run's lifecycle, and a
// terminal one is a terminal fact even with no `result`
// frame behind it. Observed live: a run whose record
// stayed `RUNNING` with a frozen `updatedAt` announced
// `FINISHED` here and sent no `result` at all, so a turn
// that accepted only `result` waited out its whole poll
// budget against a record that was never going to move.
//
// Not a break: trailing content can still be in flight,
// and `done`, the stream's end, or a quiet gap closes the
// turn now that there is an outcome to close it with.
CursorEvent::Status { status, .. } if status.is_terminal() => {
terminal = Some(status);
}
// Cursor said its piece about this run; a fresh
// connection would only be told the same thing.
CursorEvent::Error { code, message } => {
tracing::warn!(
cursor.run.id = %run,
cursor.run.error.code = code,
cursor.run.error.message = %message,
"Cursor stream reported an error"
);
break None;
}
CursorEvent::Done => break None,
_ => {}
}
};
if resumed {
let connection = opened_at.elapsed();
// A resume that delivered and then stayed up is a
// working stream again, so the next drop gets the
// full budget rather than whatever a much earlier one
// left over. One that delivered its backlog and died
// at once is the same failure continuing, and spends.
let healthy = received_content > 0
&& (interruption.is_none() || connection >= STREAM_HEALTHY_RESUME);
tracing::info!(
cursor.run.id = %run,
cursor.stream.attempt = reconnects,
cursor.stream.last_event_id = last_event_id,
cursor.stream.retention_seconds = retention_seconds,
cursor.stream.resumed_records = received,
cursor.stream.resumed_content = received_content,
cursor.stream.waited_ms = interrupted_at.map(|at| {
first_record_at
.unwrap_or_else(tokio::time::Instant::now)
.saturating_duration_since(at)
.as_millis() as u64
}),
cursor.stream.connection_ms = connection.as_millis() as u64,
cursor.stream.healthy = healthy,
cursor.stream.fast_failed = interruption.is_some() && !healthy,
"Cursor stream resumed"
);
if healthy {
reconnects = 0;
}
}
interruption
}
};
let Some(Interruption {
reason,
recoverable,
quiet,
}) = interruption
else {
break;
};
fell_back_to_poll = true;
interrupted_at = Some(tokio::time::Instant::now());
// How long the transcript has been behind: since the last record
// on any connection, or since this attempt began if none came.
let silent_ms = last_record_at.unwrap_or(started_at).elapsed().as_millis() as u64;
// A connect that stalled is tried again a bounded number of
// times before this gives up on the stream, because a stall is
// the one connect failure the client did not already retry.
let retrying_a_stall = quiet && recoverable;
if !ever_connected && !retrying_a_stall {
// Nothing to resume: the stream never opened, and the client
// has already retried an unavailable one on its own.
self.capture(
session_id,
session,
Some(run),
JournalInput::TransportError(reason.clone()),
emit,
)
.await?;
tracing::warn!(
cursor.run.id = %run,
cursor.stream.reason = %reason,
cursor.stream.stalled_connects = stalled_connects,
cursor.stream.silent_ms = silent_ms,
"Cursor stream never connected; polling the run record instead"
);
break;
}
let attempt = reconnects + 1;
self.capture(
session_id,
session,
Some(run),
JournalInput::StreamInterrupted {
reason: reason.clone(),
last_event_id: last_event_id.clone(),
attempt,
},
emit,
)
.await?;
// Hydration verifies the whole captured prefix against a stream it
// reads from the beginning, which a resumed stream cannot offer.
// A connection replaced for silence alone spends nothing: the
// budget rations a transport that is failing, and this one is
// still the only thing that can deliver the run live.
let resumable =
recoverable && !strict && (quiet || attempt <= STREAM_RECONNECT_ATTEMPTS as u32);
if !resumable {
tracing::warn!(
cursor.run.id = %run,
cursor.stream.last_event_id = last_event_id,
cursor.stream.attempt = attempt,
cursor.stream.reason = %reason,
cursor.stream.silent_ms = silent_ms,
cursor.stream.stalled_connects = stalled_connects,
"Cursor stream is not resumable; polling the run record instead"
);
break;
}
tracing::warn!(
cursor.run.id = %run,
cursor.stream.last_event_id = last_event_id,
cursor.stream.attempt = attempt,
cursor.stream.reason = %reason,
cursor.stream.quiet = quiet,
cursor.stream.silent_ms = silent_ms,
cursor.stream.stalled_connects = stalled_connects,
"Cursor stream interrupted; reconnecting"
);
let delay = STREAM_RECONNECT_DELAYS
[(attempt as usize - 1).min(STREAM_RECONNECT_DELAYS.len() - 1)];
if sleep_unless_cancelled(cancel, delay).await {
break;
}
if !quiet {
reconnects = attempt;
}
resume_from = last_event_id.clone();
fell_back_to_poll = false;
}
let span = tracing::Span::current();
span.record("cursor.stream.reconnects", reconnects);
span.record("cursor.stream.fell_back_to_poll", fell_back_to_poll);
if matched < captured.len() && strict {
return Err(rootcause::report!(
"Cursor no longer exposes the captured stream prefix for {run}"
)
.into());
}
if terminal.is_none() {
if strict {
return Err(rootcause::report!(
"Cursor cannot fully hydrate run {run}: complete native stream unavailable"
)
.into());
}
for attempt in 0..POLL_ATTEMPTS {
if attempt > 0 && cancel.is_cancelled() {
self.capture(
session_id,
session,
Some(run),
JournalInput::Interrupted("cancelled while disconnected".into()),
emit,
)
.await?;
return Ok(StopReason::Cancelled);
}
match self
.poll_once(session_id, session, agent, run, cancel, emit)
.await
{
Ok(outcome) if outcome.is_terminal() => {
terminal = Some(outcome.status);
break;
}
Ok(_) => {}
Err(error) => {
// Journal/processing failures must never be retried as
// provider errors; poll_once distinguishes them.
return Err(error);
}
}
sleep_unless_cancelled(cancel, poll_delay(attempt)).await;
}
}
if let Some(status) = &terminal {
span.record("cursor.run.status", tracing::field::debug(status));
}
let Some(status) = terminal else {
// Not a failure to describe in provider terms: the run is still
// going as far as Cursor is concerned, and this turn has simply
// run out of patience. The person who prompted gets told that in
// their own words; the diagnostics stay in the span.
tracing::warn!(
%run,
attempts = POLL_ATTEMPTS,
"gave up waiting; Cursor still reports a non-terminal status"
);
return Err(SessionError::Rejected(PromptRefusal::plain(
"Cursor has been working on this for over two hours and Macro stopped \
waiting. Send another message to continue: if Cursor has finished by \
then, that message picks up what it did, and if not, the run is \
cancelled and the conversation starts fresh from there.",
)));
};
if strict
&& !session
.state
.lock()
.expect("session state poisoned")
.machine
.complete(run)
{
return Err(rootcause::report!(
"Cursor cannot hydrate the original prompt for run {run}"
)
.into());
}
// A disconnected cancel did not get here: reconciliation is only
// marked after a real provider terminal fact, never on ACP delivery.
self.capture(
session_id,
session,
Some(run),
JournalInput::Reconciled,
emit,
)
.await?;
if strict {
return Ok(StopReason::EndTurn);
}
match status {
RunStatus::Finished => Ok(StopReason::EndTurn),
RunStatus::Cancelled => Ok(StopReason::Cancelled),
status => Err(run_failure(session, agent, run, status)),
}
}
/// One poll of a running turn.
///
/// Named explicitly so a rename of the client method underneath cannot
/// silently take the span with it: this loop is the only continuous
/// heartbeat a Cursor turn has, and a turn that stops polling is the
/// first evidence that something took it down.
///
/// `debug` because the loop runs as often as [`POLL_DELAYS`] says; the turn span
/// above carries the outcome, this carries the liveness.
async fn poll_once(
&self,
session_id: &SessionId,
session: &Session,
agent: &CursorAgentId,
run: &CursorRunId,
cancel: &tokio_util::sync::CancellationToken,
emit: Emit,
) -> Result<crate::domain::model::RunOutcome, SessionError> {
let raw = self
.fetch_run_record(session_id, agent, run, cancel)
.await?;
self.capture(
session_id,
session,
Some(run),
JournalInput::Poll(raw.clone()),
emit,
)
.await?;
Self::run_outcome(&raw)
}
/// The run's record as Cursor holds it, retried through transient
/// failures. Not captured: [`Self::poll_once`] does that, and the one
/// caller that reads the record without capturing it — a stalled stream
/// checking whether its run has ended — says why there.
#[tracing::instrument(
name = "cursor.run.poll",
level = "debug",
skip_all,
fields(
agent.acp.session_id = ?session_id,
cursor.agent.id = %agent,
cursor.run.id = %run,
),
err,
)]
async fn fetch_run_record(
&self,
session_id: &SessionId,
agent: &CursorAgentId,
run: &CursorRunId,
cancel: &tokio_util::sync::CancellationToken,
) -> Result<String, SessionError> {
for _tolerated in 0..POLL_ERROR_TOLERANCE {
match self.cursor.raw_result(agent, run).await {
Ok(value) => return Ok(value),
Err(error) => {
tracing::warn!(error = ?error, "Cursor poll failed; retrying");
if sleep_unless_cancelled(cancel, POLL_INTERVAL).await {
return Err(SessionError::Cursor(error));
}
}
}
}
// The last try past the tolerance is the one whose failure is final.
self.cursor.raw_result(agent, run).await.map_err(Into::into)
}
/// The outcome a run record states.
fn run_outcome(raw: &str) -> Result<crate::domain::model::RunOutcome, SessionError> {
let value: serde_json::Value =
serde_json::from_str(raw).map_err(|e| rootcause::report!(e).into_dynamic())?;
Ok(crate::domain::model::RunOutcome {
status: serde_json::from_value(value["status"].clone())
.map_err(|e| rootcause::report!(e).into_dynamic())?,
text: value
.get("result")
.or_else(|| value.get("text"))
.and_then(|s| s.as_str())
.map(str::to_owned),
})
}
/// Create a follow-up run, waiting out whatever run is already going.
///
/// Cursor allows one active run per agent and answers `agent_busy`
/// otherwise — and the other run is not necessarily ours, because the
/// agent's page on cursor.com drives the same agent. The session's
/// contract with its callers is a queue, so a busy agent is something to
/// wait behind, not an error. A client cancel abandons the wait.
async fn create_run_when_free(
&self,
session: &Session,
agent: &CursorAgentId,
prompt: &str,
model: Option<&ModelChoice>,
images: &[CursorPromptImage],
cancel: &tokio_util::sync::CancellationToken,
) -> Result<CursorRunId, SessionError> {
let mut released = false;
for _ in 0..BUSY_ATTEMPTS {
if cancel.is_cancelled() {
return Err(SessionError::Cursor(
rootcause::report!(crate::domain::error::PromptRejected(
"the prompt was cancelled while waiting for the agent to be free".into()
))
.into_dynamic(),
));
}
match self.cursor.create_run(agent, prompt, model, images).await {
Ok(run) => return Ok(run),
Err(error) if error.to_string().contains("agent_busy") => {
// A run this session already gave up on still holds the
// agent's single run slot, and it is not going to release
// it by itself — waiting out the full budget would only
// fail the prompt slower. Cancelling is terminal on
// Cursor's side, so it frees the agent and gives the
// abandoned run the terminal fact it needs to reconcile.
// Done once: a run that is merely slow, or one driven from
// cursor.com, is still something to wait behind.
if !std::mem::replace(&mut released, true) {
self.release_abandoned_runs(session, agent).await;
continue;
}
tracing::info!(%agent, "agent busy (a run is active, possibly from cursor.com); waiting");
if sleep_unless_cancelled(cancel, POLL_INTERVAL).await {
return Err(SessionError::Cursor(
rootcause::report!(crate::domain::error::PromptRejected(
"the prompt was cancelled while waiting for the agent to be free"
.into()
))
.into_dynamic(),
));
}
}
Err(error) => return Err(SessionError::Cursor(error)),
}
}
Err(SessionError::Cursor(
rootcause::report!(crate::domain::error::PromptRejected(format!(
"the agent stayed busy for {} seconds",
BUSY_ATTEMPTS as u64 * POLL_INTERVAL.as_secs()
)))
.into_dynamic(),
))
}
/// The runs a turn in this session already stopped waiting for.
///
/// A journal fact, not a guess: a run recorded as
/// [`JournalInput::Interrupted`] and never reconciled is one a turn gave
/// up on. That is the only class of run this service may cancel or
/// decline to recover — a run merely still going, including one driven
/// from cursor.com, is someone's live conversation.
fn abandoned_runs(session: &Session) -> Vec<CursorRunId> {
let state = session.state.lock().expect("session state poisoned");
let reconciled: std::collections::HashSet<_> = state
.journal_entries
.iter()
.filter(|e| e.input == JournalInput::Reconciled)
.filter_map(|e| e.run.clone())
.collect();
let mut abandoned = Vec::new();
for run in state
.journal_entries
.iter()
.filter(|e| matches!(e.input, JournalInput::Interrupted(_)))
.filter_map(|e| e.run.as_ref())
{
if !reconciled.contains(run) && !abandoned.contains(run) {
abandoned.push(run.clone());
}
}
abandoned
}
/// Cancel the runs this session abandoned, freeing the agent's run slot.
///
/// Cancellation is terminal on Cursor's side, so this both returns the
/// agent's single run slot and gives the abandoned run the terminal fact
/// it needs before it can ever reconcile.
///
/// Best effort. A cancel that fails leaves the caller exactly where it
/// was, waiting out the busy agent, so there is nothing here to fail on.
async fn release_abandoned_runs(&self, session: &Session, agent: &CursorAgentId) {
for run in Self::abandoned_runs(session) {
match self.cursor.cancel_run(agent, &run).await {
Ok(()) => {
tracing::info!(%agent, %run, "cancelled an abandoned run holding the agent");
}
Err(error) => {
tracing::warn!(%agent, %run, %error, "could not cancel an abandoned run");
}
}
}
}
/// Catch up foreign runs through the same journal path as local prompts.
///
/// `cancel` is the stop that ends a run still going: the turn's own token
/// when a prompt is catching up before it runs, the mirror's when the
/// host's sweep is. A run already finished is read to its end regardless
/// — the stream loop consults the token only where it waits — so a stop
/// never costs the recovery of history that is there to be had, only the
/// following of a run that has not ended. That run is left as a turn
/// leaves one it gave up on: interrupted, to be mirrored in once it does
/// end, and never blocking the prompt behind it again.
///
/// `emit` is [`Emit::Mirror`] for the host's sweep, which publishes the
/// runs as they happen and checkpoints them like a turn, and
/// [`Emit::Silent`] for a prompt catching up, whose own turn is already
/// open on the client; silent recovery is shown by a reload.
async fn backfill_foreign_runs(
&self,
session_id: &SessionId,
session: &Session,
agent: &CursorAgentId,
current_run: Option<&CursorRunId>,
cancel: &tokio_util::sync::CancellationToken,
emit: Emit,
) -> Result<bool, SessionError> {
self.ensure_journal(session_id, session).await?;
let last = session
.state
.lock()
.expect("session state poisoned")
.last_run
.clone();
// Full provider order is needed when an accepted newer run is
// waiting behind an older failed backfill. Include journal-pending runs
// even AT/BEFORE the delivered watermark, which is not a capture cursor.
let listings = self.cursor.list_runs(agent, None).await?;
let (pending, reconciled) = {
let state = session.state.lock().expect("session state poisoned");
let reconciled: std::collections::HashSet<_> = state
.journal_entries
.iter()
.filter(|e| e.input == JournalInput::Reconciled)
.filter_map(|e| e.run.clone())
.collect();
let mut pending = Vec::new();
for run in state.journal_entries.iter().filter_map(|e| e.run.as_ref()) {
if !reconciled.contains(run) && !pending.contains(run) {
pending.push(run.clone());
}
}
(pending, reconciled)
};
let newer: std::collections::HashSet<_> = listings
.iter()
.take_while(|r| Some(&r.id) != last.as_ref())
.map(|r| r.id.clone())
.collect();
// A run a turn already gave up on, which Cursor still has not ended,
// is not recoverable history: there is no terminal fact to reconcile
// against, and re-reading it cannot manufacture one. Retrying it here
// would fail every later prompt for as long as the run stays
// unfinished — which, when the provider wedges a run at `RUNNING`, is
// forever. Left pending instead, to be mirrored in once it does end.
//
// Deliberately not every unfinished run: one still going that no turn
// has abandoned — a prompt sent from cursor.com — is exactly what this
// backfill exists to stream in, and must still be followed.
let abandoned = Self::abandoned_runs(session);
let unfinished: std::collections::HashSet<_> = listings
.iter()
.filter(|r| !r.status.is_terminal() && abandoned.contains(&r.id))
.map(|r| r.id.clone())
.collect();
let listing_status: std::collections::HashMap<_, _> = listings
.iter()
.map(|r| (r.id.clone(), r.status.clone()))
.collect();
let mut runs = Vec::new();
// A pending run omitted by the provider listing still has to recover.
for run in &pending {
if !listings.iter().any(|r| &r.id == run) && current_run != Some(run) {
runs.push(run.clone());
}
}
for listing in listings.into_iter().rev() {
if current_run != Some(&listing.id)
&& (pending.contains(&listing.id) || newer.contains(&listing.id))
{
runs.push(listing.id);
}
}
runs.retain(|run| !unfinished.contains(run));
let mirrored = !runs.is_empty();
let mut delivered = None;
for run in &runs {
if !reconciled.contains(run) {
// Before the ingestion, not after: a run still going is
// followed to its end, however long that is, holding the
// turn gate the whole way. The first sign of one must not be
// a stream warning an hour in - it is this line, with the
// run's status as Cursor lists it right now.
let status = listing_status.get(run);
let still_running = status.is_some_and(|status| !status.is_terminal());
let started = std::time::Instant::now();
tracing::info!(
%agent,
%run,
cursor.run.status = ?status,
cursor.run.still_running = still_running,
cursor.run.listed = status.is_some(),
"recovering a run started elsewhere"
);
let outcome = self
.ingest_run(
session_id,
session,
agent,
run,
cancel,
IngestMode {
emit,
..IngestMode::LIVE
},
)
.await;
tracing::info!(
%agent,
%run,
cursor.run.still_running = still_running,
elapsed_ms = started.elapsed().as_millis() as u64,
outcome = ?outcome.as_ref().map_err(ToString::to_string),
"finished recovering a run started elsewhere"
);
outcome?;
}
let complete = session
.state
.lock()
.expect("session state poisoned")
.journal_entries
.iter()
.any(|e| e.run.as_ref() == Some(run) && e.input == JournalInput::Reconciled);
if !complete {
// A stop ended the following, not a failure: what was
// captured is still shown, and the prompt behind this (if
// any) answers Cancelled rather than failing.
if cancel.is_cancelled() {
tracing::info!(%agent, %run, "stopped following a run started elsewhere");
break;
}
return Err(rootcause::report!("Cursor run {run} remains unreconciled").into());
}
delivered = Some(run);
}
if mirrored {
// Everything the client has not seen went out live, so the runs
// are delivered the way a turn's is: checkpointed, no reload.
let unshown = session
.state
.lock()
.expect("session state poisoned")
.unshown;
if emit == Emit::Mirror && !unshown {
if let Some(run) = delivered {
self.notifier
.checkpoint(session_id, run)
.await
.map_err(SessionError::Cursor)?;
session
.state
.lock()
.expect("session state poisoned")
.last_run = Some(run.clone());
}
// A prompt that parked while the checkpoint was on its way
// may hold the run's last frames in its turn.
if !session
.state
.lock()
.expect("session state poisoned")
.unshown
{
return Ok(mirrored);
}
}
self.require_reload(session_id, session).await?;
}
Ok(mirrored)
}
/// Ask the host to reload, once, so a load shows what was captured.
///
/// Declined while the journal cannot yet replace the visible history:
/// a load then would show less than the client already has.
async fn require_reload(
&self,
session_id: &SessionId,
session: &Session,
) -> Result<(), SessionError> {
let notify = {
let mut state = session.state.lock().expect("session state poisoned");
if let Err(error) =
history_projection(&state.journal_entries, HistoryGap::DeclinesReplacement)
{
tracing::warn!(error = ?error, %session_id, "captured recovery cannot replace history yet");
return Ok(());
}
!std::mem::replace(&mut state.reload_pending, true)
};
if notify {
self.notifier
.require_reload(session_id)
.await
.inspect_err(|_| {
session
.state
.lock()
.expect("session state poisoned")
.reload_pending = false;
})?;
}
Ok(())
}
/// Re-host the walkthrough files this run produced and say so in the
/// turn's own text.
///
/// Artifacts never fail a turn: a listing that cannot be read, a file
/// that cannot be fetched or stored, is reported and skipped, and the
/// prompt still answers with the run's stop reason. Only a journal
/// failure propagates, and that is already fatal to the session by the
/// time it is seen here.
#[tracing::instrument(
name = "cursor.artifacts.collect",
skip_all,
fields(
cursor.agent.id = %agent,
artifacts.known = tracing::field::Empty,
artifacts.collected = tracing::field::Empty,
artifacts.retried = tracing::field::Empty,
),
)]
async fn collect_artifacts(
&self,
session_id: &SessionId,
session: &Session,
agent: &CursorAgentId,
run: &CursorRunId,
cancel: &tokio_util::sync::CancellationToken,
) -> Result<(), SessionError> {
if !self.artifacts.is_available() {
return Ok(());
}
let span = tracing::Span::current();
// Every earlier collection in this session, because the provider's
// listing is agent-scoped and repeats everything older turns wrote.
let known: std::collections::HashSet<String> = session
.state
.lock()
.expect("session state poisoned")
.journal_entries
.iter()
.filter_map(|entry| match &entry.input {
JournalInput::ArtifactsCollected(artifacts) => Some(artifacts),
_ => None,
})
.flatten()
.map(|artifact| artifact.key.clone())
.collect();
span.record("artifacts.known", known.len());
let Some(mut fresh) = self.new_artifacts(agent, &known).await else {
return Ok(());
};
let retried = fresh.is_empty();
span.record("artifacts.retried", retried);
if retried {
// A cancelled turn skips the wait and lists once more anyway:
// `sleep_unless_cancelled` returns immediately, and the second
// listing is the cheap half of this.
sleep_unless_cancelled(cancel, ARTIFACT_LISTING_RETRY_DELAY).await;
let Some(second) = self.new_artifacts(agent, &known).await else {
return Ok(());
};
fresh = second;
}
if fresh.is_empty() {
return Ok(());
}
let mut collected = Vec::new();
for listing in fresh {
if listing.size_bytes > MAX_ARTIFACT_BYTES {
tracing::warn!(
artifact.path = %listing.path,
artifact.size_bytes = listing.size_bytes,
artifact.size_limit = MAX_ARTIFACT_BYTES,
"skipping an artifact larger than this service will buffer"
);
continue;
}
let fetched = match self.cursor.fetch_artifact(agent, &listing.path).await {
Ok(fetched) => fetched,
Err(error) => {
tracing::warn!(
artifact.path = %listing.path,
%error,
"could not fetch an artifact from Cursor"
);
continue;
}
};
let mime_type = mime_type(listing.name(), fetched.content_type.as_deref());
let text = inline_text(listing.name(), &mime_type, &fetched.bytes);
match self
.artifacts
.store(listing.name(), &mime_type, fetched.bytes)
.await
{
Ok(uri) => collected.push(CollectedArtifact {
key: listing.key(),
name: listing.name().to_owned(),
mime_type,
uri,
size_bytes: listing.size_bytes,
text,
}),
Err(error) => tracing::warn!(
artifact.path = %listing.path,
%error,
"could not re-host an artifact"
),
}
}
span.record("artifacts.collected", collected.len());
if collected.is_empty() {
return Ok(());
}
tracing::info!(
%agent,
%run,
artifacts.collected = collected.len(),
"re-hosted this run's artifacts"
);
// Journalled and projected in one step, which is what puts the
// markdown on the wire: capture appends before it emits, so a crash
// between the two re-announces on replay instead of losing files
// whose provider links have since expired.
self.capture(
session_id,
session,
Some(run),
JournalInput::ArtifactsCollected(collected),
Emit::Live,
)
.await
}
/// The agent's artifacts this session has not collected yet, oldest
/// first. `None` means the listing itself failed and the turn carries on.
async fn new_artifacts(
&self,
agent: &CursorAgentId,
known: &std::collections::HashSet<String>,
) -> Option<Vec<ArtifactListing>> {
let listings = match self.cursor.list_artifacts(agent).await {
Ok(listings) => listings,
Err(error) => {
tracing::warn!(%agent, %error, "could not list this agent's artifacts");
return None;
}
};
let mut fresh: Vec<_> = listings
.into_iter()
.filter(|listing| !known.contains(&listing.key()))
.collect();
// Write order, as far as the provider's timestamps show it, so a
// walkthrough's screenshots read in the order they were taken.
fresh.sort_by(|left, right| {
(&left.updated_at, &left.path).cmp(&(&right.updated_at, &right.path))
});
Some(fresh)
}
async fn ensure_journal(&self, id: &SessionId, session: &Session) -> Result<(), SessionError> {
if session
.state
.lock()
.expect("session state poisoned")
.journal_loaded
{
return Ok(());
}
let entries = self.journal.read(id).await?;
let mut machine = ReplayMachine::default();
for entry in &entries {
// An entry that will not project is skipped rather than failed.
// It is already durable, so failing here fails identically every
// time this session is read, and a session whose journal cannot
// be read cannot be loaded or prompted ever again.
if let Err(error) = project_entry(&mut machine, entry, &entries) {
tracing::warn!(
%error,
sequence = entry.sequence,
"skipping a Cursor journal entry that will not project"
);
}
}
let fresh = {
let mut state = session.state.lock().expect("session state poisoned");
state.journal_entries = entries;
state.machine = machine;
state.journal_loaded = true;
state.fresh
};
if fresh {
self.capture(
id,
session,
None,
JournalInput::HistoryComplete,
Emit::Silent,
)
.await?;
session.state.lock().expect("session state poisoned").fresh = false;
}
Ok(())
}
/// The only route from provider input to translation and notifications.
/// Every caller holds the turn gate, including load/hydration and sync.
async fn capture(
&self,
id: &SessionId,
session: &Session,
run: Option<&CursorRunId>,
input: JournalInput,
emit: Emit,
) -> Result<(), SessionError> {
let (expected, duplicate) = {
let state = session.state.lock().expect("session state poisoned");
if state.capture_failed {
return Err(SessionError::Journal(rootcause::report!(
"reload required after native journal failure"
)));
}
(
state.journal_entries.last().map_or(0, |e| e.sequence),
matches!(input, JournalInput::Poll(_))
&& state
.journal_entries
.last()
.is_some_and(|e| e.run.as_ref() == run && e.input == input),
)
};
if duplicate {
return Ok(());
}
let entry = self
.journal
.append(id, expected, run, &input)
.await
.map_err(|error| {
let mut state = session.state.lock().expect("session state poisoned");
state.capture_failed = true;
state.ready_for_sync = false;
SessionError::Journal(error)
})?;
let (updates, completion, pull_request, working_branches) = {
let mut state = session.state.lock().expect("session state poisoned");
let previous_pr = state.machine.pull_request_url().map(str::to_owned);
let previous_branches = state.machine.working_branches().clone();
let before = run.and_then(|run| state.machine.terminal_status(run));
state.journal_entries.push(entry.clone());
let SessionState {
machine,
journal_entries,
..
} = &mut *state;
let updates = match project_entry(machine, &entry, journal_entries) {
Ok(updates) => updates,
Err(error) => {
state.capture_failed = true;
state.ready_for_sync = false;
return Err(SessionError::Journal(error));
}
};
// Local active prompts finish through their correlated response.
// A recovered tail has no pending response, so publish its fact.
let completion = if before.is_none() && run != state.active_run.as_ref() {
run.and_then(|run| state.machine.terminal_status(run))
.map(turn_outcome)
} else {
None
};
let pull_request = state
.machine
.pull_request_url()
.filter(|url| Some(*url) != previous_pr.as_deref())
.map(str::to_owned);
let working_branches: Vec<_> = state
.machine
.working_branches()
.iter()
.filter(|(repository, branch)| previous_branches.get(*repository) != Some(*branch))
.map(|(repository, branch)| (repository.clone(), branch.clone()))
.collect();
(updates, completion, pull_request, working_branches)
};
let emit = {
let emit_mode = emit;
let mut state = session.state.lock().expect("session state poisoned");
let emit = match emit {
Emit::Live => true,
Emit::Silent => false,
// Once anything is held back, the rest of the run is too:
// later frames make no sense to a client missing earlier ones.
Emit::Mirror => state.prompts_waiting == 0 && !state.unshown,
};
if emit && emit_mode == Emit::Mirror {
state.mirror_published_at = Some(tokio::time::Instant::now());
}
// A prompt's own blocks are on the client already: it sent them.
let visible = !updates.is_empty()
|| completion.is_some()
|| pull_request.is_some()
|| !working_branches.is_empty();
if !emit && visible && !matches!(input, JournalInput::Prompt(_)) {
state.unshown = true;
}
emit
};
if emit {
for (repository, branch) in working_branches {
self.notifier
.set_working_branch(id, &repository, &branch)
.await
.map_err(|error| {
let mut state = session.state.lock().expect("session state poisoned");
state.capture_failed = true;
state.ready_for_sync = false;
SessionError::Journal(error)
})?;
}
if let Some(url) = pull_request {
self.notifier
.set_pull_request(id, &url)
.await
.map_err(|error| {
let mut state = session.state.lock().expect("session state poisoned");
state.capture_failed = true;
state.ready_for_sync = false;
SessionError::Journal(error)
})?;
}
// The live prompt request already carries these original blocks.
// Replay projects them at the run boundary; live must not echo them.
let local_prompt = run.is_some_and(|run| {
let state = session.state.lock().expect("session state poisoned");
state.active_run.as_ref() == Some(run)
&& state.journal_entries.iter().any(|e| {
e.run.as_ref() == Some(run)
&& matches!(e.input, JournalInput::PromptAccepted(_))
})
});
for update in updates {
if local_prompt && restates_the_prompt(&update) {
continue;
}
self.notifier.notify(id, update).await.map_err(|error| {
let mut state = session.state.lock().expect("session state poisoned");
state.capture_failed = true;
state.ready_for_sync = false;
SessionError::Journal(error)
})?;
}
if let Some(outcome) = completion {
self.notifier
.turn_complete(id, outcome)
.await
.map_err(|error| {
let mut state = session.state.lock().expect("session state poisoned");
state.capture_failed = true;
state.ready_for_sync = false;
SessionError::Journal(error)
})?;
}
}
Ok(())
}
/// Fill in prompts the journal never captured, from Cursor's own record.
///
/// A run driven from cursor.com and mirrored here after its stream aged
/// out has an answer and no question: the stream is the only thing that
/// carries the opening message, and the run record left behind does not.
/// The conversation endpoint outlives both, so it is asked once per load
/// that has a gap, and what it recovers is journaled - a prompt written
/// exactly as a live one is, so it projects into place rather than onto
/// the end of the transcript, and so the next load needs no lookup.
///
/// Best effort throughout. Every failure here leaves the gap exactly as
/// it was, which the load already serves.
async fn recover_lost_prompts(
&self,
id: &SessionId,
session: &Session,
agent: Option<&CursorAgentId>,
) {
let Some(agent) = agent else {
return;
};
let lost = {
let state = session.state.lock().expect("session state poisoned");
runs_without_prompts(&state.journal_entries, &state.machine)
.into_iter()
.filter_map(|run| {
state
.machine
.answer(run)
.filter(|answer| !answer.is_empty())
.map(|answer| (run.clone(), answer.to_owned()))
})
.collect::<Vec<_>>()
};
if lost.is_empty() {
return;
}
let conversation = match self.cursor.conversation(agent).await {
Ok(conversation) => conversation,
Err(error) => {
tracing::warn!(%error, %agent, "could not read the Cursor conversation");
return;
}
};
for (run, answer) in lost {
let Some(prompt) = prompt_for_answer(&conversation, &answer) else {
tracing::warn!(%run, "no Cursor conversation line names this run's prompt");
continue;
};
let blocks = vec![ContentBlock::Text(TextContent::new(prompt))];
if let Err(error) = self
.capture(
id,
session,
None,
JournalInput::Prompt(blocks),
Emit::Silent,
)
.await
{
tracing::warn!(%error, %run, "could not journal a recovered Cursor prompt");
return;
}
let sequence = session
.state
.lock()
.expect("session state poisoned")
.journal_entries
.last()
.expect("captured prompt")
.sequence;
if let Err(error) = self
.capture(
id,
session,
Some(&run),
JournalInput::PromptAccepted(sequence),
Emit::Silent,
)
.await
{
tracing::warn!(%error, %run, "could not link a recovered Cursor prompt");
return;
}
tracing::info!(%run, "recovered a lost Cursor prompt from the conversation");
}
}
/// Reconstruct the entire session before allowing a successful load reply.
/// The returned guard serializes the reply itself with every live writer.
///
/// The runtime-side counterpart of the harness's handshake span: a
/// `session/load` that times out upstream is spent in here.
#[tracing::instrument(
name = "cursor.session.replay",
skip(self),
fields(agent.acp.session_id = ?id),
err,
)]
pub async fn replay_session(&self, id: &SessionId) -> Result<ReplayGuard, SessionError> {
let session = self.session(id)?;
let gate = Arc::clone(&session.turn_gate).lock_owned().await;
{
let mut state = session.state.lock().expect("session state poisoned");
state.ready_for_sync = false;
state.journal_loaded = false;
state.capture_failed = false;
}
self.ensure_journal(id, &session).await?;
let (agent, complete) = {
let state = session.state.lock().expect("session state poisoned");
(
state.agent.clone(),
state
.journal_entries
.iter()
.any(|e| e.input == JournalInput::HistoryComplete),
)
};
// Old sessions are only safe when every run can still be fetched in
// full (including its original user message), not just final answers.
if !complete {
if let Some(agent) = &agent {
let listings = self.cursor.list_runs(agent, None).await?;
if listings.is_empty() {
return Err(rootcause::report!(
"Cursor history unavailable for restored session"
)
.into());
}
for listing in listings.into_iter().rev() {
let captured = {
let state = session.state.lock().expect("session state poisoned");
state.machine.complete(&listing.id)
&& state.journal_entries.iter().any(|e| {
e.run.as_ref() == Some(&listing.id)
&& e.input == JournalInput::Reconciled
})
};
if captured {
continue;
}
self.ingest_run(
id,
&session,
agent,
&listing.id,
&tokio_util::sync::CancellationToken::new(),
IngestMode::HYDRATE,
)
.await?;
}
}
self.capture(
id,
&session,
None,
JournalInput::HistoryComplete,
Emit::Silent,
)
.await?;
}
// Before projecting, not after: a prompt recovered here closes the gap
// rather than merely surviving it, and lands in the transcript this
// load is about to publish.
self.recover_lost_prompts(id, &session, agent.as_ref())
.await;
let entries = session
.state
.lock()
.expect("session state poisoned")
.journal_entries
.clone();
// A gap here cannot be allowed to fail the load. The runtime reattaches
// to a disconnected session by loading it, so a load that refuses is
// also every future prompt refused as disconnected, with no way back.
let (machine, updates) = history_projection(&entries, HistoryGap::IsServedAnyway)?;
for (repository, branch) in machine.working_branches() {
self.notifier
.set_working_branch(id, repository, branch)
.await?;
}
if let Some(url) = machine.pull_request_url() {
self.notifier.set_pull_request(id, url).await?;
}
for (batch, outcome) in updates {
for update in batch {
self.notifier.notify(id, update).await?;
}
if let Some(outcome) = outcome {
self.notifier.turn_complete(id, outcome).await?;
}
}
if let Some(run) = entries.iter().rev().find_map(|entry| {
(entry.input == JournalInput::Reconciled)
.then_some(entry.run.as_ref())
.flatten()
}) {
self.notifier.checkpoint(id, run).await?;
session
.state
.lock()
.expect("session state poisoned")
.last_run = Some(run.clone());
}
session
.state
.lock()
.expect("session state poisoned")
.machine = machine;
Ok(ReplayGuard {
session,
_gate: gate,
})
}
/// Mirror cursor.com activity into every live session, once.
///
/// The host calls this on a timer while a session's transport is up, so
/// the cursor.com half of a conversation appears here within a tick of
/// happening rather than waiting for the next Macro prompt. A session
/// mid-turn is skipped (the turn gate is held). Failures are logged per
/// session and never stop the sweep.
pub async fn sync_foreign_runs(&self) {
let sessions: Vec<(SessionId, Arc<Session>)> = self
.sessions
.lock()
.expect("session map poisoned")
.iter()
.map(|(id, session)| (id.clone(), Arc::clone(session)))
.collect();
for (session_id, session) in sessions {
let Ok(_turn) = session.turn_gate.try_lock() else {
continue;
};
let agent = {
let state = session.state.lock().expect("session state poisoned");
(state.ready_for_sync && !state.reload_pending)
.then(|| state.agent.clone())
.flatten()
};
let Some(agent) = agent else {
continue;
};
// Fresh per sweep: a stop that landed between sweeps has nothing
// left to end, and must not end the next one.
let cancel = {
let mut state = session.state.lock().expect("session state poisoned");
state.mirror_cancel = tokio_util::sync::CancellationToken::new();
state.mirror_cancel.clone()
};
// Streaming a run is only whole if the client has everything
// before it; otherwise capture silently and let a load show it.
let emit = if session
.state
.lock()
.expect("session state poisoned")
.unshown
{
Emit::Silent
} else {
Emit::Mirror
};
if let Err(error) = self
.backfill_foreign_runs(&session_id, &session, &agent, None, &cancel, emit)
.await
{
tracing::warn!(%session_id, %agent, %error, "could not mirror cursor.com runs");
}
}
}
/// Whether any session is currently executing a turn.
///
/// Hosts use this to distinguish a genuinely idle connection from one
/// whose provider is still working without producing client updates.
#[must_use]
pub fn has_active_turn(&self) -> bool {
self.sessions
.lock()
.expect("session map poisoned")
.values()
.any(|session| session.turn_gate.try_lock().is_err())
}
fn session(&self, id: &SessionId) -> Result<Arc<Session>, SessionError> {
self.sessions
.lock()
.expect("session map poisoned")
.get(id)
.cloned()
.ok_or_else(|| SessionError::UnknownSession(id.clone()))
}
}
/// Holds the session writer gate through queuing the ACP load response.
pub struct ReplayGuard {
session: Arc<Session>,
_gate: tokio::sync::OwnedMutexGuard<()>,
}
impl ReplayGuard {
/// Enable continuation only after the response was successfully queued.
pub fn complete(self) {
let mut state = self.session.state.lock().expect("session state poisoned");
state.ready_for_sync = true;
state.reload_pending = false;
state.unshown = false;
state.mirror_published_at = None;
}
}
fn replay_input(
entry: &JournalEntry,
entries: &[JournalEntry],
) -> Result<JournalInput, rootcause::Report> {
match entry.input {
JournalInput::PromptAccepted(sequence) => entries
.iter()
.find(|e| e.sequence == sequence && e.run.is_none())
.map(|e| e.input.clone())
.ok_or_else(|| rootcause::report!("missing original Cursor prompt").into_dynamic()),
_ => Ok(entry.input.clone()),
}
}
/// Project conversational facts independently of pre-execution intent order.
fn project_entry(
machine: &mut ReplayMachine,
entry: &JournalEntry,
entries: &[JournalEntry],
) -> Result<Vec<SessionUpdate>, rootcause::Report> {
if matches!(entry.input, JournalInput::PromptAccepted(_))
|| (entry.run.is_none() && matches!(entry.input, JournalInput::Prompt(_)))
{
return Ok(Vec::new());
}
let mut updates = Vec::new();
if let Some(run) = &entry.run
&& !machine.has_prompt(run)
&& let Some(accepted) = entries.iter().find(|e| {
e.run.as_ref() == Some(run) && matches!(e.input, JournalInput::PromptAccepted(_))
})
{
updates.extend(machine.push(Some(run), &replay_input(accepted, entries)?)?);
}
if let JournalInput::PromptAborted(sequence) = entry.input
&& let Some(intent) = entries.iter().find(|e| e.sequence == sequence)
{
updates.extend(machine.push(None, &intent.input)?);
}
updates.extend(machine.push(entry.run.as_ref(), &entry.input)?);
Ok(updates)
}
fn turn_outcome(status: RunStatus) -> agent_runtime_protocol::domain::turn::TurnOutcome {
use agent_runtime_protocol::domain::turn::TurnOutcome;
match status {
RunStatus::Finished => TurnOutcome::Finished,
RunStatus::Cancelled => TurnOutcome::Cancelled,
status => TurnOutcome::Failed {
message: format!("Agent run ended in {status:?}"),
},
}
}
type HistoryUpdates = Vec<(
Vec<SessionUpdate>,
Option<agent_runtime_protocol::domain::turn::TurnOutcome>,
)>;
/// Runs the journal holds frames for but no opening prompt.
///
/// The same condition [`history_projection`] reports a gap on, named once so
/// recovery looks for exactly what the projection would complain about.
fn runs_without_prompts<'a>(
entries: &'a [JournalEntry],
machine: &ReplayMachine,
) -> Vec<&'a CursorRunId> {
let mut missing: Vec<&CursorRunId> = Vec::new();
for run in entries.iter().filter_map(|e| e.run.as_ref()) {
if missing.contains(&run) || machine.has_prompt(run) {
continue;
}
let accepted_only = entries
.iter()
.filter(|e| e.run.as_ref() == Some(run))
.all(|e| matches!(e.input, JournalInput::PromptAccepted(_)));
if !accepted_only {
missing.push(run);
}
}
missing
}
/// The prompt that produced `answer`, if the conversation says so plainly.
///
/// Anchored on the answer the journal already holds rather than on position:
/// Cursor's conversation carries no run ids, and its turn numbering does not
/// track the run list once runs are cancelled or fail. An answer that appears
/// more than once names no single turn - an agent that replied the same thing
/// twice is ordinary - so an ambiguous match yields nothing rather than a
/// guess. Attaching the wrong question to an answer is worse than leaving the
/// question blank, which is all a gap costs now.
fn prompt_for_answer<'a>(conversation: &'a [ConversationLine], answer: &str) -> Option<&'a str> {
let mut spoken = conversation
.iter()
.enumerate()
.filter(|(_, line)| line.speaker == ConversationSpeaker::Agent && line.text == answer);
let (at, _) = spoken.next()?;
if spoken.next().is_some() {
return None;
}
conversation[..at]
.iter()
.rev()
.find(|line| line.speaker == ConversationSpeaker::User)
.map(|line| line.text.as_str())
}
/// What a gap in the recovered history costs the caller asking for it.
///
/// Replacing a session's conversation is a choice, and a candidate missing a
/// turn's opening is worse than the history already on screen, so a gap
/// declines the replacement and what is there stands.
///
/// Loading is not a choice. The journal is the only history there is, and a
/// load that refuses leaves a session that cannot be opened and cannot be
/// prompted - the runtime reattaches by loading, so every later prompt is
/// refused as disconnected too. A gap is reported and the rest is served.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum HistoryGap {
DeclinesReplacement,
IsServedAnyway,
}
/// Whether `run` collects artifacts after `entry`, so its turn outcome has to
/// wait for them.
fn collects_artifacts_later(
entries: &[JournalEntry],
entry: &JournalEntry,
run: &CursorRunId,
) -> bool {
entries.iter().any(|later| {
later.sequence > entry.sequence
&& later.run.as_ref() == Some(run)
&& matches!(later.input, JournalInput::ArtifactsCollected(_))
})
}
fn history_projection(
entries: &[JournalEntry],
gap: HistoryGap,
) -> Result<(ReplayMachine, HistoryUpdates), SessionError> {
for entry in entries {
if entry.run.is_none()
&& matches!(entry.input, JournalInput::Prompt(_))
&& !entries.iter().any(|e| {
matches!(e.input, JournalInput::PromptAccepted(n) | JournalInput::PromptAborted(n) if n == entry.sequence)
})
{
if gap == HistoryGap::IsServedAnyway {
tracing::warn!(
sequence = entry.sequence,
"serving Cursor history whose prompt was never resolved"
);
break;
}
return Err(rootcause::report!("Cursor prompt acceptance is unknown; refusing incomplete replacement history").into());
}
}
let mut machine = ReplayMachine::default();
// Validate the whole candidate before publishing even its first frame.
// Intent position is audit order, not conversation order. Accepted
// prompts project immediately before their first native run input.
let mut updates = Vec::new();
// Turn outcomes held back past their run's terminal frame, keyed by run;
// see the artifact case below.
let mut deferred: HashMap<CursorRunId, agent_runtime_protocol::domain::turn::TurnOutcome> =
HashMap::new();
for entry in entries {
let before = entry
.run
.as_ref()
.and_then(|run| machine.terminal_status(run));
let projected = project_entry(&mut machine, entry, entries)?;
let terminal = entry
.run
.as_ref()
.and_then(|run| machine.terminal_status(run));
let outcome = if matches!(entry.input, JournalInput::PromptAborted(_)) {
Some(agent_runtime_protocol::domain::turn::TurnOutcome::Cancelled)
} else if before.is_none() {
terminal.map(turn_outcome)
} else {
None
};
// A run's artifacts are collected after its terminal frame but belong
// to the turn that produced them, and live delivery only ends the
// turn when the prompt answers - after that text. Holding the outcome
// back to the artifacts entry is what makes a reloaded session read
// in the same order the person watched it arrive.
let outcome = match (entry.run.as_ref(), outcome) {
(Some(run), Some(outcome)) if collects_artifacts_later(entries, entry, run) => {
deferred.insert(run.clone(), outcome);
None
}
(Some(run), None) if matches!(entry.input, JournalInput::ArtifactsCollected(_)) => {
deferred.remove(run)
}
(_, outcome) => outcome,
};
updates.push((projected, outcome));
}
// Acceptance can be durable before the first stream observation. Its
// prompt belongs at the unfinished tail, after captured older runs.
// If an older tail is still incomplete, defer the queued prompt until
// recovery reaches its run; it must not steal the older turn boundary.
for entry in entries {
if let JournalInput::PromptAccepted(_) = entry.input
&& let Some(run) = &entry.run
&& !machine.has_prompt(run)
&& !entries
.iter()
.filter_map(|e| e.run.as_ref())
.any(|other| other != run && machine.has_prompt(other) && !machine.complete(other))
{
updates.push((
machine.push(Some(run), &replay_input(entry, entries)?)?,
None,
));
}
}
for run in entries.iter().filter_map(|e| e.run.as_ref()) {
let accepted_only = entries
.iter()
.filter(|e| e.run.as_ref() == Some(run))
.all(|e| matches!(e.input, JournalInput::PromptAccepted(_)));
if !machine.has_prompt(run) && !accepted_only {
if gap == HistoryGap::IsServedAnyway {
// The run's own frames are already projected; only the line
// that opened it is missing. Serving the turn without it
// beats serving nothing, forever.
tracing::warn!(%run, "serving Cursor history without a run's original prompt");
continue;
}
return Err(rootcause::report!(
"Cursor original prompt unavailable for {run}; preserving existing history"
)
.into());
}
}
Ok((machine, updates))
}