Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
13.8 KB
Raw Blame
//! Cursor subscription provider.
//!
//! Consolidation calls the logged-in Cursor Agent CLI (`agent --print`)
//! instead of a platform API key. The CLI already holds the Cursor
//! subscription. Invocations stay in `--mode ask`: captured session text is
//! untrusted, and `--yolo` / `--force` would let that text run tools. For the
//! same reason the child gets an allowlisted environment
//! ([`cursor_child_env`]), never the server's: `AI_MEMORY_AUTH_TOKEN` and
//! other providers' keys stay out of its reach.
//!
//! The CLI has no JSON-schema mode. The schema travels in the prompt, the
//! answer is parsed leniently (code fences and surrounding prose stripped),
//! and the caller's serde deserialisation is the only validation: a value
//! that deserialises is accepted even if it breaks a schema constraint serde
//! does not check.

use std::ffi::{OsStr, OsString};
use std::path::{Path, PathBuf};
use std::process::Stdio;
use std::time::Duration;

use async_trait::async_trait;
use tokio::io::{AsyncRead, AsyncReadExt as _};
use tokio::process::Command;
use tokio::time::timeout;
use uuid::Uuid;

use crate::auth::CursorAuth;
use crate::error::{LlmError, LlmResult};
use crate::provider::LlmProvider;
use crate::types::{ChatRequest, ChatResponse, Role};

/// Model used when `AI_MEMORY_LLM_MODEL` is unset.
///
/// `agent --list-models` labels this id "Grok 4.6". Override with any other id
/// from that list.
pub const CURSOR_DEFAULT_MODEL: &str = "cursor-grok-4.6-high";

const MAX_STDOUT_BYTES: usize = 1024 * 1024;
const MAX_STDERR_BYTES: usize = 64 * 1024;

/// Variables the child keeps, compared ASCII-case-insensitively (Windows
/// names are case-insensitive and proxies come in both cases): identity and
/// home for the CLI's stored login and keychain, locale, temp, the session
/// bus for a Linux keyring, proxy and CA settings, and the Windows process
/// basics.
const CURSOR_CHILD_ENV: &[&str] = &[
    "PATH",
    "HOME",
    "USER",
    "LOGNAME",
    "SHELL",
    "LANG",
    "LANGUAGE",
    "TZ",
    "TERM",
    "TMPDIR",
    "TMP",
    "TEMP",
    "XDG_CONFIG_HOME",
    "XDG_DATA_HOME",
    "XDG_CACHE_HOME",
    "XDG_STATE_HOME",
    "XDG_RUNTIME_DIR",
    "DBUS_SESSION_BUS_ADDRESS",
    "HTTP_PROXY",
    "HTTPS_PROXY",
    "ALL_PROXY",
    "NO_PROXY",
    "SSL_CERT_FILE",
    "SSL_CERT_DIR",
    "NODE_EXTRA_CA_CERTS",
    "USERPROFILE",
    "APPDATA",
    "LOCALAPPDATA",
    "PROGRAMDATA",
    "SYSTEMROOT",
    "WINDIR",
    "COMSPEC",
    "PATHEXT",
];

/// Prefixes the child keeps: locale categories and the CLI's own settings
/// (`CURSOR_API_KEY` among them).
const CURSOR_CHILD_ENV_PREFIXES: &[&str] = &["LC_", "CURSOR_"];

/// The subset of `process_env` the Cursor Agent CLI child runs with.
///
/// The child reads untrusted captured session text, so everything outside
/// the allowlist — ai-memory's own token, other providers' keys, arbitrary
/// operator secrets — is dropped.
#[must_use]
pub fn cursor_child_env(process_env: &[(OsString, OsString)]) -> Vec<(OsString, OsString)> {
    process_env
        .iter()
        .filter(|(name, _)| is_allowed_child_var(name))
        .cloned()
        .collect()
}

fn is_allowed_child_var(name: &OsStr) -> bool {
    let Some(name) = name.to_str() else {
        return false;
    };
    CURSOR_CHILD_ENV
        .iter()
        .any(|allowed| name.eq_ignore_ascii_case(allowed))
        || CURSOR_CHILD_ENV_PREFIXES.iter().any(|prefix| {
            name.len() > prefix.len()
                && name.as_bytes()[..prefix.len()].eq_ignore_ascii_case(prefix.as_bytes())
        })
}

/// Chat provider that shells out to the Cursor `agent` CLI.
pub struct CursorAgentProvider {
    model: String,
    auth: CursorAuth,
    timeout: Duration,
}

impl CursorAgentProvider {
    /// Construct the provider.
    ///
    /// The executable is not probed here: a missing `agent` binary fails on
    /// the first completion with a path-specific error.
    #[must_use]
    pub fn new(auth: CursorAuth, model: impl Into<String>) -> Self {
        Self {
            model: model.into(),
            auth,
            timeout: Duration::from_secs(crate::DEFAULT_REQUEST_TIMEOUT_SECS),
        }
    }

    /// Override the CLI wait ceiling.
    #[must_use]
    pub fn with_timeout_secs(mut self, secs: u64) -> Self {
        self.timeout = Duration::from_secs(secs);
        self
    }

    async fn complete_text(
        &self,
        request: &ChatRequest,
        schema: Option<&serde_json::Value>,
    ) -> LlmResult<String> {
        let workspace = TempWorkspace::create(&self.auth.temp_root)?;
        let body = render_request(request, schema);
        std::fs::write(workspace.path.join("request.md"), body)
            .map_err(|err| LlmError::UnexpectedShape(format!("writing cursor prompt: {err}")))?;

        let mut command = Command::new(&self.auth.executable);
        command
            .env_clear()
            .envs(
                self.auth
                    .child_env
                    .iter()
                    .map(|(name, value)| (name, value)),
            )
            .arg("--print")
            .arg("--mode")
            .arg("ask")
            .arg("--output-format")
            .arg("text")
            .arg("--trust")
            .arg("--workspace")
            .arg(&workspace.path);
        if self.model != "default" {
            command.arg("--model").arg(&self.model);
        }
        command
            .arg(
                "Read request.md in this workspace and answer it. \
                 Reply with only the requested answer. Do not use tools.",
            )
            .current_dir(&workspace.path)
            .stdin(Stdio::null())
            .stdout(Stdio::piped())
            .stderr(Stdio::piped())
            .kill_on_drop(true);

        let mut child = spawn_retrying_busy(&mut command).await.map_err(|err| {
            LlmError::NotConfigured(format!(
                "cursor agent CLI ({}) failed to start: {err}. Install the Cursor agent \
                 or set AI_MEMORY_CURSOR_AGENT",
                self.auth.executable.display()
            ))
        })?;
        let stdout = child
            .stdout
            .take()
            .ok_or_else(|| LlmError::UnexpectedShape("cursor agent stdout missing".into()))?;
        let stderr = child
            .stderr
            .take()
            .ok_or_else(|| LlmError::UnexpectedShape("cursor agent stderr missing".into()))?;

        let collected = timeout(self.timeout, async {
            // Both pipes drain at once: reading stdout to EOF first would
            // leave a chatty child blocked on a full stderr pipe until the
            // timeout. `try_join!` also stops at the first capped stream
            // instead of waiting on the other one (the child is killed on
            // drop).
            let (stdout, stderr) = tokio::try_join!(
                read_capped(stdout, MAX_STDOUT_BYTES),
                read_capped(stderr, MAX_STDERR_BYTES)
            )?;
            let status = child.wait().await.map_err(|err| {
                LlmError::UnexpectedShape(format!("waiting for cursor agent: {err}"))
            })?;
            Ok::<_, LlmError>((status, stdout, stderr))
        })
        .await
        .map_err(|_| LlmError::Provider {
            status: 504,
            body: "cursor agent timed out".into(),
            retry_after: None,
        })??;

        let (status, stdout, stderr) = collected;
        if !status.success() {
            let code = status.code().unwrap_or(1);
            let body = String::from_utf8_lossy(&stderr);
            return Err(LlmError::Provider {
                status: u16::try_from(code).unwrap_or(1),
                body: truncate_chars(&body, 500),
                retry_after: None,
            });
        }
        let text = String::from_utf8_lossy(&stdout).trim().to_string();
        if text.is_empty() {
            return Err(LlmError::UnexpectedShape(
                "cursor agent returned an empty answer".into(),
            ));
        }
        Ok(text)
    }
}

#[async_trait]
impl LlmProvider for CursorAgentProvider {
    fn name(&self) -> &'static str {
        "cursor"
    }

    fn model(&self) -> &str {
        &self.model
    }

    async fn complete(&self, request: ChatRequest) -> LlmResult<ChatResponse> {
        let text = self.complete_text(&request, None).await?;
        Ok(ChatResponse {
            text,
            usage: None,
            model: self.model.clone(),
        })
    }

    async fn complete_structured_raw(
        &self,
        request: ChatRequest,
        schema: serde_json::Value,
    ) -> LlmResult<serde_json::Value> {
        let text = self.complete_text(&request, Some(&schema)).await?;
        parse_json_answer(&text)
    }
}

struct TempWorkspace {
    path: PathBuf,
}

impl TempWorkspace {
    fn create(root: &Path) -> LlmResult<Self> {
        if !root.is_absolute() {
            return Err(LlmError::NotConfigured(format!(
                "cursor workspace root must be an absolute path, got {}",
                root.display()
            )));
        }
        let path = root.join(format!("ai-memory-cursor-{}", Uuid::now_v7()));
        // The prompt is captured session text: keep the workspace private
        // to the server's user on a shared temp directory.
        #[cfg(unix)]
        let builder = {
            use std::os::unix::fs::DirBuilderExt as _;
            let mut builder = std::fs::DirBuilder::new();
            builder.mode(0o700);
            builder
        };
        #[cfg(not(unix))]
        let builder = std::fs::DirBuilder::new();
        builder.create(&path).map_err(|err| {
            LlmError::UnexpectedShape(format!("creating cursor workspace: {err}"))
        })?;
        Ok(Self { path })
    }
}

impl Drop for TempWorkspace {
    fn drop(&mut self) {
        let _ = std::fs::remove_dir_all(&self.path);
    }
}

fn render_request(request: &ChatRequest, schema: Option<&serde_json::Value>) -> String {
    let mut body = String::new();
    if let Some(system) = &request.system {
        body.push_str("# System\n");
        body.push_str(system);
        body.push_str("\n\n");
    }
    for message in &request.messages {
        let heading = match message.role {
            Role::User => "# User\n",
            Role::Assistant => "# Assistant\n",
        };
        body.push_str(heading);
        body.push_str(&message.content);
        body.push_str("\n\n");
    }
    if let Some(schema) = schema {
        body.push_str("# Output\nReturn one JSON value matching this schema and nothing else.\n");
        body.push_str(&schema.to_string());
        body.push('\n');
    }
    body
}

fn parse_json_answer(text: &str) -> LlmResult<serde_json::Value> {
    let stripped = strip_fence(text.trim());
    if let Ok(value) = serde_json::from_str::<serde_json::Value>(stripped) {
        return Ok(value);
    }
    let start = stripped.find(['{', '[']);
    let end = stripped.rfind(['}', ']']);
    if let (Some(start), Some(end)) = (start, end)
        && end > start
        && let Ok(value) = serde_json::from_str::<serde_json::Value>(&stripped[start..=end])
    {
        return Ok(value);
    }
    // Prose around the answer can carry its own brackets (`for [the
    // request]:`, `(see [schema])`), which throws the first/last slice off.
    // Fall back to the first balanced, string-aware object.
    if let Some(value) = crate::openai_compat::first_json_object(stripped)
        .and_then(|slice| serde_json::from_str::<serde_json::Value>(slice).ok())
    {
        return Ok(value);
    }
    Err(LlmError::UnexpectedShape(format!(
        "cursor agent did not return JSON: {}",
        truncate_chars(stripped, 200)
    )))
}

fn strip_fence(text: &str) -> &str {
    let Some(rest) = text.strip_prefix("```") else {
        return text;
    };
    let rest = rest.trim_start_matches(|c: char| c.is_ascii_alphanumeric() || c == '-');
    let rest = rest.trim_start_matches(['\r', '\n']);
    rest.trim_end().trim_end_matches('`').trim_end()
}

fn truncate_chars(text: &str, max: usize) -> String {
    let mut out = String::new();
    for ch in text.chars() {
        if out.chars().count() >= max {
            out.push('…');
            break;
        }
        out.push(ch);
    }
    out
}

async fn read_capped(mut reader: impl AsyncRead + Unpin, cap: usize) -> LlmResult<Vec<u8>> {
    let mut buf = [0_u8; 8192];
    let mut out = Vec::new();
    loop {
        let n = reader
            .read(&mut buf)
            .await
            .map_err(|err| LlmError::UnexpectedShape(format!("reading cursor agent: {err}")))?;
        if n == 0 {
            break;
        }
        if out.len().saturating_add(n) > cap {
            return Err(LlmError::UnexpectedShape(
                "cursor agent output exceeded the size cap".into(),
            ));
        }
        out.extend_from_slice(&buf[..n]);
    }
    Ok(out)
}

/// Executable the provider will spawn. `AI_MEMORY_CURSOR_AGENT` wins; otherwise
/// the name `agent` is resolved from `PATH` at spawn time.
#[must_use]
pub fn cursor_executable(override_path: Option<&Path>) -> PathBuf {
    override_path
        .map(Path::to_path_buf)
        .unwrap_or_else(|| PathBuf::from("agent"))
}

/// Spawn, retrying briefly while the executable is busy (ETXTBSY): a file
/// still open for writing in another process — an agent binary being
/// replaced by its updater, or a just-written script whose descriptor a
/// concurrent fork inherited until its exec — cannot be executed yet.
async fn spawn_retrying_busy(command: &mut Command) -> std::io::Result<tokio::process::Child> {
    const ATTEMPTS: u32 = 5;
    let mut attempt = 1;
    loop {
        match command.spawn() {
            Err(err)
                if err.kind() == std::io::ErrorKind::ExecutableFileBusy && attempt < ATTEMPTS =>
            {
                attempt += 1;
                tokio::time::sleep(std::time::Duration::from_millis(20)).await;
            }
            result => return result,
        }
    }
}