Skip to content

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.rs
index 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<()>
where
W: std::io::Write,
S: FnOnce(&Path, Option<&str>) -> std::io::Result<()>,
@@ -583,7 +619,7 @@ where
let 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 @@ where
inspection_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 @@ where
INCREMENTAL_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.rs
index 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.rs
index 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 resolved
let 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.rs
index 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.rs
index 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.md
index 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.md
index 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, or
zero values fall back to the built-in defaults; values above 60 are clamped. The
diff --git a/docs/windows.md b/docs/windows.md
index 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, or
zero values fall back to the built-in defaults; values above 60 are clamped. The