Skip to content

Reason Network: your team's coding agents, talking to each other. The engine behind `reason network`.

16.5 KB
Raw Blame
//! Install a native plugin without rewriting Hermes YAML or opting into background turns.
use super::*;

const MANIFEST: &str = include_str!("../../integrations/hermes/plugin.yaml");
const PLUGIN: &str = include_str!("../../integrations/hermes/__init__.py");
const README: &str = include_str!("../../integrations/hermes/README.md");
const MARKER: &str = ".reason-setup.json";

#[cfg(test)]
thread_local! {
    /// A test's Hermes home, so setup's own dispatch can be run against it.
    static TEST_HOME: std::cell::RefCell<Option<PathBuf>> = const { std::cell::RefCell::new(None) };
}

/// The Hermes home, before a sticky profile is chosen.
fn base() -> PathBuf {
    #[cfg(test)]
    if let Some(home) = TEST_HOME.with(|h| h.borrow().clone()) {
        return home;
    }
    if let Some(path) = std::env::var_os("HERMES_HOME").filter(|p| !p.is_empty()) {
        let path = PathBuf::from(path);
        return path.strip_prefix("~").map(|p| home().join(p)).unwrap_or(path);
    }
    let suffix = std::env::var("HERMES_DATA_DIR_SUFFIX").unwrap_or_default();
    if cfg!(windows) {
        std::env::var_os("LOCALAPPDATA")
            .map(PathBuf::from)
            .unwrap_or_else(|| home().join("AppData/Local"))
            .join(format!("hermes{suffix}"))
    } else {
        home().join(format!(".hermes{suffix}"))
    }
}

fn root() -> PathBuf {
    active_root(&base())
}

/// Where this Hermes's own code is: its installer's checkout, else what `hermes --version` reports.
fn source() -> Option<PathBuf> {
    let bundled = base().join("hermes-agent");
    if bundled.join("hermes_cli").is_dir() {
        return Some(bundled);
    }
    let mut version = Command::new(agent::find_bin("hermes")?);
    version.arg("--version");
    install_dir(version)
}

/// The `Install directory:` a Hermes command reports, waiting at most a few seconds for it.
fn install_dir(mut command: Command) -> Option<PathBuf> {
    command.stdin(std::process::Stdio::null()).stdout(std::process::Stdio::piped()).stderr(std::process::Stdio::null());
    // In its own process group, so giving up on it ends what it started too (a launcher's Python, a shell's `sleep`).
    #[cfg(unix)]
    std::os::unix::process::CommandExt::process_group(&mut command, 0);
    let mut child = command.spawn().ok()?;
    let stdout = child.stdout.take()?;
    let (tx, rx) = std::sync::mpsc::channel();
    std::thread::spawn(move || {
        let found = std::io::BufRead::lines(std::io::BufReader::new(stdout))
            .map_while(Result::ok)
            .find_map(|l| l.trim().strip_prefix("Install directory:").map(|p| PathBuf::from(p.trim())));
        let _ = tx.send(found);
    });
    // A Hermes that hangs on `--version` (or leaves something holding its output) mustn't hang setup, init and join.
    let found = rx.recv_timeout(std::time::Duration::from_secs(5)).ok().flatten();
    kill_tree(&mut child);
    let _ = child.wait();
    found
}

/// Ends `child` and everything it started: its process group on Unix, its process tree on Windows.
fn kill_tree(child: &mut std::process::Child) {
    #[cfg(unix)]
    // SAFETY: signals the process group `install_dir` created for this child, which isn't reaped yet.
    unsafe {
        libc::killpg(child.id() as libc::pid_t, libc::SIGKILL);
    }
    #[cfg(windows)]
    {
        use std::os::windows::process::CommandExt;
        let taskkill = std::env::var_os("SystemRoot")
            .map_or_else(|| PathBuf::from("taskkill.exe"), |r| PathBuf::from(r).join(r"System32\taskkill.exe"));
        let _ = Command::new(taskkill)
            .args(["/T", "/F", "/PID", &child.id().to_string()])
            .stdin(std::process::Stdio::null())
            .stdout(std::process::Stdio::null())
            .stderr(std::process::Stdio::null())
            .creation_flags(0x0800_0000)
            .status();
    }
    let _ = child.kill();
}

/// The plugin context methods the plugin needs (NousResearch/hermes-agent#143310), wherever in `hermes_cli` they are.
const APIS: [&str; 3] = ["def session_key(self", "def is_interrupted(self", "def session_supports_async_delivery(self"];

fn has_apis(source: &Path) -> bool {
    let Ok(files) = std::fs::read_dir(source.join("hermes_cli")) else { return false };
    let code: String = files
        .flatten()
        .map(|f| f.path())
        .filter(|p| p.extension().is_some_and(|e| e == "py"))
        .filter_map(|p| std::fs::read_to_string(p).ok())
        .collect();
    APIS.iter().all(|api| code.contains(api))
}

fn supported() -> bool {
    source().is_some_and(|s| has_apis(&s))
}

fn active_root(base: &Path) -> PathBuf {
    let active = std::fs::read_to_string(base.join("active_profile")).unwrap_or_default();
    let active = active.trim();
    if !active.is_empty() && active != "default" && active != "." && active != ".." && !active.contains(['/', '\\']) {
        let profile = base.join("profiles").join(active);
        if profile.is_dir() {
            return profile;
        }
    }
    base.to_path_buf()
}

/// A Hermes that can run the plugin, or one it is already in (so it can be updated or removed).
pub(super) fn installed() -> bool {
    (root().exists() || agent::find_bin("hermes").is_some())
        && (root().join("plugins/reason-network").exists() || supported())
}

pub(super) fn wired(_: &Path) -> bool {
    let dir = root().join("plugins/reason-network");
    std::fs::read_to_string(dir.join("__init__.py")).is_ok_and(|s| s == PLUGIN)
        && std::fs::read_to_string(dir.join("plugin.yaml")).is_ok_and(|s| s == MANIFEST)
}

pub(super) fn apply(_: &Path, remove: bool, dry: bool) -> Result<Option<Report>> {
    if !remove && !supported() {
        return Err(anyhow!(
            "this Hermes doesn't have the plugin APIs the native plugin needs yet (NousResearch/hermes-agent#143310); \
             Reason's MCP server works with it meanwhile"
        ));
    }
    apply_in(&root(), remove, dry)
}

/// Takes `remove, dry` in the order setup passes them to every agent: a dry run swapped for a removal deletes.
fn apply_in(root: &Path, remove: bool, dry: bool) -> Result<Option<Report>> {
    let dir = root.join("plugins/reason-network");
    let files = [("plugin.yaml", MANIFEST), ("__init__.py", PLUGIN), ("README.md", README)];
    let mut lines = Vec::new();
    let marker = dir.join(MARKER);
    let saved =
        std::fs::read_to_string(&marker).ok().and_then(|s| serde_json::from_str::<BTreeMap<String, String>>(&s).ok());
    let owned = saved.as_ref().is_some_and(|saved| {
        files.iter().all(|(file, _)| {
            std::fs::read(dir.join(file))
                .is_ok_and(|bytes| saved.get(*file) == Some(&blake3::hash(&bytes).to_hex().to_string()))
        })
    });
    let populated =
        files.iter().any(|(file, _)| dir.join(file).exists()) || marker.exists() || dir.join(".git").exists();
    let shown = crate::util::tilde(&dir.display().to_string());
    if populated && !owned {
        lines.push(format!("kept the existing plugin at {shown} (customized or managed by Hermes)"));
        return Ok(Some(Report { agent: "Hermes", lines, notes: Vec::new() }));
    }
    if remove {
        if owned {
            for (file, _) in files {
                if !dry {
                    std::fs::remove_file(dir.join(file))?;
                }
            }
            if !dry {
                std::fs::remove_file(&marker)?;
            }
            lines.push(format!("removed the plugin at {shown}"));
        }
    } else {
        let mut wrote = false;
        for (file, content) in files {
            wrote |= write_file(&dir.join(file), content, dry)?;
        }
        if wrote {
            lines.push(format!("installed the plugin at {shown}"));
        }
        let hashes: BTreeMap<&str, String> = files
            .iter()
            .map(|(file, content)| (*file, blake3::hash(content.as_bytes()).to_hex().to_string()))
            .collect();
        write_file(&marker, &(serde_json::to_string(&hashes)? + "\n"), dry)?;
    }
    // Said once, when something changed; a run that changes nothing says so, as the other agents do.
    let notes = if lines.is_empty() {
        lines.push(changed(&dir, false));
        Vec::new()
    } else if remove {
        vec!["disable the plugin in Hermes if it was enabled".into()]
    } else {
        vec![
            format!(
                "plugin profile: {}; enable with hermes plugins enable reason-network in this profile",
                root.display()
            ),
            "restart Hermes afterward; repeat with HERMES_HOME set for each additional profile".into(),
            "wake is off until configured; use the native plugin instead of a duplicate MCP entry".into(),
        ]
    };
    Ok(Some(Report { agent: "Hermes", lines, notes }))
}

use std::collections::BTreeMap;

#[cfg(test)]
mod tests {
    use super::*;
    fn temp() -> PathBuf {
        std::env::temp_dir().join(format!("reason-hermes-{}", ulid::Ulid::generate()))
    }

    #[cfg(unix)]
    #[test]
    fn a_hermes_that_hangs_on_version_does_not_hang_setup() {
        let sh = |script: &str| {
            let mut c = Command::new("sh");
            c.args(["-c", script]);
            c
        };
        assert_eq!(install_dir(sh("echo 'Install directory: /opt/hermes'")), Some(PathBuf::from("/opt/hermes")));
        // The line is used as soon as it's there, and what's still running is ended, including its children.
        let pid = temp();
        let started = std::time::Instant::now();
        let script = format!("sleep 30 & echo $! > {}; echo 'Install directory: /opt/hermes'; wait", pid.display());
        assert_eq!(install_dir(sh(&script)), Some(PathBuf::from("/opt/hermes")));
        assert!(started.elapsed() < std::time::Duration::from_secs(4), "{:?}", started.elapsed());
        let gone = |pid: &PathBuf| {
            let sleep: libc::pid_t = std::fs::read_to_string(pid).unwrap().trim().parse().unwrap();
            // SAFETY: signal 0 only checks that the process exists.
            (0..50).any(|_| {
                let alive = unsafe { libc::kill(sleep, 0) } == 0;
                if alive {
                    std::thread::sleep(std::time::Duration::from_millis(100));
                }
                !alive
            })
        };
        assert!(gone(&pid), "the sleep outlived the probe");
        // Nothing said: given up on after a few seconds, and ended the same way.
        let started = std::time::Instant::now();
        let script = format!("sleep 30 & echo $! > {}; wait", pid.display());
        assert_eq!(install_dir(sh(&script)), None);
        assert!(started.elapsed() < std::time::Duration::from_secs(15), "{:?}", started.elapsed());
        assert!(gone(&pid), "the sleep outlived the probe");
        let _ = std::fs::remove_file(&pid);
    }

    /// On Windows a pip or uv `hermes.exe` launcher runs Python as its child: ending the launcher alone would leave it.
    #[cfg(windows)]
    #[test]
    fn giving_up_ends_what_the_command_started() {
        let mut child = Command::new("cmd")
            .args(["/C", "ping -n 60 127.0.0.1"])
            .stdin(std::process::Stdio::null())
            .stdout(std::process::Stdio::piped())
            .spawn()
            .unwrap();
        let mut stdout = child.stdout.take().unwrap();
        let (tx, rx) = std::sync::mpsc::channel();
        std::thread::spawn(move || {
            let _ = std::io::Read::read_to_end(&mut stdout, &mut Vec::new());
            let _ = tx.send(());
        });
        std::thread::sleep(std::time::Duration::from_millis(500));
        kill_tree(&mut child);
        let _ = child.wait();
        // `ping` holds the output open until it's gone too.
        assert!(rx.recv_timeout(std::time::Duration::from_secs(10)).is_ok(), "ping outlived cmd");
    }

    #[test]
    fn install_and_remove_are_idempotent_and_never_rewrite_config() {
        let root = temp();
        std::fs::create_dir_all(&root).unwrap();
        let config = "# preserve formatting\nmodel: example\n";
        std::fs::write(root.join("config.yaml"), config).unwrap();
        let first = apply_in(&root, false, false).unwrap().unwrap();
        assert!(first.lines[0].starts_with("installed") && !first.notes.is_empty());
        // Again: one line saying so, and the notes aren't repeated.
        let again = apply_in(&root, false, false).unwrap().unwrap();
        assert!(again.lines.len() == 1 && again.lines[0].ends_with("unchanged"), "{:?}", again.lines);
        assert!(again.notes.is_empty());
        apply_in(&root, true, false).unwrap();
        assert!(!root.join("plugins/reason-network/plugin.yaml").exists());
        apply_in(&root, true, false).unwrap();
        assert_eq!(std::fs::read_to_string(root.join("config.yaml")).unwrap(), config);
        std::fs::remove_dir_all(root).unwrap();
    }
    #[test]
    fn a_customized_plugin_is_kept_whole_including_its_manifest() {
        let root = temp();
        apply_in(&root, false, false).unwrap();
        let plugin = root.join("plugins/reason-network/__init__.py");
        std::fs::write(&plugin, "# custom version\n").unwrap();
        apply_in(&root, false, false).unwrap();
        apply_in(&root, true, false).unwrap();
        assert_eq!(std::fs::read_to_string(&plugin).unwrap(), "# custom version\n");
        assert!(root.join("plugins/reason-network/plugin.yaml").exists());
        std::fs::remove_dir_all(root).unwrap();
    }
    #[test]
    fn dry_run_never_changes_an_existing_plugin_or_creates_a_profile() {
        let root = temp();
        apply_in(&root, false, true).unwrap();
        assert!(!root.exists());
        apply_in(&root, false, false).unwrap();
        apply_in(&root, true, true).unwrap();
        assert!(root.join("plugins/reason-network/plugin.yaml").exists());
        std::fs::remove_dir_all(root).unwrap();
    }
    #[test]
    fn active_named_profiles_are_selected_without_allowing_path_traversal() {
        let root = temp();
        let profile = root.join("profiles/work");
        std::fs::create_dir_all(&profile).unwrap();
        std::fs::write(root.join("active_profile"), "work\n").unwrap();
        assert_eq!(active_root(&root), profile);
        // A name that leads out of `profiles` is refused, even where it leads to a real folder.
        std::fs::create_dir_all(root.join("other")).unwrap();
        std::fs::write(root.join("active_profile"), "../other").unwrap();
        assert_eq!(active_root(&root), root);
        std::fs::write(root.join("active_profile"), "..").unwrap();
        assert_eq!(active_root(&root), root);
        std::fs::remove_dir_all(root).unwrap();
    }
    #[tokio::test]
    async fn setup_dry_runs_change_nothing_and_its_flags_reach_hermes_the_right_way_round() {
        let home = temp();
        // A Hermes with the plugin APIs, as its installer lays it out.
        let cli = home.join("hermes-agent/hermes_cli");
        std::fs::create_dir_all(&cli).unwrap();
        std::fs::write(cli.join("plugin_session.py"), APIS.map(|a| format!("{a}): ...\n")).concat()).unwrap();
        TEST_HOME.with(|h| *h.borrow_mut() = Some(home.clone()));
        let plugin = home.join("plugins/reason-network/__init__.py");
        let (exe, hermes) = (Path::new("/reason-network"), &["hermes"][..]);
        // Through setup's own dispatch, as `setup`, `--dry-run` and `--remove` run it.
        super::super::apply(exe, hermes, &[], None, true).await;
        assert!(!plugin.exists(), "a dry run installed");
        super::super::apply(exe, hermes, &[], None, false).await;
        assert!(plugin.exists());
        super::super::apply(exe, &[], hermes, None, true).await;
        assert!(plugin.exists(), "a dry run removed");
        super::super::apply(exe, &[], hermes, None, false).await;
        assert!(!plugin.exists());
        TEST_HOME.with(|h| h.borrow_mut().take());
        std::fs::remove_dir_all(home).unwrap();
    }

    #[test]
    fn only_a_hermes_with_the_plugin_apis_counts_as_supported() {
        let source = temp();
        let cli = source.join("hermes_cli");
        std::fs::create_dir_all(&cli).unwrap();
        // Released Hermes: session_cwd and session_surface, but no routing key or cancellation.
        std::fs::write(cli.join("plugins.py"), "class PluginContext:\n    def session_cwd(self) -> str: ...\n")
            .unwrap();
        assert!(!has_apis(&source));
        // With the APIs, in whichever module they live.
        std::fs::write(
            cli.join("plugin_session.py"),
            "class M:\n    def session_key(self) -> str: ...\n    def is_interrupted(self) -> bool: ...\n    \
             def session_supports_async_delivery(self) -> bool: ...\n",
        )
        .unwrap();
        assert!(has_apis(&source));
        assert!(!has_apis(&source.join("missing")));
        std::fs::remove_dir_all(source).unwrap();
    }
}