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 ACP adapter, on the SDK's own connection machinery.
//!
//! [`serve`] registers one typed handler per method on
//! [`agent_client_protocol::Builder`] and hands the transport to the SDK.
//! Everything transport-shaped that used to live here is the SDK's job now,
//! and deliberately so — each of these was once hand-built in this file, as an
//! invariant maintained by design notes:
//!
//! - **One outgoing queue.** Responses and `session/update` notifications
//! leave through the same queue, so a `session/prompt` response can never
//! overtake the updates of its own turn. The SDK's outgoing actor is that
//! queue; [`AcpNotifier`] pushes into it via the connection handle rather
//! than owning a second one.
//! - **EOF drains the queue.** Responses already accepted when the client
//! hangs up are written out before the connection future resolves, so a
//! client that batches requests and closes its end still gets every answer.
//! - **Unknown methods answer `method_not_found`**, with the method name in
//! the error data.
//!
//! What remains here is what is genuinely this agent's: which methods exist,
//! what each one does to the session service, and which MCP servers can
//! honestly be forwarded to a cloud sandbox.
//!
//! Prompts and cancels run on connection-spawned tasks so a long-running turn
//! never blocks the event loop — that is what lets `session/cancel` land while
//! a turn is streaming.
#[cfg(test)]
mod test;
use crate::domain::error::SessionError;
use crate::domain::model::{McpHeader, McpServer, McpTransport};
use crate::domain::model_options::{
MODEL_CONFIG_ID, REASONING_EFFORT_CONFIG_ID, cursor_session_config_options,
};
use crate::domain::ports::{
ArtifactStore, CursorAgents, CursorArtifacts, RepositoryChooser, RunStream, SessionNotifier,
WorkingBranchReporter,
};
use crate::domain::service::CursorSessionService;
use crate::domain::slash_commands::cursor_slash_commands;
use agent_client_protocol::schema::ProtocolVersion;
use agent_client_protocol::schema::v1::{
AgentCapabilities, AuthenticateRequest, AuthenticateResponse, AvailableCommandsUpdate,
CancelNotification, CloseSessionRequest, CloseSessionResponse, ContentBlock, ContentChunk,
Error as AcpError, HttpHeader, Implementation, InitializeRequest, InitializeResponse,
LoadSessionRequest, LoadSessionResponse, McpCapabilities, McpServer as AcpMcpServer, Meta,
NewSessionRequest, NewSessionResponse, PromptCapabilities, PromptRequest, PromptResponse,
SessionConfigOption, SessionId, SessionNotification, SessionUpdate,
SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, TextContent,
};
use agent_client_protocol::{
Agent, ByteStreams, Client, ConnectTo, ConnectionTo, on_receive_notification,
on_receive_request,
};
use std::sync::{Arc, OnceLock};
use tokio_util::compat::{TokioAsyncReadCompatExt as _, TokioAsyncWriteCompatExt as _};
/// Delivers session updates as `session/update` notifications on the ACP
/// connection.
///
/// The domain service holds one of these for the whole connection and notifies
/// from wherever a turn produces updates — including
/// [`CursorSessionService::sync_foreign_runs`], which the Macro harness drives
/// on its own timer, *outside* any request handler. That is why this wraps a
/// connection handle the service can hold from construction, filled in by
/// [`serve`] once the connection exists, rather than a handle passed per call.
///
/// Notifications enter the connection's own outgoing queue — the same one
/// responses use — so a turn's updates and its `session/prompt` response
/// cannot reorder.
#[derive(Clone, Default)]
pub struct AcpNotifier {
/// Empty until the connection is up. Write-once: one notifier serves one
/// connection, exactly as one service does.
connection: Arc<OnceLock<ConnectionTo<Client>>>,
pull_request: Option<Arc<dyn PullRequestReporter>>,
working_branch: Option<Arc<dyn WorkingBranchReporter>>,
bound: Arc<tokio::sync::Notify>,
reload: Option<tokio::sync::mpsc::UnboundedSender<SessionId>>,
}
/// Host operation receiving PRs independently of ACP presentation.
pub trait PullRequestReporter: Send + Sync {
/// Persist a PR reported by this provider.
fn set_pull_request<'a>(
&'a self,
url: &'a str,
) -> std::pin::Pin<Box<dyn Future<Output = Result<(), rootcause::Report>> + Send + 'a>>;
}
impl AcpNotifier {
/// A notifier awaiting its connection.
#[must_use]
pub fn new() -> Self {
Self::default()
}
/// Deliver recovery requirements to the embedding ACP client, not the wire.
pub fn with_reload(mut self, reload: tokio::sync::mpsc::UnboundedSender<SessionId>) -> Self {
self.reload = Some(reload);
self
}
/// Use the embedding host's shared session operation for PR reports.
pub fn with_pull_requests(mut self, reporter: Arc<dyn PullRequestReporter>) -> Self {
self.pull_request = Some(reporter);
self
}
/// Use the embedding host's session operation for repository branch facts.
pub fn with_working_branches(mut self, reporter: Arc<dyn WorkingBranchReporter>) -> Self {
self.working_branch = Some(reporter);
self
}
/// Attach the connection updates will travel over.
fn bind(&self, connection: ConnectionTo<Client>) {
// A second bind can only be a bug in `serve`; the first connection
// stays authoritative and the duplicate is dropped.
let _ = self.connection.set(connection);
self.bound.notify_waiters();
}
}
impl SessionNotifier for AcpNotifier {
async fn set_working_branch(
&self,
_session: &SessionId,
repository_url: &str,
branch: &str,
) -> Result<(), rootcause::Report> {
if let Some(reporter) = &self.working_branch {
reporter.set_working_branch(repository_url, branch).await?;
}
Ok(())
}
async fn set_pull_request(
&self,
_session: &SessionId,
url: &str,
) -> Result<(), rootcause::Report> {
if let Some(reporter) = &self.pull_request {
reporter.set_pull_request(url).await?;
}
Ok(())
}
async fn notify(
&self,
session: &SessionId,
update: SessionUpdate,
) -> Result<(), rootcause::Report> {
let connection = loop {
let bound = self.bound.notified();
tokio::pin!(bound);
bound.as_mut().enable();
if let Some(connection) = self.connection.get() {
break connection;
}
bound.await;
};
connection
.send_notification(SessionNotification::new(session.clone(), update))
.map_err(|error| rootcause::report!("{error}"))
}
async fn require_reload(&self, session: &SessionId) -> Result<(), rootcause::Report> {
let Some(reload) = &self.reload else {
// Standalone ACP clients own their load lifecycle. Keep serving
// prompts without inventing a client request or pushing history.
tracing::warn!(%session, "recovered Cursor history is available on session/load");
return Ok(());
};
reload
.send(session.clone())
.map_err(|error| rootcause::report!("{error}"))
}
async fn turn_complete(
&self,
session: &SessionId,
outcome: agent_runtime_protocol::domain::turn::TurnOutcome,
) -> Result<(), rootcause::Report> {
let connection = self
.connection
.get()
.ok_or_else(|| rootcause::report!("ACP connection is not bound"))?;
connection
.send_notification(
agent_runtime_protocol::domain::turn::TurnCompleteNotification {
session_id: session.clone(),
outcome,
},
)
.map_err(|error| rootcause::report!("{error}"))
}
async fn checkpoint(
&self,
session: &SessionId,
run: &crate::domain::model::CursorRunId,
) -> Result<(), rootcause::Report> {
// Standalone domain tests and embedders without a durable host have no
// connection to checkpoint through. The Macro host always binds first;
// there the metadata marker is persisted with the ordinary ACP log.
let Some(connection) = self.connection.get() else {
return Ok(());
};
let mut meta = Meta::new();
meta.insert(
"macroCursorRunCheckpoint".to_owned(),
serde_json::Value::String(run.to_string()),
);
let update = SessionUpdate::AgentMessageChunk(ContentChunk::new(ContentBlock::Text(
TextContent::new(""),
)));
connection
.send_notification(SessionNotification::new(session.clone(), update).meta(meta))
.map_err(|error| rootcause::report!("{error}"))
}
}
/// The MCP servers this agent can honour, with the rest declined out loud.
///
/// `POST /v1/agents` accepts `mcpServers[]`, so a remote server the client
/// configures really is reachable from Cursor's sandbox and is forwarded
/// unchanged.
///
/// stdio is not, and the reason is locality rather than capability. ACP
/// defines its `command` as an absolute path on the **client's** machine, and
/// its `env` as literal values — routinely API tokens. Forwarding that would
/// ask Cursor to spawn a different executable, on different hardware, with
/// the user's secrets, and the result would look configured while being
/// wired to nothing. ACP does say every agent must support stdio; an agent
/// whose work happens in someone else's sandbox cannot, and saying so is
/// better than pretending.
///
/// An entry whose shape the schema cannot read at all never reaches here: ACP
/// declares `mcpServers` item-skipping, so the schema drops it and the request
/// still succeeds. That is the property this used to buy with a hand-written
/// enum.
fn forwardable_mcp_servers(requested: Vec<AcpMcpServer>) -> Vec<McpServer> {
let mut forwarded = Vec::new();
let mut declined = Vec::new();
for server in requested {
let remote = match server {
AcpMcpServer::Http(http) => McpServer {
name: http.name,
transport: McpTransport::Http,
url: http.url,
headers: forwardable_headers(http.headers),
},
AcpMcpServer::Sse(sse) => McpServer {
name: sse.name,
transport: McpTransport::Sse,
url: sse.url,
headers: forwardable_headers(sse.headers),
},
AcpMcpServer::Stdio(stdio) => {
declined.push(stdio.name);
continue;
}
// The schema's `McpServer` is non-exhaustive: a transport added to
// ACP after this was written is unforwardable until it is handled
// here, and saying so beats pretending it was configured.
other => {
tracing::warn!(server = ?other, "declining an MCP transport this agent cannot forward");
continue;
}
};
forwarded.push(remote);
}
if !declined.is_empty() {
tracing::warn!(
servers = ?declined,
"declining stdio MCP servers: they name an executable on this machine, but the \
agent runs in Cursor's sandbox - configure these as http or sse servers to \
forward them"
);
}
forwarded
}
/// ACP's `{name, value}` header pairs as this crate's domain models them.
fn forwardable_headers(headers: Vec<HttpHeader>) -> Vec<McpHeader> {
headers
.into_iter()
.map(|header| McpHeader {
name: header.name,
value: header.value,
})
.collect()
}
/// What this agent actually supports.
///
/// Only claims what the code does. [`prompt_text`] turns a `ResourceLink`
/// into an `@`-mention, so embedded context is real and advertising it false
/// suppressed context the agent handles fine. HTTP and SSE MCP servers are
/// forwarded to Cursor at agent creation, so those are real too — while stdio
/// is declined, which is why no capability claims it (see
/// [`forwardable_mcp_servers`]). Pasted links that fetch as images are sent
/// as Cursor prompt images and as ACP image frames, so image is real. Audio
/// is not.
///
/// Nothing here can express the divergence that matters most: this agent
/// never sends `session/request_permission`, because Cursor approves tool use
/// server-side and exposes no hook to intercept it. An ACP client's
/// permission gate therefore does not apply to anything this agent does. ACP
/// has no capability field for "I will never ask", so it is said on stderr at
/// startup instead — see the binary's docs.
fn agent_capabilities() -> AgentCapabilities {
AgentCapabilities::default()
.prompt_capabilities(PromptCapabilities::new().embedded_context(true).image(true))
.mcp_capabilities(McpCapabilities::new().http(true).sse(true))
// Without this a client resuming a session it persisted never sends
// `session/load` — it gives up on the session instead, which for the
// Macro harness means a session that stops answering after a restart.
.load_session(true)
}
/// Serve ACP over a byte stream until it closes: newline-delimited JSON, one
/// frame per line.
///
/// The two production transports are both byte streams — the binary's
/// stdin/stdout, and the Macro harness's in-process `tokio::io::duplex` — so
/// this takes the tokio halves directly and keeps the SDK types out of the
/// callers. Anything more exotic goes through [`serve_transport`].
///
/// `notifier` must be the same [`AcpNotifier`] the service was constructed
/// with (they share state through a clone): the service delivers updates
/// through it, and this function is what binds it to the connection.
///
/// # Errors
///
/// A clean EOF from the client is `Ok`; transport and protocol-level failures
/// are the SDK's error.
pub async fn serve<Reader, Writer, Cursor, Notifier, Chooser, Store>(
service: Arc<CursorSessionService<Cursor, Notifier, Chooser, Store>>,
notifier: AcpNotifier,
reader: Reader,
writer: Writer,
) -> Result<(), AcpError>
where
Reader: tokio::io::AsyncRead + Send + 'static,
Writer: tokio::io::AsyncWrite + Send + 'static,
Cursor: CursorAgents + CursorArtifacts + RunStream + Send + Sync + 'static,
Notifier: SessionNotifier + Send + Sync + 'static,
Chooser: RepositoryChooser + 'static,
Store: ArtifactStore + 'static,
{
serve_transport(
service,
notifier,
ByteStreams::new(writer.compat_write(), reader.compat()),
)
.await
}
/// [`serve`] over any transport the SDK can connect to — a
/// [`Channel`](agent_client_protocol::Channel) pair in tests, byte streams in
/// production.
///
/// # Errors
///
/// A clean EOF from the client is `Ok`; transport and protocol-level failures
/// are the SDK's error.
pub async fn serve_transport<Transport, Cursor, Notifier, Chooser, Store>(
service: Arc<CursorSessionService<Cursor, Notifier, Chooser, Store>>,
notifier: AcpNotifier,
transport: Transport,
) -> Result<(), AcpError>
where
Transport: ConnectTo<Agent> + 'static,
Cursor: CursorAgents + CursorArtifacts + RunStream + Send + Sync + 'static,
Notifier: SessionNotifier + Send + Sync + 'static,
Chooser: RepositoryChooser + 'static,
Store: ArtifactStore + 'static,
{
let startup_notifier = notifier.clone();
Agent
.builder()
.name("cursor-cloud-agents")
// Runs with the connection's event loop, so the notifier is bound
// before any handler can start a turn that would notify.
.with_spawned(move |connection| async move {
startup_notifier.bind(connection);
Ok(())
})
.on_receive_request(
async move |request: InitializeRequest, responder, _connection| {
// Answer with the newest version both sides speak: a client
// offering v0 must not be told v1 and left disagreeing about
// the wire format, and a client offering something newer than
// this agent gets this agent's newest, not an echo.
responder.respond(
InitializeResponse::new(request.protocol_version.min(ProtocolVersion::V1))
.agent_capabilities(agent_capabilities())
.agent_info(Implementation::new("cursor-acp", env!("CARGO_PKG_VERSION"))),
)
},
on_receive_request!(),
)
.on_receive_request(
async move |_request: AuthenticateRequest, responder, _connection| {
// The API key comes from the environment; nothing to negotiate
// with the client, so not even the method it named is read.
responder.respond(AuthenticateResponse::new())
},
on_receive_request!(),
)
.on_receive_request(
{
let service = Arc::clone(&service);
let notifier = notifier.clone();
async move |request: NewSessionRequest, responder, connection| {
notifier.bind(connection.clone());
let mcp_servers = forwardable_mcp_servers(request.mcp_servers);
let session = service.new_session(&request.cwd, mcp_servers);
let options = session_config_options(&service, &session).await;
let response = responder
.respond(NewSessionResponse::new(session.clone()).config_options(options));
// After the session exists, same as Cursor's own ACP agent:
// commands arrive on `session/update`, not on the new-session
// result. A failure here costs the `/` menu, not the session.
advertise_slash_commands(¬ifier, &session).await;
response
}
},
on_receive_request!(),
)
.on_receive_request(
{
let service = Arc::clone(&service);
let notifier = notifier.clone();
async move |request: PromptRequest, responder, connection| {
notifier.bind(connection.clone());
// On its own task so the event loop keeps servicing
// cancels while the turn streams.
let service = Arc::clone(&service);
connection.spawn(async move {
let session = request.session_id;
let text = prompt_text(&request.prompt);
// A failed respond means the client is gone; failing
// the spawned task would tear down the (already
// closing) connection, so it is dropped instead.
match service
.prompt_content(&session, &text, request.prompt)
.await
{
Ok(stop_reason) => {
let _ = responder.respond(PromptResponse::new(stop_reason));
}
Err(error) => {
tracing::error!(error = %error, "prompt failed");
let _ = responder.respond_with_error(prompt_error(&error));
}
}
Ok(())
})
}
},
on_receive_request!(),
)
.on_receive_request(
{
let service = Arc::clone(&service);
let notifier = notifier.clone();
async move |request: LoadSessionRequest, responder, connection| {
notifier.bind(connection.clone());
let session = request.session_id;
let guard = match service.replay_session(&session).await {
Ok(guard) => guard,
Err(error) => {
return responder
.respond_with_error(AcpError::new(-32603, error.to_string()));
}
};
service.set_mcp_servers(&session, forwardable_mcp_servers(request.mcp_servers));
let options = session_config_options(&service, &session).await;
let response =
responder.respond(LoadSessionResponse::new().config_options(options));
if response.is_ok() {
guard.complete();
advertise_slash_commands(¬ifier, &session).await;
}
response
}
},
on_receive_request!(),
)
.on_receive_request(
{
let service = Arc::clone(&service);
async move |request: CloseSessionRequest, responder, _connection| {
// Dropping a session the client is done with, so the
// session map does not grow for the process lifetime. A
// session this agent never had is the client's mistake,
// not a no-op worth acknowledging.
if service.close(&request.session_id) {
responder.respond(CloseSessionResponse::new())
} else {
responder.respond_with_error(AcpError::invalid_params())
}
}
},
on_receive_request!(),
)
.on_receive_request(
{
let service = Arc::clone(&service);
async move |request: SetSessionConfigOptionRequest, responder, _connection| {
let session = request.session_id;
let Some(model) = request.value.as_value_id() else {
return responder.respond_with_error(AcpError::invalid_params());
};
let result = match request.config_id.to_string().as_str() {
MODEL_CONFIG_ID => service.set_model(&session, &model.to_string()).await,
REASONING_EFFORT_CONFIG_ID => {
service
.set_reasoning_effort(&session, &model.to_string())
.await
}
_ => return responder.respond_with_error(AcpError::invalid_params()),
};
if let Err(error) = result {
// The id is the client's to get right, and the error
// names what this account may choose instead.
tracing::warn!(error = %error, "could not set the session model");
return responder.respond_with_error(AcpError::invalid_params());
}
// Answered with the whole option set, not just the new
// value: that is the shape a client folds config from, and
// it is the same shape `session/new` sent.
let options = session_config_options(&service, &session).await;
responder.respond(SetSessionConfigOptionResponse::new(options))
}
},
on_receive_request!(),
)
.on_receive_notification(
{
let service = Arc::clone(&service);
async move |notification: CancelNotification, connection| {
// Spawned for the same reason prompts are: cancelling is a
// Cursor API round trip, and the event loop must not wait
// on it.
let service = Arc::clone(&service);
connection.spawn(async move {
let session = notification.session_id;
if let Err(error) = service.cancel(&session).await {
tracing::error!(error = %error, "cancel failed");
}
Ok(())
})
}
},
on_receive_notification!(),
)
.connect_to(transport)
.await
}
/// The session's config options: model and any effort values its variant supports.
///
/// This is the whole of how a client learns which models exist and which one a
/// session is on — ACP carries it as `configOptions` on the `session/new`,
/// `session/load` and `session/set_config_option` responses, and a client reads
/// the same field whichever response it arrived on.
///
/// One entry per model, using Cursor's own default variant, rather than one per
/// variant: `claude-opus-4-8` alone offers forty, and a picker listing hundreds
/// of near-identical rows is worse than one listing the models. Exposing the
/// reasoning variant is projected as a separate ACP thought-level control;
/// unrelated variant parameters remain on Cursor's selected default.
///
/// The entries go out grouped by family ([`ModelFamily`]) — ACP's select
/// options may be headed groups — so a client can show `Claude Opus` once with
/// its versions under it rather than forty rows sorted by nothing. The family
/// is inferred from the display name, because Cursor's listing carries nothing
/// else to group on. A listing where no family has two members goes out flat:
/// a header per single model is noise, not structure.
///
/// A failure to reach `GET /v1/models` costs the picker, not the session: the
/// options come back empty and the client simply has nothing to offer, which is
/// the state it was in before any of this existed.
async fn session_config_options<Cursor, Notifier, Chooser, Store>(
service: &CursorSessionService<Cursor, Notifier, Chooser, Store>,
session: &SessionId,
) -> Vec<SessionConfigOption>
where
Cursor: CursorAgents + CursorArtifacts + RunStream,
Notifier: SessionNotifier,
Chooser: RepositoryChooser,
Store: ArtifactStore,
{
let models = match service.models().await {
Ok(models) => models,
Err(error) => {
tracing::warn!(error = %error, "could not list cursor models; offering no model choice");
return Vec::new();
}
};
let current = match service.session_model(session).await {
Ok(current) => current,
Err(error) => {
tracing::warn!(error = %error, "could not read the session's model");
return Vec::new();
}
};
// With no explicit or configured choice, the select rests on Cursor's own
// "Auto" entry — a real model in their list (`id: "default"`), the same
// resting value their own picker shows, and the closest ACP can get to
// the truth: the account's configured default is resolved server-side at
// agent creation and never disclosed (`/v1/me` and `/v1/models` both
// carry no marker for it). Display only — the session's state stays
// unset, so runs keep omitting `model` and Cursor keeps resolving the
// user's own default. Only an explicit pick of "Auto" pins `default` onto
// the wire, which forces Auto routing over the account default; the
// difference is invisible unless the account default is a concrete model.
//
// If Cursor ever drops the entry there is no honest resting value, and no
// picker beats one resting on a guess.
cursor_session_config_options(&models, current.as_ref())
}
/// Advertise the curated Cursor slash-command catalog as an
/// `available_commands_update`.
///
/// There is no `GET /v1/skills` to fetch — see [`cursor_slash_commands`]. The
/// fold stores whatever this notification carries, and the agents-block
/// composer only opens `/` when that list is non-empty. Sending nothing is
/// why Cursor sessions used to treat `/` as plain text.
async fn advertise_slash_commands(notifier: &AcpNotifier, session: &SessionId) {
if let Err(error) = notifier
.notify(
session,
SessionUpdate::AvailableCommandsUpdate(AvailableCommandsUpdate::new(
cursor_slash_commands(),
)),
)
.await
{
tracing::warn!(error = %error, "could not advertise cursor slash commands");
}
}
/// The `session/prompt` error for a failed turn.
///
/// The message is the error's `Display` - one sentence for a refusal, the
/// report for anything else. A refusal the person can act on also carries
/// its notice as the error's `data`, which is where the fold picks it up.
fn prompt_error(error: &SessionError) -> AcpError {
let acp_error = AcpError::new(-32603, error.to_string());
match error {
#[cfg(feature = "postgres")]
SessionError::Admission(error) => acp_error.data(Some(serde_json::json!({
"code": error.code(),
"retryable": error.is_retryable(),
}))),
SessionError::Rejected(refusal) => acp_error.data(
refusal
.notice
.as_ref()
.and_then(|notice| serde_json::to_value(notice).ok()),
),
_ => acp_error,
}
}
/// Concatenate a prompt's content blocks into the single string Cursor takes.
fn prompt_text(blocks: &[ContentBlock]) -> String {
blocks
.iter()
.filter_map(|block| match block {
ContentBlock::Text(text) => Some(text.text.clone()),
ContentBlock::ResourceLink(link) => Some(format!("@{}", link.uri)),
_ => None,
})
.collect::<Vec<_>>()
.join("\n")
}