Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

17.0 KB
Raw Blame
//! The capabilities the session service requires from the outside.
//!
//! [`CursorAgents`] and [`RunStream`] are implemented by the Cursor API
//! client ([`crate::api`]); [`SessionNotifier`] by whatever transport the
//! session's updates travel over (the ACP stdio connection today, anything
//! that can carry a `session/update` tomorrow); [`RepositoryChooser`] by
//! a classifier for hosted Macro sessions or [`NoRepositoryChooser`] standalone.
//! Native records and polling bodies cross these
//! contracts for capture before decoding; HTTP I/O, SSE framing, JSON-RPC, and
//! subprocesses remain outside the service.

use crate::domain::artifact::{ArtifactListing, FetchedArtifact};
use crate::domain::model::{
    ConversationLine, CursorAgentId, CursorModel, CursorRunId, McpServer, ModelChoice, RepoUrl,
    RunListing,
};
use crate::domain::prompt_image::CursorPromptImage;
use agent_client_protocol::schema::v1::{SessionId, SessionUpdate};
use futures::Stream;

/// Create and control Cursor cloud agents.
pub trait CursorAgents: Sync {
    /// Raw successful polling body, captured before interpretation, including
    /// provider fields unknown to the domain. A turn whose stream is unavailable
    /// falls back to polling this until the run is terminal.
    fn raw_result(
        &self,
        agent: &CursorAgentId,
        run: &CursorRunId,
    ) -> impl Future<Output = Result<String, rootcause::Report>> + Send;

    /// Create an agent with its first run. Cursor has no bare "create agent":
    /// an agent only exists once there is a prompt to run, which is why this
    /// returns both ids at once.
    ///
    /// `mcp_servers` is applied here: Cursor fixes an agent's MCP
    /// configuration at creation. An empty slice leaves Cursor's own
    /// configuration untouched.
    ///
    /// `model` absent means "whatever the user's own Cursor settings resolve
    /// to" — Cursor falls back user default, then team, then system — which is
    /// a better default than any id this crate could pick.
    ///
    /// `open_pull_request` asks Cursor to push its work to a generated branch
    /// and open a pull request against the starting ref. It is a caller's
    /// decision and has no effect without a repository.
    ///
    /// `images` are raster pictures for `prompt.images`. Empty leaves the
    /// prompt as text.
    fn create_agent(
        &self,
        prompt: &str,
        repo: Option<&RepoUrl>,
        open_pull_request: bool,
        mcp_servers: &[McpServer],
        model: Option<&ModelChoice>,
        images: &[CursorPromptImage],
    ) -> impl Future<Output = Result<(CursorAgentId, CursorRunId), rootcause::Report>> + Send;

    /// Send a follow-up prompt to an existing agent, opening a new run.
    ///
    /// `model` is honoured per run, which is what makes a mid-session model
    /// change possible: the field is undocumented on this endpoint but
    /// validated by it, and absent means the agent's own model stands.
    ///
    /// `images` are the same raster pictures as on [`Self::create_agent`].
    fn create_run(
        &self,
        agent: &CursorAgentId,
        prompt: &str,
        model: Option<&ModelChoice>,
        images: &[CursorPromptImage],
    ) -> impl Future<Output = Result<CursorRunId, rootcause::Report>> + Send;

    /// The models this account may choose from, with the variants each accepts.
    ///
    /// Cursor validates an id together with its params, so the variants are
    /// not decoration — they are the only source of a selection it will accept.
    fn list_models(
        &self,
    ) -> impl Future<Output = Result<Vec<CursorModel>, rootcause::Report>> + Send;

    /// Cancel a run. Terminal: a cancelled run cannot resume.
    fn cancel_run(
        &self,
        agent: &CursorAgentId,
        run: &CursorRunId,
    ) -> impl Future<Output = Result<(), rootcause::Report>> + Send;

    /// The agent's runs, newest first.
    ///
    /// How a session finds out what happened to its agent while it was not
    /// looking: the conversation also advances from cursor.com (the agent's
    /// page there drives the same agent), and those runs never pass through
    /// this session. Before a new prompt, the runs since the last one this
    /// session drove are backfilled so the client's view does not silently
    /// fork from the conversation the new prompt continues.
    fn list_runs(
        &self,
        agent: &CursorAgentId,
        through: Option<&CursorRunId>,
    ) -> impl Future<Output = Result<Vec<RunListing>, rootcause::Report>> + Send;

    /// The agent's prompts and replies in order, as Cursor still holds them.
    ///
    /// The longest-lived record Cursor keeps, and the reason this exists: a
    /// run's stream expires within hours and its record drops its final text
    /// within weeks, while this still answers for agents whose every other
    /// trace is gone. It is where a prompt that was never captured here -
    /// a run driven from cursor.com, mirrored after its stream aged out -
    /// can still be found.
    ///
    /// Carries no run ids, so a line is tied to a run by matching text the
    /// journal already holds, never by position. See
    /// [`CursorSessionService::recover_lost_prompts`](crate::domain::service::CursorSessionService).
    fn conversation(
        &self,
        agent: &CursorAgentId,
    ) -> impl Future<Output = Result<Vec<ConversationLine>, rootcause::Report>> + Send;
}

/// Read the walkthrough files a Cursor agent saved.
///
/// A sibling of [`CursorAgents`] rather than more methods on it: the agent
/// lifecycle is what every session needs, and artifacts are what one optional
/// step at the end of a turn needs. Splitting them keeps a fake that scripts
/// a listing from having to script an agent lifecycle too.
pub trait CursorArtifacts: Sync {
    /// Every artifact the agent has written, across all of its runs.
    ///
    /// Cursor offers no run filter, so a later turn still sees everything
    /// earlier turns wrote; the caller diffs.
    fn list_artifacts(
        &self,
        agent: &CursorAgentId,
    ) -> impl Future<Output = Result<Vec<ArtifactListing>, rootcause::Report>> + Send;

    /// Fetch one artifact's bytes by its listed path.
    ///
    /// One call rather than "mint a url" then "fetch it": the url is a
    /// credential with a fifteen-minute life, and nothing above this port has
    /// any business holding one.
    fn fetch_artifact(
        &self,
        agent: &CursorAgentId,
        path: &str,
    ) -> impl Future<Output = Result<FetchedArtifact, rootcause::Report>> + Send;
}

/// Re-host an artifact's bytes somewhere that outlives the provider's link.
///
/// The domain's only opinion about storage is this trade: bytes in, a URL out
/// that is still good when someone reopens the conversation next year. Which
/// service that is, what it names the object, and how it authenticates are
/// all outside.
pub trait ArtifactStore: Send + Sync {
    /// Whether this deployment can re-host anything at all.
    ///
    /// A service built without a store — the standalone binary, most tests —
    /// skips artifact collection whole rather than listing files it would
    /// only fail to store one at a time. `false` is a configuration fact, not
    /// a failure, which is why it is a question and not an error.
    fn is_available(&self) -> bool {
        true
    }

    /// Store `bytes` under `file_name` and answer with their permanent URI.
    fn store(
        &self,
        file_name: &str,
        mime_type: &str,
        bytes: bytes::Bytes,
    ) -> impl Future<Output = Result<String, rootcause::Report>> + Send;
}

/// Fetch a link pasted into a prompt when it might be an image.
///
/// `None` means the link is not an image we can hand to Cursor — a page, a
/// private address, a failure — and the prompt continues as text.
pub trait PromptImageFetcher: Send + Sync + std::fmt::Debug {
    /// Fetch `url` and return an image when the response is one.
    fn fetch_image<'a>(
        &'a self,
        url: &'a str,
    ) -> futures::future::BoxFuture<'a, Option<CursorPromptImage>>;
}

/// A fetcher that never fetches. Prompts stay text.
#[derive(Debug, Clone, Copy, Default)]
pub struct NoPromptImageFetcher;

impl PromptImageFetcher for NoPromptImageFetcher {
    fn fetch_image<'a>(
        &'a self,
        _url: &'a str,
    ) -> futures::future::BoxFuture<'a, Option<CursorPromptImage>> {
        Box::pin(async { None })
    }
}

/// The store for a deployment that has nowhere to put artifacts.
///
/// Reports itself unavailable, so a session built with it never lists an
/// agent's artifacts; the error exists only for a caller that ignores that
/// and asks anyway.
#[derive(Debug, Clone, Copy, Default)]
pub struct NoArtifactStore;

impl ArtifactStore for NoArtifactStore {
    fn is_available(&self) -> bool {
        false
    }

    async fn store(
        &self,
        _file_name: &str,
        _mime_type: &str,
        _bytes: bytes::Bytes,
    ) -> Result<String, rootcause::Report> {
        Err(rootcause::report!(
            "this session has no artifact store configured"
        ))
    }
}

/// One connected run stream, with what the provider said about resuming it.
pub struct ConnectedStream<Records> {
    /// Complete native records, captured before decoding or translation.
    pub records: Records,
    /// The provider's `X-Cursor-Stream-Retention-Seconds`, when it sent one.
    ///
    /// How long a dropped stream stays resumable. Not enforced here — the
    /// provider answers an expired resume with
    /// [`StreamConnectError::Expired`] — but worth logging, because a run
    /// whose tool call outlives the window can never be resumed and the
    /// number is the only warning of that.
    pub retention_seconds: Option<u64>,
}

/// Why one connect did not produce a stream.
///
/// The domain acts differently on each: an unavailable stream is retried, an
/// invalid resume position is retried without one, an expired stream is
/// gone for good and leaves polling as the only way to learn the outcome,
/// and a stalled connect is checked against the run's record before it is
/// tried again.
#[derive(Debug)]
pub enum StreamConnectError {
    /// `stream_unavailable`: the stream is not there (yet). Carries the
    /// provider's message.
    Unavailable(String),
    /// `invalid_last_event_id`: the resume position is not this run's.
    InvalidResumePosition(String),
    /// `stream_expired`: the retention window closed behind us.
    Expired(String),
    /// The provider accepted the connection but sent no response headers
    /// within the adapter's patience.
    ///
    /// Observed live (prod, 2026-09-26): a resume after a mid-run body
    /// failure was held for 6m43s with no headers, then answered with every
    /// record since the break in one burst, the moment the run finished. A
    /// connect that waits indefinitely turns that into a turn nobody can see
    /// working; this variant is what lets the domain keep polling the run's
    /// record in the meantime.
    Stalled(String),
    /// Every other failure.
    Other(rootcause::Report),
}

impl std::fmt::Display for StreamConnectError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Unavailable(message) => write!(formatter, "Cursor stream unavailable: {message}"),
            Self::InvalidResumePosition(message) => {
                write!(formatter, "Cursor rejected the resume position: {message}")
            }
            Self::Expired(message) => write!(formatter, "Cursor stream expired: {message}"),
            Self::Stalled(message) => {
                write!(
                    formatter,
                    "Cursor stream stalled before its headers: {message}"
                )
            }
            Self::Other(report) => write!(formatter, "{report}"),
        }
    }
}

/// Observe a run as a stream of native SSE records.
///
/// The stream ends when the server closes it — normally just after a
/// [`CursorEvent::Done`](super::event::CursorEvent::Done). A consumer that never sees a terminal
/// [`CursorEvent::Result`](super::event::CursorEvent::Result) must treat the run's outcome as unknown rather
/// than successful.
pub trait RunStream: Sync {
    /// Connect a run's stream, optionally resuming after an event id.
    ///
    /// `resume_from` is an id observed on an earlier record of this same run,
    /// passed back verbatim: the provider's ids are opaque and a consumer that
    /// parses or invents one gets [`StreamConnectError::InvalidResumePosition`].
    /// `None` connects from the beginning of what the provider still retains.
    fn raw_stream(
        &self,
        agent: &CursorAgentId,
        run: &CursorRunId,
        resume_from: Option<&str>,
    ) -> impl Future<
        Output = Result<
            ConnectedStream<
                impl Stream<Item = Result<super::journal::NativeRecord, rootcause::Report>> + Send,
            >,
            StreamConnectError,
        >,
    > + Send;
}

/// Host operation receiving repository facts independently of ACP presentation.
pub trait WorkingBranchReporter: Send + Sync {
    /// Persist the authoritative branch for the reported repository.
    fn set_working_branch<'a>(
        &'a self,
        repository_url: &'a str,
        branch: &'a str,
    ) -> std::pin::Pin<Box<dyn Future<Output = Result<(), rootcause::Report>> + Send + 'a>>;
}

/// Deliver one translated update to the session's client.
pub trait SessionNotifier {
    /// Report a provider repository's branch to the host's session operation.
    fn set_working_branch(
        &self,
        session: &SessionId,
        repository_url: &str,
        branch: &str,
    ) -> impl Future<Output = Result<(), rootcause::Report>> + Send;

    /// Report the provider's PR to the host's shared session operation.
    fn set_pull_request(
        &self,
        session: &SessionId,
        url: &str,
    ) -> impl Future<Output = Result<(), rootcause::Report>> + Send;

    /// Send a `session/update` for the given session.
    fn notify(
        &self,
        session: &SessionId,
        update: SessionUpdate,
    ) -> impl Future<Output = Result<(), rootcause::Report>> + Send;
    /// Ask the host to load recovered history after the current prompt completes.
    /// This must only enqueue a signal: the caller holds the session writer gate.
    fn require_reload(
        &self,
        session: &SessionId,
    ) -> impl Future<Output = Result<(), rootcause::Report>> + Send;
    /// Emit a terminal lifecycle fact after the reconstructed turn's updates.
    fn turn_complete(
        &self,
        session: &SessionId,
        outcome: agent_runtime_protocol::domain::turn::TurnOutcome,
    ) -> impl Future<Output = Result<(), rootcause::Report>> + Send;
    /// Emit a non-rendering marker after every update for `run` was delivered.
    /// Durable hosts use it to atomically checkpoint the run with their log.
    fn checkpoint(
        &self,
        session: &SessionId,
        run: &CursorRunId,
    ) -> impl Future<Output = Result<(), rootcause::Report>> + Send;
}

/// What a session's first prompt asks for, decided before the agent is minted.
///
/// The two answers travel together because they are one decision: Cursor can
/// only open a pull request against a repository, so `open_pull_request` is
/// meaningless without `repository` and the chooser is the only place that
/// knows both.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct SessionIntent {
    /// The repository the work belongs to, when one clearly does.
    pub repository: Option<RepoUrl>,
    /// Whether the work should ship as a pull request.
    pub open_pull_request: bool,
}

/// Decide which repository a prompt's work belongs to.
///
/// Asked once per session, at the first prompt, because the prompt is the only
/// evidence there is: a session opened from a chat message names no checkout,
/// and the repository has to be right before the agent is minted - Cursor fixes
/// an agent's repository at creation.
///
/// Sessions without a repository still run, but the Cursor dashboard files
/// sessions under repositories, so a repo-less session never appears in the
/// user's sessions list. Whether that is acceptable is the service's call;
/// deciding is this port's.
pub trait RepositoryChooser: Send + Sync {
    /// The repository this prompt's work belongs to, if any, and whether it
    /// wants a pull request. Hosted adapters choose from the prompt; standalone
    /// sessions leave the repository unset.
    ///
    /// An error is a failed prompt, not a reason to guess: a session pointed at
    /// the wrong repository is worse than a session that says it could not tell.
    fn choose(
        &self,
        prompt: &str,
        cwd: &std::path::Path,
    ) -> impl Future<Output = Result<SessionIntent, rootcause::Report>> + Send;
}

/// Leaves repository selection to Cursor in standalone sessions.
pub struct NoRepositoryChooser;

impl RepositoryChooser for NoRepositoryChooser {
    async fn choose(
        &self,
        _prompt: &str,
        _cwd: &std::path::Path,
    ) -> Result<SessionIntent, rootcause::Report> {
        Ok(SessionIntent::default())
    }
}