Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(hook-spool): keep transient 4xx retryable and the hook path config-free (#1092)
AkitaOnRails9dbf9bbf4a1b
diff --git a/crates/ai-memory-cli/src/commands/hook.rs b/crates/ai-memory-cli/src/commands/hook.rsindex d5aa2eb6..ed2228c2 100644--- a/crates/ai-memory-cli/src/commands/hook.rs+++ b/crates/ai-memory-cli/src/commands/hook.rs@@ -332,8 +332,16 @@ fn after_background_drain_event_enqueue(}/// Hidden drain-only fast path. Reads no stdin and writes no stdout.-pub async fn run_drain(config: &Config) -> anyhow::Result<()> {- let dd = config.data_dir.clone();+pub async fn run_drain(data_dir: Option<PathBuf>) -> anyhow::Result<()> {+ let runtime_env = RuntimeEnv::from_process();+ let dd = resolve_data_dir_with(data_dir.as_deref(), &runtime_env);+ // The hook path never runs a full `Config::load` (see the fast-path+ // contract in `lib.rs`): an invalid config section elsewhere must not+ // fail the drainer. Only the spool retry policy is needed, loaded+ // tolerantly — any load error falls back to defaults.+ let config =+ Config::load_with_runtime_env(Some(&dd.join("config.toml")), Some(dd.clone()), runtime_env)+ .unwrap_or_default();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(@@ -558,23 +566,29 @@ 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(config: &Config, args: HookArgs) -> anyhow::Result<()> {+pub async fn run(data_dir: Option<PathBuf>, 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_and_settings(- Some(config.data_dir.clone()),+ run_with_payload(+ data_dir,args,payload,&mut stdout,spawn_background_drainer,- config.runtime_env.clone(),- hook_spool::MaxAttempts::new(config.hook_spool.max_attempts),).await}-#[cfg(test)]+/// [`run`] with the payload and output sink injected, so tests drive the hook+/// implementation directly without stdin/stdout.+///+/// Hooks deliberately bypass the full `Config::load` (the fast-path contract+/// in `lib.rs`): an unrelated invalid config section must never fail the hook+/// or add stdout noise. The spool retry policy is the only config needed, and+/// it is loaded tolerantly — a malformed config falls back to defaults rather+/// than erroring. The process environment is captured once, here, and+/// threaded down as data.async fn run_with_payload<W, S>(data_dir: Option<PathBuf>,args: HookArgs,@@ -588,38 +602,14 @@ where{let runtime_env = RuntimeEnv::from_process();let dd = resolve_data_dir_with(data_dir.as_deref(), &runtime_env);- let config =+ let spool_policy =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<()>,-{+ let max_attempts = hook_spool::MaxAttempts::new(spool_policy.hook_spool.max_attempts);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.+ // than server configuration. Hooks deliberately bypass Config::load.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())diff --git a/crates/ai-memory-cli/src/commands/hook_capture.rs b/crates/ai-memory-cli/src/commands/hook_capture.rsindex a5475ee5..9adb4e91 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,- /// A server error or unexpected response that may succeed on retry and- /// should count against the configured attempt limit.+ /// Any other non-2xx: the server answered and refused. A genuine miss+ /// that should count against the retry limit.Failed,/// The request never reached a server — connection refused, DNS failure,/// or timeout. Distinguished from [`Self::Failed`] because it says@@ -751,12 +751,13 @@ pub enum PostOutcome {/// so the drain can skip past them instead of stopping at the first one/// (#493).Unreachable,- /// A permanent client error — the server understood the request and will- /// never accept it unchanged. `401` and `429` have their own outcomes.+ /// `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.////// Terminal, and that is the whole point of separating it from/// [`Self::Failed`]. A refusal that counts as a failure gets re-sent until- /// it exhausts `MAX_ATTEMPTS`, and every one of those attempts is+ /// it exhausts the retry limit, and every one of those attempts is/// guaranteed to be refused for the same reason. Retrying something that/// cannot succeed is how a parse failure once cost this project 10.7M/// tokens in a day. The entry is dropped on the spot.@@ -796,7 +797,7 @@ pub async fn post_hook(PostOutcome::Saturated}Ok(resp) if resp.status() == reqwest::StatusCode::UNAUTHORIZED => PostOutcome::Unauthorized,- Ok(resp) if resp.status().is_client_error() => PostOutcome::Refused,+ Ok(resp) if resp.status() == reqwest::StatusCode::FORBIDDEN => PostOutcome::Refused,Ok(_) => PostOutcome::Failed,Err(_) => PostOutcome::Unreachable,}@@ -839,9 +840,6 @@ 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.@@ -909,8 +907,6 @@ 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}@@ -1097,29 +1093,53 @@ mod tests {}#[tokio::test]- 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;+ 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 the retry limit, 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"+ );+ }++ #[tokio::test]+ async fn post_hook_408_and_425_are_retryable_failed_not_refused() {+ // 408 (request timeout) and 425 (too early) say "retry me", not+ // "never": they must fall through to `Failed` so the spool keeps the+ // entry queued subject to the attempt limit. Classifying every 4xx as+ // a terminal refusal deleted such events on the spot (#1092+ // regression).+ for status in ["408 Request Timeout", "425 Too Early"] {+ let url = serve_once(status, "retry later").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"+ PostOutcome::Refused,+ "{status} is retryable and must not be terminal");+ assert_eq!(outcome, PostOutcome::Failed, "{status} is a retryable miss");}}#[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);+ async fn post_batch_unhandled_4xx_is_retryable_failed() {+ // Base semantics: only 401/404/405/429 are special-cased for batches;+ // every other status — 400, and retryable timeouts like 408/425 — is+ // a `Failed` with an unknown outcome, never a terminal refusal.+ for status in ["400 Bad Request", "408 Request Timeout", "425 Too Early"] {+ let url = serve_once(status, "invalid batch").await;+ let outcome =+ post_batch(&build_client(), &url, "[]", None, Duration::from_secs(1)).await;+ assert_eq!(outcome, BatchOutcome::Failed, "{status} is retryable");+ }}#[tokio::test]diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rsindex a1db8a80..a8998b43 100644--- a/crates/ai-memory-cli/src/commands/hook_spool.rs+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs@@ -974,12 +974,6 @@ 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).@@ -1645,6 +1639,60 @@ mod tests {assert_eq!(list_entries(&spool).unwrap().0.len(), 2);}+ #[tokio::test]+ async fn drain_keeps_entry_when_first_response_is_408() {+ // A 408 from the server is retryable, not a terminal refusal: the+ // drain must keep the entry queued (charged one attempt) so a later+ // pass can still deliver it, subject to the retry limit. Treating+ // every 4xx as permanent deleted such events on the spot (#1092+ // regression).+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();+ let addr = listener.local_addr().unwrap();+ tokio::spawn(async move {+ use tokio::io::{AsyncReadExt, AsyncWriteExt};+ // Answer every request (batch first) with 408 until the drain+ // gives up on this pass.+ while let Ok((mut stream, _)) = listener.accept().await {+ let mut buf = [0_u8; 1024];+ let _ = stream.read(&mut buf).await;+ let response = "HTTP/1.1 408 Request Timeout\r\nContent-Length: 0\r\nConnection: close\r\n\r\n";+ let _ = stream.write_all(response.as_bytes()).await;+ }+ });++ let tmp = tempfile::tempdir().unwrap();+ let spool = spool_dir(tmp.path());+ enqueue(+ &spool,+ &entry_for(+ format!("http://{addr}/hook?event=e0"),+ "{}".into(),+ None,+ false,+ ),+ )+ .unwrap();++ let r = drain_with_max_attempts(+ &spool,+ tmp.path(),+ Duration::from_secs(2),+ Duration::from_millis(500),+ MaxAttempts::new(MAX_ATTEMPTS),+ )+ .await;++ assert_eq!(r.sent, 0);+ assert_eq!(r.dropped, 0, "a 408 first response must not drop the entry");+ let (files, _) = list_entries(&spool).unwrap();+ assert_eq!(files.len(), 1, "the entry stays queued for the next pass");+ let entry: SpoolEntry = serde_json::from_slice(&std::fs::read(&files[0]).unwrap()).unwrap();+ assert_eq!(+ entry.attempts, 1,+ "the retryable miss is charged one attempt"+ );+ }+/// #493: an unreadable spool must not read as an idle pass.////// `list_entries` used to be `read_dir(spool).ok()?`, so a permissions ordiff --git a/crates/ai-memory-cli/src/lib.rs b/crates/ai-memory-cli/src/lib.rsindex 4dc7a682..b03dfd54 100644--- a/crates/ai-memory-cli/src/lib.rs+++ b/crates/ai-memory-cli/src/lib.rs@@ -44,18 +44,15 @@ pub async fn run() -> Result<()> {command,} = cli::parse_process();- // 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.+ // 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.let command = match command {- 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;- }+ Command::Hook(args) => return commands::hook::run(data_dir, args).await,+ Command::HookDrain(_args) => return commands::hook::run_drain(data_dir).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@@ -148,9 +145,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(&config, args).await,+ Command::Hook(args) => commands::hook::run(Some(config.data_dir.clone()), args).await,// `HookDrain` is handled in the fast-path above (before config/tracing).- Command::HookDrain(_args) => commands::hook::run_drain(&config).await,+ Command::HookDrain(_args) => commands::hook::run_drain(Some(config.data_dir.clone())).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,