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.

39.8 KB
Raw Blame
//! Hands out Cursor cloud agents as session "containers".
//!
//! "Container" is the port's word, not reality's: there is no sandbox here.
//! Spawning wires an in-process ACP agent (`cursor_cloud_agents::serve`) to a
//! [`PipeTransport`] over a `tokio::io::duplex`, and the actual work happens
//! on a Cursor cloud agent in Cursor's VMs. That is why the lifecycle is so
//! much smaller than Daytona's — no image, no readiness recipe, no idle
//! reaper (an idle cloud agent costs us nothing), and teardown archives the
//! agent on cursor.com rather than destroying anything.
//!
//! What does need managing is the mapping. Cursor's API has no labels, so
//! `AgentSessionId -> cursor agent` lives only in the external-session repo:
//! written the moment an agent is minted (by [`RecordingCursor`], before the
//! create call returns), read back by `resume` to pre-seed the served session
//! with `restore_session`, and deleted on teardown.
//!
//! There is no deployment-wide Cursor client here, because there is no
//! deployment-wide Cursor key: a session runs on *its owner's* account, so
//! every entry point resolves the owner's key and mints a client for that one
//! session. The manager holds only what a client is built from.

use std::sync::{Arc, OnceLock};

use agent_client_protocol::schema::v1::SessionId;
use agent_session::domain::model::{AgentSession, AgentSessionId, ExternalSession, ReplicaId};
use agent_session::domain::ports::{AgentSessionRepo, ExternalSessionRepo};
use cursor_cloud_agents::api::{ApiKey, CursorClient, CursorConfig};
use cursor_cloud_agents::domain::artifact::{ArtifactListing, FetchedArtifact};
use cursor_cloud_agents::domain::model::RepoUrl as CursorRepoUrl;
use cursor_cloud_agents::domain::model::{
    CursorAgentId, CursorModel, CursorRunId, McpServer, ModelChoice,
};
use cursor_cloud_agents::domain::ports::{
    ArtifactStore, CursorAgents, CursorArtifacts, NoArtifactStore, RunStream,
};
use cursor_cloud_agents::domain::service::CursorSessionService;
use cursor_cloud_agents::inbound::acp::{AcpNotifier, serve};
use futures::Stream;
use tracing::Instrument as _;

use super::keys::CursorApiKeys;
use super::pipe::PipeTransport;
use super::repository_chooser::HaikuRepositoryChooser;
use crate::domain::error::{HarnessError, Result};
use crate::domain::model::{AgentKind, SessionBlocker, SpawnContainer};
use crate::domain::pending::PendingCommands;
use crate::domain::ports::{ContainerManager, ReachableRepositories};
use crate::domain::sandbox::SandboxResizeEffect;
use agent_session::domain::model::SandboxSize;
use macro_user_id::user_id::MacroUserIdStr;

#[cfg(test)]
mod test;

/// The provider name stored on external-session rows this manager writes.
pub const CURSOR_PROVIDER: &str = "cursor";

/// Byte capacity of each session's in-process ACP pipe. Frames are single
/// JSON lines; this only bounds how far one side can run ahead of the other.
const PIPE_CAPACITY: usize = 64 * 1024;

/// How often a live session checks for cursor.com activity on its agent.
///
/// The agent's page on cursor.com drives the same conversation, and Cursor's
/// v1 API has no webhooks yet — so while a session's transport is up, its
/// service polls, and a turn driven over there mirrors into Macro within
/// about a second instead of waiting for the next Macro prompt. One
/// `list_runs` per second per live session; a session mid-turn skips its
/// tick, and the poll dies with the pipe.
///
/// A fixed rate rather than a delay between polls: `list_runs` is a network
/// call, so sleeping this long *after* each one would quietly make the real
/// period `1s + latency` — the mirror falling furthest behind exactly when
/// Cursor is slowest.
const FOREIGN_SYNC_INTERVAL: std::time::Duration = std::time::Duration::from_secs(1);

/// A pipe idle this long is shut down, Daytona's reaper made local: the
/// session actor sees a clean disconnect and the next prompt resumes through
/// [`ContainerManager::resume`]. What this reclaims is not a sandbox — there
/// is none — but the pipe's tasks and its per-second cursor.com poll.
const CURSOR_IDLE_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5 * 60);

/// How often the idle timeout is evaluated.
///
/// Separate from [`FOREIGN_SYNC_INTERVAL`] because the two answer different
/// questions: the mirror's rate is how stale a cursor.com turn may look, this
/// is how late a pipe may be reclaimed. Checking a five-minute deadline once
/// a second would spend three hundred wakeups to fire once, and would tie the
/// reaper's precision to a poll rate chosen for something else. The cost of a
/// coarse check is that a pipe lives up to this long past its deadline, which
/// for reclaiming two idle tasks is nothing.
const CURSOR_IDLE_CHECK_INTERVAL: std::time::Duration = std::time::Duration::from_secs(30);

fn should_reap_cursor_pipe(idle: std::time::Duration, active_turn: bool, pending: bool) -> bool {
    idle >= CURSOR_IDLE_TIMEOUT && !active_turn && !pending
}

/// How long a pipe may sit idle past its deadline, kept open only by a turn
/// or an admitted command, before the idle check says so at `warn`.
///
/// The idle check logs its inputs every tick at `debug`, which production
/// does not ship. A long Cursor run legitimately holds a pipe open for an
/// hour with nothing moving through it, so the first half hour is nobody's
/// business - but a pipe held open this long, and again every interval
/// after, is either a very long run or a gate nobody will ever release, and
/// the second was found only by noticing which sessions were *not* reaped.
const HELD_OPEN_WARNING_INTERVAL: std::time::Duration = std::time::Duration::from_secs(30 * 60);

/// Whether this tick should warn that the pipe is held open, and the
/// threshold the next warning waits for.
///
/// `next` is the idle duration the next warning fires at; a pipe that saw
/// activity again resets it, so a session that is simply busy every day
/// warns once per long stretch rather than once per process.
fn held_open_warning(
    idle: std::time::Duration,
    held: bool,
    next: std::time::Duration,
) -> (bool, std::time::Duration) {
    if !held || idle < CURSOR_IDLE_TIMEOUT {
        return (false, HELD_OPEN_WARNING_INTERVAL);
    }
    if idle >= next {
        (true, next + HELD_OPEN_WARNING_INTERVAL)
    } else {
        (false, next)
    }
}

/// The ref new agents start their work from.
const DEFAULT_STARTING_REF: &str = "main";

/// A ticker of period `every`, first firing one period from now.
///
/// Two deliberate choices `tokio::time::interval` would not have made. It
/// fires its first tick immediately, which here would poll cursor.com the
/// instant a pipe opens — before the first prompt, on a session that has no
/// agent to ask about yet. And it defaults to [`MissedTickBehavior::Burst`],
/// which after one slow poll fires the whole backlog back to back at Cursor's
/// API; [`MissedTickBehavior::Delay`] just resumes the cadence from the tick
/// that ran late.
fn interval_from_now(every: std::time::Duration) -> tokio::time::Interval {
    let mut ticker = tokio::time::interval_at(tokio::time::Instant::now() + every, every);
    ticker.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
    ticker
}

/// Hands out Cursor cloud agents.
///
/// There is no deployment repository here either: a session's repository is
/// chosen from its first prompt, per session and per owner, which is what the
/// [`HaikuRepositoryChooser`] built in [`Self::serve_session`] answers. The
/// manager holds only what building one takes.
#[derive(Clone)]
pub struct CursorContainerManager<Sessions, Keys, Repositories, Store> {
    keys: Keys,
    /// Where a session's walkthrough artifacts are re-hosted, handed to every
    /// session this manager serves.
    artifacts: Store,
    base_url: String,
    sessions: Sessions,
    repositories: Arc<Repositories>,
    usage: Arc<dyn ai_usage::UsageRecorder>,
    admission: Arc<dyn ai_billing::AiAdmissionService>,
    pull_requests: Option<Arc<dyn agent_session::domain::pull_request::SessionPullRequests>>,
    working_branches:
        Option<Arc<dyn agent_session::domain::working_branch::SessionWorkingBranches>>,
    journal_storage: JournalStorage,
    /// Sessions the harness has a command in flight for right now, shared
    /// with `AgentHarnessService` so the idle reaper below never closes a
    /// pipe a command is already on its way to.
    pending: PendingCommands,
}

/// Where a hosted session's journal lives: the pool it is written to and the
/// replica claiming its rows. Passed as one value so the manager's constructor
/// takes a journal rather than its two halves.
#[derive(Clone)]
pub struct PostgresJournal {
    /// The pool session-log rows are written to.
    pub pool: sqlx::PgPool,
    /// The replica claiming those rows.
    pub replica: ReplicaId,
}

/// Hosted sessions always use durable storage; tests select memory explicitly.
#[derive(Clone)]
enum JournalStorage {
    Postgres {
        pool: sqlx::PgPool,
        replica: ReplicaId,
    },
    #[cfg(test)]
    Memory,
}

/// What a resumed session gets back at restore time.
///
/// The identity halves land in Postgres at different moments — the ACP session
/// id when `session/new` answers, the Cursor agent when the first prompt mints
/// it — so each is optional on its own; see [`CursorContainerManager::resume`].
struct RestoredCursorSession {
    /// The ACP session id the harness will name in `session/load`.
    acp_session: SessionId,
    /// The Cursor agent, when one was ever minted.
    agent: Option<CursorAgentId>,
    /// The last Cursor run whose output reached Macro's session log.
    last_run: Option<CursorRunId>,
}

impl<Sessions, Keys, Repositories>
    CursorContainerManager<Sessions, Keys, Repositories, NoArtifactStore>
where
    Sessions: AgentSessionRepo + ExternalSessionRepo + Clone,
    Keys: CursorApiKeys,
    Repositories: ReachableRepositories,
{
    /// Build a manager with required durable journal storage and replica identity.
    ///
    /// Sessions it serves re-host no artifacts until one is given to
    /// [`Self::with_artifact_store`].
    pub fn new(
        keys: Keys,
        base_url: String,
        sessions: Sessions,
        repositories: Arc<Repositories>,
        usage: Arc<dyn ai_usage::UsageRecorder>,
        journal: PostgresJournal,
        pending: PendingCommands,
    ) -> Self {
        Self {
            keys,
            artifacts: NoArtifactStore,
            base_url,
            sessions,
            repositories,
            usage,
            admission: Arc::new(ai_billing::DisabledAiAdmissionService),
            pull_requests: None,
            working_branches: None,
            journal_storage: JournalStorage::Postgres {
                pool: journal.pool,
                replica: journal.replica,
            },
            pending,
        }
    }

    /// Re-host every session's walkthrough artifacts through `artifacts`.
    ///
    /// Changes the manager's store type rather than taking an option, so a
    /// deployment without a static file service cannot accidentally be
    /// handed one that fails per file.
    #[must_use]
    pub fn with_artifact_store<Store>(
        self,
        artifacts: Store,
    ) -> CursorContainerManager<Sessions, Keys, Repositories, Store> {
        CursorContainerManager {
            keys: self.keys,
            artifacts,
            base_url: self.base_url,
            sessions: self.sessions,
            repositories: self.repositories,
            usage: self.usage,
            admission: self.admission,
            pull_requests: self.pull_requests,
            working_branches: self.working_branches,
            journal_storage: self.journal_storage,
            pending: self.pending,
        }
    }
}

impl<Sessions, Keys, Repositories, Store>
    CursorContainerManager<Sessions, Keys, Repositories, Store>
where
    Sessions: AgentSessionRepo + ExternalSessionRepo + Clone,
    Keys: CursorApiKeys,
    Repositories: ReachableRepositories,
    Store: ArtifactStore + Clone + 'static,
{
    #[cfg(test)]
    fn with_memory_journal(
        keys: Keys,
        base_url: String,
        sessions: Sessions,
        repositories: Arc<Repositories>,
        artifacts: Store,
    ) -> Self {
        Self {
            keys,
            artifacts,
            base_url,
            sessions,
            repositories,
            usage: Arc::new(ai_usage::NoOpUsageRecorder),
            admission: Arc::new(ai_billing::DisabledAiAdmissionService),
            pull_requests: None,
            working_branches: None,
            journal_storage: JournalStorage::Memory,
            pending: PendingCommands::new(),
        }
    }

    /// Configure admission for Macro-funded helpers, not the owner's Cursor runtime.
    pub fn with_admission(mut self, admission: Arc<dyn ai_billing::AiAdmissionService>) -> Self {
        self.admission = admission;
        self
    }

    /// Persist Cursor's returned PR using the shared session operation.
    pub fn with_pull_requests(
        mut self,
        service: Arc<dyn agent_session::domain::pull_request::SessionPullRequests>,
    ) -> Self {
        self.pull_requests = Some(service);
        self
    }

    /// Persist Cursor's repository branch facts through the owning session service.
    pub fn with_working_branches(
        mut self,
        service: Arc<dyn agent_session::domain::working_branch::SessionWorkingBranches>,
    ) -> Self {
        self.working_branches = Some(service);
        self
    }

    /// A client authenticated as `session`'s owner.
    ///
    /// Built per session and dropped with it, rather than held on the manager:
    /// the key belongs to one user, and the sessions of two users must not be
    /// able to reach each other's Cursor accounts through a shared client.
    #[tracing::instrument(
        name = "cursor.client.resolve",
        skip_all,
        err,
        fields(agent.session.id = %session.id)
    )]
    async fn client_for(&self, session: &AgentSession) -> Result<(CursorClient, Option<String>)> {
        // The key is a person's: a session owned by anything else has no
        // Cursor account to run on, and is refused here rather than resolved
        // as though it did.
        let config = self.keys.resolve(session.owner_user()?).await?;
        let client = CursorClient::new(CursorConfig {
            api_key: ApiKey::new(config.key.expose()),
            base_url: self.base_url.clone(),
            // The client-level model stays absent: the *session* carries the
            // model now (the user's default, seeded below via
            // `with_default_model`, or a per-session pick), applied per run.
            model: None,
            starting_ref: session
                .repo_branch
                .as_ref()
                .map(|branch| branch.as_str())
                .unwrap_or(DEFAULT_STARTING_REF)
                .to_owned(),
            record_dir: None,
        })
        .map_err(|error| {
            // The key came out of KMS, so a shape complaint here means a
            // corrupt row rather than a bad paste — the user cannot fix it by
            // retyping, and the fix is to register the key again.
            tracing::error!(error = %error, session_id = %session.id, "a stored cursor api key is unusable");
            HarnessError::Container("the stored cursor api key is unusable".to_owned())
        })?;
        Ok((client, config.default_model_id))
    }

    /// Wire up one session's in-process agent and return our end of its pipe.
    ///
    /// `restore` carries what a resumed session gets back; a fresh spawn
    /// passes `None`.
    async fn serve_session(
        &self,
        client: CursorClient,
        default_model_id: Option<String>,
        session: &AgentSession,
        restore: Option<RestoredCursorSession>,
    ) -> Result<agent_session::domain::connection::RuntimeAttachment<PipeTransport>> {
        let session_id = session.id;
        let owner = session.owner_user()?.clone();
        let owner_binding: Option<agent_session::domain::connection::AttachmentActivation>;
        let journal: Arc<dyn cursor_cloud_agents::domain::journal::CursorJournal> = match &self
            .journal_storage
        {
            JournalStorage::Postgres { pool, replica } => {
                let journal = Arc::new(
                    cursor_cloud_agents::outbound::postgres_journal::PgCursorJournal::new(
                        pool.clone(),
                        session_id,
                        *replica,
                    ),
                );
                let activated = journal.clone();
                owner_binding = Some(Box::new(move |claim| {
                    activated
                        .activate(claim.session, claim.replica, claim.fence)
                        .map_err(|e| {
                            agent_runtime_protocol::domain::ports::TransportError::Client(
                                e.to_string(),
                            )
                            .into()
                        })
                }));
                journal
            }
            #[cfg(test)]
            JournalStorage::Memory => {
                owner_binding = None;
                Arc::new(cursor_cloud_agents::outbound::memory_journal::MemoryJournal::default())
            }
        };
        let claim = Arc::new(OnceLock::new());
        let activated_claim = claim.clone();
        let owner_binding: agent_session::domain::connection::AttachmentActivation =
            Box::new(move |ownership| {
                if let Some(activate) = owner_binding {
                    activate(ownership)?;
                }
                activated_claim.set(ownership).map_err(|_| {
                    agent_runtime_protocol::domain::ports::TransportError::Client(
                        "Cursor attachment already activated".into(),
                    )
                    .into()
                })
            });
        let (ours, theirs) = tokio::io::duplex(PIPE_CAPACITY);
        let (agent_reader, agent_writer) = tokio::io::split(theirs);
        let cursor = RecordingCursor {
            client,
            session_id,
            sessions: self.sessions.clone(),
        };
        let (reload_tx, reload_rx) = tokio::sync::mpsc::unbounded_channel();
        let mut notifier = AcpNotifier::new().with_reload(reload_tx);
        if let Some(service) = &self.pull_requests {
            notifier = notifier.with_pull_requests(Arc::new(
                super::pull_request::CursorPullRequestReporter {
                    service: service.clone(),
                    session: session_id,
                    owner: owner.clone(),
                },
            ));
        }
        if let Some(service) = &self.working_branches {
            notifier = notifier.with_working_branches(Arc::new(
                super::working_branch::CursorWorkingBranchReporter {
                    service: service.clone(),
                    session: session_id,
                    owner: owner.clone(),
                    claim,
                },
            ));
        }
        let chooser = crate::domain::repository_choice::RepositoryChoiceService::new(
            Arc::clone(&self.repositories),
            self.sessions.clone(),
            HaikuRepositoryChooser::new(Arc::clone(&self.usage)),
            Arc::clone(&self.admission),
            owner,
            session_id,
        );
        let service = Arc::new(
            CursorSessionService::new(
                cursor,
                notifier.clone(),
                chooser,
                journal,
                self.artifacts.clone(),
            )
            .with_default_model(default_model_id)
            // The session's own model outranks the account default: what its
            // owner picked for it when they opened it, what they switched it
            // to since, or - for a session that never picked - the slug this
            // harness seeded the record with, which resolves to no opinion.
            .with_host_model(Some(session.model.clone()))
            .with_image_fetcher(Arc::new(
                cursor_cloud_agents::outbound::http_prompt_images::HttpPromptImageFetcher::new(),
            )),
        );
        if let Some(restored) = restore {
            service.restore_session_with_watermark(
                restored.acp_session,
                restored.agent,
                // The repository this session's first prompt chose, read back
                // from the row the chooser wrote it to. There is no
                // deployment default to fall back on, and a restored session
                // must land on the repository its agent was minted against.
                session.repo_url.as_deref().and_then(CursorRepoUrl::parse),
                restored.last_run,
            );
        }
        let pipe_closed = tokio_util::sync::CancellationToken::new();
        // Cloned before the tasks below move `pipe_closed` itself: the
        // attachment built at the end of this function hands this same
        // signal to the session actor's command wait, so a command sent
        // right as - or just after - this pipe dies fails at once instead
        // of riding out its own separate timeout for nothing.
        let attachment_closed = pipe_closed.clone();
        let shutdown = tokio_util::sync::CancellationToken::new();
        let sync_service = Arc::clone(&service);
        let on_pipe_close = pipe_closed.clone();
        tokio::spawn(async move {
            if let Err(error) = serve(service, notifier, agent_reader, agent_writer).await {
                tracing::warn!(%session_id, error = %error, "cursor acp connection ended with an error");
            }
            on_pipe_close.cancel();
        });
        // One task carries the session's two background jobs, on their own
        // cadences: mirroring cursor.com, and retiring a pipe nothing has
        // moved through.
        // tokio's clock, not std's: identical on a running service, and it
        // honours `tokio::time::pause` so both paths are testable without
        // waiting out five real minutes.
        let last_activity = Arc::new(std::sync::Mutex::new(tokio::time::Instant::now()));
        let observed = Arc::clone(&last_activity);
        let reaper_shutdown = shutdown.clone();
        let pending = self.pending.clone();
        // The Macro session id on everything this task does. The mirror's
        // own spans know only the ACP session id (`cursor-acp-1` for every
        // hosted session), so without this a run it follows for an hour is
        // unsearchable by the session it belongs to.
        let background = tracing::info_span!(
            "agent.session.background",
            agent.session.id = %session_id,
        );
        tokio::spawn(async move {
            let mut mirror = interval_from_now(FOREIGN_SYNC_INTERVAL);
            let mut reaper = interval_from_now(CURSOR_IDLE_CHECK_INTERVAL);
            let mut next_held_open_warning = HELD_OPEN_WARNING_INTERVAL;
            loop {
                tokio::select! {
                    () = pipe_closed.cancelled() => break,
                    _ = reaper.tick() => {
                        let observed_at = *last_activity
                            .lock()
                            .unwrap_or_else(std::sync::PoisonError::into_inner);
                        let active_turn = sync_service.has_active_turn();
                        // Checked alongside `active_turn`: a command already
                        // admitted for this session but not yet turn-active
                        // (the harness marks this at admission, before
                        // dispatch - see `queue::enqueue_then_dispatch`) is
                        // exactly the case `active_turn` alone cannot see.
                        let pending_command = pending.is_pending(session_id);
                        let activity = last_activity
                            .lock()
                            .unwrap_or_else(std::sync::PoisonError::into_inner);
                        // Recheck under the activity lock after inspecting the
                        // turn gate. A prompt frame arriving in that window
                        // changes the instant and prevents a stale idle reap.
                        let raced = *activity != observed_at;
                        let idle_ms = activity.elapsed().as_millis();
                        let reaped = !raced
                            && should_reap_cursor_pipe(
                                activity.elapsed(),
                                active_turn,
                                pending_command,
                            );
                        // Every tick, not just the reaping one. The inputs to
                        // this decision are what tell a pipe that died of
                        // idleness apart from one pulled out from under a
                        // live turn, and after the fact only the tick that
                        // fired is reconstructable - so the deadline being
                        // long expired while a turn held it open has to be
                        // visible on the ticks that did nothing.
                        tracing::debug!(
                            %session_id,
                            agent.pipe.idle_ms = idle_ms as u64,
                            agent.pipe.active_turn = active_turn,
                            agent.pipe.pending_command = pending_command,
                            agent.pipe.activity_raced = raced,
                            agent.pipe.reaped = reaped,
                            "cursor pipe idle check"
                        );
                        if reaped {
                            let _reap = tracing::info_span!(
                                "agent.pipe.reap",
                                agent.session.id = %session_id,
                                agent.pipe.idle_ms = idle_ms as u64,
                                agent.pipe.close_cause = "idle_timeout",
                            )
                            .entered();
                            tracing::info!(%session_id, "idle cursor session; closing its pipe");
                            reaper_shutdown.cancel();
                            break;
                        }
                        let (warn, next) = held_open_warning(
                            activity.elapsed(),
                            active_turn || pending_command,
                            next_held_open_warning,
                        );
                        next_held_open_warning = next;
                        if warn {
                            let in_flight = pending.turn(session_id);
                            tracing::warn!(
                                %session_id,
                                agent.pipe.idle_ms = idle_ms as u64,
                                agent.pipe.active_turn = active_turn,
                                agent.pipe.pending_command = pending_command,
                                in_flight_turn = in_flight.as_ref().map(|turn| turn.turn.0),
                                in_flight_action_id = in_flight.as_ref().map(|turn| tracing::field::display(turn.action_id)),
                                in_flight_age_secs = in_flight.as_ref().map(|turn| turn.age().num_seconds()),
                                "cursor pipe idle past its deadline but held open by a turn or an admitted command"
                            );
                        }
                    }
                    _ = mirror.tick() => sync_service.sync_foreign_runs().await,
                }
            }
        }.instrument(background));
        let transport = PipeTransport::connect_recoverable(
            ours,
            move || {
                *observed
                    .lock()
                    .unwrap_or_else(std::sync::PoisonError::into_inner) =
                    tokio::time::Instant::now();
            },
            shutdown,
            Some(reload_rx),
        );
        Ok(
            agent_session::domain::connection::RuntimeAttachment::solo(transport)
                .with_closed(attachment_closed)
                .on_activate(owner_binding),
        )
    }
}

impl<Sessions, Keys, Repositories, Store> ContainerManager
    for CursorContainerManager<Sessions, Keys, Repositories, Store>
where
    Sessions: AgentSessionRepo + ExternalSessionRepo + Clone,
    Keys: CursorApiKeys,
    Repositories: ReachableRepositories,
    Store: ArtifactStore + Clone + 'static,
{
    type Transport = PipeTransport;

    /// A `@cursor` session runs on its owner's key, so an owner without one
    /// is told so before any session exists for them. The kind is not
    /// consulted: the router only asks this manager about Cursor sessions.
    async fn preflight(
        &self,
        _kind: AgentKind,
        owner: &MacroUserIdStr<'_>,
    ) -> Result<Option<SessionBlocker>> {
        match self.keys.resolve(owner).await {
            Ok(_) => Ok(None),
            Err(HarnessError::CursorNotConnected) => Ok(Some(SessionBlocker::CursorNotConnected)),
            Err(error) => Err(error),
        }
    }

    async fn spawn(
        &self,
        command: SpawnContainer,
    ) -> Result<agent_session::domain::connection::RuntimeAttachment<PipeTransport>> {
        // The session row is read for its owner alone. The mention path has
        // already asked [`Self::preflight`] about the owner's key; sessions
        // opened from the create menu and older rows still reach the refusal
        // here, so "the bot ignored me" stays a sentence they can act on.
        let session = AgentSessionRepo::get(&self.sessions, command.session_id).await?;
        let (client, default_model_id) = self.client_for(&session).await?;
        // No MCP servers pass through here: they ride the ACP protocol
        // itself. The harness's session actor names them in `session/new`,
        // and the in-process adapter forwards them to Cursor's API - the same
        // rail every other transport uses.
        self.serve_session(client, default_model_id, &session, None)
            .await
    }

    async fn resume(
        &self,
        session: AgentSessionId,
    ) -> Result<agent_session::domain::connection::RuntimeAttachment<PipeTransport>> {
        // The identity lives in Postgres in two halves that appear at
        // different moments: the ACP session id lands when `session/new`
        // answers, the Cursor agent only when the first prompt mints it. A
        // session can die between the two, so each half is restored on its
        // own — the harness re-enters with `session/load` whenever it has an
        // acp id, and a load must find its session even when there is no
        // agent yet (the next prompt mints one). No acp id at all means the
        // session never opened; serve it fresh, exactly like `spawn`.
        let stored = AgentSessionRepo::get(&self.sessions, session).await?;
        let (client, default_model_id) = self.client_for(&stored).await?;
        let restore = match &stored.acp_session_id {
            Some(acp) => {
                let external = ExternalSessionRepo::get(&self.sessions, session).await?;
                let agent = external
                    .as_ref()
                    .map(|external| CursorAgentId::new(external.external_id.clone()));
                Some(RestoredCursorSession {
                    acp_session: acp.clone(),
                    agent,
                    last_run: external
                        .and_then(|external| external.last_run_id)
                        .map(CursorRunId::new),
                })
            }
            None => None,
        };
        // No MCP servers on resume, deliberately. Cursor fixes an agent's MCP
        // config when the agent is created, so a session that prompted before
        // the restart keeps its servers on cursor.com regardless of what is
        // passed here - and the session token needed to mint fresh entries
        // died with the process (only its hash is persisted). The one session
        // this loses servers for is one restored before its first prompt ever
        // landed, which then creates its agent bare rather than not at all.
        self.serve_session(client, default_model_id, &stored, restore)
            .await
    }

    /// A Cursor session has no container of ours to hold a token: the raw
    /// token went to Cursor's cloud at agent creation and is not readable
    /// back.
    async fn session_token(&self, _session: AgentSessionId) -> Result<Option<String>> {
        Ok(None)
    }

    async fn teardown(&self, session: AgentSessionId) -> Result<()> {
        // Archive, never delete: the agent and its work belong to the Cursor
        // account's owner, and archiving is reversible on cursor.com while
        // deletion is not. A session with no external row never minted an
        // agent, which is already the state teardown asks for.
        let Some(external) = ExternalSessionRepo::get(&self.sessions, session).await? else {
            return Ok(());
        };
        // Archiving needs the owner's key, and teardown is exactly when it may
        // be gone — a user who disconnects Cursor still has sessions to clean
        // up. The row is ours and the agent is theirs, so a key we no longer
        // hold costs them an unarchived agent on cursor.com, which they can
        // see and archive; refusing the teardown instead would leave a Macro
        // session that can never be cleaned up at all.
        let stored = AgentSessionRepo::get(&self.sessions, session).await?;
        let agent = CursorAgentId::new(external.external_id);
        match self.client_for(&stored).await {
            Ok((client, _default_model_id)) => client
                .archive_agent(&agent)
                .await
                .map_err(|error| HarnessError::Container(error.to_string()))?,
            Err(error) => tracing::warn!(
                %session,
                %agent,
                error = %error,
                "tearing down a cursor session without archiving its agent",
            ),
        }
        ExternalSessionRepo::delete(&self.sessions, session).await?;
        Ok(())
    }

    // A Cursor session's compute is Cursor's: there is no sandbox here whose
    // size this manager could change, so every resize is unsupported and the
    // domain persists the preference without touching anything.
    fn resize_effect(&self, _from: SandboxSize, _to: SandboxSize) -> SandboxResizeEffect {
        SandboxResizeEffect::Unsupported
    }

    async fn resize(&self, _session: AgentSessionId, _size: SandboxSize) -> Result<()> {
        Err(HarnessError::Container(
            "a cursor session has no sandbox to resize".to_owned(),
        ))
    }
}

/// A [`CursorAgents`] decorator that records each minted agent's identity.
///
/// The agent is created inside the served session's first prompt, long after
/// `spawn` returned, so the manager cannot write the mapping itself. This
/// wrapper does it at the only moment the fact exists: after `create_agent`
/// succeeds and before it returns, so no prompt can be answered by an agent
/// the database does not know about. The name and url are fetched with a
/// follow-up `get_agent` — one extra call per session lifetime — and are
/// cosmetic: if the fetch fails the row is still written with the id alone.
struct RecordingCursor<Sessions> {
    client: CursorClient,
    session_id: AgentSessionId,
    sessions: Sessions,
}

impl<Sessions> CursorAgents for RecordingCursor<Sessions>
where
    Sessions: ExternalSessionRepo + Clone,
{
    async fn raw_result(
        &self,
        agent: &CursorAgentId,
        run: &CursorRunId,
    ) -> std::result::Result<String, rootcause::Report> {
        self.client.raw_result(agent, run).await
    }

    #[tracing::instrument(skip_all, err, fields(
        agent.session.id = %self.session_id,
        cursor.repository.configured = repo.is_some(),
        cursor.pull_request.auto_create = open_pull_request && repo.is_some(),
        cursor.model.configured = model.is_some(),
        cursor.mcp_server.count = mcp_servers.len(),
    ))]
    async fn create_agent(
        &self,
        prompt: &str,
        repo: Option<&CursorRepoUrl>,
        open_pull_request: bool,
        mcp_servers: &[McpServer],
        model: Option<&ModelChoice>,
        images: &[cursor_cloud_agents::domain::prompt_image::CursorPromptImage],
    ) -> std::result::Result<(CursorAgentId, CursorRunId), rootcause::Report> {
        let (agent, run) = self
            .client
            .create_agent(prompt, repo, open_pull_request, mcp_servers, model, images)
            .await?;
        let summary = self
            .client
            .get_agent(&agent)
            .await
            .inspect_err(|error| {
                tracing::warn!(error = ?error, %agent, "could not fetch the new agent's name and url");
            })
            .ok();
        self.sessions
            .upsert(
                self.session_id,
                ExternalSession {
                    provider: CURSOR_PROVIDER.to_owned(),
                    external_id: agent.to_string(),
                    external_name: summary.as_ref().map(|summary| summary.name.clone()),
                    external_url: summary.map(|summary| summary.url),
                    last_run_id: None,
                },
            )
            .await
            .map_err(|error| rootcause::report!("could not record the cursor agent: {error}"))?;
        Ok((agent, run))
    }

    #[tracing::instrument(
        skip_all,
        err,
        fields(
            agent.session.id = %self.session_id,
            cursor.agent.id = %agent,
            cursor.model.configured = model.is_some(),
        )
    )]
    async fn create_run(
        &self,
        agent: &CursorAgentId,
        prompt: &str,
        model: Option<&ModelChoice>,
        images: &[cursor_cloud_agents::domain::prompt_image::CursorPromptImage],
    ) -> std::result::Result<CursorRunId, rootcause::Report> {
        self.client.create_run(agent, prompt, model, images).await
    }

    async fn list_models(&self) -> std::result::Result<Vec<CursorModel>, rootcause::Report> {
        self.client.list_models().await
    }

    async fn cancel_run(
        &self,
        agent: &CursorAgentId,
        run: &CursorRunId,
    ) -> std::result::Result<(), rootcause::Report> {
        self.client.cancel_run(agent, run).await
    }

    async fn list_runs(
        &self,
        agent: &CursorAgentId,
        through: Option<&CursorRunId>,
    ) -> std::result::Result<Vec<cursor_cloud_agents::domain::model::RunListing>, rootcause::Report>
    {
        self.client.list_runs(agent, through).await
    }

    async fn conversation(
        &self,
        agent: &CursorAgentId,
    ) -> std::result::Result<
        Vec<cursor_cloud_agents::domain::model::ConversationLine>,
        rootcause::Report,
    > {
        self.client.conversation(agent).await
    }
}

impl<Sessions> CursorArtifacts for RecordingCursor<Sessions>
where
    Sessions: ExternalSessionRepo + Clone,
{
    async fn list_artifacts(
        &self,
        agent: &CursorAgentId,
    ) -> std::result::Result<Vec<ArtifactListing>, rootcause::Report> {
        CursorArtifacts::list_artifacts(&self.client, agent).await
    }

    async fn fetch_artifact(
        &self,
        agent: &CursorAgentId,
        path: &str,
    ) -> std::result::Result<FetchedArtifact, rootcause::Report> {
        CursorArtifacts::fetch_artifact(&self.client, agent, path).await
    }
}

impl<Sessions> RunStream for RecordingCursor<Sessions>
where
    Sessions: ExternalSessionRepo + Clone,
{
    async fn raw_stream(
        &self,
        agent: &CursorAgentId,
        run: &CursorRunId,
        resume_from: Option<&str>,
    ) -> std::result::Result<
        cursor_cloud_agents::domain::ports::ConnectedStream<
            impl Stream<
                Item = std::result::Result<
                    cursor_cloud_agents::domain::journal::NativeRecord,
                    rootcause::Report,
                >,
            > + Send,
        >,
        cursor_cloud_agents::domain::ports::StreamConnectError,
    > {
        self.client.raw_stream(agent, run, resume_from).await
    }
}