Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hook-spool): resolve the retry budget once at the drain boundary (#1092)
AkitaOnRails22a1bbefcb73
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex 0ccb3e77..d5aa2eb6 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -25,6 +25,7 @@ use ai_memory_hooks::{use ai_memory_llm::OidcToken;use crate::cli::HookArgs;+use crate::config::{Config, RuntimeEnv};use crate::server_profiles::{self, ProfileName, Rejection, ResolvedServer};use sha2::{Digest as _, Sha256};@@ -331,8 +332,9 @@ fn after_background_drain_event_enqueue(}/// Hidden drain-only fast path. Reads no stdin and writes no stdout.-pub async fn run_drain(data_dir: Option<PathBuf>) -> anyhow::Result<()> {- let dd = resolve_data_dir(data_dir.as_deref());+pub async fn run_drain(config: &Config) -> anyhow::Result<()> {+ let dd = config.data_dir.clone();+ let max_attempts = hook_spool::MaxAttempts::new(config.hook_spool.max_attempts);let spool = hook_spool::spool_dir(&dd);match hook_spool::drain_until_quiescent(&spool,@@ -340,6 +342,7 @@ pub async fn run_drain(data_dir: Option<PathBuf>) -> anyhow::Result<()> {background_drain_budget(),drain_event_timeout(),hook_spool::DrainLockWait::Bounded(Duration::from_secs(30)),+ max_attempts,).await{@@ -555,20 +558,23 @@ fn session_start_handoff_envelope(agent: AgentKind, handoff: String) -> serde_js////// `data_dir` is the resolved global `--data-dir` (if any); used to locate the/// spool and the stored OIDC token.-pub async fn run(data_dir: Option<PathBuf>, args: HookArgs) -> anyhow::Result<()> {+pub async fn run(config: &Config, args: HookArgs) -> anyhow::Result<()> {let mut payload = String::new();std::io::stdin().read_to_string(&mut payload).ok();let mut stdout = std::io::stdout();- run_with_payload(- data_dir,+ run_with_payload_and_settings(+ Some(config.data_dir.clone()),args,payload,&mut stdout,spawn_background_drainer,+ config.runtime_env.clone(),+ hook_spool::MaxAttempts::new(config.hook_spool.max_attempts),).await}+#[cfg(test)]async fn run_with_payload<W, S>(data_dir: Option<PathBuf>,args: HookArgs,@@ -576,6 +582,36 @@ async fn run_with_payload<W, S>(stdout: &mut W,spawn_background_drainer: S,) -> anyhow::Result<()>+where+ W: std::io::Write,+ S: FnOnce(&Path, Option<&str>) -> std::io::Result<()>,+{+ let runtime_env = RuntimeEnv::from_process();+ let dd = resolve_data_dir_with(data_dir.as_deref(), &runtime_env);+ let config =+ Config::load_with_runtime_env(Some(&dd.join("config.toml")), Some(dd), runtime_env.clone())+ .unwrap_or_default();+ run_with_payload_and_settings(+ data_dir,+ args,+ payload,+ stdout,+ spawn_background_drainer,+ runtime_env,+ hook_spool::MaxAttempts::new(config.hook_spool.max_attempts),+ )+ .await+}++async fn run_with_payload_and_settings<W, S>(+ data_dir: Option<PathBuf>,+ args: HookArgs,+ payload: String,+ stdout: &mut W,+ spawn_background_drainer: S,+ runtime_env: RuntimeEnv,+ max_attempts: hook_spool::MaxAttempts,+) -> anyhow::Result<()>whereW: std::io::Write,S: FnOnce(&Path, Option<&str>) -> std::io::Result<()>,@@ -583,7 +619,7 @@ wherelet agent_kind = AgentKind::from_wire(&args.agent);let hook_event = HookEvent::parse(&args.event);// This is inherited execution context, like AI_MEMORY_RUN_ID, rather- // than server configuration. Hooks deliberately bypass Config::load.+ // than server configuration.let external_capture = env_lookup(CAPTURE_OWNER_ENV).is_some_and(|v| !v.trim().is_empty());let delivers_context = (hook_event == HookEvent::SessionStart&& agent_kind.session_start_injects_handoff())@@ -596,7 +632,10 @@ where// Retiring the fallback session ID is lifecycle housekeeping, not// capture. Preserve it even when no event is enqueued.if agent_kind == AgentKind::Devin && hook_event == HookEvent::SessionEnd {- clear_session_id(&resolve_data_dir(data_dir.as_deref()), agent_kind);+ clear_session_id(+ &resolve_data_dir_with(data_dir.as_deref(), &runtime_env),+ agent_kind,+ );}write_success_response(stdout, agent_kind, hook_event)?;return Ok(());@@ -688,7 +727,7 @@ whereinspection_cwd.as_deref().unwrap_or(""),)});- let dd = resolve_data_dir(data_dir.as_deref());+ let dd = resolve_data_dir_with(data_dir.as_deref(), &runtime_env);// Precedence: an explicit flag (tests, one-off runs) wins; otherwise the// persisted per-install mode; otherwise the historical default.let capture_mode = args.capture_mode.map_or_else(@@ -901,6 +940,7 @@ whereINCREMENTAL_DRAIN_BUDGET,INCREMENTAL_DRAIN_BUDGET,hook_spool::DrainLockWait::NoWait,+ max_attempts,).await;}@@ -932,6 +972,7 @@ where&dd,start_drain_budget(),drain_event_timeout(),+ max_attempts,).await;}@@ -1331,13 +1372,18 @@ fn is_tool_event(event: &str) -> bool {)}-/// Resolve the data dir cheaply, without loading the full config (the hook-/// fast-path skips config for latency). Mirrors `config.rs`: explicit-/// `--data-dir`, else `AI_MEMORY_DATA_DIR`, else the platform local-data dir.+/// Resolve the data dir for tests that exercise the hook implementation+/// directly: explicit `--data-dir`, then the captured runtime environment, then+/// the platform local-data directory.+#[cfg(test)]fn resolve_data_dir(data_dir: Option<&Path>) -> PathBuf {+ resolve_data_dir_with(data_dir, &RuntimeEnv::from_process())+}++fn resolve_data_dir_with(data_dir: Option<&Path>, runtime_env: &RuntimeEnv) -> PathBuf {let dir = data_dir.map(Path::to_path_buf)- .or_else(|| std::env::var_os("AI_MEMORY_DATA_DIR").map(PathBuf::from))+ .or_else(|| runtime_env.data_dir().map(Path::to_path_buf)).unwrap_or_else(|| {dirs::data_local_dir().unwrap_or_else(|| PathBuf::from("."))@@ -3912,6 +3958,7 @@ mod tests {Duration::from_secs(5),Duration::from_millis(500),Some("INSTALL-TOKEN"),+ hook_spool::MaxAttempts::new(crate::config::DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS),).await;assert_eq!(result.sent, 2, "{result:?}");diff --git a/crates/ai-memory-cli/src/commands/hook_capture.rs b/crates/ai-memory-cli/src/commands/hook_capture.rsindex 5fb4ccdf..a5475ee5 100644--- a/crates/ai-memory-cli/src/commands/hook_capture.rs+++ b/crates/ai-memory-cli/src/commands/hook_capture.rs@@ -741,8 +741,8 @@ pub enum PostOutcome {/// backpressure, the event was never processed. Keep it queued WITHOUT/// bumping attempts so saturation never burns the entry's retry budget.Saturated,- /// Any other non-2xx: the server answered and refused. A genuine miss- /// that should count against `MAX_ATTEMPTS`.+ /// A server error or unexpected response that may succeed on retry and+ /// should count against the configured attempt limit.Failed,/// The request never reached a server — connection refused, DNS failure,/// or timeout. Distinguished from [`Self::Failed`] because it says@@ -751,9 +751,8 @@ pub enum PostOutcome {/// so the drain can skip past them instead of stopping at the first one/// (#493).Unreachable,- /// `403` — the server understood the request and will never accept it.- /// Today that means the author may not write the project- /// the event belongs to.+ /// A permanent client error — the server understood the request and will+ /// never accept it unchanged. `401` and `429` have their own outcomes.////// Terminal, and that is the whole point of separating it from/// [`Self::Failed`]. A refusal that counts as a failure gets re-sent until@@ -797,7 +796,7 @@ pub async fn post_hook(PostOutcome::Saturated}Ok(resp) if resp.status() == reqwest::StatusCode::UNAUTHORIZED => PostOutcome::Unauthorized,- Ok(resp) if resp.status() == reqwest::StatusCode::FORBIDDEN => PostOutcome::Refused,+ Ok(resp) if resp.status().is_client_error() => PostOutcome::Refused,Ok(_) => PostOutcome::Failed,Err(_) => PostOutcome::Unreachable,}@@ -840,6 +839,9 @@ pub enum BatchOutcome {/// [`PostOutcome::Unauthorized`]; the whole batch shares one identity, so/// a rejected credential fails all of it and none of it was processed.Unauthorized,+ /// A permanent client error other than the explicitly handled `401`, `404`,+ /// `405`, and `429`; none of the batch was accepted.+ Refused,/// Transport error or any other non-2xx: the batch outcome is unknown. The/// drain charges conservatively so trailing events that may never have been/// attempted do not burn retry budget.@@ -907,6 +909,8 @@ pub async fn post_batch(BatchOutcome::Unsupported} else if status == reqwest::StatusCode::UNAUTHORIZED {BatchOutcome::Unauthorized+ } else if status.is_client_error() {+ BatchOutcome::Refused} else {BatchOutcome::Failed}@@ -1093,20 +1097,29 @@ mod tests {}#[tokio::test]- async fn post_hook_refused_on_403_is_terminal_not_a_failure() {- // 403 means the server will never accept this event. Classifying it as- // `Failed` would re-send it until it burnt `MAX_ATTEMPTS`, and every- // attempt would be refused identically — the shape of retry loop that- // once cost this project 10.7M tokens in a day. It must be its own- // outcome so the drain can drop it on the spot.- let url = serve_once("403 Forbidden", "capture not authorized").await;- let outcome = post_hook(&build_client(), &url, "{}", None, Duration::from_secs(1)).await;- assert_eq!(outcome, PostOutcome::Refused);- assert_ne!(- outcome,- PostOutcome::Failed,- "a refusal must never be charged a retry attempt"- );+ async fn post_hook_permanent_4xx_is_terminal_not_a_failure() {+ for (status, body) in [+ ("400 Bad Request", "invalid event"),+ ("403 Forbidden", "capture not authorized"),+ ] {+ let url = serve_once(status, body).await;+ let outcome =+ post_hook(&build_client(), &url, "{}", None, Duration::from_secs(1)).await;+ assert_eq!(outcome, PostOutcome::Refused);+ assert_ne!(+ outcome,+ PostOutcome::Failed,+ "a refusal must never be charged a retry attempt"+ );+ }+ }++ #[tokio::test]+ async fn post_batch_permanent_4xx_is_terminal_not_a_failure() {+ let url = serve_once("400 Bad Request", "invalid batch").await;+ let outcome = post_batch(&build_client(), &url, "[]", None, Duration::from_secs(1)).await;+ assert_eq!(outcome, BatchOutcome::Refused);+ assert_ne!(outcome, BatchOutcome::Failed);}#[tokio::test]diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rsindex 6f992acd..a1db8a80 100644--- a/crates/ai-memory-cli/src/commands/hook_spool.rs+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs@@ -32,7 +32,20 @@ use super::hook_capture::{BatchOutcome, PostOutcome, build_client, post_batch, p/// Default number of failed drain passes before dropping an event — bounds/// retries of a permanently-undeliverable event (e.g. a dead server URL).-const MAX_ATTEMPTS: u32 = 8;+#[cfg(test)]+const MAX_ATTEMPTS: u32 = crate::config::DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS;++/// Failed drain-pass limit resolved at the hook command boundary.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub struct MaxAttempts(u32);++impl MaxAttempts {+ /// Preserve an explicitly configured limit, including zero (no attempt drop).+ #[must_use]+ pub const fn new(value: u32) -> Self {+ Self(value)+ }+}/// Drop a spooled event older than this regardless of attempts (7 days), so a/// long-dead instance can't leave the spool growing without bound.const MAX_AGE_MS: u64 = 7 * 24 * 60 * 60 * 1000;@@ -383,8 +396,18 @@ pub async fn drain_exclusive(total_budget: Duration,per_event_timeout: Duration,wait: DrainLockWait,+ max_attempts: MaxAttempts,) -> Option<DrainResult> {- match drain_exclusive_result(spool, data_dir, total_budget, per_event_timeout, wait).await {+ match drain_exclusive_result(+ spool,+ data_dir,+ total_budget,+ per_event_timeout,+ wait,+ max_attempts,+ )+ .await+ {Ok(LockedDrainResult::Drained(result)) => Some(result),Ok(LockedDrainResult::LockBusy) | Err(_) => None,}@@ -397,12 +420,20 @@ pub async fn drain_exclusive_result(total_budget: Duration,per_event_timeout: Duration,wait: DrainLockWait,+ max_attempts: MaxAttempts,) -> std::io::Result<LockedDrainResult> {let Some(_lock) = acquire_drain_lock(spool, wait)? else {return Ok(LockedDrainResult::LockBusy);};Ok(LockedDrainResult::Drained(- drain(spool, data_dir, total_budget, per_event_timeout).await,+ drain_with_max_attempts(+ spool,+ data_dir,+ total_budget,+ per_event_timeout,+ max_attempts,+ )+ .await,))}@@ -412,6 +443,7 @@ pub async fn drain_exclusive_within_budget(data_dir: &Path,total_budget: Duration,per_event_timeout: Duration,+ max_attempts: MaxAttempts,) -> std::io::Result<LockedDrainResult> {let started = Instant::now();let Some(_lock) = acquire_drain_lock(spool, DrainLockWait::Bounded(total_budget))? else {@@ -430,7 +462,14 @@ pub async fn drain_exclusive_within_budget(}));}Ok(LockedDrainResult::Drained(- drain(spool, data_dir, remaining_budget, per_event_timeout).await,+ drain_with_max_attempts(+ spool,+ data_dir,+ remaining_budget,+ per_event_timeout,+ max_attempts,+ )+ .await,))}@@ -441,6 +480,7 @@ pub async fn drain_until_quiescent(total_budget: Duration,per_event_timeout: Duration,wait: DrainLockWait,+ max_attempts: MaxAttempts,) -> std::io::Result<LockedDrainResult> {let Some(_lock) = acquire_drain_lock(spool, wait)? else {return Ok(LockedDrainResult::LockBusy);@@ -458,7 +498,14 @@ pub async fn drain_until_quiescent(return Ok(LockedDrainResult::Drained(combined));}- let result = drain(spool, data_dir, remaining_budget, per_event_timeout).await;+ let result = drain_with_max_attempts(+ spool,+ data_dir,+ remaining_budget,+ per_event_timeout,+ max_attempts,+ )+ .await;combined.sent += result.sent;combined.dropped += result.dropped;combined.remaining = result.remaining;@@ -495,11 +542,29 @@ pub async fn drain_until_quiescent(////// Best-effort: returns counts and never errors, so a session boundary is never/// blocked beyond the budget and never fails the agent.-pub async fn drain(+#[cfg(test)]+async fn drain(spool: &Path,data_dir: &Path,total_budget: Duration,per_event_timeout: Duration,+) -> DrainResult {+ drain_with_max_attempts(+ spool,+ data_dir,+ total_budget,+ per_event_timeout,+ MaxAttempts::new(MAX_ATTEMPTS),+ )+ .await+}++pub async fn drain_with_max_attempts(+ spool: &Path,+ data_dir: &Path,+ total_budget: Duration,+ per_event_timeout: Duration,+ max_attempts: MaxAttempts,) -> DrainResult {drain_with_live_token(spool,@@ -507,22 +572,23 @@ pub async fn drain(total_budget,per_event_timeout,live_static_token().as_deref(),+ max_attempts,).await}-/// [`drain`] with the current static bearer supplied explicitly.+/// [`drain_with_max_attempts`] with the current static bearer supplied explicitly.///-/// The environment is read once, at the boundary in [`drain`], and passed down-/// as data. Tests drive this directly: mutating process-wide environment from a-/// test would race every other test in the binary, and `set_var` is `unsafe` in-/// this edition — which this workspace forbids outright.+/// The live token and retry policy are resolved at the command boundary and+/// passed down as data. Tests drive this directly, so drain behavior is isolated+/// from ambient process configuration.pub async fn drain_with_live_token(spool: &Path,data_dir: &Path,total_budget: Duration,per_event_timeout: Duration,live_token: Option<&str>,+ max_attempts: MaxAttempts,) -> DrainResult {let (mut files, unreadable) = match list_entries(spool) {Ok(listed) => listed,@@ -551,7 +617,7 @@ pub async fn drain_with_live_token(let mut oidc_cache: Option<Option<String>> = None; // outer None = not yet resolvedlet mut profile_tokens = ProfileTokens::new(data_dir);let mut result = DrainResult::default();- let max_attempts = configured_max_attempts(data_dir);+ let max_attempts = max_attempts.0;let mut idx = 0;let mut batch_supported = true;@@ -908,6 +974,12 @@ pub async fn drain_with_live_token(chunk.len().saturating_sub(1) + files.len().saturating_sub(idx);break;}+ BatchOutcome::Refused => {+ for (path, _) in &chunk {+ let _ = std::fs::remove_file(path);+ }+ result.dropped += chunk.len();+ }BatchOutcome::Failed => {// The batch didn't land (server answered with an unexpected// status, or the body did not parse).@@ -1211,27 +1283,6 @@ fn configured_server_url(data_dir: &Path) -> Option<String> {.map(std::string::ToString::to_string)}-/// Hook commands bypass `Config::load`; read this store's retry setting once-/// per drain, with the process environment taking precedence.-fn configured_max_attempts(data_dir: &Path) -> u32 {- configured_max_attempts_from(data_dir, |name| std::env::var(name).ok())-}--fn configured_max_attempts_from(- data_dir: &Path,- mut env_lookup: impl FnMut(&str) -> Option<String>,-) -> u32 {- if let Some(raw) = env_lookup("AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS") {- return raw.trim().parse().unwrap_or(MAX_ATTEMPTS);- }- std::fs::read_to_string(data_dir.join("config.toml"))- .ok()- .and_then(|text| text.parse::<toml_edit::DocumentMut>().ok())- .and_then(|doc| doc.get("hook_spool")?.get("max_attempts")?.as_integer())- .and_then(|value| u32::try_from(value).ok())- .unwrap_or(MAX_ATTEMPTS)-}-/// The `/hook/batch` URL for a spooled per-event URL: strip the `?…` query and/// append `/batch` (a spooled URL ends in `…/hook` before its query). Entries/// whose endpoint string matches can ride one batch request.@@ -1700,6 +1751,7 @@ mod tests {Duration::from_secs(1),Duration::from_millis(100),DrainLockWait::NoWait,+ MaxAttempts::new(MAX_ATTEMPTS),).await;@@ -1721,6 +1773,7 @@ mod tests {tmp.path(),Duration::ZERO,Duration::from_millis(100),+ MaxAttempts::new(MAX_ATTEMPTS),).await.unwrap();@@ -1752,6 +1805,7 @@ mod tests {Duration::from_secs(5),Duration::from_secs(2),DrainLockWait::NoWait,+ MaxAttempts::new(MAX_ATTEMPTS),).await.expect("lock acquired");@@ -1777,6 +1831,7 @@ mod tests {Duration::from_secs(1),Duration::from_millis(100),DrainLockWait::NoWait,+ MaxAttempts::new(MAX_ATTEMPTS),).await.unwrap_err();@@ -1822,11 +1877,6 @@ mod tests {#[tokio::test]async fn zero_max_attempts_keeps_unreachable_event_after_twenty_drains() {let tmp = tempfile::tempdir().unwrap();- std::fs::write(- tmp.path().join("config.toml"),- "[hook_spool]\nmax_attempts = 0\n",- )- .unwrap();let spool = spool_dir(tmp.path());enqueue(&spool,@@ -1840,11 +1890,12 @@ mod tests {.unwrap();for _ in 0..20 {- let result = drain(+ let result = drain_with_max_attempts(&spool,tmp.path(),Duration::from_secs(2),Duration::from_millis(100),+ MaxAttempts::new(0),).await;assert_eq!(result.dropped, 0);@@ -1856,14 +1907,67 @@ mod tests {assert_eq!(entry.attempts, 20);}+ #[tokio::test]+ async fn explicit_max_attempts_isolated_from_ambient_zero() {+ const CHILD_MARKER: &str = "AI_MEMORY_TEST_HOOK_SPOOL_AMBIENT_CHILD";+ if std::env::var_os(CHILD_MARKER).is_some() {+ assert_eq!(+ std::env::var("AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS").as_deref(),+ Ok("0")+ );+ let tmp = tempfile::tempdir().unwrap();+ let spool = spool_dir(tmp.path());+ enqueue(+ &spool,+ &entry_for(+ "http://127.0.0.1:1/hook?event=dead".into(),+ "{}".into(),+ None,+ false,+ ),+ )+ .unwrap();++ let result = drain_with_max_attempts(+ &spool,+ tmp.path(),+ Duration::from_secs(2),+ Duration::from_millis(100),+ MaxAttempts::new(1),+ )+ .await;++ assert_eq!(result.dropped, 1);+ assert!(list_entries(&spool).unwrap().0.is_empty());+ println!("ambient-zero-isolated");+ return;+ }++ let output = std::process::Command::new(std::env::current_exe().unwrap())+ .arg("--exact")+ .arg("commands::hook_spool::tests::explicit_max_attempts_isolated_from_ambient_zero")+ .arg("--test-threads=1")+ .arg("--nocapture")+ .env(CHILD_MARKER, "1")+ .env("AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS", "0")+ .output()+ .unwrap();+ assert!(+ output.status.success(),+ "child test failed:\nstdout: {}\nstderr: {}",+ String::from_utf8_lossy(&output.stdout),+ String::from_utf8_lossy(&output.stderr)+ );+ assert!(+ String::from_utf8_lossy(&output.stdout).contains("ambient-zero-isolated"),+ "child stdout: {}",+ String::from_utf8_lossy(&output.stdout)+ );+ }+#[tokio::test]async fn configured_max_attempts_drops_after_three_drains() {let tmp = tempfile::tempdir().unwrap();- std::fs::write(- tmp.path().join("config.toml"),- "[hook_spool]\nmax_attempts = 3\n",- )- .unwrap();let spool = spool_dir(tmp.path());enqueue(&spool,@@ -1877,11 +1981,12 @@ mod tests {.unwrap();for pass in 1..=3 {- let result = drain(+ let result = drain_with_max_attempts(&spool,tmp.path(),Duration::from_secs(2),Duration::from_millis(100),+ MaxAttempts::new(3),).await;assert_eq!(result.dropped, usize::from(pass == 3));@@ -1890,33 +1995,35 @@ mod tests {assert!(list_entries(&spool).unwrap().0.is_empty());}- #[test]- fn max_attempts_env_overrides_config_and_invalid_values_use_default() {+ #[tokio::test]+ async fn zero_max_attempts_still_drops_stale_event() {let tmp = tempfile::tempdir().unwrap();- let config = tmp.path().join("config.toml");- std::fs::write(&config, "[hook_spool]\nmax_attempts = 3\n").unwrap();- assert_eq!(configured_max_attempts_from(tmp.path(), |_| None), 3);- assert_eq!(- configured_max_attempts_from(tmp.path(), |name| {- assert_eq!(name, "AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS");- Some("0".into())- }),- 0- );- assert_eq!(- configured_max_attempts_from(tmp.path(), |_| Some("invalid".into())),- MAX_ATTEMPTS- );- std::fs::write(&config, "[hook_spool]\nmax_attempts = -1\n").unwrap();- assert_eq!(- configured_max_attempts_from(tmp.path(), |_| None),- MAX_ATTEMPTS- );- std::fs::write(&config, "[hook_spool]\nmax_attempts = \"invalid\"\n").unwrap();- assert_eq!(- configured_max_attempts_from(tmp.path(), |_| None),- MAX_ATTEMPTS+ let spool = spool_dir(tmp.path());+ std::fs::create_dir_all(&spool).unwrap();+ let mut entry = entry_for(+ "http://127.0.0.1:1/hook?event=old".into(),+ "{}".into(),+ None,+ false,);+ entry.created_ms = now_ms().saturating_sub(MAX_AGE_MS + 1);+ std::fs::write(+ spool.join("stale.json"),+ serde_json::to_vec(&entry).unwrap(),+ )+ .unwrap();++ let result = drain_with_max_attempts(+ &spool,+ tmp.path(),+ Duration::from_secs(2),+ Duration::from_millis(100),+ MaxAttempts::new(0),+ )+ .await;++ assert_eq!(result.dropped, 1);+ assert!(list_entries(&spool).unwrap().0.is_empty());}#[tokio::test]@@ -2485,6 +2592,7 @@ mod tests {Duration::from_secs(5),Duration::from_millis(500),Some("rotated-new"),+ MaxAttempts::new(MAX_ATTEMPTS),).await;@@ -2517,6 +2625,7 @@ mod tests {Duration::from_secs(5),Duration::from_millis(500),None,+ MaxAttempts::new(MAX_ATTEMPTS),).await;@@ -2549,6 +2658,7 @@ mod tests {Duration::from_secs(5),Duration::from_millis(500),Some("A-LIVE"),+ MaxAttempts::new(MAX_ATTEMPTS),).await;@@ -2590,6 +2700,7 @@ mod tests {Duration::from_secs(5),Duration::from_millis(500),Some("A-LIVE"),+ MaxAttempts::new(MAX_ATTEMPTS),).await;diff --git a/crates/ai-memory-cli/src/config.rs b/crates/ai-memory-cli/src/config.rsindex 0d7c4309..899264b8 100644--- a/crates/ai-memory-cli/src/config.rs+++ b/crates/ai-memory-cli/src/config.rs@@ -35,6 +35,9 @@ pub const DEFAULT_TCP_KEEPALIVE_SECS: u64 = 60;/// Default base URL used by thin-client CLI subcommands.pub const DEFAULT_SERVER_URL: &str = "http://127.0.0.1:49374";+/// Default number of failed hook-spool drain passes before dropping an event.+pub const DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS: u32 = 8;+/// Placeholder credential that lets `Config::load` validate a fallback/// profile whose `api_key_env` is absent from this process. Never reaches a/// provider: the config built from it is discarded (#762).@@ -586,6 +589,8 @@ pub struct Config {/// Default `follow-cwd` preserves the historical per-event resolution;/// `sticky` keeps the session's project. See [`RoutingSettings`].pub routing: RoutingSettings,+ /// Client-side hook spool retry policy.+ pub hook_spool: HookSpoolSettings,/// Env-backed alias for hook ingest tokens per second per source.pub hook_rate_per_sec: f64,/// Env-backed alias for hook ingest burst tokens per source.@@ -664,10 +669,11 @@ pub struct RuntimeEnv {copilot_client_id: Option<String>,voyage_api_key: Option<SecretString>,opencode_api_key: Option<SecretString>,+ hook_spool_max_attempts: Option<String>,}impl RuntimeEnv {- fn from_process() -> Self {+ pub(crate) fn from_process() -> Self {let platform_home = dirs::home_dir();Self {data_dir: env_path("AI_MEMORY_DATA_DIR"),@@ -718,9 +724,16 @@ impl RuntimeEnv {copilot_client_id: env_string("AI_MEMORY_COPILOT_CLIENT_ID"),voyage_api_key: env_secret("VOYAGE_API_KEY"),opencode_api_key: env_secret("OPENCODE_API_KEY"),+ hook_spool_max_attempts: std::env::var("AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS").ok(),}}+ /// Data directory captured from the process environment, if present.+ #[must_use]+ pub fn data_dir(&self) -> Option<&Path> {+ self.data_dir.as_deref()+ }+/// Host cwd forwarded by the docker wrapper, if present.#[must_use]pub fn host_cwd(&self) -> Option<&str> {@@ -764,6 +777,12 @@ impl RuntimeEnv {self.claude_code_session_id.as_deref()}+ /// Hook-spool attempt override captured from the process environment.+ #[must_use]+ pub fn hook_spool_max_attempts(&self) -> Option<&str> {+ self.hook_spool_max_attempts.as_deref()+ }+#[cfg(test)]pub fn with_host_cwd_for_tests(host_cwd: impl Into<String>) -> Self {Self {@@ -974,6 +993,41 @@ pub struct RoutingSettings {pub mid_session: ai_memory_core::MidSessionRouting,}+/// Client-side hook spool retry policy.+#[derive(Debug, Clone, Copy, Serialize, Deserialize)]+#[serde(default)]+pub struct HookSpoolSettings {+ /// Failed drain passes before an event is dropped; zero disables this limit.+ #[serde(+ default = "default_hook_spool_max_attempts",+ deserialize_with = "deserialize_hook_spool_max_attempts"+ )]+ pub max_attempts: u32,+}++impl Default for HookSpoolSettings {+ fn default() -> Self {+ Self {+ max_attempts: default_hook_spool_max_attempts(),+ }+ }+}++const fn default_hook_spool_max_attempts() -> u32 {+ DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS+}++fn deserialize_hook_spool_max_attempts<'de, D>(deserializer: D) -> Result<u32, D::Error>+where+ D: serde::Deserializer<'de>,+{+ let value = serde_json::Value::deserialize(deserializer)?;+ Ok(value+ .as_u64()+ .and_then(|value| u32::try_from(value).ok())+ .unwrap_or(DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS))+}+impl Default for Config {fn default() -> Self {Self {@@ -1026,6 +1080,7 @@ impl Default for Config {auth: AuthSettings::default(),auto_scope: AutoScopeSettings::default(),routing: RoutingSettings::default(),+ hook_spool: HookSpoolSettings::default(),hook_rate_per_sec: 0.0,hook_rate_burst: 0.0,allowed_hosts: vec!["localhost".into(), "127.0.0.1".into(), "::1".into()],@@ -1753,6 +1808,14 @@ fn apply_fts_stopwords_env(config: &mut Config, raw: Option<&str>) {);}+fn apply_hook_spool_max_attempts_env(config: &mut Config, raw: Option<&str>) {+ let Some(raw) = raw else { return };+ config.hook_spool.max_attempts = raw+ .trim()+ .parse()+ .unwrap_or(DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS);+}+impl Config {/// Load the merged configuration: defaults → file → env → CLI.///@@ -1760,8 +1823,14 @@ impl Config {/// Returns an error if the config file is malformed or any required/// field is missing.pub fn load(config_path: Option<&Path>, cli_data_dir: Option<PathBuf>) -> Result<Self> {- let runtime_env = RuntimeEnv::from_process();+ Self::load_with_runtime_env(config_path, cli_data_dir, RuntimeEnv::from_process())+ }+ pub(crate) fn load_with_runtime_env(+ config_path: Option<&Path>,+ cli_data_dir: Option<PathBuf>,+ runtime_env: RuntimeEnv,+ ) -> Result<Self> {// Figure out where the config file *would* live so we can read it// before knowing the final data dir. CLI > env > default.let probe_data_dir = cli_data_dir@@ -1829,6 +1898,7 @@ impl Config {.ok().as_deref(),);+ apply_hook_spool_max_attempts_env(&mut config, runtime_env.hook_spool_max_attempts());// Home is captured once in RuntimeEnv (config-read-path invariant);// threaded to the resolver guard and startup heal so neither reads the@@ -3039,6 +3109,7 @@ mod tests {assert_eq!(cfg.bind, DEFAULT_BIND);assert_eq!(cfg.tcp_keepalive_secs, DEFAULT_TCP_KEEPALIVE_SECS);assert_eq!(cfg.server_url, DEFAULT_SERVER_URL);+ assert_eq!(cfg.hook_spool.max_attempts, DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS);assert_eq!(cfg.log_level, "info");assert_eq!(cfg.llm_timeout_secs,@@ -3198,6 +3269,107 @@ mod tests {/// A configured list parses verbatim and resolves to exactly those/// words (lowercased), replacing the default outright rather than/// extending it.+ #[test]+ fn hook_spool_max_attempts_config_and_runtime_override_precedence() {+ let tmp = TempDir::new().unwrap();+ let config_path = tmp.path().join("config.toml");+ std::fs::write(&config_path, "[hook_spool]\nmax_attempts = 3\n").unwrap();++ let from_config = Config::load_with_runtime_env(+ Some(&config_path),+ Some(tmp.path().to_path_buf()),+ RuntimeEnv::default(),+ )+ .unwrap();+ assert_eq!(from_config.hook_spool.max_attempts, 3);++ let overridden = Config::load_with_runtime_env(+ Some(&config_path),+ Some(tmp.path().to_path_buf()),+ RuntimeEnv {+ hook_spool_max_attempts: Some("0".into()),+ ..RuntimeEnv::default()+ },+ )+ .unwrap();+ assert_eq!(overridden.hook_spool.max_attempts, 0);+ }++ #[test]+ fn loader_hook_spool_runtime_env_overrides_config() {+ const CHILD_MARKER: &str = "AI_MEMORY_TEST_HOOK_SPOOL_CONFIG_CHILD";+ if std::env::var_os(CHILD_MARKER).is_some() {+ let tmp = TempDir::new().unwrap();+ let config_path = tmp.path().join("config.toml");+ std::fs::write(&config_path, "[hook_spool]\nmax_attempts = 3\n").unwrap();+ let config = Config::load(Some(&config_path), Some(tmp.path().to_path_buf())).unwrap();+ assert_eq!(config.hook_spool.max_attempts, 0);+ println!("runtime-override-applied");+ return;+ }++ let output = std::process::Command::new(std::env::current_exe().unwrap())+ .arg("--exact")+ .arg("config::tests::loader_hook_spool_runtime_env_overrides_config")+ .arg("--test-threads=1")+ .arg("--nocapture")+ .env(CHILD_MARKER, "1")+ .env("AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS", "0")+ .output()+ .unwrap();+ assert!(+ output.status.success(),+ "child test failed:\nstdout: {}\nstderr: {}",+ String::from_utf8_lossy(&output.stdout),+ String::from_utf8_lossy(&output.stderr)+ );+ assert!(+ String::from_utf8_lossy(&output.stdout).contains("runtime-override-applied"),+ "child stdout: {}",+ String::from_utf8_lossy(&output.stdout)+ );+ }++ #[test]+ fn invalid_hook_spool_max_attempts_values_use_default() {+ let tmp = TempDir::new().unwrap();+ let config_path = tmp.path().join("config.toml");+ for invalid in ["-1", "\"invalid\""] {+ std::fs::write(+ &config_path,+ format!("[hook_spool]\nmax_attempts = {invalid}\n"),+ )+ .unwrap();+ let config = Config::load_with_runtime_env(+ Some(&config_path),+ Some(tmp.path().to_path_buf()),+ RuntimeEnv::default(),+ )+ .unwrap();+ assert_eq!(+ config.hook_spool.max_attempts, DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS,+ "invalid config value {invalid} must use the default"+ );+ }++ std::fs::remove_file(&config_path).unwrap();+ for invalid in ["invalid", "-1", ""] {+ let invalid_env = Config::load_with_runtime_env(+ Some(&config_path),+ Some(tmp.path().to_path_buf()),+ RuntimeEnv {+ hook_spool_max_attempts: Some(invalid.into()),+ ..RuntimeEnv::default()+ },+ )+ .unwrap();+ assert_eq!(+ invalid_env.hook_spool.max_attempts, DEFAULT_HOOK_SPOOL_MAX_ATTEMPTS,+ "invalid env value {invalid:?} must use the default"+ );+ }+ }+#[test]fn configured_search_fts_stopwords_list_parses_and_replaces_default() {let tmp = TempDir::new().unwrap();diff --git a/crates/ai-memory-cli/src/lib.rs b/crates/ai-memory-cli/src/lib.rsindex b03dfd54..4dc7a682 100644--- a/crates/ai-memory-cli/src/lib.rs+++ b/crates/ai-memory-cli/src/lib.rs@@ -44,15 +44,18 @@ pub async fn run() -> Result<()> {command,} = cli::parse_process();- // Hooks fire on every tool call: they must be cheap and must emit ONLY- // their JSON object to stdout. Short-circuit before config load and- // tracing init (added latency + possible stdout noise). The hook reads- // its server URL + token from flags; it only needs the data-dir to locate- // a stored OIDC token when no explicit `--auth-token` is given, so we pass- // the bare path rather than loading the full config.+ // Hooks fire on every tool call and must emit only their JSON object to+ // stdout. Load configuration once at this command boundary, but still+ // short-circuit before tracing initialization so the hot path stays quiet.let command = match command {- Command::Hook(args) => return commands::hook::run(data_dir, args).await,- Command::HookDrain(_args) => return commands::hook::run_drain(data_dir).await,+ Command::Hook(args) => {+ let config = Config::load(config_path.as_deref(), data_dir)?;+ return commands::hook::run(&config, args).await;+ }+ Command::HookDrain(_args) => {+ let config = Config::load(config_path.as_deref(), data_dir)?;+ return commands::hook::run_drain(&config).await;+ }// Completions are pure text derived from the command tree. Emitting// them must not require a loadable config or an initialised data dir// (they are typically generated before `init`, or in a packaging@@ -145,9 +148,9 @@ pub async fn run() -> Result<()> {Command::Reindex(args) => commands::reindex::run(&config, args).await,Command::InstallHooks(args) => commands::install_hooks::run(&config, args),// `Hook` is handled in the fast-path above (before config/tracing).- Command::Hook(args) => commands::hook::run(Some(config.data_dir.clone()), args).await,+ Command::Hook(args) => commands::hook::run(&config, args).await,// `HookDrain` is handled in the fast-path above (before config/tracing).- Command::HookDrain(_args) => commands::hook::run_drain(Some(config.data_dir.clone())).await,+ Command::HookDrain(_args) => commands::hook::run_drain(&config).await,Command::InstallMcp(args) => commands::install_mcp::run(&config, args),Command::McpBridge(args) => commands::mcp_bridge::run(&config, args).await,Command::Commit(args) => commands::commit::run(&config, args).await,diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.mdindex d1e71320..3f821342 100644--- a/docs/ARCHITECTURE.md+++ b/docs/ARCHITECTURE.md@@ -1026,8 +1026,8 @@ idle_window_secs = 300 # operator must be quiet this long before a ru[hook_spool]max_attempts = 8 # failed drain passes before dropping an event; 0 disables- # this limit. Age (7 days) and spool size (10,000 files)- # still bound retention. Env:+ # only this limit. Age (7 days) and spool size (10,000 files)+ # still bound retention. Runtime env wins when set:# AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS```diff --git a/docs/install.md b/docs/install.mdindex 290e8477..8f91fddb 100644--- a/docs/install.md+++ b/docs/install.md@@ -704,6 +704,11 @@ agent's environment; no `install-hooks` rerun is needed:| `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 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 |+| `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS` | 8 failed passes | non-negative integer | failed drain passes before dropping an event; `0` disables only attempt-count drops |++The retry setting can also be written as `max_attempts` under `[hook_spool]` in+`<data_dir>/config.toml`; the runtime environment wins when both are set. A zero+value still leaves the 7-day age limit and 10,000-file spool cap active.Timing values must be positive whole minutes. Missing, empty, non-numeric, orzero values fall back to the built-in defaults; values above 60 are clamped. Thediff --git a/docs/windows.md b/docs/windows.mdindex 30dd74ff..87641bae 100644--- a/docs/windows.md+++ b/docs/windows.md@@ -583,6 +583,11 @@ host agent. The warning never includes payload contents.| `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_INCREMENTAL_THRESHOLD` | 32 events | positive integer | spool backlog size that triggers a 250 ms `post-tool-use` catch-up drain |+| `AI_MEMORY_HOOK_SPOOL_MAX_ATTEMPTS` | 8 failed passes | non-negative integer | failed drain passes before dropping an event; `0` disables only attempt-count drops |++The retry setting can also be written as `max_attempts` under `[hook_spool]` in+`<data_dir>/config.toml`; the runtime environment wins when both are set. A zero+value still leaves the 7-day age limit and 10,000-file spool cap active.Timing values must be positive whole minutes. Missing, empty, non-numeric, orzero values fall back to the built-in defaults; values above 60 are clamped. The