Skip to content

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

Rust
16.3 KB
Raw Blame
//! Detached native process launcher for background hook-spool drains.

use std::ffi::OsString;
use std::fs::OpenOptions;
use std::io::{self, Write as _};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};

/// Rotate `hook-drain.log` once it grows past this. The log only receives
/// drainer warnings, but a chronically unreachable server emits one on every
/// session boundary forever — without a cap the append-only file grows
/// unbounded. One rotation generation (`.old`) keeps the recent history.
const MAX_DRAIN_LOG_BYTES: u64 = 1024 * 1024;

/// Rename an oversized log to `<name>.old` (replacing any previous `.old`)
/// so the next append starts a fresh file. Best-effort: a failed rotation
/// must never block spawning the drainer.
fn rotate_oversized_log(log: &Path, max_bytes: u64) {
    let Ok(meta) = std::fs::metadata(log) else {
        return;
    };
    if meta.len() <= max_bytes {
        return;
    }
    let mut old = log.as_os_str().to_os_string();
    old.push(".old");
    let _ = std::fs::rename(log, PathBuf::from(old));
}

/// Unit-testable description of the hidden drainer command.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DrainCommandSpec {
    /// Executable path.
    pub exe: PathBuf,
    /// Command arguments.
    pub args: Vec<OsString>,
    /// Stderr log file under `<data_dir>/logs`.
    pub stderr_log: PathBuf,
    /// Current static bearer to hand the child in its environment, when the
    /// spawning hook has one.
    ///
    /// The environment rather than an argument: a flag would put the
    /// credential in the process table for the lifetime of the drain, readable
    /// by anyone who can run `ps`.
    pub live_token: Option<OsString>,
}

/// Unit-testable stdio/detach configuration for a drainer process.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SpawnConfig {
    /// stdin is redirected to null.
    pub stdin_null: bool,
    /// stdout is redirected to null.
    pub stdout_null: bool,
    /// stderr is redirected to this file.
    pub stderr_file: PathBuf,
    /// Platform detach flags applied to the command.
    pub detach: DetachConfig,
}

/// Platform detach configuration.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DetachConfig {
    /// Unix starts the drainer in a new session through a trusted `setsid`
    /// launcher when available; otherwise it falls back to a new process group.
    #[cfg(unix)]
    UnixNewSession { setsid: Option<PathBuf> },
    /// Windows creation flags.
    #[cfg(windows)]
    WindowsCreationFlags(u32),
    /// No extra detach flags on unsupported platforms.
    #[cfg(not(any(unix, windows)))]
    None,
}

/// Build `ai-memory --data-dir <dir> hook-drain`.
///
/// `live_token` is the bearer the spawning hook is currently configured with.
/// A spooled envelope froze its own credential at capture time, so handing the
/// drain a current one is what lets it recover entries stranded by a rotation
/// (#542).
pub fn command_spec(data_dir: &Path, live_token: Option<&str>) -> io::Result<DrainCommandSpec> {
    Ok(DrainCommandSpec {
        exe: std::env::current_exe()?,
        args: vec![
            OsString::from("--data-dir"),
            data_dir.as_os_str().to_os_string(),
            OsString::from("hook-drain"),
        ],
        stderr_log: data_dir.join("logs").join("hook-drain.log"),
        live_token: live_token.filter(|t| !t.is_empty()).map(OsString::from),
    })
}

/// Which server the spawned backfill delivers to: the one the spawning hook
/// resolved for this event, never whatever the environment points at.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum BackfillTarget<'a> {
    /// The hook's install-time `--server-url`.
    ServerUrl(&'a str),
    /// A server profile the repository's marker selected (#992).
    Profile(&'a str),
}

/// Build `ai-memory --data-dir <dir> backfill --auto --quiet` plus the hook's
/// resolved target.
///
/// The one-time boot backfill of pre-hook local history is potentially long
/// (it reads native transcripts and imports them), so it runs detached exactly
/// like the drainer rather than inline in the SessionStart hook's tight budget.
///
/// The target is passed explicitly because, left to itself, `backfill`
/// resolves the server from config and the environment: a hook pointed at a
/// remote server then backfilled into `127.0.0.1` whenever the agent was
/// launched without `AI_MEMORY_SERVER_URL`. It carries no bearer on its argv
/// or in its environment: `backfill` reads the persisted hook token, or the
/// profile's own token, from the data dir.
pub fn backfill_command_spec(
    data_dir: &Path,
    target: BackfillTarget<'_>,
    inflight_claim: &str,
) -> io::Result<DrainCommandSpec> {
    let (flag, value) = match target {
        BackfillTarget::ServerUrl(url) => ("--server-url", url),
        BackfillTarget::Profile(name) => ("--server-profile", name),
    };
    Ok(DrainCommandSpec {
        exe: std::env::current_exe()?,
        args: vec![
            OsString::from("--data-dir"),
            data_dir.as_os_str().to_os_string(),
            OsString::from("backfill"),
            OsString::from("--auto"),
            OsString::from("--quiet"),
            OsString::from("--inflight-claim"),
            OsString::from(inflight_claim),
            OsString::from(flag),
            OsString::from(value),
        ],
        stderr_log: data_dir.join("logs").join("backfill.log"),
        live_token: None,
    })
}

/// Spawn the detached one-time boot backfill without inheriting hook stdio.
/// Best-effort: a spawn failure must never break session start.
pub fn spawn_backfill(
    data_dir: &Path,
    target: BackfillTarget<'_>,
    inflight_claim: &str,
) -> io::Result<()> {
    let spec = backfill_command_spec(data_dir, target, inflight_claim)?;
    spawn_spec(&spec)
}

/// Build the stdio/detach shape used when spawning.
#[must_use]
pub fn spawn_config(spec: &DrainCommandSpec, try_breakaway: bool) -> SpawnConfig {
    SpawnConfig {
        stdin_null: true,
        stdout_null: true,
        stderr_file: spec.stderr_log.clone(),
        detach: detach_config(try_breakaway),
    }
}

/// Spawn the hidden drainer without inheriting hook stdio.
pub fn spawn(data_dir: &Path, live_token: Option<&str>) -> io::Result<()> {
    let spec = command_spec(data_dir, live_token)?;
    spawn_spec(&spec)
}

/// Hand the child the current bearer in its environment, when there is one.
/// Applied to every spawn path so the breakaway-retry cannot silently drop it.
fn apply_live_token(command: &mut Command, spec: &DrainCommandSpec) {
    if let Some(token) = &spec.live_token {
        command.env(crate::commands::hook_spool::LIVE_TOKEN_ENV, token);
    }
}

fn spawn_spec(spec: &DrainCommandSpec) -> io::Result<()> {
    if let Some(parent) = spec.stderr_log.parent() {
        std::fs::create_dir_all(parent)?;
    }
    rotate_oversized_log(&spec.stderr_log, MAX_DRAIN_LOG_BYTES);
    let config = spawn_config(spec, true);
    let stderr = OpenOptions::new()
        .create(true)
        .append(true)
        .open(&config.stderr_file)?;

    let mut command = command_for_spec(spec, &config.detach);
    apply_live_token(&mut command, spec);
    command
        .stdin(Stdio::null())
        .stdout(Stdio::null())
        .stderr(Stdio::from(stderr));

    match command.spawn() {
        Ok(_child) => Ok(()),
        Err(err) if should_retry_without_breakaway(&err) => {
            let mut log = OpenOptions::new()
                .create(true)
                .append(true)
                .open(&spec.stderr_log)?;
            let _ = writeln!(
                log,
                "ai-memory hook-drain: breakaway spawn failed with access denied; retrying without breakaway"
            );
            let config = spawn_config(spec, false);
            let stderr = OpenOptions::new()
                .create(true)
                .append(true)
                .open(&config.stderr_file)?;
            let mut retry = command_for_spec(spec, &config.detach);
            apply_live_token(&mut retry, spec);
            retry
                .stdin(Stdio::null())
                .stdout(Stdio::null())
                .stderr(Stdio::from(stderr));
            retry.spawn().map(|_| ())
        }
        Err(err) => Err(err),
    }
}

#[cfg(unix)]
fn detach_config(_try_breakaway: bool) -> DetachConfig {
    DetachConfig::UnixNewSession {
        setsid: trusted_setsid_launcher(),
    }
}

#[cfg(unix)]
fn command_for_spec(spec: &DrainCommandSpec, detach: &DetachConfig) -> Command {
    use std::os::unix::process::CommandExt as _;

    match detach {
        DetachConfig::UnixNewSession {
            setsid: Some(setsid),
        } => {
            let mut command = Command::new(setsid);
            command.arg(&spec.exe).args(&spec.args);
            command
        }
        DetachConfig::UnixNewSession { setsid: None } => {
            let mut command = Command::new(&spec.exe);
            command.args(&spec.args);
            command.process_group(0);
            command
        }
    }
}

#[cfg(unix)]
fn trusted_setsid_launcher() -> Option<PathBuf> {
    [Path::new("/usr/bin/setsid"), Path::new("/bin/setsid")]
        .into_iter()
        .find(|path| path.is_file())
        .map(Path::to_path_buf)
}

#[cfg(windows)]
fn detach_config(try_breakaway: bool) -> DetachConfig {
    const DETACHED_PROCESS: u32 = 0x0000_0008;
    const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
    const CREATE_NO_WINDOW: u32 = 0x0800_0000;
    const CREATE_BREAKAWAY_FROM_JOB: u32 = 0x0100_0000;

    let mut flags = DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW;
    if try_breakaway {
        flags |= CREATE_BREAKAWAY_FROM_JOB;
    }
    DetachConfig::WindowsCreationFlags(flags)
}

#[cfg(windows)]
fn apply_detach_flags(command: &mut Command, detach: &DetachConfig) {
    use std::os::windows::process::CommandExt as _;
    let DetachConfig::WindowsCreationFlags(flags) = detach;
    command.creation_flags(*flags);
}

#[cfg(windows)]
fn command_for_spec(spec: &DrainCommandSpec, detach: &DetachConfig) -> Command {
    let mut command = Command::new(&spec.exe);
    command.args(&spec.args);
    apply_detach_flags(&mut command, detach);
    command
}

#[cfg(not(any(unix, windows)))]
fn detach_config(_try_breakaway: bool) -> DetachConfig {
    DetachConfig::None
}

#[cfg(not(any(unix, windows)))]
fn command_for_spec(spec: &DrainCommandSpec, _detach: &DetachConfig) -> Command {
    let mut command = Command::new(&spec.exe);
    command.args(&spec.args);
    command
}

#[cfg(not(windows))]
fn should_retry_without_breakaway(_err: &io::Error) -> bool {
    false
}

#[cfg(windows)]
fn should_retry_without_breakaway(err: &io::Error) -> bool {
    err.raw_os_error() == Some(5)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn command_spec_uses_data_dir_then_hidden_subcommand() {
        let tmp = tempfile::tempdir().unwrap();
        let spec = command_spec(tmp.path(), None).unwrap();

        assert_eq!(
            spec.args,
            vec![
                OsString::from("--data-dir"),
                tmp.path().as_os_str().to_os_string(),
                OsString::from("hook-drain"),
            ]
        );
        assert_eq!(
            spec.stderr_log,
            tmp.path().join("logs").join("hook-drain.log")
        );
    }

    #[test]
    fn rotate_oversized_log_rotates_once_over_cap_and_keeps_small_logs() {
        let tmp = tempfile::tempdir().unwrap();
        let log = tmp.path().join("hook-drain.log");
        let old = tmp.path().join("hook-drain.log.old");

        // Under the cap: untouched.
        std::fs::write(&log, b"small").unwrap();
        rotate_oversized_log(&log, 16);
        assert!(log.exists());
        assert!(!old.exists());

        // Over the cap: current becomes .old, next append starts fresh.
        std::fs::write(&log, vec![b'x'; 32]).unwrap();
        rotate_oversized_log(&log, 16);
        assert!(!log.exists());
        assert_eq!(std::fs::metadata(&old).unwrap().len(), 32);

        // A second rotation replaces the previous .old rather than failing.
        std::fs::write(&log, vec![b'y'; 32]).unwrap();
        rotate_oversized_log(&log, 16);
        assert_eq!(std::fs::read(&old).unwrap(), vec![b'y'; 32]);

        // Missing file: no-op, no panic.
        rotate_oversized_log(&log, 16);
    }

    /// The credential must reach the drain in its environment and nowhere
    /// near its argv. A command line is world-readable through the process
    /// table for as long as the process lives, so passing the token as a flag
    /// would publish it to every local user each time a session ends.
    #[test]
    fn the_live_token_travels_in_the_environment_not_the_command_line() {
        let tmp = tempfile::tempdir().unwrap();
        let spec = command_spec(tmp.path(), Some("SECRET-BEARER")).unwrap();

        assert_eq!(
            spec.live_token.as_deref(),
            Some(std::ffi::OsStr::new("SECRET-BEARER"))
        );
        let rendered: Vec<String> = spec
            .args
            .iter()
            .map(|a| a.to_string_lossy().into_owned())
            .collect();
        assert!(
            !rendered.iter().any(|a| a.contains("SECRET-BEARER")),
            "token leaked into argv: {rendered:?}"
        );
        assert!(
            rendered.iter().any(|a| a == "hook-drain"),
            "still the drain command: {rendered:?}"
        );
    }

    /// The backfill goes where the hook resolved, and a profile travels as a
    /// name only — the worker reads its server credential from the data dir.
    #[test]
    fn backfill_carries_the_hooks_target_and_no_bearer() {
        let tmp = tempfile::tempdir().unwrap();
        let default = backfill_command_spec(
            tmp.path(),
            BackfillTarget::ServerUrl("https://a.example"),
            "11111111222243338444555555555555",
        )
        .unwrap();
        assert_eq!(
            &default.args[2..],
            [
                "backfill",
                "--auto",
                "--quiet",
                "--inflight-claim",
                "11111111222243338444555555555555",
                "--server-url",
                "https://a.example"
            ]
            .map(OsString::from)
        );
        let profile = backfill_command_spec(
            tmp.path(),
            BackfillTarget::Profile("team-b"),
            "11111111222243338444555555555555",
        )
        .unwrap();
        assert_eq!(
            &profile.args[7..],
            ["--server-profile", "team-b"].map(OsString::from)
        );
        assert!(profile.live_token.is_none());
        assert!(default.live_token.is_none());
    }

    /// An absent or empty token carries nothing, so a no-auth deployment does
    /// not export an empty bearer into the child.
    #[test]
    fn an_absent_or_empty_token_is_not_carried() {
        let tmp = tempfile::tempdir().unwrap();
        assert!(command_spec(tmp.path(), None).unwrap().live_token.is_none());
        assert!(
            command_spec(tmp.path(), Some(""))
                .unwrap()
                .live_token
                .is_none()
        );
    }

    #[test]
    fn spawn_config_redirects_stdio_and_logs_under_data_dir_logs() {
        let tmp = tempfile::tempdir().unwrap();
        let spec = command_spec(tmp.path(), None).unwrap();
        let config = spawn_config(&spec, true);

        assert!(config.stdin_null);
        assert!(config.stdout_null);
        assert_eq!(
            config.stderr_file,
            tmp.path().join("logs").join("hook-drain.log")
        );
    }

    #[cfg(unix)]
    #[test]
    fn unix_spawn_config_prefers_true_session_detach_when_available() {
        let tmp = tempfile::tempdir().unwrap();
        let spec = command_spec(tmp.path(), None).unwrap();
        let DetachConfig::UnixNewSession { setsid } = spawn_config(&spec, true).detach;
        if let Some(path) = setsid {
            assert!(
                path == Path::new("/usr/bin/setsid") || path == Path::new("/bin/setsid"),
                "only trusted absolute setsid launchers are used: {path:?}"
            );
        }
    }

    #[cfg(windows)]
    #[test]
    fn windows_spawn_config_uses_expected_flags_and_breakaway_toggle() {
        let tmp = tempfile::tempdir().unwrap();
        let spec = command_spec(tmp.path(), None).unwrap();
        let DetachConfig::WindowsCreationFlags(with_breakaway) = spawn_config(&spec, true).detach;
        let DetachConfig::WindowsCreationFlags(without_breakaway) =
            spawn_config(&spec, false).detach;
        assert_ne!(with_breakaway, without_breakaway);
    }
}