Skip to content

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.rs
index 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.rs
index 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.rs
index 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 or
diff --git a/crates/ai-memory-cli/src/lib.rs b/crates/ai-memory-cli/src/lib.rs
index 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,