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.

15.7 KB
Raw Blame
//! Identifiers and small value types shared across the crate.

#[cfg(test)]
mod test;

use serde::{Deserialize, Serialize};

/// The identity of a Cursor cloud agent (`bc-…`), which holds the
/// conversation across runs.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct CursorAgentId(String);

impl CursorAgentId {
    /// Wrap an agent id as returned by the Cursor API.
    #[must_use]
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }

    /// The id as the API path segment.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

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

/// The identity of one run (`run-…`) — one turn of a Cursor agent.
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct CursorRunId(String);

impl CursorRunId {
    /// Wrap a run id as returned by the Cursor API.
    #[must_use]
    pub fn new(id: impl Into<String>) -> Self {
        Self(id.into())
    }

    /// The id as the API path segment.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

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

/// An HTTPS repository url in the form the Cursor API accepts,
/// e.g. `https://github.com/macro-inc/macro`.
///
/// Constructed only through [`RepoUrl::parse`], which normalizes the ssh and
/// scp-like forms a checkout's `origin` remote commonly uses. An agent
/// created without one still runs, but the Cursor dashboard files sessions
/// under a repository, so it never appears in the sessions list.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(transparent)]
pub struct RepoUrl(String);

impl RepoUrl {
    /// Normalize a git remote into the HTTPS url the Cursor API wants.
    ///
    /// `[email protected]:org/repo.git`, `ssh://[email protected]/org/repo.git` and
    /// `https://github.com/org/repo.git` all normalize to
    /// `https://github.com/org/repo`. Anything that does not end up HTTPS is
    /// rejected rather than guessed at.
    #[must_use]
    pub fn parse(remote: &str) -> Option<Self> {
        let remote = remote.trim();
        let normalized = if let Some(rest) = remote.strip_prefix("ssh://git@") {
            format!("https://{rest}")
        } else if let Some((host, path)) = remote
            .strip_prefix("git@")
            .and_then(|rest| rest.split_once(':'))
        {
            format!("https://{host}/{path}")
        } else {
            remote.to_owned()
        };
        let normalized = normalized.strip_suffix(".git").unwrap_or(&normalized);
        normalized
            .starts_with("https://")
            .then(|| Self(normalized.to_owned()))
    }

    /// Canonical identity for a GitHub repository in native result metadata.
    /// Cursor reports both scheme-less and HTTPS URLs across result records.
    pub(crate) fn from_git_state(remote: &str) -> Option<Self> {
        if remote.trim() != remote {
            return None;
        }
        let (scheme, address) = remote.split_once("://").unwrap_or(("https", remote));
        if !scheme.eq_ignore_ascii_case("https") {
            return None;
        }
        let (host, path) = address.split_once('/')?;
        if !host.eq_ignore_ascii_case("github.com") {
            return None;
        }
        let path = path.strip_suffix('/').unwrap_or(path);
        let repository = Self::parse(&format!("https://github.com/{path}"))?;
        let slug = repository.github_owner_and_name()?;
        if slug.split('/').any(|part| {
            part == "."
                || part == ".."
                || !part
                    .bytes()
                    .all(|byte| byte.is_ascii_alphanumeric() || b"._-".contains(&byte))
        }) {
            return None;
        }
        Some(Self(repository.as_str().to_ascii_lowercase()))
    }

    /// The url as the API wants it.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.0
    }

    /// `owner/name` for a github.com url, the form a person recognizes.
    ///
    /// `None` for anything else — a self-hosted host, or a github.com url
    /// with more or fewer path segments than a repository has — so callers
    /// fall back to printing the whole url rather than a guessed slug.
    #[must_use]
    pub fn github_owner_and_name(&self) -> Option<&str> {
        let path = self.0.strip_prefix("https://github.com/")?;
        let (owner, name) = path.split_once('/')?;
        (!owner.is_empty() && !name.is_empty() && !name.contains('/')).then_some(path)
    }
}

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

/// The lifecycle state of a run as the Cursor API reports it.
///
/// Non-exhaustive on the wire: statuses this crate has not seen round-trip
/// through [`RunStatus::Unknown`] rather than failing the stream.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
pub enum RunStatus {
    /// The run's environment is being prepared.
    Creating,
    /// The run is executing.
    Running,
    /// The run completed successfully.
    Finished,
    /// The run was cancelled.
    Cancelled,
    /// The run failed.
    Error,
    /// A status this crate does not know yet.
    #[serde(untagged)]
    Unknown(String),
}

/// A run's state as `GET /v1/agents/{id}/runs/{run}` reports it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunOutcome {
    /// Where the run is in its lifecycle.
    pub status: RunStatus,
    /// The final assistant reply, present once the run is terminal.
    pub text: Option<String>,
}

impl RunStatus {
    /// Whether the run has ended, in any way. `Unknown` counts as terminal:
    /// a status this crate cannot read is not one worth polling forever on.
    #[must_use]
    pub fn is_terminal(&self) -> bool {
        !matches!(self, Self::Creating | Self::Running)
    }
}

impl RunOutcome {
    /// Whether the run has ended, in any way. See [`RunStatus::is_terminal`].
    #[must_use]
    pub fn is_terminal(&self) -> bool {
        self.status.is_terminal()
    }
}

/// One run in an agent's history, as `GET /v1/agents/{id}/runs` lists it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RunListing {
    /// The run's id.
    pub id: CursorRunId,
    /// Where the run is in its lifecycle.
    pub status: RunStatus,
}

/// Who said one line of an agent's conversation.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConversationSpeaker {
    /// A prompt, whether typed here or on cursor.com.
    User,
    /// One of the agent's replies. A turn has several, one per step.
    Agent,
}

/// One line of an agent's conversation, as Cursor still holds it.
///
/// Prompts and replies only: no tool calls, no reasoning, no run ids and no
/// timestamps. Enough to find a prompt that was lost, not enough to rebuild
/// a turn - which is why this supplements captured history rather than
/// replacing it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ConversationLine {
    /// Who said it.
    pub speaker: ConversationSpeaker,
    /// What was said.
    pub text: String,
}

/// An MCP server a session should make available to its Cursor agent.
///
/// Only the transports a *cloud* agent can honour. ACP's third transport,
/// stdio, names an executable by absolute path on the **client's** machine
/// (`command`, `args`, `env`); a Cursor agent runs in Cursor's sandbox, where
/// that path does not exist and where those env values — routinely API tokens
/// — would be shipped to be spawned. Forwarding it would produce a server
/// that looks configured and silently isn't, so the adapter declines it out
/// loud instead of modelling it here. See [`crate::inbound::acp`].
///
/// Cursor sets MCP configuration when an agent is created, so these belong to
/// the session from `session/new` onward and cannot change mid-conversation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct McpServer {
    /// The client's name for the server, passed through unchanged.
    pub name: String,
    /// Which remote transport to speak.
    pub transport: McpTransport,
    /// The server's url.
    pub url: String,
    /// Headers to send with each request — typically the server's auth.
    pub headers: Vec<McpHeader>,
}

/// The remote MCP transports this agent can forward.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum McpTransport {
    /// Streamable HTTP.
    Http,
    /// Server-sent events.
    Sse,
}

impl McpTransport {
    /// The transport as the Cursor API's `type` discriminator.
    #[must_use]
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Http => "http",
            Self::Sse => "sse",
        }
    }
}

/// One HTTP header for an MCP server.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct McpHeader {
    /// Header name.
    pub name: String,
    /// Header value.
    pub value: String,
}

/// A model choice: an id, plus the parameters that make it a *variant*.
///
/// Cursor validates the pair, not the id alone — `grok-4.5` with no params is
/// rejected with `does not match a known variant`, while the same id with
/// `effort=high, fast=true` is accepted. So a bare id is not a usable
/// selection and this type never models one.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct ModelChoice {
    /// The model id, e.g. `claude-sonnet-5`.
    pub id: String,
    /// The variant's parameters, in the order Cursor listed them.
    pub params: Vec<ModelParam>,
}

/// One tunable of a model variant, e.g. `effort=high`.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModelParam {
    /// The parameter's id, e.g. `effort`.
    pub id: String,
    /// The chosen value, e.g. `high`. A string even for booleans: Cursor's own
    /// enumeration gives `"true"`/`"false"` as values, not JSON booleans.
    pub value: String,
}

/// A model Cursor offers, as `GET /v1/models` describes it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CursorModel {
    /// The id to send, e.g. `gpt-5.5`.
    pub id: String,
    /// The name a person should see, e.g. `GPT-5.5`.
    pub display_name: String,
    /// The concrete id+params combinations Cursor will accept, one of which it
    /// marks as the default.
    pub variants: Vec<ModelVariant>,
}

impl CursorModel {
    /// The variant Cursor marks default, or its first — the params to send
    /// when a caller names a model and nothing more.
    ///
    /// Cursor rejects a selection whose params are not a known variant, so
    /// "the model with no params" is not an option; something has to be
    /// chosen, and Cursor's own default is the least surprising choice.
    #[must_use]
    pub fn default_variant(&self) -> Option<&ModelVariant> {
        self.variants
            .iter()
            .find(|variant| variant.is_default)
            .or_else(|| self.variants.first())
    }

    /// This model as a selection, using [`Self::default_variant`].
    #[must_use]
    pub fn default_choice(&self) -> ModelChoice {
        ModelChoice {
            id: self.id.clone(),
            params: self
                .default_variant()
                .map(|variant| variant.params.clone())
                .unwrap_or_default(),
        }
    }

    /// The family this model belongs to, read off its display name.
    ///
    /// Cursor's listing carries no provider or family field, so the family is
    /// inferred: the words before the first version-looking token. `Claude
    /// Opus 4.8` and `Claude Opus 5` are both `Claude Opus`; `GPT-5.6 Sol` is
    /// `GPT`; `Kimi K3` is `Kimi`. A name with no version, or one that starts
    /// with a version (`Auto`, `o3 Pro`), is its own family, so nothing is ever
    /// forced into a bucket it does not plainly belong to.
    #[must_use]
    pub fn family(&self) -> String {
        model_family(&self.display_name)
    }
}

/// A group of models that share a family, as a picker would head them.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModelFamily {
    /// The family's name, e.g. `Claude Opus`.
    pub name: String,
    /// A stable id for the family: the name lowercased and hyphenated, e.g.
    /// `claude-opus`.
    pub id: String,
    /// The members, in the order the listing gave them.
    pub models: Vec<CursorModel>,
}

impl ModelFamily {
    /// Bucket models by [`CursorModel::family`], families in order of first
    /// appearance and each family's members in listing order, so a client that
    /// renders the groups in order shows the same overall order Cursor did.
    #[must_use]
    pub fn group(models: &[CursorModel]) -> Vec<ModelFamily> {
        let mut families: Vec<ModelFamily> = Vec::new();
        for model in models {
            let name = model.family();
            match families.iter_mut().find(|family| family.name == name) {
                Some(family) => family.models.push(model.clone()),
                None => families.push(ModelFamily {
                    id: family_id(&name),
                    name,
                    models: vec![model.clone()],
                }),
            }
        }
        families
    }

    /// Whether grouping adds any structure: at least one family with more
    /// than one member. A listing of singletons is better shown flat than
    /// under one header per model.
    #[must_use]
    pub fn is_informative(families: &[ModelFamily]) -> bool {
        families.iter().any(|family| family.models.len() > 1)
    }
}

/// See [`CursorModel::family`].
fn model_family(display_name: &str) -> String {
    let tokens: Vec<&str> = display_name
        .split_whitespace()
        .flat_map(split_hyphenated_version)
        .collect();
    let family: Vec<&str> = tokens
        .iter()
        .take_while(|token| !is_version_token(token))
        .copied()
        .collect();
    if family.is_empty() || family.len() == tokens.len() {
        display_name.trim().to_owned()
    } else {
        family.join(" ")
    }
}

/// `GPT-5.6` is a name and a version joined by a hyphen; split it so the
/// version can be recognised. `gpt-oss` and the like stay whole.
fn split_hyphenated_version(token: &str) -> Vec<&str> {
    match token.split_once('-') {
        Some((head, tail))
            if !head.is_empty() && tail.chars().next().is_some_and(|c| c.is_ascii_digit()) =>
        {
            vec![head, tail]
        }
        _ => vec![token],
    }
}

/// A version-looking token: alphanumerics and dots, with a digit as the first
/// or second character. `4.6`, `5`, `K3`, `o3`, `4o`, `R1` — but not `GPT`,
/// `Sol`, `Fast` or `Mini`.
fn is_version_token(token: &str) -> bool {
    let mut chars = token.chars();
    let starts_with_version = match (chars.next(), chars.next()) {
        (Some(first), _) if first.is_ascii_digit() => true,
        (Some(first), Some(second)) => first.is_ascii_alphabetic() && second.is_ascii_digit(),
        _ => false,
    };
    starts_with_version && token.chars().all(|c| c.is_ascii_alphanumeric() || c == '.')
}

/// A family name as a stable id: lowercase, runs of non-alphanumerics as one
/// hyphen, no leading or trailing hyphen.
fn family_id(name: &str) -> String {
    let mut id = String::with_capacity(name.len());
    for c in name.chars() {
        if c.is_ascii_alphanumeric() {
            id.push(c.to_ascii_lowercase());
        } else if !id.ends_with('-') {
            id.push('-');
        }
    }
    id.trim_matches('-').to_owned()
}

/// One accepted id+params combination for a model.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ModelVariant {
    /// The parameters this variant fixes.
    pub params: Vec<ModelParam>,
    /// Whether Cursor marks this the model's default variant.
    pub is_default: bool,
}