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 Cursor cloud API client.
//!
//! A plain reqwest wrapper over `api.cursor.com`'s Cloud Agents API — create
//! an agent, follow up with runs, cancel, and stream a run's SSE events. It
//! knows nothing about ACP; it implements the domain's
//! [`CursorAgents`]/[`RunStream`] ports, retaining native SSE records for
//! capture before the domain decodes them.
//!
//! Authentication is HTTP Basic with the API key as username and an empty
//! password, per Cursor's docs. The key is validated for shape at
//! construction so a placeholder pasted into a config fails at startup with
//! a message, not at first prompt with a bare 401.
#[cfg(test)]
mod test;
/// Capturing raw SSE bytes as fixtures.
pub mod record;
/// Reading a stream's body, and the report written when it fails.
mod stream;
/// Request/response DTOs for the endpoints this crate uses.
pub mod wire;
use crate::api::record::SseRecording;
use crate::api::stream::ConnectionFacts;
use crate::api::wire::{
AgentSummary, ArchiveAgentResponse, ArtifactDownloadResponse, ConversationResponse,
CreateAgentRequest, CreateAgentResponse, CreateRunRequest, CreateRunResponse,
ListAgentsResponse, ListArtifactsResponse, ListModelsResponse, ListRunsResponse,
McpServerSelection, MeResponse, ModelSelection, PromptBody, PromptImage, RepoSelection,
};
use crate::domain::artifact::{ArtifactListing, FetchedArtifact};
use crate::domain::model::{
ConversationLine, ConversationSpeaker, CursorAgentId, CursorModel, CursorRunId, McpServer,
ModelChoice, ModelParam, ModelVariant, RepoUrl, RunListing,
};
use crate::domain::ports::{
ConnectedStream, CursorAgents, CursorArtifacts, RunStream, StreamConnectError,
};
use crate::domain::prompt_image::CursorPromptImage;
use futures::Stream;
use std::num::NonZeroUsize;
/// The largest single SSE record payload this agent will buffer, 16 MiB.
///
/// A bound is required rather than optional: without one, a stream that never
/// sends a blank line grows a buffer until the process dies, which the
/// hand-rolled decoder this replaced was quietly vulnerable to.
///
/// 16 MiB rather than `sse_core`'s 512 KiB default because Cursor's tool
/// results embed whole file contents — a `read_file` on a large source file is
/// ordinary traffic, not an attack, and a run should not fail for it. The
/// largest payload in the recorded corpus is 7.7 KB, so this is far past any
/// legitimate one while still bounded. Shared with [`crate::replay`] so a
/// fixture decodes exactly as the wire does; a second limit somewhere else
/// would mean the corpus no longer tests what production runs.
///
/// Typed `NonZeroUsize` so the zero case is a compile error rather than a
/// runtime unwrap.
pub(crate) const MAX_SSE_PAYLOAD: NonZeroUsize = match NonZeroUsize::new(16 * 1024 * 1024) {
Some(limit) => limit,
None => panic!("the payload limit is a non-zero literal"),
};
fn prompt_body(text: &str, images: &[CursorPromptImage]) -> PromptBody {
PromptBody {
text: text.to_owned(),
images: images
.iter()
.map(|image| PromptImage {
data: image.data.clone(),
mime_type: image.mime_type.clone(),
})
.collect(),
}
}
/// The one real base url. A [`CursorConfig`] still names its own, because a
/// test points at a stand-in server, but there is nothing for a deployment to
/// choose between.
pub const CURSOR_API_BASE_URL: &str = "https://api.cursor.com";
macro_env_var::maybe_env_vars! {
/// Overrides [`CURSOR_API_BASE_URL`] when set. Only a local stack sets
/// it, to point every Cursor call at a stand-in server; deployed
/// environments leave it unset and talk to Cursor.
pub struct CursorApiBaseUrl;
}
/// The Cursor API base url this process should call: the
/// `CURSOR_API_BASE_URL` override when set, else the one real
/// [`CURSOR_API_BASE_URL`].
#[must_use]
pub fn cursor_api_base_url() -> String {
CursorApiBaseUrl::new()
.map(|url| url.trim_end_matches('/').to_owned())
.filter(|url| !url.is_empty())
.unwrap_or_else(|| CURSOR_API_BASE_URL.to_owned())
}
/// A Cursor API key that never prints itself and does not outlive its client.
///
/// The key used to be a bare `String` in a `Debug`-deriving config, so a
/// single `tracing::debug!(?config)` — or any `{:?}` on the client — wrote a
/// live credential into the user's log file. A newtype whose `Debug` redacts
/// makes that unrepresentable; the plaintext leaves only through
/// [`ApiKey::expose`], which is the Basic-auth header and nothing else.
///
/// `Zeroizing` because server-side these are *users'* keys, decrypted per
/// session and held for as long as the session's client lives. That is a copy
/// per concurrent session in a long-lived process, so the least it can do is
/// not linger in freed memory once the session ends.
#[derive(Clone)]
pub struct ApiKey(zeroize::Zeroizing<String>);
impl ApiKey {
/// Wrap a key.
///
/// Keys routinely arrive from JSON `env` blocks with surrounding quotes
/// or a trailing newline, which the API rejects as an *invalid* key rather
/// than a malformed header — so the key is trimmed and unquoted here,
/// before anything validates or sends it.
#[must_use]
pub fn new(key: impl AsRef<str>) -> Self {
Self(zeroize::Zeroizing::new(
key.as_ref()
.trim()
.trim_matches(|character| character == '"' || character == '\'')
.to_owned(),
))
}
/// The plaintext key. Only for handing to the transport that authenticates
/// with it — never for logging.
#[must_use]
pub fn expose(&self) -> &str {
&self.0
}
}
impl std::fmt::Debug for ApiKey {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("ApiKey(redacted)")
}
}
/// The prefixes a Cursor API key carries. Cursor now mints `grok_` keys, and
/// the `crsr_` keys minted before that still authenticate.
const CURSOR_KEY_PREFIXES: [&str; 2] = ["crsr_", "grok_"];
/// Static configuration for a [`CursorClient`].
#[derive(Debug, Clone)]
pub struct CursorConfig {
/// The API key (`grok_…`, or `crsr_…` for older keys).
pub api_key: ApiKey,
/// Base url, `https://api.cursor.com` outside tests.
pub base_url: String,
/// Model id to request, or the server default when `None`.
pub model: Option<String>,
/// Starting ref for new agents' repos.
pub starting_ref: String,
/// Where to record each run's raw SSE bytes, for turning real traffic
/// into fixtures. `None` records nothing, which is the default.
pub record_dir: Option<std::path::PathBuf>,
}
/// Why a [`CursorClient`] could not be constructed.
#[derive(Debug, thiserror::Error)]
pub enum CursorClientError {
/// The key does not look like a Cursor key. Caught here so a placeholder
/// (`"..."`) fails when the client is built, with a message, instead of at
/// the first prompt with a bare 401. The length and prefix are the only
/// diagnostics that are safe to print: enough to recognize a placeholder
/// or a stray quote, never enough to reconstruct a real key.
#[error(
"not a Cursor API key (got {length} chars starting {prefix:?}, expected a \"grok_\" or \"crsr_\" prefix)"
)]
MalformedKey {
/// Length of the offending key.
length: usize,
/// Its first few characters, for recognizing a placeholder.
prefix: String,
},
/// The underlying HTTP client could not be built.
#[error(transparent)]
Http(#[from] reqwest::Error),
}
/// Cursor's error codes for "this key's account cannot reach that repository".
///
/// `repository_access` is the direct one: the repo exists but this account
/// cannot use it. `integration_not_connected` is the same wall one step
/// earlier — the GitHub app is not installed for the owner at all — and its
/// remedy is the same connect flow, which is why both map to one error.
///
/// Deliberately excluded: `repository_required` (the request sent no repo, a
/// bug here, not the user's), `validation_error` in general (a malformed url
/// is ours to fix; the one branch-verification wording is matched separately
/// by [`classify_repository_rejection`]), and `unauthorized`/`plan_required`
/// (about the key, not the repo).
const REPOSITORY_ACCESS_CODES: [&str; 2] = ["repository_access", "integration_not_connected"];
/// The wording Cursor uses when its GitHub-side check could not confirm the
/// starting ref. Filed under the generic `validation_error` code, so the
/// message is the only handle. Seen in production for a `main` that existed,
/// and reported on Cursor's forum as intermittent for unchanged inputs.
const BRANCH_UNVERIFIABLE_MESSAGE: &str = "Failed to verify existence of branch";
/// How long to wait before each retry of a create that Cursor answered with
/// [`BRANCH_UNVERIFIABLE_MESSAGE`]; its length is the retry budget.
///
/// Retrying is safe here and nowhere else in create: the 400 proves no agent
/// was minted, so a second POST cannot duplicate work on cursor.com. Two
/// retries and ~7s is enough to ride out a flake without holding a chat
/// turn open for long when the repository genuinely is not visible.
const BRANCH_UNVERIFIABLE_RETRY_BACKOFF: [std::time::Duration; 2] = [
std::time::Duration::from_secs(2),
std::time::Duration::from_secs(5),
];
/// How long to wait before each retry of a POST that starts a turn; its
/// length is the retry budget.
///
/// Sized against the one limit we have watched a turn die on — GitHub
/// throttling Cursor's token mint, asking for sixty seconds (prod,
/// 2026-09-22). Forty-two seconds of asking does not outlast that, and is
/// not meant to: a turn that sits silent for a full minute is its own kind
/// of broken. It covers a limit that clears early, a gateway restarting,
/// and every other transient that is measured in seconds.
const TURN_START_RETRY_BACKOFF: [std::time::Duration; 3] = [
std::time::Duration::from_secs(2),
std::time::Duration::from_secs(10),
std::time::Duration::from_secs(30),
];
/// Whether a failed POST is worth simply asking again.
///
/// Status alone, deliberately. Every provider states its transients in its
/// own dialect — Cursor's 429 arrives as a `connect` envelope wrapping a
/// base64 blob — and a classifier that reads bodies is a classifier that
/// goes stale the first time one changes. The status codes do not: 429 and
/// 5xx mean "not now", 408 means the request never landed, and every other
/// 4xx is a fact about the request itself that an identical second POST
/// cannot change.
fn is_transient(status: reqwest::StatusCode) -> bool {
status == reqwest::StatusCode::TOO_MANY_REQUESTS
|| status == reqwest::StatusCode::REQUEST_TIMEOUT
|| status.is_server_error()
}
/// Which repository refusal, if any, a create-agent failure is.
///
/// Matches only the documented envelope, `{"error": {"code", "message"}}`,
/// and only on a 4xx: an unrecognized body — a different code, a proxy's
/// HTML, a 5xx — is left to the generic path so a new failure mode is never
/// mislabelled as a repository the user must go connect.
fn classify_repository_rejection(
status: reqwest::StatusCode,
body: &str,
starting_ref: &str,
) -> Option<crate::domain::error::RepositoryRejection> {
use crate::domain::error::RepositoryRejection;
if !status.is_client_error() || status == reqwest::StatusCode::REQUEST_TIMEOUT {
return None;
}
let envelope = serde_json::from_str::<crate::api::wire::ApiErrorEnvelope>(body).ok()?;
if REPOSITORY_ACCESS_CODES.contains(&envelope.error.code.as_str()) {
return Some(RepositoryRejection::Inaccessible);
}
if envelope.error.code == "validation_error"
&& envelope.error.message.contains(BRANCH_UNVERIFIABLE_MESSAGE)
{
return Some(RepositoryRejection::BranchUnverifiable {
starting_ref: starting_ref.to_owned(),
});
}
None
}
/// Whether a 4xx body is Cursor refusing for want of budget.
///
/// Keyed on the envelope's `error.code` alone. The message names a dollar
/// figure and a dashboard, both Cursor's to reword; the code is the contract.
/// Reached for a create and for a follow-up run alike - a budget runs out
/// mid-conversation as readily as before it.
fn classify_usage_limit(body: &str) -> Option<crate::domain::error::UsageLimitExceeded> {
let envelope = serde_json::from_str::<crate::api::wire::ApiErrorEnvelope>(body).ok()?;
crate::domain::error::UsageLimitExceeded::CODES
.contains(&envelope.error.code.as_str())
.then(|| crate::domain::error::UsageLimitExceeded {
code: envelope.error.code,
detail: body.to_owned(),
})
}
/// The Cursor cloud API client.
#[derive(Debug, Clone)]
pub struct CursorClient {
http: reqwest::Client,
config: CursorConfig,
/// Delays before each retry of a branch-unverifiable create; see
/// [`BRANCH_UNVERIFIABLE_RETRY_BACKOFF`]. Overridable so a test can
/// exercise the retry without sleeping through the production schedule.
branch_retry_backoff: Vec<std::time::Duration>,
turn_start_retry_backoff: Vec<std::time::Duration>,
}
impl CursorClient {
/// Build a client, validating the key's shape.
///
/// [`ApiKey::new`] has already trimmed the stray quotes and newlines a key
/// picks up in transit, so what is checked here is the key itself.
pub fn new(config: CursorConfig) -> Result<Self, CursorClientError> {
let key = config.api_key.expose();
if !CURSOR_KEY_PREFIXES
.iter()
.any(|prefix| key.starts_with(prefix))
{
return Err(CursorClientError::MalformedKey {
length: key.len(),
prefix: key.chars().take(4).collect(),
});
}
// No global timeout — the run stream is long-lived by design — but a
// bounded connect: a peer that neither answers nor closes would
// otherwise hang a caller forever, and the session poller runs its
// idle check between calls, so one wedged call is a session that
// never retires.
let http = reqwest::Client::builder()
.connect_timeout(std::time::Duration::from_secs(10))
.build()?;
Ok(Self {
http,
config,
branch_retry_backoff: BRANCH_UNVERIFIABLE_RETRY_BACKOFF.to_vec(),
turn_start_retry_backoff: TURN_START_RETRY_BACKOFF.to_vec(),
})
}
/// Replace the retry schedule for branch-unverifiable creates. An empty
/// schedule disables the retry.
#[must_use]
pub fn with_branch_retry_backoff(mut self, backoff: Vec<std::time::Duration>) -> Self {
self.branch_retry_backoff = backoff;
self
}
/// Replace the retry schedule for turn-starting POSTs. An empty schedule
/// disables the retry.
#[must_use]
pub fn with_turn_start_retry_backoff(mut self, backoff: Vec<std::time::Duration>) -> Self {
self.turn_start_retry_backoff = backoff;
self
}
fn url(&self, path: &str) -> String {
format!("{}{path}", self.config.base_url)
}
/// POST a JSON body and decode a JSON response, mapping non-2xx statuses
/// to reports that carry the body — Cursor's error bodies are the only
/// diagnostic there is.
async fn post_json<Body, Reply>(
&self,
path: &str,
body: &Body,
) -> Result<Reply, rootcause::Report>
where
Body: serde::Serialize + Sync,
Reply: serde::de::DeserializeOwned,
{
let (status, text) = self.post_for_text(path, body).await?;
Self::decode_post(path, status, &text)
}
/// POST a JSON body and read the response back as status plus raw text.
///
/// Split out of [`Self::post_json`] so a caller that classifies error
/// bodies — [`Self::create_agent`] — sees the body itself rather than
/// re-parsing it out of a formatted message.
async fn post_for_text<Body>(
&self,
path: &str,
body: &Body,
) -> Result<(reqwest::StatusCode, String), rootcause::Report>
where
Body: serde::Serialize + Sync,
{
let response = self
.http
.post(self.url(path))
.basic_auth(self.config.api_key.expose(), Some(""))
.json(body)
.send()
.await
.map_err(|error| rootcause::report!(error))?;
let status = response.status();
let text = response
.text()
.await
.map_err(|error| rootcause::report!(error))?;
Ok((status, text))
}
/// POST a request that starts a turn, riding out transient failures.
///
/// Only the two calls that begin a turn take this path: minting an agent
/// and opening a follow-up run. Both are safe to repeat, because a
/// failed status is Cursor saying it started nothing, so a second POST
/// cannot duplicate work on cursor.com. Cancelling and archiving keep
/// the plain path — making a stop wait out someone else's limit is worse
/// than the stop failing.
///
/// A budget spent without success returns the last answer rather than a
/// failure of its own, so an exhausted retry is reported exactly as the
/// same failure is today.
async fn post_starting_turn<Body>(
&self,
path: &str,
body: &Body,
) -> Result<(reqwest::StatusCode, String), rootcause::Report>
where
Body: serde::Serialize + Sync,
{
let mut retries = self.turn_start_retry_backoff.iter();
loop {
let (status, text) = self.post_for_text(path, body).await?;
if !is_transient(status) {
return Ok((status, text));
}
let Some(delay) = retries.next() else {
return Ok((status, text));
};
tracing::warn!(
path,
status = status.as_u16(),
retry_in_ms = delay.as_millis() as u64,
detail = %text,
"cursor could not start the turn; retrying"
);
tokio::time::sleep(*delay).await;
}
}
/// Turn one POST's status and body into the reply or a report.
fn decode_post<Reply>(
path: &str,
status: reqwest::StatusCode,
text: &str,
) -> Result<Reply, rootcause::Report>
where
Reply: serde::de::DeserializeOwned,
{
if !status.is_success() {
if status.is_client_error() && status != reqwest::StatusCode::REQUEST_TIMEOUT {
if let Some(exceeded) = classify_usage_limit(text) {
return Err(rootcause::report!(exceeded).into_dynamic());
}
return Err(
rootcause::report!(crate::domain::error::PromptRejected(format!(
"cursor POST {path} -> {status}: {text}"
)))
.into_dynamic(),
);
}
return Err(rootcause::report!("cursor POST {path} -> {status}: {text}"));
}
serde_json::from_str(text)
.map_err(|error| rootcause::report!("cursor POST {path}: bad response body: {error}"))
}
/// GET a JSON response, mapping non-2xx statuses to reports that carry
/// the body, same as [`Self::post_json`].
async fn get_json<Reply>(&self, path: &str) -> Result<Reply, rootcause::Report>
where
Reply: serde::de::DeserializeOwned,
{
let response = self
.http
.get(self.url(path))
.basic_auth(self.config.api_key.expose(), Some(""))
.send()
.await
.map_err(|error| rootcause::report!(error))?;
let status = response.status();
let text = response
.text()
.await
.map_err(|error| rootcause::report!(error))?;
if !status.is_success() {
return Err(rootcause::report!("cursor GET {path} -> {status}: {text}"));
}
serde_json::from_str(&text)
.map_err(|error| rootcause::report!("cursor GET {path}: bad response body: {error}"))
}
/// Fetch one agent's durable record.
#[tracing::instrument(skip(self), err)]
pub async fn get_agent(
&self,
agent: &CursorAgentId,
) -> Result<AgentSummary, rootcause::Report> {
self.get_json(&format!("/v1/agents/{agent}")).await
}
/// Fetch one page of the key's agents, newest first.
///
/// `cursor` is the previous page's `next_cursor`; `None` starts from the
/// top. Pagination is the caller's loop — the manager reconciling on boot
/// decides how far back is worth walking.
#[tracing::instrument(skip(self), err)]
pub async fn list_agents(
&self,
limit: u32,
cursor: Option<&str>,
) -> Result<ListAgentsResponse, rootcause::Report> {
let path = match cursor {
Some(cursor) => format!("/v1/agents?limit={limit}&cursor={cursor}"),
None => format!("/v1/agents?limit={limit}"),
};
self.get_json(&path).await
}
/// Archive an agent: readable but closed to new runs. Idempotent, and
/// deliberately not delete — teardown of a session must not destroy work
/// the agent's owner may still want on cursor.com.
#[tracing::instrument(skip(self), err)]
pub async fn archive_agent(&self, agent: &CursorAgentId) -> Result<(), rootcause::Report> {
let _: ArchiveAgentResponse = self
.post_json(
&format!("/v1/agents/{agent}/archive"),
&serde_json::json!({}),
)
.await?;
Ok(())
}
/// List the files an agent has written to its `artifacts/` directory —
/// the screenshots and screen recordings a walkthrough produces.
///
/// The listing is agent-scoped and cumulative: artifacts survive their
/// run, and Cursor offers no run filter, so every turn sees everything
/// every earlier turn wrote. A caller that wants "new since last turn"
/// has to diff `path` plus `updated_at` against what it saw before —
/// `path` alone is not enough, because an agent that reshoots a
/// screenshot writes the same path again.
#[tracing::instrument(skip(self), err)]
pub async fn list_artifacts(
&self,
agent: &CursorAgentId,
) -> Result<ListArtifactsResponse, rootcause::Report> {
self.get_json(&format!("/v1/agents/{agent}/artifacts"))
.await
}
/// Ask for a presigned url to one artifact's bytes.
///
/// `path` is a [`wire::ArtifactListing::path`] exactly as the listing gave it;
/// Cursor requires it to be under `artifacts/` and rejects anything else.
/// The url it answers with is good for fifteen minutes, so it is worth
/// requesting when a caller is ready to fetch and not worth storing.
#[tracing::instrument(skip(self), err)]
pub async fn artifact_download_url(
&self,
agent: &CursorAgentId,
path: &str,
) -> Result<ArtifactDownloadResponse, rootcause::Report> {
self.get_json(&format!(
"/v1/agents/{agent}/artifacts/download?path={}",
urlencoding::encode(path)
))
.await
}
/// Fetch an artifact's bytes from the presigned url
/// [`Self::artifact_download_url`] handed back.
///
/// Its own method rather than another `get_*` because everything about
/// the request differs from a Cursor API call: the url is S3's, not this
/// client's base url; its credentials are already in its query string, so
/// the Cursor key must *not* be attached — sending a live API key to a
/// third-party host is a credential leak, not a harmless extra header —
/// and it stops working fifteen minutes after it was minted.
///
/// The response is returned unread. Artifact videos run to tens of
/// megabytes, so the caller decides whether to stream the body somewhere
/// or buffer it; this method will not buffer it for them.
#[tracing::instrument(skip(self, url), err)]
pub async fn fetch_artifact(&self, url: &str) -> Result<reqwest::Response, rootcause::Report> {
let response = self
.http
.get(url)
.send()
.await
.map_err(|error| rootcause::report!(error))?;
let status = response.status();
if !status.is_success() {
// S3 answers a stale or malformed presigned url with an XML body
// naming the reason, which is the only diagnostic there is — the
// same bargain `get_json` makes with Cursor's error bodies.
let text = response.text().await.unwrap_or_default();
return Err(rootcause::report!("artifact fetch -> {status}: {text}"));
}
Ok(response)
}
/// Identify the configured API key. The cheap call that proves the key is
/// live, for a boot-time health check.
#[tracing::instrument(skip(self), err)]
pub async fn me(&self) -> Result<MeResponse, rootcause::Report> {
self.get_json("/v1/me").await
}
}
impl CursorAgents for CursorClient {
#[tracing::instrument(
skip(self),
err,
fields(
cursor.poll.status = tracing::field::Empty,
cursor.poll.rate_limited = tracing::field::Empty,
)
)]
async fn raw_result(
&self,
agent: &CursorAgentId,
run: &CursorRunId,
) -> Result<String, rootcause::Report> {
let response = self
.http
.get(self.url(&format!("/v1/agents/{agent}/runs/{run}")))
.basic_auth(self.config.api_key.expose(), Some(""))
.send()
.await
.map_err(|e| rootcause::report!(e))?;
let status = response.status();
let retry_after = response
.headers()
.get(reqwest::header::RETRY_AFTER)
.and_then(|value| value.to_str().ok())
.map(str::to_owned);
let text = response.text().await.map_err(|e| rootcause::report!(e))?;
let span = tracing::Span::current();
span.record("cursor.poll.status", status.as_u16());
span.record(
"cursor.poll.rate_limited",
status == reqwest::StatusCode::TOO_MANY_REQUESTS,
);
if !status.is_success() {
// The rate limit is per API key and shared by every session this
// deployment drives, so one session's 429 is a fact about the
// fleet, not about this run. Logged in its own right: until now
// it existed only inside an error chain that reached the reader
// and nothing else, so "are we over the limit" was unanswerable
// from telemetry.
if status == reqwest::StatusCode::TOO_MANY_REQUESTS {
tracing::warn!(
%agent,
%run,
retry_after = retry_after.as_deref().unwrap_or("unset"),
"Cursor run poll was rate limited"
);
}
return Err(rootcause::report!(
"Cursor run poll failed: {status}: {text}"
));
}
Ok(text)
}
#[tracing::instrument(skip_all, err, fields(mcp_servers = mcp_servers.len()))]
async fn create_agent(
&self,
prompt: &str,
repo: Option<&RepoUrl>,
open_pull_request: bool,
mcp_servers: &[McpServer],
model: Option<&ModelChoice>,
images: &[CursorPromptImage],
) -> Result<(CursorAgentId, CursorRunId), rootcause::Report> {
let request = CreateAgentRequest {
prompt: prompt_body(prompt, images),
repos: repo
.map(|repo| {
vec![RepoSelection {
url: repo.as_str().to_owned(),
starting_ref: self.config.starting_ref.clone(),
}]
})
.unwrap_or_default(),
model: model.map(ModelSelection::from),
mcp_servers: mcp_servers.iter().map(McpServerSelection::from).collect(),
// A repo-less agent has nothing to open a pull request against,
// whatever the caller asked for.
auto_create_pr: open_pull_request && repo.is_some(),
};
let mut retries = self.branch_retry_backoff.iter();
let (status, text) = loop {
let (status, text) = self.post_starting_turn("/v1/agents", &request).await?;
let Some(repo) = repo else {
break (status, text);
};
let Some(reason) =
classify_repository_rejection(status, &text, &self.config.starting_ref)
else {
break (status, text);
};
if matches!(
reason,
crate::domain::error::RepositoryRejection::BranchUnverifiable { .. }
) && let Some(delay) = retries.next()
{
tracing::warn!(
repo = %repo,
starting_ref = %self.config.starting_ref,
retry_in_ms = delay.as_millis() as u64,
detail = %text,
"cursor could not verify the starting ref; retrying the create"
);
tokio::time::sleep(*delay).await;
continue;
}
return Err(
rootcause::report!(crate::domain::error::RepositoryUnavailable {
repo: repo.clone(),
reason,
detail: text,
})
.into_dynamic(),
);
};
let reply: CreateAgentResponse = Self::decode_post("/v1/agents", status, &text)?;
tracing::info!(agent = %reply.agent.id, url = %reply.agent.url, "cursor agent created");
Ok((
CursorAgentId::new(reply.agent.id),
CursorRunId::new(reply.run.id),
))
}
#[tracing::instrument(skip(self, prompt), err)]
async fn create_run(
&self,
agent: &CursorAgentId,
prompt: &str,
model: Option<&ModelChoice>,
images: &[CursorPromptImage],
) -> Result<CursorRunId, rootcause::Report> {
let request = CreateRunRequest {
prompt: prompt_body(prompt, images),
model: model.map(ModelSelection::from),
};
let path = format!("/v1/agents/{agent}/runs");
let (status, text) = self.post_starting_turn(&path, &request).await?;
let reply: CreateRunResponse = Self::decode_post(&path, status, &text)?;
Ok(CursorRunId::new(reply.into_run_id()))
}
#[tracing::instrument(skip(self), err)]
async fn list_models(&self) -> Result<Vec<CursorModel>, rootcause::Report> {
let reply: ListModelsResponse = self.get_json("/v1/models").await?;
Ok(reply
.items
.into_iter()
.map(|listing| CursorModel {
display_name: listing.display_name.unwrap_or_else(|| listing.id.clone()),
id: listing.id,
variants: listing
.variants
.into_iter()
.map(|variant| ModelVariant {
params: variant
.params
.into_iter()
.map(|param| ModelParam {
id: param.id,
value: param.value,
})
.collect(),
is_default: variant.is_default,
})
.collect(),
})
.collect())
}
#[tracing::instrument(skip(self), err)]
async fn cancel_run(
&self,
agent: &CursorAgentId,
run: &CursorRunId,
) -> Result<(), rootcause::Report> {
let _: serde_json::Value = self
.post_json(
&format!("/v1/agents/{agent}/runs/{run}/cancel"),
&serde_json::json!({}),
)
.await?;
Ok(())
}
#[tracing::instrument(skip(self), err)]
async fn list_runs(
&self,
agent: &CursorAgentId,
through: Option<&CursorRunId>,
) -> Result<Vec<RunListing>, rootcause::Report> {
let mut listings = Vec::new();
let mut cursor = None;
let mut seen_cursors = std::collections::HashSet::new();
loop {
let mut request = self
.http
.get(self.url(&format!("/v1/agents/{agent}/runs")))
.basic_auth(self.config.api_key.expose(), Some(""))
.query(&[("limit", "100")]);
if let Some(cursor) = cursor.as_deref() {
request = request.query(&[("cursor", cursor)]);
}
let response = request
.send()
.await
.map_err(|error| rootcause::report!(error))?;
let status = response.status();
let text = response
.text()
.await
.map_err(|error| rootcause::report!(error))?;
if !status.is_success() {
return Err(rootcause::report!(
"cursor GET /v1/agents/{agent}/runs -> {status}: {text}"
));
}
let page: ListRunsResponse = serde_json::from_str(&text).map_err(|error| {
rootcause::report!("cursor run list: bad response body: {error}")
})?;
let reached = through
.is_some_and(|through| page.items.iter().any(|item| item.id == through.as_str()));
listings.extend(page.items.into_iter().map(|item| RunListing {
id: CursorRunId::new(item.id),
status: item.status,
}));
if reached {
break;
}
let Some(next) = page.next_cursor else {
break;
};
if !seen_cursors.insert(next.clone()) {
return Err(rootcause::report!(
"cursor run list repeated pagination cursor"
));
}
cursor = Some(next);
}
Ok(listings)
}
/// Version zero on purpose: v1 exposes no conversation endpoint, and this
/// one answers for the agents v1 created.
#[tracing::instrument(skip(self), err)]
async fn conversation(
&self,
agent: &CursorAgentId,
) -> Result<Vec<ConversationLine>, rootcause::Report> {
let reply: ConversationResponse = self
.get_json(&format!("/v0/agents/{agent}/conversation"))
.await?;
Ok(reply
.messages
.into_iter()
.filter_map(|message| {
let speaker = match message.kind.as_str() {
"user_message" => ConversationSpeaker::User,
"assistant_message" => ConversationSpeaker::Agent,
_ => return None,
};
Some(ConversationLine {
speaker,
text: message.text?,
})
})
.collect())
}
}
impl CursorArtifacts for CursorClient {
#[tracing::instrument(skip(self), err)]
async fn list_artifacts(
&self,
agent: &CursorAgentId,
) -> Result<Vec<ArtifactListing>, rootcause::Report> {
let reply = CursorClient::list_artifacts(self, agent).await?;
Ok(reply
.items
.into_iter()
.map(|listing| ArtifactListing {
path: listing.path,
size_bytes: listing.size_bytes,
updated_at: listing.updated_at,
})
.collect())
}
#[tracing::instrument(skip(self), err)]
async fn fetch_artifact(
&self,
agent: &CursorAgentId,
path: &str,
) -> Result<FetchedArtifact, rootcause::Report> {
// Minted and spent inside this method: the url carries credentials in
// its query string and stops working in fifteen minutes, so it is
// never returned, logged, or stored.
let download = self.artifact_download_url(agent, path).await?;
let response = CursorClient::fetch_artifact(self, &download.url).await?;
let content_type = response
.headers()
.get(reqwest::header::CONTENT_TYPE)
.and_then(|value| value.to_str().ok())
.map(str::to_owned);
let bytes = response
.bytes()
.await
.map_err(|error| rootcause::report!(error))?;
Ok(FetchedArtifact {
content_type,
bytes,
})
}
}
/// How many times a run's stream is connected before an unavailable stream
/// is the turn's failure.
const STREAM_CONNECT_ATTEMPTS: usize = 5;
/// Pause between stream connect attempts. The window being papered over is
/// the second or so between a run's creation and its stream existing.
const STREAM_RETRY_DELAY: std::time::Duration = std::time::Duration::from_millis(400);
/// Cursor's header naming how long a dropped stream stays resumable.
const RETENTION_HEADER: &str = "x-cursor-stream-retention-seconds";
/// The SSE resume header. Not in `http`'s constant set, so it is spelled here.
const LAST_EVENT_ID_HEADER: &str = "last-event-id";
/// How long a stream connect waits for the response headers before it is a
/// [`StreamConnectError::Stalled`].
///
/// A stream's headers ordinarily arrive within the second. The one case that
/// takes longer is the one this bounds: a resume the server held open for
/// minutes and answered all at once when the run ended (prod, 2026-09-26).
/// Thirty seconds is far past any honest handshake and short enough that
/// the domain, which checks the run's record on every stall, notices a run
/// that has finished behind a wedged stream within the minute.
const STREAM_HEADERS_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(30);
impl RunStream for CursorClient {
// Covers connecting the stream, retries included; reading it belongs to
// the caller's `cursor.run.ingest` span.
#[tracing::instrument(skip(self), fields(cursor.stream.resumed = resume_from.is_some()))]
async fn raw_stream(
&self,
agent: &CursorAgentId,
run: &CursorRunId,
resume_from: Option<&str>,
) -> Result<
ConnectedStream<
impl Stream<Item = Result<crate::domain::journal::NativeRecord, rootcause::Report>> + Send,
>,
StreamConnectError,
> {
// Only retry an unavailable stream. Successful SSE records, including
// a `stream_unavailable` record, must reach the domain journal before
// inspection, and a rejected or expired resume position is the
// domain's decision to make, not a thing to sit and retry.
for attempt in 1..=STREAM_CONNECT_ATTEMPTS {
match self.connect_stream(agent, run, resume_from).await {
Ok(stream) => return Ok(stream),
Err(StreamConnectError::Unavailable(_)) if attempt < STREAM_CONNECT_ATTEMPTS => {
tokio::time::sleep(STREAM_RETRY_DELAY).await
}
Err(error) => return Err(error),
}
}
unreachable!("connect attempts are nonzero")
}
}
impl CursorClient {
async fn connect_stream(
&self,
agent: &CursorAgentId,
run: &CursorRunId,
resume_from: Option<&str>,
) -> Result<
ConnectedStream<
impl Stream<Item = Result<crate::domain::journal::NativeRecord, rootcause::Report>>
+ Send
+ use<>,
>,
StreamConnectError,
> {
// `identity` is stated rather than left to the default. This client
// is built without reqwest's decompression features, so it would
// never decode a compressed body — but it would not have asked for
// one either, and an intermediary that compresses an event stream
// when nothing forbids it buffers records until a block is full.
// Asking for identity forbids it, and a `content-encoding` on the
// answer becomes a fact worth a warning rather than a guess.
let mut request = self
.http
.get(self.url(&format!("/v1/agents/{agent}/runs/{run}/stream")))
.basic_auth(self.config.api_key.expose(), Some(""))
.header(reqwest::header::ACCEPT, "text/event-stream")
.header(reqwest::header::ACCEPT_ENCODING, "identity");
if let Some(resume_from) = resume_from {
request = request.header(LAST_EVENT_ID_HEADER, resume_from);
}
let asked_at = std::time::Instant::now();
let response = match tokio::time::timeout(STREAM_HEADERS_TIMEOUT, request.send()).await {
Ok(Ok(response)) => response,
Ok(Err(error)) => {
return Err(StreamConnectError::Other(rootcause::report!(
"{}",
stream::error_chain(&error)
)));
}
Err(_elapsed) => {
tracing::warn!(
cursor.run.id = %run,
cursor.stream.resumed = resume_from.is_some(),
cursor.stream.last_event_id = resume_from,
cursor.stream.headers_timeout_ms = STREAM_HEADERS_TIMEOUT.as_millis() as u64,
"Cursor sent no stream headers before the timeout"
);
return Err(StreamConnectError::Stalled(format!(
"no response headers after {}s",
STREAM_HEADERS_TIMEOUT.as_secs()
)));
}
};
let headers_ms = asked_at.elapsed().as_millis() as u64;
let status = response.status();
// Read before the body is consumed; a resumed stream's window is the
// only thing that says whether the next drop is recoverable at all.
let retention_seconds = response
.headers()
.get(RETENTION_HEADER)
.and_then(|value| value.to_str().ok())
.and_then(|value| value.parse().ok());
if !status.is_success() {
let text = response.text().await.unwrap_or_default();
let detail = format!("{status}: {text}");
if text.contains("stream_unavailable") {
return Err(StreamConnectError::Unavailable(detail));
}
if status == reqwest::StatusCode::BAD_REQUEST && text.contains("invalid_last_event_id")
{
return Err(StreamConnectError::InvalidResumePosition(detail));
}
if status == reqwest::StatusCode::GONE || text.contains("stream_expired") {
return Err(StreamConnectError::Expired(detail));
}
return Err(StreamConnectError::Other(rootcause::report!(
"cursor stream -> {detail}"
)));
}
let facts = ConnectionFacts::of(&response, resume_from.is_some());
tracing::info!(
cursor.run.id = %run,
cursor.stream.resumed = facts.resumed,
cursor.stream.last_event_id = resume_from,
cursor.stream.headers_ms = headers_ms,
cursor.stream.status = facts.status,
cursor.stream.http_version = %facts.version,
cursor.stream.content_type = facts.content_type.as_deref(),
cursor.stream.content_encoding = facts.content_encoding.as_deref(),
cursor.stream.transfer_encoding = facts.transfer_encoding.as_deref(),
cursor.stream.server = facts.server.as_deref(),
cursor.stream.request_id = facts.request_id.as_deref(),
cursor.stream.retention_seconds = retention_seconds,
"Cursor stream connected"
);
if facts.is_compressed() {
tracing::warn!(
cursor.run.id = %run,
cursor.stream.content_encoding = facts.content_encoding.as_deref(),
cursor.stream.request_id = facts.request_id.as_deref(),
"Cursor stream arrived compressed despite asking for identity"
);
}
// Recording taps the bytes before the decoder sees them, so a
// fixture is byte-identical to the wire.
let recording = match &self.config.record_dir {
Some(dir) => SseRecording::create(dir, agent.as_str(), run.as_str()),
None => SseRecording::disabled(),
};
Ok(ConnectedStream {
records: stream::records(response, facts, recording, MAX_SSE_PAYLOAD),
retention_seconds,
})
}
}