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.

9.8 KB
Raw Blame
//! Errors the session service can produce.

use crate::domain::model::{CursorAgentId, RepoUrl, RunStatus};
use agent_client_protocol::schema::v1::SessionId;
pub use agent_runtime_protocol::domain::turn::{FailureLink, FailureNotice, FailureNoticeKind};
use thiserror::Error;

/// Why a session operation failed.
#[derive(Debug, Error)]
pub enum SessionError {
    /// A Macro-funded hosted helper was refused; the owner's Cursor budget is unrelated.
    #[cfg(feature = "postgres")]
    #[error(transparent)]
    Admission(#[from] agent_session::domain::error::AiAdmissionError),
    /// The client referenced a session this agent never created.
    #[error("unknown session {0}")]
    UnknownSession(SessionId),
    /// A prompt arrived while the session's previous turn was still running.
    /// ACP turns are strictly sequential; the client must wait for the
    /// previous `session/prompt` to respond.
    #[error("session {0} already has an active turn")]
    TurnAlreadyActive(SessionId),
    /// Native capture or replay processing failed; never masked by cancellation.
    #[error("Cursor native journal failed: {0}")]
    Journal(rootcause::Report),
    /// The Cursor API or its stream failed.
    #[error("{0}")]
    Cursor(rootcause::Report),
    /// The provider refused the prompt for a reason the person who sent it
    /// can act on. Carries what is meant for them and nothing else: it is
    /// what the `session/prompt` error says, so a report's decorations (a
    /// bullet, a source location) would be read as part of the instruction.
    #[error("{0}")]
    Rejected(PromptRefusal),
}

impl From<rootcause::Report> for SessionError {
    fn from(report: rootcause::Report) -> Self {
        #[cfg(feature = "postgres")]
        if let Some(error) =
            report.downcast_current_context::<agent_session::domain::error::AiAdmissionError>()
        {
            return Self::Admission(*error);
        }
        Self::Cursor(report)
    }
}

/// What a refused prompt tells the person who sent it.
///
/// `message` is the `session/prompt` error's message and is always present.
/// `notice` is the same refusal in the shape a reader renders as an
/// instruction with somewhere to go; it exists only for the refusals a
/// person can resolve outside Macro, and travels as the error's `data`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PromptRefusal {
    /// One plain sentence or two, no report decorations.
    pub message: String,
    /// The refusal as a rendered notice, when there is more to say than a line.
    pub notice: Option<Box<FailureNotice>>,
}

impl PromptRefusal {
    /// A refusal that is only its message.
    #[must_use]
    pub fn plain(message: impl Into<String>) -> Self {
        Self {
            message: message.into(),
            notice: None,
        }
    }
}

impl std::fmt::Display for PromptRefusal {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter.write_str(&self.message)
    }
}

/// A prompt Cursor refused because the account behind the API key has no
/// background-agent budget left.
///
/// Seen in production as a 400 with code `usage_limit_exceeded`: "You need
/// to increase your hard limit. Background Agent requires at least $2
/// remaining until your hard limit." A fact about the person's own Cursor
/// account, fixed on Cursor's dashboard, so it is the person's to read - not
/// an internal error, which is how the raw report presented it.
#[derive(Debug, Error)]
#[error("cursor refused the prompt ({code}): {detail}")]
pub struct UsageLimitExceeded {
    /// Cursor's error code, one of [`Self::CODES`].
    pub code: String,
    /// Cursor's own error body, verbatim, for the logs.
    pub detail: String,
}

impl UsageLimitExceeded {
    /// Cursor's error codes for an exhausted budget.
    ///
    /// Matched on the structured `error.code`, never the message: Cursor's
    /// wording (and the dollar figure in it) is theirs to change.
    pub const CODES: [&'static str; 1] = ["usage_limit_exceeded"];

    /// Where the limit is raised.
    pub const DASHBOARD_URL: &'static str = "https://www.cursor.com/dashboard?tab=settings";

    /// What to show the person who sent the prompt.
    #[must_use]
    pub fn notice(&self) -> FailureNotice {
        FailureNotice {
            kind: FailureNoticeKind::ProviderUsageLimit,
            title: "Cursor usage limit reached".to_owned(),
            body: "Your Cursor account has no background-agent budget left, so this message \
                   wasn't sent. Raise the spending limit in your Cursor dashboard, then send \
                   it again."
                .to_owned(),
            link: Some(FailureLink {
                label: "Manage Cursor usage".to_owned(),
                url: Self::DASHBOARD_URL.to_owned(),
            }),
        }
    }

    /// The refusal as the `session/prompt` error carries it.
    #[must_use]
    pub fn refusal(&self) -> PromptRefusal {
        let notice = self.notice();
        PromptRefusal {
            message: format!("{} {}", notice.title, notice.body),
            notice: Some(Box::new(notice)),
        }
    }
}

/// A run Cursor ended in neither `FINISHED` nor `CANCELLED`.
///
/// Cursor's API carries no reason for a failed run: the run record and the
/// stream's `result` have only the status, and the stream's `error` events
/// seen in production are all about the stream itself. The run's page on
/// cursor.com is the one place that says why, so the notice sends the person
/// there. Before this the turn failed with a raw report naming a source line.
#[derive(Debug, Error)]
#[error("cursor run ended in {status:?}")]
pub struct RunFailed {
    /// The agent whose run failed, for the link to Cursor's page for it.
    pub agent: CursorAgentId,
    /// The terminal status Cursor reported.
    pub status: RunStatus,
}

impl RunFailed {
    /// Where Cursor shows an agent's runs; the agent id follows.
    pub const AGENT_PAGE_URL: &'static str = "https://cursor.com/agents/";

    /// What to show the person who sent the prompt.
    #[must_use]
    pub fn notice(&self) -> FailureNotice {
        FailureNotice {
            kind: FailureNoticeKind::ProviderRunFailed,
            title: "Cursor run failed".to_owned(),
            body: "Cursor stopped this run with an error. Open the run in Cursor to see why, \
                   then send another message to continue."
                .to_owned(),
            link: Some(FailureLink {
                label: "Open in Cursor".to_owned(),
                url: format!("{}{}", Self::AGENT_PAGE_URL, self.agent),
            }),
        }
    }

    /// The failure as the `session/prompt` error carries it.
    #[must_use]
    pub fn refusal(&self) -> PromptRefusal {
        let notice = self.notice();
        PromptRefusal {
            message: format!("{} {}", notice.title, notice.body),
            notice: Some(Box::new(notice)),
        }
    }
}

/// A provider response proving a prompt was rejected before execution.
#[derive(Debug, Error)]
#[error("{0}")]
pub struct PromptRejected(pub String);

/// A prompt rejected specifically because Cursor could not use the session's
/// repository.
///
/// A distinct context because it is the one rejection the user can act on,
/// and acting on it happens outside Macro. `detail` keeps Cursor's own body
/// for the logs; [`Self::user_message`] is what a person should read.
#[derive(Debug, Error)]
#[error("cursor cannot use {repo} ({reason}): {detail}")]
pub struct RepositoryUnavailable {
    /// The repository the session asked Cursor to work in.
    pub repo: RepoUrl,
    /// Which of Cursor's refusals this was.
    pub reason: RepositoryRejection,
    /// Cursor's own error body, verbatim.
    pub detail: String,
}

/// The ways Cursor has refused a repository, as seen in production.
///
/// Each maps to a different sentence for the user: an inaccessible repository
/// wants the GitHub app connected, while a branch Cursor could not verify is
/// usually Cursor's own verification flaking — the ref exists — so the
/// message must not send the user off to rename a branch that is fine.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RepositoryRejection {
    /// `repository_access` / `integration_not_connected`: the account cannot
    /// reach the repository at all.
    Inaccessible,
    /// `validation_error` "Failed to verify existence of branch …": Cursor's
    /// GitHub-side check could not confirm the starting ref. Observed to be
    /// intermittent for refs that exist, so the client retries it before
    /// surfacing it.
    BranchUnverifiable {
        /// The ref the request asked to start from.
        starting_ref: String,
    },
}

impl std::fmt::Display for RepositoryRejection {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Inaccessible => formatter.write_str("inaccessible"),
            Self::BranchUnverifiable { starting_ref } => {
                write!(formatter, "could not verify branch {starting_ref}")
            }
        }
    }
}

impl RepositoryUnavailable {
    /// What to show the person who sent the prompt.
    #[must_use]
    pub fn user_message(&self) -> String {
        let repo = self
            .repo
            .github_owner_and_name()
            .unwrap_or_else(|| self.repo.as_str());
        match &self.reason {
            RepositoryRejection::Inaccessible => format!(
                "Cursor can't access {repo}. Connect the repository to Cursor's GitHub app, then prompt again."
            ),
            RepositoryRejection::BranchUnverifiable { starting_ref } => format!(
                "Cursor couldn't verify that branch '{starting_ref}' exists in {repo}, even after retrying. \
                 This is usually transient on Cursor's side; prompt again in a moment. \
                 If it keeps happening, check that {repo} is connected to Cursor's GitHub app."
            ),
        }
    }
}