Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hooks): trigger detached drains at safe boundaries
AkitaOnRailsaaf934174c7d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f29de938..1e65a707 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Fixed+- Native hook spool delivery no longer relies only on the cancellation-prone+ `session-end` hook to start the detached drainer. `stop` and `pre-compact`+ also request the background `hook-drain` helper after enqueue, and Unix builds+ use a trusted `setsid` launcher when available before falling back to a+ separate process group.- OpenCode generated plugins now close sessions from the official`session.deleted` event and a deduped best-effort `dispose` fallback, soOpenCode sessions can produce automatic session summaries and handoffs withoutdiff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex 3beb871d..2881eff6 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -105,17 +105,21 @@ fn incremental_drain_threshold_from(mut lookup: impl FnMut(&str) -> Option<Strin/// Whether to run a mid-session catch-up drain for this event: only/// `post-tool-use` (the highest-frequency event) and only once the spool backlog-/// has crossed `threshold`. Boundaries (`session-start`/`session-end`) remain-/// the main flush, so a light session never drains mid-session.+/// has crossed `threshold`. Boundaries run their own cleanup/background drains,+/// so a light session never drains mid-session.fn should_incremental_drain(event: &str, spool_len: usize, threshold: usize) -> bool {event == "post-tool-use" && spool_len >= threshold}-fn spawn_session_end_drainer(data_dir: &Path) -> std::io::Result<()> {+fn spawn_background_drainer(data_dir: &Path) -> std::io::Result<()> {hook_drain_process::spawn(data_dir)}-fn after_session_end_enqueue(+fn should_spawn_background_drainer(event: &str) -> bool {+ matches!(event, "session-end" | "stop" | "pre-compact")+}++fn after_background_drain_event_enqueue(data_dir: &Path,spawn: impl FnOnce(&Path) -> std::io::Result<()>,) -> std::io::Result<()> {@@ -182,7 +186,7 @@ pub async fn run(data_dir: Option<PathBuf>, args: HookArgs) -> anyhow::Result<()args,payload,&mut stdout,- spawn_session_end_drainer,+ spawn_background_drainer,).await}@@ -192,7 +196,7 @@ async fn run_with_payload<W, S>(args: HookArgs,payload: String,stdout: &mut W,- spawn_session_end_drainer: S,+ spawn_background_drainer: S,) -> anyhow::Result<()>whereW: std::io::Write,@@ -283,10 +287,12 @@ where}}- // session-end: enqueue and hand delivery to a detached native drainer so the- // agent quit path is not cancelled while the server processes backlog.- if args.event == "session-end"- && let Err(err) = after_session_end_enqueue(&dd, spawn_session_end_drainer)+ // Boundary drain trigger: enqueue first, then ask a detached native drainer+ // to flush the shared spool. `session-end` remains the primary close path,+ // but `stop` and `pre-compact` also trigger the helper so delivery does not+ // rely on the single hook most likely to be cancelled during agent shutdown.+ if should_spawn_background_drainer(&args.event)+ && let Err(err) = after_background_drain_event_enqueue(&dd, spawn_background_drainer){eprintln!("ai-memory hook warning: failed to start background spool drainer; event remains queued: {err}"@@ -352,6 +358,18 @@ mod tests {assert!(!should_incremental_drain("stop", 999, 32));}+ #[test]+ fn boundary_events_trigger_background_drainer() {+ assert!(should_spawn_background_drainer("session-end"));+ assert!(should_spawn_background_drainer("stop"));+ assert!(should_spawn_background_drainer("pre-compact"));++ assert!(!should_spawn_background_drainer("session-start"));+ assert!(!should_spawn_background_drainer("post-tool-use"));+ assert!(!should_spawn_background_drainer("pre-tool-use"));+ assert!(!should_spawn_background_drainer("user-prompt"));+ }+#[test]fn incremental_threshold_parses_and_falls_back() {assert_eq!(incremental_drain_threshold_from(|_| Some("64".into())), 64);@@ -467,6 +485,47 @@ mod tests {);}+ #[tokio::test]+ async fn stop_and_pre_compact_spawn_background_drainer_after_enqueue() {+ for event in ["stop", "pre-compact"] {+ let tmp = tempfile::tempdir().unwrap();+ let data_dir = tmp.path().to_path_buf();+ let spool = hook_spool::spool_dir(&data_dir);+ let called = std::cell::Cell::new(0);+ let mut stdout = Vec::new();+ let args = HookArgs {+ event: event.into(),+ agent: "claude-code".into(),+ server_url: "http://127.0.0.1:1".into(),+ auth_token: None,+ project_strategy: None,+ };++ run_with_payload(+ Some(data_dir.clone()),+ args,+ r#"{"session_id":"s","cwd":"/tmp"}"#.into(),+ &mut stdout,+ |path| {+ assert_eq!(path, data_dir.as_path());+ assert_eq!(hook_spool::spool_len(&spool), 1, "spawn runs after enqueue");+ called.set(called.get() + 1);+ Ok(())+ },+ )+ .await+ .unwrap();++ assert_eq!(stdout, b"{}\n", "{event} should keep hook stdout clean");+ assert_eq!(called.get(), 1, "{event} should start background drain");+ assert_eq!(+ hook_spool::spool_len(&spool),+ 1,+ "{event} must not drain inline"+ );+ }+ }+#[tokio::test]async fn session_end_run_spawn_failure_keeps_event_queued_and_stdout_clean() {let tmp = tempfile::tempdir().unwrap();@@ -494,7 +553,7 @@ mod tests {#[test]fn session_end_spawn_failure_is_returned_for_warning_only() {let tmp = tempfile::tempdir().unwrap();- let err = after_session_end_enqueue(tmp.path(), |_path| {+ let err = after_background_drain_event_enqueue(tmp.path(), |_path| {Err(std::io::Error::other("spawn failed"))}).unwrap_err();@@ -503,11 +562,11 @@ mod tests {}#[test]- fn session_end_policy_spawns_without_inline_drain() {+ fn background_drain_event_policy_spawns_without_inline_drain() {let tmp = tempfile::tempdir().unwrap();let called = std::cell::Cell::new(false);- after_session_end_enqueue(tmp.path(), |path| {+ after_background_drain_event_enqueue(tmp.path(), |path| {assert_eq!(path, tmp.path());called.set(true);Ok(())diff --git a/crates/ai-memory-cli/src/commands/hook_drain_process.rs b/crates/ai-memory-cli/src/commands/hook_drain_process.rsindex 87a50dae..17f2e457 100644--- a/crates/ai-memory-cli/src/commands/hook_drain_process.rs+++ b/crates/ai-memory-cli/src/commands/hook_drain_process.rs@@ -33,9 +33,10 @@ pub struct SpawnConfig {/// Platform detach configuration.#[derive(Debug, Clone, PartialEq, Eq)]pub enum DetachConfig {- /// Unix starts a new process group.+ /// 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)]- UnixProcessGroupZero,+ UnixNewSession { setsid: Option<PathBuf> },/// Windows creation flags.#[cfg(windows)]WindowsCreationFlags(u32),@@ -84,13 +85,11 @@ fn spawn_spec(spec: &DrainCommandSpec) -> io::Result<()> {.append(true).open(&config.stderr_file)?;- let mut command = Command::new(&spec.exe);+ let mut command = command_for_spec(spec, &config.detach);command- .args(&spec.args).stdin(Stdio::null()).stdout(Stdio::null()).stderr(Stdio::from(stderr));- apply_detach_flags(&mut command, &config.detach);match command.spawn() {Ok(_child) => Ok(()),@@ -108,13 +107,11 @@ fn spawn_spec(spec: &DrainCommandSpec) -> io::Result<()> {.create(true).append(true).open(&config.stderr_file)?;- let mut retry = Command::new(&spec.exe);+ let mut retry = command_for_spec(spec, &config.detach);retry- .args(&spec.args).stdin(Stdio::null()).stdout(Stdio::null()).stderr(Stdio::from(stderr));- apply_detach_flags(&mut retry, &config.detach);retry.spawn().map(|_| ())}Err(err) => Err(err),@@ -123,17 +120,40 @@ fn spawn_spec(spec: &DrainCommandSpec) -> io::Result<()> {#[cfg(unix)]fn detach_config(_try_breakaway: bool) -> DetachConfig {- DetachConfig::UnixProcessGroupZero+ DetachConfig::UnixNewSession {+ setsid: trusted_setsid_launcher(),+ }}#[cfg(unix)]-fn apply_detach_flags(command: &mut Command, detach: &DetachConfig) {+fn command_for_spec(spec: &DrainCommandSpec, detach: &DetachConfig) -> Command {use std::os::unix::process::CommandExt as _;- if matches!(detach, DetachConfig::UnixProcessGroupZero) {- command.process_group(0);++ 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;@@ -156,13 +176,25 @@ fn apply_detach_flags(command: &mut Command, detach: &DetachConfig) {}}+#[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 apply_detach_flags(_command: &mut Command, _detach: &DetachConfig) {}+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 {@@ -213,13 +245,16 @@ mod tests {#[cfg(unix)]#[test]- fn unix_spawn_config_uses_process_group_zero() {+ fn unix_spawn_config_prefers_true_session_detach_when_available() {let tmp = tempfile::tempdir().unwrap();let spec = command_spec(tmp.path()).unwrap();- assert_eq!(- spawn_config(&spec, true).detach,- DetachConfig::UnixProcessGroupZero- );+ 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)]diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rsindex e2c02aad..f7af1f87 100644--- a/crates/ai-memory-cli/src/commands/hook_spool.rs+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs@@ -1,11 +1,13 @@//! Local spool for lifecycle-hook events — decouples capture from the network.//!-//! Per-tool-call hooks (`pre-tool-use`, `post-tool-use`, `user-prompt-submit`,-//! `stop`) append an event here (an instant local write) instead of POSTing-//! synchronously. The spool is drained to the server at **session boundaries**-//! (a cleanup pass at `session-start`, the main flush at `session-end`), where a-//! few seconds of latency is acceptable — unlike the per-tool-call hot path,-//! which must never block the agent.+//! Per-tool-call hooks (`pre-tool-use`, `post-tool-use`, `user-prompt-submit`)+//! append an event here (an instant local write) instead of POSTing+//! synchronously. The spool is drained to the server at **session boundaries**:+//! a cleanup pass at `session-start`, detached background flushes at+//! cancellation-prone boundaries (`stop`, `pre-compact`, `session-end`), and a+//! small threshold-triggered catch-up on busy `post-tool-use` streams. A few+//! seconds of latency is acceptable at boundaries, unlike the per-tool-call hot+//! path, which must never block the agent.//!//! This makes capture reliable against a remote/slow server (no event is lost://! a file persists until the server answers 2xx) without ever blocking a tooldiff --git a/docs/install.md b/docs/install.mdindex 1f41f034..d1ed9a80 100644--- a/docs/install.md+++ b/docs/install.md@@ -369,18 +369,23 @@ the agent can execute files owned by your user. Re-run `install-hooks --apply`after package upgrades to refresh those staged copies.Native `ai-memory hook --event ...` commands spool events locally. Session start-does a short bounded cleanup drain before fetching a handoff; session end starts-a detached `hook-drain` helper so agent quit paths are not blocked by a large-backlog. The built-in timings stay short on agent-facing paths, but high-latency-or large-backlog instances can raise them with whole-minute runtime env vars in-the agent's environment; no `install-hooks` rerun is needed:+does a short bounded cleanup drain before fetching a handoff; cancellation-prone+boundary events (`stop`, `pre-compact`, and `session-end`) start a detached+`hook-drain` helper so delivery does not depend on one shutdown hook surviving.+On Unix, the helper uses a trusted `setsid` launcher when available and falls+back to a separate process group otherwise; Windows uses detached/breakaway+process flags. The spool is capped, so a permanently undrained backlog is+eventually pruned rather than unbounded, but old undelivered events can be lost.+The built-in timings stay short on agent-facing paths, but high-latency or+large-backlog instances can raise them with whole-minute runtime env vars in the+agent's environment; no `install-hooks` rerun is needed:| Env var | Built-in default | Max override | What it caps ||---|---:|---:|---|| `AI_MEMORY_HOOK_DRAIN_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | each event POST during a drain || `AI_MEMORY_HOOK_HANDOFF_TIMEOUT_MINUTES` | 3 seconds | 60 minutes | the synchronous `session-start` handoff GET || `AI_MEMORY_HOOK_START_BUDGET_MINUTES` | 3 seconds | 60 minutes | total time `session-start` may spend waiting for the drain lock and cleanup draining |-| `AI_MEMORY_HOOK_BACKGROUND_DRAIN_BUDGET_MINUTES` | 5 minutes | 60 minutes | total time the detached `hook-drain` helper may spend after `session-end` |+| `AI_MEMORY_HOOK_BACKGROUND_DRAIN_BUDGET_MINUTES` | 5 minutes | 60 minutes | total time the detached `hook-drain` helper may spend after a background-drain boundary || `AI_MEMORY_HOOK_INCREMENTAL_THRESHOLD` | 32 events | positive integer | spool backlog size that triggers a 250 ms `post-tool-use` catch-up drain |Timing values must be positive whole minutes. Missing, empty, non-numeric, or