Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hermes): drop delegated child lifecycle and scope gateway TERMINAL_CWD
4nrry2236a6763503
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex 7c46584b..c904b1bb 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -1000,11 +1000,30 @@ fn first_prompt_context_envelope(handoff: String) -> serde_json::Value {/// every hook process (`hermes_cli/cli_config_load.py`, `gateway/run.py`).const HERMES_TERMINAL_CWD_ENV: &str = "TERMINAL_CWD";+/// Set to "1" in a Hermes gateway process (`gateway/run.py`); hooks inherit it.+const HERMES_GATEWAY_ENV: &str = "_HERMES_GATEWAY";++/// The profile a multiplexing Hermes gateway runs as (`profiles_to_serve`).+const HERMES_GATEWAY_HOST_PROFILE: &str = "default";+/// The Hermes session's working directory, when the hook process carries one/// that exists here. A container backend can export a path that exists only/// inside the sandbox, and a relative value names nothing, so either falls/// back to the payload cwd.-fn hermes_terminal_cwd(runtime_env: &RuntimeEnv) -> Option<String> {+///+/// A multiplexing gateway serves every profile from the default profile's+/// process. Its environment holds the default profile's `terminal.cwd`, while+/// each other profile's lives in a per-turn scope its hooks never see, so in+/// a gateway the variable is trusted only for an event the default profile+/// fired. A standalone gateway of another profile loses it too: nothing in+/// the hook's environment tells it apart from a multiplexed one.+fn hermes_terminal_cwd(runtime_env: &RuntimeEnv, profile: Option<&str>) -> Option<String> {+ let in_gateway = runtime_env+ .var_os(HERMES_GATEWAY_ENV)+ .is_some_and(|value| value == "1");+ if in_gateway && profile != Some(HERMES_GATEWAY_HOST_PROFILE) {+ return None;+ }let path = PathBuf::from(runtime_env.var_os(HERMES_TERMINAL_CWD_ENV)?);if !path.is_absolute() || !path.is_dir() {return None;@@ -1132,9 +1151,26 @@ wherereturn Ok(());}};- // Read before the Hermes shaping below drops `extra`, where it lives.+ // Read before the Hermes shaping below drops `extra` and `profile`.+ // A delegated child's lifecycle belongs to the parent's session: storing+ // it would open a session nothing ever finalizes, and its first turn+ // would claim a handoff meant for the user's next session.+ let hermes_delegated_child = agent_kind == AgentKind::Hermes+ && matches!(+ hook_event,+ HookEvent::SessionStart+ | HookEvent::UserPrompt+ | HookEvent::Stop+ | HookEvent::SessionEnd+ )+ && ai_memory_hooks::hermes_is_delegated_child(&json);+ let hermes_profile = (agent_kind == AgentKind::Hermes)+ .then(|| json.get("profile").and_then(serde_json::Value::as_str))+ .flatten()+ .map(str::to_owned);let first_prompt_of_session = hook_event == HookEvent::UserPrompt&& agent_kind.first_user_prompt_injects_handoff()+ && !hermes_delegated_child&& ai_memory_hooks::hermes_is_first_turn(&json);if agent_kind == AgentKind::Hermes&& ai_memory_hooks::shape_hermes_lifecycle_body(&mut json, hook_event)@@ -1154,7 +1190,8 @@ where&json,super::install_hooks::cursor_native_hooks_installed,)- && !is_dropped_plugin_copy(&args, &json, env_lookup);+ && !is_dropped_plugin_copy(&args, &json, env_lookup)+ && !hermes_delegated_child;if !event_admits_capture && !args.check_capture {write_success_response(stdout, agent_kind, hook_event)?;return Ok(());@@ -1227,7 +1264,7 @@ where// replaces the reported cwd. A tool event can still move to another// checkout its own absolute locations prove (below).let payload_cwd = match (agent_kind == AgentKind::Hermes)- .then(|| hermes_terminal_cwd(&runtime_env))+ .then(|| hermes_terminal_cwd(&runtime_env, hermes_profile.as_deref())).flatten(){Some(cwd) => {@@ -4112,12 +4149,16 @@ mod tests {let mut args = devin_hook_args("post-tool-use");args.agent = agent.into();args.capture_mode = capture_mode;- run_with_payload(+ // An empty environment: a suite run from a Hermes terminal inherits+ // its TERMINAL_CWD, which would reroute the Hermes cases.+ run_with_payload_in_home(Some(data_dir.to_path_buf()),args,raw.to_string(),&mut Vec::new(),|_, _| panic!("a tool event below the threshold must only spool"),+ home_dir(),+ RuntimeEnv::default(),).await.unwrap();@@ -5641,7 +5682,7 @@ mod tests {"cwd": tmp.path(),"extra": {"tool_call_id": "call-42", "status": "ok"}});- run_with_payload(+ run_with_payload_in_home(Some(data_dir.clone()),args,raw.to_string(),@@ -5650,6 +5691,8 @@ mod tests {called.set(true);Ok(())},+ home_dir(),+ RuntimeEnv::default(),).await.unwrap();@@ -8161,7 +8204,6 @@ mod tests {"is_first_turn": is_first_turn,"model": "hermes-4","platform": "cli",- "parent_session_id": "","sender_id": ""})}@@ -8313,6 +8355,53 @@ mod tests {}}+ /// A `delegate_task` child runs as its own Hermes session with an empty+ /// history, so its first `pre_llm_call` reports `is_first_turn` too. It+ /// must not claim the handoff, and none of its lifecycle events may be+ /// stored as a session of its own.+ #[tokio::test]+ async fn hermes_delegated_child_lifecycle_is_neither_stored_nor_handed_off() {+ let tmp = tempfile::tempdir().unwrap();+ let data_dir = tmp.path().join("data");+ let (base, mut requests) = serve_requests("200 OK", "HERMES-HANDOFF").await;+ let mut first_turn = pre_llm_call_extra(true);+ first_turn["platform"] = "subagent".into();+ first_turn["user_message"] = "CHILD_GOAL_SENTINEL".into();+ let child = serde_json::json!({"model": "hermes-4", "platform": "subagent"});+ for (event, payload) in [+ (+ "user-prompt-submit",+ hermes_payload("pre_llm_call", tmp.path(), first_turn),+ ),+ (+ "session-start",+ hermes_payload("on_session_start", tmp.path(), child.clone()),+ ),+ (+ "stop",+ hermes_payload("on_session_end", tmp.path(), child.clone()),+ ),+ (+ "session-end",+ hermes_payload("on_session_finalize", tmp.path(), child),+ ),+ ] {+ let stdout = run_hermes(+ &data_dir,+ hermes_args(event, &base),+ payload,+ RuntimeEnv::default(),+ )+ .await;+ assert_eq!(stdout, b"{}\n", "{event}");+ }+ assert!(spooled_entries(&data_dir).is_empty());+ while let Some(request) = first_request(&mut requests).await {+ assert!(!request.starts_with("GET /handoff"), "{request}");+ assert!(!request.contains("CHILD_GOAL_SENTINEL"), "{request}");+ }+ }+/// `on_session_finalize` after a gateway `/new` names both sessions; only/// the ending one may be closed.#[tokio::test]@@ -8362,14 +8451,46 @@ mod tests {std::fs::write(&file, "x").unwrap();let dir = tmp.path().to_str().unwrap();let env = |value: &str| RuntimeEnv::with_process_env_for_tests(&[("TERMINAL_CWD", value)]);- assert_eq!(hermes_terminal_cwd(&env(dir)).as_deref(), Some(dir));- assert_eq!(hermes_terminal_cwd(&env("relative/dir")), None);+ let cwd = |env: &RuntimeEnv| hermes_terminal_cwd(env, Some("work"));+ assert_eq!(cwd(&env(dir)).as_deref(), Some(dir));+ assert_eq!(cwd(&env("relative/dir")), None);assert_eq!(- hermes_terminal_cwd(&env(&tmp.path().join("missing").to_string_lossy())),+ cwd(&env(&tmp.path().join("missing").to_string_lossy())),None);- assert_eq!(hermes_terminal_cwd(&env(&file.to_string_lossy())), None);- assert_eq!(hermes_terminal_cwd(&RuntimeEnv::default()), None);+ assert_eq!(cwd(&env(&file.to_string_lossy())), None);+ assert_eq!(cwd(&RuntimeEnv::default()), None);+ // Outside a gateway one process serves one profile, so its variable+ // holds whatever profile fired, named or not.+ assert_eq!(hermes_terminal_cwd(&env(dir), None).as_deref(), Some(dir));+ }++ /// A multiplexing gateway exports the default profile's `terminal.cwd`+ /// to every hook, whichever profile fired it. Only the default profile's+ /// events may use it there.+ #[test]+ fn hermes_gateway_terminal_cwd_belongs_to_the_default_profile_only() {+ let tmp = tempfile::tempdir().unwrap();+ let dir = tmp.path().to_str().unwrap();+ let gateway = RuntimeEnv::with_process_env_for_tests(&[+ ("TERMINAL_CWD", dir),+ ("_HERMES_GATEWAY", "1"),+ ]);+ assert_eq!(+ hermes_terminal_cwd(&gateway, Some("default")).as_deref(),+ Some(dir)+ );+ assert_eq!(hermes_terminal_cwd(&gateway, Some("work")), None);+ assert_eq!(hermes_terminal_cwd(&gateway, Some("custom")), None);+ assert_eq!(hermes_terminal_cwd(&gateway, None), None);+ let other_marker = RuntimeEnv::with_process_env_for_tests(&[+ ("TERMINAL_CWD", dir),+ ("_HERMES_GATEWAY", "0"),+ ]);+ assert_eq!(+ hermes_terminal_cwd(&other_marker, Some("work")).as_deref(),+ Some(dir)+ );}/// A gateway reports its own process cwd (here an unmarked home); the@@ -8435,6 +8556,45 @@ mod tests {}}+ /// In a multiplexing gateway the variable is the default profile's, so an+ /// event another profile fired keeps the gateway's own cwd, which+ /// allowlist mode drops, while the default profile's event is routed.+ #[tokio::test]+ async fn hermes_gateway_terminal_cwd_routes_only_the_default_profile() {+ let tmp = tempfile::tempdir().unwrap();+ let home = tmp.path().join("home");+ std::fs::create_dir_all(&home).unwrap();+ let repo = repo_with_marker(tmp.path(), "default-repo", "project = \"default-repo\"\n");+ let gateway = RuntimeEnv::with_process_env_for_tests(&[+ ("TERMINAL_CWD", repo.to_str().unwrap()),+ ("_HERMES_GATEWAY", "1"),+ ]);+ let payload = |profile: &str| {+ let mut payload: serde_json::Value = serde_json::from_str(&hermes_payload(+ "pre_llm_call",+ &home,+ pre_llm_call_extra(false),+ ))+ .unwrap();+ payload["profile"] = profile.into();+ payload.to_string()+ };+ let args = || {+ let mut args = hermes_args("user-prompt-submit", &dead_server_url());+ args.capture_mode = Some(crate::cli::CaptureModeArg::Allowlist);+ args+ };+ for (profile, spooled) in [("default", 1), ("work", 0)] {+ let data_dir = tmp.path().join(format!("data-{profile}"));+ run_hermes(&data_dir, args(), payload(profile), gateway.clone()).await;+ let entries = spooled_entries(&data_dir);+ assert_eq!(entries.len(), spooled, "{profile}");+ if let Some(entry) = entries.first() {+ assert_eq!(query_param(&entry.url, "project"), Some("default-repo"));+ }+ }+ }+/// Adversarial: `TERMINAL_CWD` selects a checkout, so that checkout's/// exclusions and server profile apply to what lands there. A relative/// read of an excluded path is dropped before the spool, a public read isdiff --git a/crates/ai-memory-hooks/src/hermes.rs b/crates/ai-memory-hooks/src/hermes.rsindex b3030f18..5dcedd78 100644--- a/crates/ai-memory-hooks/src/hermes.rs+++ b/crates/ai-memory-hooks/src/hermes.rs@@ -18,6 +18,11 @@//! 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};@@ -38,6 +43,20 @@ const TEXT_PART_KEYS: [&str; 5] = ["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.@@ -232,6 +251,26 @@ mod tests {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!({diff --git a/crates/ai-memory-hooks/src/lib.rs b/crates/ai-memory-hooks/src/lib.rsindex bffdb8ff..e2a3e561 100644--- a/crates/ai-memory-hooks/src/lib.rs+++ b/crates/ai-memory-hooks/src/lib.rs@@ -58,7 +58,7 @@ pub use capture_policy::{glob_segment_matches, glob_walk, repository_admits_capture, tool_call_payload, valid_call_id,};pub use drop_list::IngestDropList;-pub use hermes::{hermes_is_first_turn, shape_hermes_lifecycle_body};+pub use hermes::{hermes_is_delegated_child, hermes_is_first_turn, shape_hermes_lifecycle_body};pub use idle_end::{IDLE_END_BATCH, IDLE_END_INTERVAL_SECS, IdleEndTickInput, IdleEndTickOutcome, run_idle_end_tick,};