Skip to content

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

Rust
13.4 KB
Raw Blame
//! Hermes Agent lifecycle payloads, shaped before the native hook spools them.
//!
//! Hermes runs every configured shell hook with one stdin envelope
//! (`agent/shell_hooks.py`, v0.22.2): `hook_event_name`, `tool_name`,
//! `tool_input`, `session_id`, `cwd`, `profile`, and an `extra` object holding
//! every other keyword argument of the event. The tool events already parse as
//! sent. The lifecycle events do not, and two of them carry more than
//! ai-memory may keep:
//!
//! - `pre_llm_call` puts the prompt in `extra.user_message`, a string or a list
//!   of content parts, next to `extra.conversation_history`, the whole
//!   conversation so far. Only the prompt's text is kept.
//! - `on_session_finalize` names the ending session in `session_id`. A gateway
//!   `/new` also sends `extra.old_session_id` and `extra.new_session_id`
//!   (`gateway/slash_commands_session.py`). Only the ending id is kept, so the
//!   session that has just begun cannot be closed by it.
//! - `on_session_start` and `on_session_end`, which Hermes fires at the end of
//!   every turn rather than at session end, carry nothing stored beyond the
//!   session id.
//!
//! A `delegate_task` child is its own Hermes agent with its own session, and
//! it fires the same lifecycle events (`tools/delegate_tool.py`). Its
//! `parent_session_id` never reaches the payload: Hermes keeps it at the top
//! level only as a `session_id` fallback. `extra.platform` is the one marker.
//!
//! Hook reference: <https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks>.

use serde_json::{Map, Value};

use crate::payload::HookEvent;

/// Part types Hermes itself drops when it flattens message content
/// (`agent/message_content.py`).
const NON_TEXT_PART_TYPES: [&str; 5] =
    ["image", "image_url", "input_image", "audio", "input_audio"];

/// Keys Hermes reads a text part's text from, in its order.
const TEXT_PART_KEYS: [&str; 5] = [
    "text",
    "content",
    "input_text",
    "output_text",
    "summary_text",
];

/// The `platform` Hermes gives a delegated child agent.
const DELEGATED_CHILD_PLATFORM: &str = "subagent";

/// Whether a Hermes lifecycle payload comes from a delegated child agent. A
/// child starts with no history, so its first `pre_llm_call` also reports
/// `is_first_turn`, and its `user_message` is the goal the parent model
/// wrote, not a user prompt.
#[must_use]
pub fn hermes_is_delegated_child(raw: &Value) -> bool {
    raw.pointer("/extra/platform")
        .and_then(Value::as_str)
        .is_some_and(|platform| platform.trim() == DELEGATED_CHILD_PLATFORM)
}

/// Whether a Hermes `pre_llm_call` payload is the first turn of its session.
/// Hermes sets `extra.is_first_turn` when the turn starts with no prior
/// history (`agent/turn_context.py`); a resumed session never sets it.
#[must_use]
pub fn hermes_is_first_turn(raw: &Value) -> bool {
    raw.pointer("/extra/is_first_turn").and_then(Value::as_bool) == Some(true)
}

/// Replace a Hermes lifecycle payload with the fields ai-memory stores, in the
/// shape the router reads. Returns whether the payload changed; tool events and
/// non-object payloads are left alone.
pub fn shape_hermes_lifecycle_body(raw: &mut Value, event: HookEvent) -> bool {
    if !matches!(
        event,
        HookEvent::SessionStart | HookEvent::UserPrompt | HookEvent::Stop | HookEvent::SessionEnd
    ) || !raw.is_object()
    {
        return false;
    }
    let extra = raw.get("extra").and_then(Value::as_object);
    let extra_string = |key: &str| {
        extra
            .and_then(|extra| extra.get(key))
            .and_then(Value::as_str)
            .filter(|value| !value.trim().is_empty())
    };
    let mut shaped = Map::new();
    for key in ["hook_event_name", "cwd"] {
        if let Some(value) = raw.get(key).and_then(Value::as_str) {
            shaped.insert(key.into(), value.into());
        }
    }
    let session_id = match event {
        HookEvent::SessionEnd => extra_string("old_session_id"),
        _ => None,
    }
    .or_else(|| {
        raw.get("session_id")
            .and_then(Value::as_str)
            .filter(|value| !value.trim().is_empty())
    });
    if let Some(session_id) = session_id {
        shaped.insert("session_id".into(), session_id.into());
    }
    match event {
        HookEvent::SessionStart => {
            if let Some(model) = extra_string("model") {
                shaped.insert("model".into(), model.into());
            }
        }
        HookEvent::UserPrompt => {
            if let Some(prompt) = extra
                .and_then(|extra| extra.get("user_message"))
                .and_then(prompt_text)
            {
                shaped.insert("prompt".into(), prompt.into());
            }
        }
        HookEvent::SessionEnd => {
            if let Some(reason) = extra_string("reason") {
                shaped.insert("reason".into(), reason.into());
            }
        }
        _ => {}
    }
    *raw = Value::Object(shaped);
    true
}

/// The visible text of `extra.user_message`, flattened the way Hermes does
/// it: a string as is, a list joined by line, and image or audio parts
/// dropped.
fn prompt_text(message: &Value) -> Option<String> {
    let text = match message {
        Value::Array(parts) => parts
            .iter()
            .filter_map(part_text)
            .filter(|text| !text.is_empty())
            .collect::<Vec<_>>()
            .join("\n"),
        other => part_text(other)?.to_owned(),
    };
    (!text.trim().is_empty()).then_some(text)
}

fn part_text(part: &Value) -> Option<&str> {
    match part {
        Value::String(text) => Some(text),
        Value::Object(fields) => {
            let kind = fields
                .get("type")
                .and_then(Value::as_str)
                .map(|kind| kind.trim().to_ascii_lowercase());
            if kind.is_some_and(|kind| NON_TEXT_PART_TYPES.contains(&kind.as_str())) {
                return None;
            }
            TEXT_PART_KEYS
                .iter()
                .find_map(|key| fields.get(*key).and_then(Value::as_str))
        }
        _ => None,
    }
}

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

    fn pre_llm_call(user_message: Value) -> Value {
        json!({
            "hook_event_name": "pre_llm_call",
            "tool_name": null,
            "tool_input": null,
            "session_id": "hermes-session",
            "cwd": "/home/alice",
            "profile": "default",
            "extra": {
                "task_id": "task-1",
                "turn_id": "turn-1",
                "user_message": user_message,
                "conversation_history": [
                    {"role": "user", "content": "HISTORY_SENTINEL earlier prompt"},
                    {"role": "assistant", "content": "HISTORY_SENTINEL earlier answer"}
                ],
                "is_first_turn": false,
                "model": "hermes-4",
                "platform": "cli",
                "sender_id": ""
            }
        })
    }

    #[test]
    fn prompt_keeps_the_user_message_and_never_the_history() {
        let mut raw = pre_llm_call(json!("fix the flaky test"));
        assert!(shape_hermes_lifecycle_body(&mut raw, HookEvent::UserPrompt));
        assert_eq!(
            raw,
            json!({
                "hook_event_name": "pre_llm_call",
                "cwd": "/home/alice",
                "session_id": "hermes-session",
                "prompt": "fix the flaky test"
            })
        );
        assert!(!raw.to_string().contains("HISTORY_SENTINEL"));
        assert_eq!(
            crate::payload::user_prompt_text(&raw).as_deref(),
            Some("fix the flaky test")
        );
    }

    #[test]
    fn prompt_content_parts_keep_only_their_text() {
        let mut raw = pre_llm_call(json!([
            {"type": "text", "text": "describe this"},
            {"type": "image_url", "image_url": {"url": "data:image/png;base64,SECRETPIXELS"}},
            {"type": "input_audio", "input_audio": {"data": "AUDIOBYTES"}},
            "and this",
            {"type": "input_text", "input_text": "plus that"}
        ]));
        assert!(shape_hermes_lifecycle_body(&mut raw, HookEvent::UserPrompt));
        assert_eq!(raw["prompt"], "describe this\nand this\nplus that");
        let text = raw.to_string();
        assert!(!text.contains("SECRETPIXELS") && !text.contains("AUDIOBYTES"));
    }

    #[test]
    fn a_prompt_without_text_stores_no_prompt_field() {
        for message in [
            json!([{"type": "image_url", "image_url": {"url": "https://x/y.png"}}]),
            json!("   "),
            json!(null),
            json!(42),
        ] {
            let mut raw = pre_llm_call(message.clone());
            assert!(shape_hermes_lifecycle_body(&mut raw, HookEvent::UserPrompt));
            assert!(raw.get("prompt").is_none(), "{message}");
            assert!(raw.get("extra").is_none(), "{message}");
        }
    }

    #[test]
    fn first_turn_comes_only_from_a_true_flag() {
        let mut raw = pre_llm_call(json!("hi"));
        assert!(!hermes_is_first_turn(&raw));
        raw["extra"]["is_first_turn"] = json!(true);
        assert!(hermes_is_first_turn(&raw));
        raw["extra"]["is_first_turn"] = json!("true");
        assert!(!hermes_is_first_turn(&raw), "only a JSON boolean counts");
        assert!(!hermes_is_first_turn(&json!({"is_first_turn": true})));
    }

    /// Hermes sends `platform` "subagent" for a `delegate_task` child and the
    /// session's own platform otherwise; `parent_session_id` never arrives.
    #[test]
    fn delegated_child_comes_only_from_the_subagent_platform() {
        let mut raw = pre_llm_call(json!("hi"));
        assert!(!hermes_is_delegated_child(&raw));
        raw["extra"]["platform"] = json!("subagent");
        assert!(hermes_is_delegated_child(&raw));
        for platform in [
            json!("telegram"),
            json!(""),
            json!(null),
            json!(["subagent"]),
        ] {
            raw["extra"]["platform"] = platform.clone();
            assert!(!hermes_is_delegated_child(&raw), "{platform}");
        }
        assert!(!hermes_is_delegated_child(&json!({"platform": "subagent"})));
    }

    #[test]
    fn finalize_closes_the_ending_session_never_the_new_one() {
        let mut raw = json!({
            "hook_event_name": "on_session_finalize",
            "session_id": "old-session",
            "cwd": "/srv/gateway",
            "extra": {
                "platform": "telegram",
                "reason": "new_session",
                "old_session_id": "old-session",
                "new_session_id": "new-session"
            }
        });
        assert!(shape_hermes_lifecycle_body(&mut raw, HookEvent::SessionEnd));
        assert_eq!(
            raw,
            json!({
                "hook_event_name": "on_session_finalize",
                "cwd": "/srv/gateway",
                "session_id": "old-session",
                "reason": "new_session"
            })
        );
        assert!(!raw.to_string().contains("new-session"));

        // A top-level id that disagrees still loses to the ending id.
        let mut raw = json!({
            "session_id": "new-session",
            "extra": {"old_session_id": "old-session", "new_session_id": "new-session"}
        });
        shape_hermes_lifecycle_body(&mut raw, HookEvent::SessionEnd);
        assert_eq!(raw["session_id"], "old-session");

        // The CLI's shutdown finalize carries only `session_id`.
        let mut raw = json!({
            "session_id": "cli-session",
            "extra": {"platform": "cli", "reason": "shutdown"}
        });
        shape_hermes_lifecycle_body(&mut raw, HookEvent::SessionEnd);
        assert_eq!(
            raw,
            json!({"session_id": "cli-session", "reason": "shutdown"})
        );
    }

    #[test]
    fn session_start_and_turn_end_keep_only_identity() {
        let mut start = json!({
            "hook_event_name": "on_session_start",
            "session_id": "s",
            "cwd": "/w",
            "profile": "default",
            "extra": {"model": "hermes-4", "platform": "cli", "telemetry_schema_version": 1}
        });
        assert!(shape_hermes_lifecycle_body(
            &mut start,
            HookEvent::SessionStart
        ));
        assert_eq!(
            start,
            json!({"hook_event_name": "on_session_start", "cwd": "/w", "session_id": "s", "model": "hermes-4"})
        );

        let mut turn_end = json!({
            "hook_event_name": "on_session_end",
            "session_id": "s",
            "cwd": "/w",
            "extra": {"completed": true, "turn_exit_reason": "done", "task_id": "t"}
        });
        assert!(shape_hermes_lifecycle_body(&mut turn_end, HookEvent::Stop));
        assert_eq!(
            turn_end,
            json!({"hook_event_name": "on_session_end", "cwd": "/w", "session_id": "s"})
        );
    }

    #[test]
    fn tool_events_are_left_as_sent() {
        let original = json!({
            "hook_event_name": "post_tool_call",
            "tool_name": "terminal",
            "tool_input": {"command": "ls"},
            "session_id": "s",
            "cwd": "/w",
            "extra": {"result": "ok", "status": "ok"}
        });
        for event in [HookEvent::PreToolUse, HookEvent::PostToolUse] {
            let mut raw = original.clone();
            assert!(!shape_hermes_lifecycle_body(&mut raw, event));
            assert_eq!(raw, original);
        }
        let mut not_object = json!(["x"]);
        assert!(!shape_hermes_lifecycle_body(
            &mut not_object,
            HookEvent::UserPrompt
        ));
    }
}