Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

24.2 KB
Raw Blame
//! Bounded installed-source capability inspection; no native command, plugin or helper runs.
use hiroute_domain::CanonicalDigest;
use std::path::{Path, PathBuf};

mod managed_runtime;

pub struct HermesSupportFacts {
    pub version: String,
    pub middleware: bool,
    pub skills: bool,
    pub shell: bool,
    pub chat_sdk: bool,
    pub responses_sdk: bool,
    pub messages_sdk: bool,
    pub dependency_digest: CanonicalDigest,
}

pub fn hermes_support_facts() -> HermesSupportFacts {
    let home = std::env::var_os("HOME").map(PathBuf::from);
    let executable = selected_hermes_executable(
        super::executable::resolve(Path::new("hermes")),
        home.as_deref(),
    );
    inspect_installation(executable)
}

fn selected_hermes_executable(
    primary: Result<Option<PathBuf>, super::executable::ProbeFailure>,
    home: Option<&Path>,
) -> Option<PathBuf> {
    match primary {
        Ok(Some(path)) => Some(path),
        // A broken selected command cannot be replaced by an unrelated installation.
        Err(_) => None,
        Ok(None) => super::executable::resolve(
            &home
                .filter(|home| home.is_absolute())?
                .join(".hermes-bundle/venv/bin/hermes"),
        )
        .ok()
        .flatten(),
    }
}

fn inspect_installation(executables: impl IntoIterator<Item = PathBuf>) -> HermesSupportFacts {
    let mut roots = Vec::new();
    let mut interpreters = Vec::new();
    for executable in executables {
        let Some((executable, text)) = selected_launcher(&executable) else {
            continue;
        };
        if let Some(parent) = executable.parent() {
            roots.push(parent.to_path_buf());
            if let Some(p) = parent.parent() {
                roots.push(p.to_path_buf());
            }
        }
        // Installed console scripts and the official shell launcher expose literal Python/
        // project locations. Read only those locations; never evaluate launcher text or env.
        for word in
            text.split(|c: char| c.is_whitespace() || matches!(c, '"' | '\'' | '(' | ')' | ','))
        {
            let raw = word.strip_prefix("#!").unwrap_or(word);
            let path = Path::new(raw);
            if !path.is_absolute() || raw.contains(['$', '`', '\0']) {
                continue;
            }
            // PM launchers embed the source directory itself, rather than a script in it.
            roots.push(path.to_path_buf());
            if path
                .file_name()
                .and_then(|name| name.to_str())
                .is_some_and(|name| name.starts_with("python"))
            {
                interpreters.push(path.to_path_buf());
            }
            let mut ancestor = path.parent();
            for _ in 0..4 {
                let Some(parent) = ancestor else {
                    break;
                };
                roots.push(parent.to_path_buf());
                ancestor = parent.parent();
            }
        }
        // Native execution selects the first executable on PATH, not another installation
        // discovered later merely because its interfaces would pass.
        break;
    }
    let sdk_paths = python_package_paths(&interpreters);
    roots.extend(sdk_paths.iter().cloned());
    roots.extend(editable_source_roots(&sdk_paths));
    roots.sort();
    roots.dedup();
    for root in roots.into_iter().take(256) {
        let plugins =
            bounded_text(&root.join("hermes_cli/plugins.py"), 2 * 1024 * 1024).unwrap_or_default();
        let middleware = bounded_text(&root.join("hermes_cli/middleware.py"), 2 * 1024 * 1024)
            .unwrap_or_default();
        let skill_source =
            bounded_text(&root.join("tools/skills_tool.py"), 2 * 1024 * 1024).unwrap_or_default();
        if plugins.is_empty() && middleware.is_empty() && skill_source.is_empty() {
            continue;
        }
        let selected_sdk_paths =
            managed_runtime::sdk_paths(&root, &interpreters).unwrap_or_else(|| sdk_paths.clone());
        let sdk = inspect_sdks(&selected_sdk_paths);
        let shell_source =
            bounded_text(&root.join("tools/terminal_tool.py"), 2 * 1024 * 1024).unwrap_or_default();
        let shell =
            shell_source.contains("def terminal_tool(") && shell_source.contains("terminal");
        let calls = ["agent/turn_api_request.py", "agent/conversation_loop.py"]
            .into_iter()
            .filter_map(|p| bounded_text(&root.join(p), 2 * 1024 * 1024))
            .collect::<Vec<_>>();
        let valid_call = calls.iter().any(|call| {
            let compact: String = call.chars().filter(|c| !c.is_whitespace()).collect();
            compact.contains("apply_llm_request_middleware(")
                && [
                    "session_id=agent.session_id",
                    "model=agent.model",
                    "provider=agent.provider",
                    "base_url=agent.base_url",
                    "api_mode=agent.api_mode",
                ]
                .iter()
                .all(|field| compact.contains(field))
        });
        let config =
            bounded_text(&root.join("hermes_cli/config.py"), 2 * 1024 * 1024).unwrap_or_default();
        let supported = config.contains("def load_config_readonly(")
            && plugins.contains("def register_middleware(")
            && plugins.contains("plugins")
            && middleware.contains("def apply_llm_request_middleware(")
            && valid_call;
        let skill_source =
            bounded_text(&root.join("tools/skills_tool.py"), 2 * 1024 * 1024).unwrap_or_default();
        let skills = skill_source.contains("def _skills_dir(")
            && skill_source.contains("get_hermes_home() / \"skills\"");
        let project = bounded_text(&root.join("pyproject.toml"), 128 * 1024).unwrap_or_default();
        let version = project
            .lines()
            .find_map(|line| {
                let (k, v) = line.trim().split_once('=')?;
                (k.trim() == "version").then(|| v.trim().trim_matches('"').to_owned())
            })
            .unwrap_or_else(|| "unknown".into());
        // Preserve the existing dependency digest inputs for accepted-operation continuity.
        // These optional upstream replay sources do not determine plugin admission.
        let replay = [
            "agent/message_sanitization.py",
            "agent/reasoning_params.py",
            "agent/agent_runtime_helpers.py",
        ]
        .map(|path| bounded_text(&root.join(path), 2 * 1024 * 1024).unwrap_or_default());
        let dependency_digest = CanonicalDigest::of(&(
            "hermes-native-interfaces/v3",
            &sdk.digest,
            CanonicalDigest::of_bytes(plugins.as_bytes()),
            CanonicalDigest::of_bytes(middleware.as_bytes()),
            calls
                .iter()
                .map(|v| CanonicalDigest::of_bytes(v.as_bytes()))
                .collect::<Vec<_>>(),
            CanonicalDigest::of_bytes(config.as_bytes()),
            CanonicalDigest::of_bytes(skill_source.as_bytes()),
            replay.map(|source| CanonicalDigest::of_bytes(source.as_bytes())),
        ))
        .expect("bounded native proof is serializable");
        return HermesSupportFacts {
            version,
            middleware: supported,
            skills,
            shell,
            chat_sdk: sdk.chat,
            responses_sdk: sdk.responses,
            messages_sdk: sdk.messages,
            dependency_digest,
        };
    }
    HermesSupportFacts {
        version: "unknown".into(),
        middleware: false,
        skills: false,
        shell: false,
        chat_sdk: false,
        responses_sdk: false,
        messages_sdk: false,
        dependency_digest: CanonicalDigest::of_bytes(b"hermes-native-interfaces/unavailable"),
    }
}

/// Follow only a literal, argument-preserving Hermes launcher handoff. Never run shell text.
fn selected_launcher(executable: &Path) -> Option<(PathBuf, String)> {
    let mut selected = super::executable::resolve(executable).ok()??;
    let mut visited = Vec::new();
    for _ in 0..4 {
        if visited.contains(&selected) {
            return None;
        }
        visited.push(selected.clone());
        let text = bounded_text(&selected, 64 * 1024)?;
        let handoff = text.lines().find_map(|line| {
            let command = line.strip_prefix("exec ")?.strip_suffix(" \"$@\"")?;
            let path = command.trim_matches(['\'', '"']);
            let candidate = Path::new(path);
            (candidate.is_absolute()
                && candidate.file_name().is_some_and(|name| name == "hermes")
                && !path.contains(['$', '`', '\0']))
            .then_some(candidate.to_path_buf())
        });
        let Some(next) = handoff else {
            return Some((selected, text));
        };
        selected = super::executable::resolve(&next).ok()??;
    }
    None
}

fn bounded_text(path: &Path, bound: u64) -> Option<String> {
    let metadata = std::fs::symlink_metadata(path).ok()?;
    if !metadata.is_file() || metadata.len() > bound {
        return None;
    }
    std::fs::read_to_string(path).ok()
}

/// Follow only the literal launcher's interpreter installation. No imports or environment search.
fn python_package_paths(interpreters: &[PathBuf]) -> Vec<PathBuf> {
    let mut packages = Vec::new();
    for interpreter in interpreters.iter().take(8) {
        let Some(prefix) = interpreter.parent().and_then(Path::parent) else {
            continue;
        };
        for library in ["lib", "lib64"] {
            let Ok(versions) = std::fs::read_dir(prefix.join(library)) else {
                continue;
            };
            for version in versions.take(32).flatten() {
                let name = version.file_name();
                if !name.to_string_lossy().starts_with("python3.") {
                    continue;
                }
                for directory in ["site-packages", "dist-packages"] {
                    let path = version.path().join(directory);
                    if path.is_dir() {
                        packages.push(path);
                    }
                }
            }
        }
    }
    packages.sort();
    packages.dedup();
    packages
}

/// PEP 610 installation metadata locates editable sources without importing their finder.
fn editable_source_roots(paths: &[PathBuf]) -> Vec<PathBuf> {
    let mut roots = Vec::new();
    for site in paths.iter().take(32) {
        let Ok(entries) = std::fs::read_dir(site) else {
            continue;
        };
        for entry in entries.take(4096).flatten() {
            let name = entry.file_name();
            let name = name.to_string_lossy();
            if !name.starts_with("hermes_agent-") || !name.ends_with(".dist-info") {
                continue;
            }
            let Some(metadata) = bounded_text(&entry.path().join("direct_url.json"), 16 * 1024)
            else {
                continue;
            };
            let Ok(value) = serde_json::from_str::<serde_json::Value>(&metadata) else {
                continue;
            };
            if value["dir_info"]["editable"] != true {
                continue;
            }
            let Some(url) = value["url"]
                .as_str()
                .and_then(|url| reqwest::Url::parse(url).ok())
            else {
                continue;
            };
            if url.scheme() != "file" || url.query().is_some() || url.fragment().is_some() {
                continue;
            }
            if let Ok(root) = url.to_file_path()
                && root.is_absolute()
                && root.is_dir()
            {
                roots.push(root);
            }
        }
    }
    roots
}
struct HermesSdkSupport {
    chat: bool,
    responses: bool,
    messages: bool,
    digest: CanonicalDigest,
}

fn inspect_sdks(paths: &[PathBuf]) -> HermesSdkSupport {
    let mut chat = false;
    let mut responses = false;
    let mut messages = false;
    let mut evidence = Vec::new();
    for path in paths {
        for (package, resource, protocol) in [
            (
                "openai",
                "resources/chat/completions/completions.py",
                "chat",
            ),
            ("openai", "resources/responses/responses.py", "responses"),
            ("anthropic", "resources/messages/messages.py", "messages"),
        ] {
            let module = path.join(package).join(resource);
            let source = bounded_text(&module, 2 * 1024 * 1024);
            let supported = source.as_ref().is_some_and(|source| {
                source.contains("def create(") && source.contains("extra_headers:")
            });
            evidence.push((
                module,
                source
                    .as_ref()
                    .map(|source| CanonicalDigest::of_bytes(source.as_bytes())),
            ));
            if protocol == "chat" {
                chat |= supported;
            } else if protocol == "responses" {
                responses |= supported;
            } else {
                messages |= supported;
            }
        }
    }
    HermesSdkSupport {
        chat,
        responses,
        messages,
        digest: CanonicalDigest::of(&("hermes-selected-sdk-interfaces/v2", evidence))
            .expect("bounded sdk evidence"),
    }
}

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

    #[cfg(unix)]
    #[test]
    fn hermes_packaged_installation_is_inspected_without_running_its_launcher() {
        use std::os::unix::fs::PermissionsExt;
        let home = tempfile::tempdir().unwrap();
        let prefix = home.path().join(".hermes-bundle/venv");
        let executable = prefix.join("bin/hermes");
        std::fs::create_dir_all(executable.parent().unwrap()).unwrap();
        let sentinel = home.path().join("must-not-execute");
        std::fs::write(
            &executable,
            format!(
                "#!{}\nraise RuntimeError({:?})\n",
                prefix.join("bin/python3").display(),
                sentinel
            ),
        )
        .unwrap();
        std::fs::set_permissions(&executable, std::fs::Permissions::from_mode(0o700)).unwrap();
        let site = prefix.join("lib/python3.13/site-packages");
        for (file, text) in [
            ("hermes_cli/plugins.py", "plugins\ndef register_middleware("),
            (
                "hermes_cli/middleware.py",
                "def apply_llm_request_middleware(",
            ),
            ("hermes_cli/config.py", "def load_config_readonly("),
            (
                "agent/turn_api_request.py",
                "apply_llm_request_middleware(session_id=agent.session_id, model=agent.model, provider=agent.provider, base_url=agent.base_url, api_mode=agent.api_mode)",
            ),
            (
                "tools/skills_tool.py",
                "def _skills_dir(\nget_hermes_home() / \"skills\"",
            ),
            (
                "openai/resources/chat/completions/completions.py",
                "def create(self, *, extra_headers: dict): pass",
            ),
        ] {
            let path = site.join(file);
            std::fs::create_dir_all(path.parent().unwrap()).unwrap();
            std::fs::write(path, text).unwrap();
        }
        let selected = selected_hermes_executable(Ok(None), Some(home.path())).unwrap();
        assert_eq!(selected, executable.canonicalize().unwrap());
        let support = inspect_installation([selected]);
        assert!(support.middleware && support.skills && support.chat_sdk);
        assert!(!support.responses_sdk && !support.messages_sdk);
        assert!(!sentinel.exists());
        // Preserve first-command selection, even if another package would pass inspection.
        let first = home.path().join("selected/hermes");
        assert_eq!(
            selected_hermes_executable(Ok(Some(first.clone())), Some(home.path())),
            Some(first)
        );
        assert!(
            selected_hermes_executable(
                Err(super::super::executable::ProbeFailure::NotExecutable),
                Some(home.path())
            )
            .is_none()
        );
    }

    #[test]
    fn chat_sdk_headers_are_required_independently_of_other_transports() {
        let prefix = tempfile::tempdir().unwrap();
        let site = prefix.path();
        let chat = site.join("openai/resources/chat/completions/completions.py");
        std::fs::create_dir_all(chat.parent().unwrap()).unwrap();
        std::fs::write(&chat, "def create(self): pass\n").unwrap();
        let missing = inspect_sdks(&[site.to_path_buf()]);
        assert!(!missing.chat && !missing.responses && !missing.messages);
        std::fs::write(&chat, "def create(self, *, extra_headers: dict): pass\n").unwrap();
        let supported = inspect_sdks(&[site.to_path_buf()]);
        assert!(supported.chat && !supported.responses && !supported.messages);
        assert_ne!(missing.digest, supported.digest);
        std::fs::remove_file(chat).unwrap();
        assert!(!inspect_sdks(&[site.to_path_buf()]).chat);
    }

    #[test]
    fn editable_source_locator_uses_only_selected_local_install_metadata() {
        let root = tempfile::tempdir().unwrap();
        let site = root.path().join("site");
        let info = site.join("hermes_agent-0.19.1.dist-info");
        std::fs::create_dir_all(&info).unwrap();
        let source = root.path().join("native source");
        std::fs::create_dir(&source).unwrap();
        let metadata = info.join("direct_url.json");
        let url = reqwest::Url::from_directory_path(&source).unwrap();
        for (url, editable, expected) in [
            (url.as_str(), true, vec![source.clone()]),
            (url.as_str(), false, vec![]),
            ("https://example.invalid/hermes", true, vec![]),
            ("file://remote.example.invalid/native", true, vec![]),
        ] {
            std::fs::write(
                &metadata,
                serde_json::to_vec(&serde_json::json!({
                "url":url,"dir_info":{"editable":editable}}))
                .unwrap(),
            )
            .unwrap();
            assert_eq!(editable_source_roots(std::slice::from_ref(&site)), expected);
        }
        std::fs::write(&metadata, "import forbidden_native_code").unwrap();
        assert!(editable_source_roots(&[site]).is_empty());
    }

    #[test]
    fn selected_interpreter_sdks_are_protocol_specific_and_digest_bound() {
        let prefix = tempfile::tempdir().unwrap();
        let site = prefix.path().join("lib/python3.11/site-packages");
        let responses = site.join("openai/resources/responses/responses.py");
        std::fs::create_dir_all(responses.parent().unwrap()).unwrap();
        std::fs::write(
            &responses,
            "def create(self, *, extra_headers: dict):\n    pass\n",
        )
        .unwrap();
        let paths = python_package_paths(&[prefix.path().join("bin/python")]);
        assert_eq!(paths, vec![site.clone()]);
        let first = inspect_sdks(&paths);
        assert!(first.responses);
        assert!(!first.messages);
        let messages = site.join("anthropic/resources/messages/messages.py");
        std::fs::create_dir_all(messages.parent().unwrap()).unwrap();
        std::fs::write(&messages, "def create(self):\n    pass\n").unwrap();
        let without_headers = inspect_sdks(&paths);
        assert!(!without_headers.messages);
        assert_ne!(first.digest, without_headers.digest);
        std::fs::write(
            &messages,
            "def create(self, *, extra_headers: dict):\n    pass\n",
        )
        .unwrap();
        let both = inspect_sdks(&paths);
        assert!(both.responses && both.messages);
        assert_ne!(both.digest, without_headers.digest);
        std::fs::remove_file(responses).unwrap();
        let messages_only = inspect_sdks(&paths);
        assert!(!messages_only.responses && messages_only.messages);
        assert_ne!(both.digest, messages_only.digest);
    }

    #[cfg(unix)]
    #[test]
    fn pm_launcher_inspects_only_its_committed_environment_without_execution() {
        use std::os::unix::fs::PermissionsExt;
        let temporary = tempfile::tempdir().unwrap();
        let project = temporary.path().join("native");
        let owner = temporary.path().join("profile");
        let python = owner.join("tools/python-native/bin/python3");
        let executable = project.join(".hermes/bin/hermes");
        let sentinel = temporary.path().join("must-not-execute");
        let write = |path: &Path, text: &str| {
            std::fs::create_dir_all(path.parent().unwrap()).unwrap();
            std::fs::write(path, text).unwrap();
        };
        write(&python, "#!/bin/sh\nexit 97\n");
        write(
            &executable,
            &format!(
                "#!/bin/sh\ntouch '{}'\nexec {} -I -c 'import sys; sys.path.insert(0, \"{}\")'\n",
                sentinel.display(),
                python.display(),
                project.display(),
            ),
        );
        std::fs::set_permissions(&executable, std::fs::Permissions::from_mode(0o700)).unwrap();
        for (file, text) in [
            ("hermes_cli/plugins.py", "plugins\ndef register_middleware("),
            (
                "hermes_cli/middleware.py",
                "def apply_llm_request_middleware(",
            ),
            ("hermes_cli/config.py", "def load_config_readonly("),
            (
                "agent/turn_api_request.py",
                "apply_llm_request_middleware(session_id=agent.session_id, model=agent.model, provider=agent.provider, base_url=agent.base_url, api_mode=agent.api_mode)",
            ),
            (
                "tools/skills_tool.py",
                "def _skills_dir(\nget_hermes_home() / \"skills\"",
            ),
            ("tools/terminal_tool.py", "def terminal_tool("),
            (
                "pm/environments.py",
                "def install_key(\ndef _recorded_venv(",
            ),
        ] {
            write(&project.join(file), text);
        }
        let canonical = project.canonicalize().unwrap();
        let key = CanonicalDigest::of_bytes(canonical.to_str().unwrap().as_bytes());
        let state = owner.join("installs").join(&key.as_str()[7..23]);
        let selected = state.join("environments/selected/venv");
        let unused = state.join("environments/unused/venv");
        let sdk = "lib/python3.14/site-packages/openai/resources/chat/completions/completions.py";
        let cfg = format!("home = {}\n", python.parent().unwrap().display());
        for environment in [&selected, &unused] {
            write(&environment.join("pyvenv.cfg"), &cfg);
            write(
                &environment.join(sdk),
                "def create(self, *, extra_headers: dict): pass",
            );
        }
        let facts = state.join("facts.json");
        let select = |environment: &Path| {
            write(&facts, &serde_json::json!({"schema": 1, "packages": {"venv": {"environment": environment}}}).to_string());
        };
        select(&selected);
        let first = inspect_installation([executable.clone()]);
        assert!(first.middleware && first.skills && first.shell && first.chat_sdk);
        let wrapper = temporary.path().join("bin/hermes");
        write(
            &wrapper,
            &format!("#!/bin/sh\nexec '{}' \"$@\"\n", executable.display()),
        );
        std::fs::set_permissions(&wrapper, std::fs::Permissions::from_mode(0o700)).unwrap();
        assert!(inspect_installation([wrapper.clone()]).chat_sdk);
        std::fs::remove_file(selected.join(sdk)).unwrap();
        let missing = inspect_installation([executable.clone()]);
        assert!(
            !missing.chat_sdk,
            "an unused generation must not supply the SDK"
        );
        assert_ne!(first.dependency_digest, missing.dependency_digest);
        select(&unused);
        assert!(inspect_installation([executable.clone()]).chat_sdk);
        let foreign = temporary.path().join("foreign");
        write(&foreign.join("pyvenv.cfg"), &cfg);
        write(
            &foreign.join(sdk),
            "def create(self, *, extra_headers: dict): pass",
        );
        select(&foreign);
        assert!(!inspect_installation([executable.clone()]).chat_sdk);
        write(&facts, "invalid JSON");
        assert!(!inspect_installation([executable]).chat_sdk);
        write(
            &wrapper,
            &format!("#!/bin/sh\nexec '{}' \"$@\"\n", wrapper.display()),
        );
        assert!(!inspect_installation([wrapper]).middleware);
        assert!(!sentinel.exists());
    }
}