Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

feat(hook): batch spool delivery via POST /hook/batch to amortize per-event RTT

Djalma Júnior3c83a5cabd36
diff --git a/Cargo.lock b/Cargo.lock
index 80b6178c..4266f4ac 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -140,6 +140,7 @@ dependencies = [
"regex",
"serde",
"serde_json",
+ "serde_urlencoded",
"tempfile",
"thiserror 2.0.18",
"tokio",
diff --git a/crates/ai-memory-cli/src/commands/hook_capture.rs b/crates/ai-memory-cli/src/commands/hook_capture.rs
index ac83fc80..a5c5efe1 100644
--- a/crates/ai-memory-cli/src/commands/hook_capture.rs
+++ b/crates/ai-memory-cli/src/commands/hook_capture.rs
@@ -177,6 +177,75 @@ pub async fn post_hook(
}
}
+/// Outcome of one `POST /hook/batch` request — many spooled events delivered in
+/// a single round-trip, so a draining client amortizes TLS + network RTT + the
+/// edge auth hop over the whole batch instead of paying it per event.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum BatchOutcome {
+ /// Server committed the leading `usize` items (contiguous prefix, oldest
+ /// first). Equals the request length on full success; a smaller value means
+ /// the server stopped on that item (fail-fast) — the caller deletes the
+ /// prefix and charges the next item a retry.
+ Accepted(usize),
+ /// `429` — ingest saturated; nothing was processed. Keep the whole batch and
+ /// retry it later WITHOUT bumping attempts (saturation isn't a failure).
+ Saturated,
+ /// `404`/`405` — the server has no `/hook/batch` (a pre-upgrade build). The
+ /// caller falls back to per-event `POST /hook` for the rest of the drain.
+ Unsupported,
+ /// Transport error or any other non-2xx: the batch didn't land. Treated as a
+ /// failed attempt for each item it carried (bounded by `MAX_ATTEMPTS`).
+ Failed,
+}
+
+/// POST a pre-serialized JSON array of `{url, body}` events to `<batch_url>`.
+/// `bearer` authenticates the whole batch (every item shares the drain's single
+/// identity). Best-effort: never errors. Reads `{"accepted": K}` from a 2xx
+/// body; a 2xx whose body can't be read is treated as `Failed` (re-send rather
+/// than risk dropping undelivered events).
+pub async fn post_batch(
+ client: &reqwest::Client,
+ batch_url: &str,
+ payload: &str,
+ token: Option<&str>,
+ timeout: Duration,
+) -> BatchOutcome {
+ let mut req = client
+ .post(batch_url)
+ .header("Content-Type", "application/json")
+ .timeout(timeout)
+ .body(payload.to_owned());
+ if let Some(t) = token {
+ req = req.bearer_auth(t);
+ }
+ match req.send().await {
+ Ok(resp) => {
+ let status = resp.status();
+ if status.is_success() {
+ match resp.json::<serde_json::Value>().await {
+ Ok(v) => {
+ let accepted = v
+ .get("accepted")
+ .and_then(serde_json::Value::as_u64)
+ .unwrap_or(0) as usize;
+ BatchOutcome::Accepted(accepted)
+ }
+ Err(_) => BatchOutcome::Failed,
+ }
+ } else if status == reqwest::StatusCode::TOO_MANY_REQUESTS {
+ BatchOutcome::Saturated
+ } else if status == reqwest::StatusCode::NOT_FOUND
+ || status == reqwest::StatusCode::METHOD_NOT_ALLOWED
+ {
+ BatchOutcome::Unsupported
+ } else {
+ BatchOutcome::Failed
+ }
+ }
+ Err(_) => BatchOutcome::Failed,
+ }
+}
+
/// GET the handoff text with a caller-chosen budget. Returns None on any error
/// or an empty body. This is the one synchronous read on the agent's critical
/// path (session-start injects it as context), so the budget is larger than a
diff --git a/crates/ai-memory-cli/src/commands/hook_spool.rs b/crates/ai-memory-cli/src/commands/hook_spool.rs
index b2f76bb3..377091e5 100644
--- a/crates/ai-memory-cli/src/commands/hook_spool.rs
+++ b/crates/ai-memory-cli/src/commands/hook_spool.rs
@@ -25,7 +25,7 @@ use ai_memory_llm::{OidcToken, refresh_access_token};
use secrecy::ExposeSecret as _;
use serde::{Deserialize, Serialize};
-use super::hook_capture::{PostOutcome, build_client, post_hook};
+use super::hook_capture::{BatchOutcome, PostOutcome, build_client, post_batch, post_hook};
/// Drop a spooled event after this many failed drain passes — bounds retries of
/// a permanently-undeliverable event (e.g. a server URL that never comes back).
@@ -40,6 +40,15 @@ const MAX_SPOOL_FILES: usize = 10_000;
#[cfg(test)]
const MAX_SPOOL_FILES: usize = 3;
+/// Max events per `POST /hook/batch` request (count bound; the byte bound below
+/// also applies). Caps the blast radius of a failed batch and keeps one request
+/// well under the server's body limit even with many small events.
+const MAX_BATCH_ITEMS: usize = 256;
+/// Soft byte budget for one `/hook/batch` body — stays under the server's 10 MiB
+/// `DefaultBodyLimit` with margin for JSON framing. A chunk always carries at
+/// least one event even if that event alone exceeds this.
+const MAX_BATCH_BYTES: usize = 8 * 1024 * 1024;
+
/// How a spooled event authenticates to the server when drained.
#[derive(Serialize, Deserialize, Clone, Copy, PartialEq, Eq, Debug)]
pub enum AuthMode {
@@ -55,7 +64,7 @@ pub enum AuthMode {
}
/// One spooled hook event: the full request plus how to authenticate it.
-#[derive(Serialize, Deserialize, Debug)]
+#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct SpoolEntry {
/// Full hook URL including the `?event=…&agent=…[&cwd&workspace&project]`
/// query the agent's payload resolved to.
@@ -167,9 +176,21 @@ pub struct DrainResult {
pub dropped: usize,
}
-/// Drain the spool to the server, oldest-first, within `total_budget`. Each
-/// event that gets a 2xx is deleted; failures stay for the next boundary.
-/// OIDC bearer is resolved + refreshed at most once per drain and cached.
+/// Drain the spool to the server, oldest-first, within `total_budget`.
+///
+/// Events are delivered in **batches** via `POST /hook/batch`: one request
+/// carries many spooled events, so the per-request cost (TLS + network RTT + the
+/// edge auth hop) is amortized over the whole batch instead of paid per event.
+/// That is the throughput fix — a sequential per-event drain falls behind when
+/// many parallel sessions share one spool against a remote, gated server, and
+/// the spool then grows to its cap and evicts undelivered events. A server
+/// without `/hook/batch` (a pre-upgrade build) answers `404`/`405`, and the
+/// drain transparently falls back to per-event `POST /hook`.
+///
+/// A delivered event is deleted; a failed one is charged a retry attempt
+/// (dropped at `MAX_ATTEMPTS`); a `429` (saturation) is retried untouched so it
+/// never burns the retry budget. OIDC bearer is resolved + refreshed at most
+/// once per drain and cached.
///
/// Best-effort: returns counts and never errors, so a session boundary is never
/// blocked beyond the budget and never fails the agent.
@@ -190,76 +211,201 @@ pub async fn drain(
let mut oidc_cache: Option<Option<String>> = None; // outer None = not yet resolved
let mut result = DrainResult::default();
+ // Load entries oldest-first, dropping unparseable / too-old files up front
+ // (a long-dead instance must not keep the spool growing). The batch path
+ // then only ever sees live, parseable events.
+ let mut items: Vec<(PathBuf, SpoolEntry)> = Vec::with_capacity(files.len());
for path in files {
- if started.elapsed() >= total_budget {
- result.remaining += 1;
- continue;
- }
let Ok(bytes) = std::fs::read(&path) else {
result.remaining += 1;
continue;
};
- let Ok(mut entry) = serde_json::from_slice::<SpoolEntry>(&bytes) else {
+ let Ok(entry) = serde_json::from_slice::<SpoolEntry>(&bytes) else {
// Unparseable spool file: drop it so it can't wedge the queue.
let _ = std::fs::remove_file(&path);
result.dropped += 1;
continue;
};
-
- // Prune events too old to be worth retrying (a long-dead instance).
if now_ms().saturating_sub(entry.created_ms) > MAX_AGE_MS {
let _ = std::fs::remove_file(&path);
result.dropped += 1;
continue;
}
+ items.push((path, entry));
+ }
+
+ let mut idx = 0;
+ let mut batch_supported = true;
+ while idx < items.len() {
+ if started.elapsed() >= total_budget {
+ result.remaining += items.len() - idx;
+ break;
+ }
- let bearer: Option<String> = match entry.auth_mode {
- AuthMode::Static => entry.token.clone(),
- AuthMode::Anonymous => None,
- AuthMode::Oidc => {
- if oidc_cache.is_none() {
- oidc_cache = Some(resolve_oidc(&client, data_dir).await);
+ let bearer = entry_bearer(&items[idx].1, &client, data_dir, &mut oidc_cache).await;
+
+ if batch_supported {
+ // Extend the chunk over consecutive entries sharing the same batch
+ // endpoint AND bearer (one request carries one Authorization header),
+ // bounded by item count and body bytes.
+ let base = batch_endpoint(&items[idx].1.url);
+ let mut end = idx + 1;
+ let mut bytes = entry_wire_len(&items[idx].1);
+ while end < items.len() && end - idx < MAX_BATCH_ITEMS {
+ if batch_endpoint(&items[end].1.url) != base {
+ break;
}
- oidc_cache.clone().flatten()
+ let next_bearer =
+ entry_bearer(&items[end].1, &client, data_dir, &mut oidc_cache).await;
+ if next_bearer != bearer {
+ break;
+ }
+ let next_len = entry_wire_len(&items[end].1);
+ if bytes + next_len > MAX_BATCH_BYTES {
+ break;
+ }
+ bytes += next_len;
+ end += 1;
}
- };
- match post_hook(
- &client,
- &entry.url,
- &entry.body,
- bearer.as_deref(),
- per_event_timeout,
- )
- .await
- {
- PostOutcome::Delivered => {
- let _ = std::fs::remove_file(&path);
- result.sent += 1;
- }
- // Transient server backpressure (429 `hook queue full`): the event
- // was never processed, so leave it untouched — no attempt bump, no
- // rewrite — and saturation never burns the entry's retry budget. It
- // rides the next pass unchanged; `MAX_AGE_MS` still bounds it.
- PostOutcome::Saturated => {
- result.remaining += 1;
+ let payload = batch_payload(&items[idx..end]);
+ match post_batch(&client, &base, &payload, bearer.as_deref(), per_event_timeout).await {
+ BatchOutcome::Accepted(k) => {
+ let k = k.min(end - idx);
+ for (path, _) in &items[idx..idx + k] {
+ let _ = std::fs::remove_file(path);
+ }
+ result.sent += k;
+ if idx + k < end {
+ // The (idx+k)th event is the one the server stopped on
+ // (fail-fast). Charge it a failed attempt and skip past it
+ // so a single bad event can't wedge the rest — the
+ // per-event loop also advances past a failed entry.
+ bump_or_drop(&items[idx + k].0, &items[idx + k].1, &mut result);
+ idx += k + 1;
+ } else {
+ idx = end;
+ }
+ }
+ BatchOutcome::Saturated => {
+ // Server ingest is full; further batches would 429 too. Leave
+ // everything queued, no attempt bump (parity with per-event).
+ result.remaining += items.len() - idx;
+ break;
+ }
+ BatchOutcome::Unsupported => {
+ // Pre-upgrade server with no /hook/batch: fall back to the
+ // per-event path for the rest of the drain. Retry items[idx]
+ // below (don't advance).
+ batch_supported = false;
+ }
+ BatchOutcome::Failed => {
+ // The batch didn't land (transport error / unexpected status).
+ // Charge each item a failed attempt so a dead server still
+ // bounds retries via MAX_ATTEMPTS, then move past the chunk.
+ for (path, entry) in &items[idx..end] {
+ bump_or_drop(path, entry, &mut result);
+ }
+ idx = end;
+ }
}
- PostOutcome::Failed => {
- entry.attempts = entry.attempts.saturating_add(1);
- if entry.attempts >= MAX_ATTEMPTS {
- let _ = std::fs::remove_file(&path);
- result.dropped += 1;
- } else {
- // Persist the bumped attempt count for the next boundary.
- let _ = note_retry_persist(rewrite_entry(&path, &entry));
+ } else {
+ // Per-event fallback (server without /hook/batch). Mirrors the
+ // original drain's per-entry semantics exactly.
+ let path = &items[idx].0;
+ let entry = &items[idx].1;
+ match post_hook(
+ &client,
+ &entry.url,
+ &entry.body,
+ bearer.as_deref(),
+ per_event_timeout,
+ )
+ .await
+ {
+ PostOutcome::Delivered => {
+ let _ = std::fs::remove_file(path);
+ result.sent += 1;
+ }
+ PostOutcome::Saturated => {
result.remaining += 1;
}
+ PostOutcome::Failed => {
+ bump_or_drop(path, entry, &mut result);
+ }
}
+ idx += 1;
}
}
result
}
+/// Resolve the bearer for a spooled entry at drain time: a `Static` token is
+/// stored inline; an `Oidc` entry resolves (and refreshes) the stored token
+/// once per drain via `oidc_cache`; `Anonymous` is None.
+async fn entry_bearer(
+ entry: &SpoolEntry,
+ client: &reqwest::Client,
+ data_dir: &Path,
+ oidc_cache: &mut Option<Option<String>>,
+) -> Option<String> {
+ match entry.auth_mode {
+ AuthMode::Static => entry.token.clone(),
+ AuthMode::Anonymous => None,
+ AuthMode::Oidc => {
+ if oidc_cache.is_none() {
+ *oidc_cache = Some(resolve_oidc(client, data_dir).await);
+ }
+ oidc_cache.clone().flatten()
+ }
+ }
+}
+
+/// 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.
+fn batch_endpoint(url: &str) -> String {
+ let path = url.split('?').next().unwrap_or(url);
+ format!("{path}/batch")
+}
+
+/// Rough wire size of one event inside a batch body (`{"url":…,"body":…}` plus
+/// framing) — used only to keep a chunk under [`MAX_BATCH_BYTES`].
+fn entry_wire_len(entry: &SpoolEntry) -> usize {
+ entry.url.len() + entry.body.len() + 32
+}
+
+/// Serialize a chunk of entries into the `/hook/batch` request body — a JSON
+/// array of `{url, body}`. Each `body` is re-parsed from its stored text so a
+/// malformed one becomes `null` (skipped server-side) instead of poisoning the
+/// whole batch.
+fn batch_payload(items: &[(PathBuf, SpoolEntry)]) -> String {
+ let arr: Vec<serde_json::Value> = items
+ .iter()
+ .map(|(_, e)| {
+ let body = serde_json::from_str::<serde_json::Value>(&e.body)
+ .unwrap_or(serde_json::Value::Null);
+ serde_json::json!({ "url": e.url, "body": body })
+ })
+ .collect();
+ serde_json::to_string(&arr).unwrap_or_else(|_| "[]".to_string())
+}
+
+/// Charge a spooled entry a failed delivery attempt: drop it once it reaches
+/// `MAX_ATTEMPTS`, else persist the bumped count for the next boundary. Updates
+/// `result.dropped` / `result.remaining` accordingly.
+fn bump_or_drop(path: &Path, entry: &SpoolEntry, result: &mut DrainResult) {
+ let mut bumped = entry.clone();
+ bumped.attempts = bumped.attempts.saturating_add(1);
+ if bumped.attempts >= MAX_ATTEMPTS {
+ let _ = std::fs::remove_file(path);
+ result.dropped += 1;
+ } else {
+ let _ = note_retry_persist(rewrite_entry(path, &bumped));
+ result.remaining += 1;
+ }
+}
+
/// Overwrite a spool file in place with the updated entry (atomic temp+rename),
/// used to persist a bumped attempt count after a failed delivery.
fn rewrite_entry(path: &Path, entry: &SpoolEntry) -> std::io::Result<()> {
@@ -325,6 +471,14 @@ fn prune_spool_file_count(spool: &Path) {
return;
}
files.sort();
+ // The spool is at its hard cap: the oldest events are about to be deleted
+ // WITHOUT ever reaching the server — silent capture loss otherwise. Surface
+ // it on stderr (never stdout, which carries the hook's JSON protocol output)
+ // so a sustained backlog dropping events is visible, not invisible.
+ eprintln!(
+ "ai-memory: hook-spool at capacity ({} > {MAX_SPOOL_FILES}); evicting {excess} oldest UNDELIVERED event(s)",
+ files.len()
+ );
for path in files.into_iter().take(excess) {
let _ = std::fs::remove_file(path);
}
@@ -562,6 +716,124 @@ mod tests {
assert_eq!(loaded.attempts, 0, "429 must not consume the retry budget");
}
+ /// A mock hook server: answers `200 {"accepted":N}` to `POST /hook/batch`
+ /// (N = array length in the body) and `202 queued` to a per-event
+ /// `POST /hook`. Counts every request so a test can assert batching. Reads
+ /// the whole request in one shot (small test payloads), mirroring the other
+ /// raw-TCP mocks in this module.
+ async fn serve_counting_hook(
+ req_count: std::sync::Arc<std::sync::atomic::AtomicUsize>,
+ batch_status: &'static str,
+ ) -> String {
+ use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let addr = listener.local_addr().unwrap();
+ tokio::spawn(async move {
+ while let Ok((mut s, _)) = listener.accept().await {
+ let rc = req_count.clone();
+ tokio::spawn(async move {
+ let mut buf = vec![0_u8; 65536];
+ let n = s.read(&mut buf).await.unwrap_or(0);
+ rc.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+ let req = String::from_utf8_lossy(&buf[..n]);
+ let is_batch = req
+ .lines()
+ .next()
+ .is_some_and(|l| l.contains("/hook/batch"));
+ let (status, body) = if is_batch {
+ let payload = req.split("\r\n\r\n").nth(1).unwrap_or("");
+ let accepted = serde_json::from_str::<serde_json::Value>(payload)
+ .ok()
+ .and_then(|v| v.as_array().map(Vec::len))
+ .unwrap_or(0);
+ (batch_status, format!("{{\"accepted\":{accepted}}}"))
+ } else {
+ ("202 Accepted", "queued".to_string())
+ };
+ let resp = format!(
+ "HTTP/1.1 {status}\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
+ body.len()
+ );
+ let _ = s.write_all(resp.as_bytes()).await;
+ });
+ }
+ });
+ addr.to_string()
+ }
+
+ fn write_spool_entry(spool: &Path, name: &str, url: String) {
+ std::fs::create_dir_all(spool).unwrap();
+ let e = entry_for(url, "{}".into(), None, false);
+ std::fs::write(spool.join(name), serde_json::to_vec(&e).unwrap()).unwrap();
+ }
+
+ #[tokio::test]
+ async fn drain_delivers_all_events_in_one_batch() {
+ let req_count = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
+ let addr = serve_counting_hook(req_count.clone(), "200 OK").await;
+ let tmp = tempfile::tempdir().unwrap();
+ let spool = spool_dir(tmp.path());
+ for i in 0..3 {
+ write_spool_entry(&spool, &format!("evt-{i}.json"), format!("http://{addr}/hook?event=e{i}"));
+ }
+
+ let r = drain(
+ &spool,
+ tmp.path(),
+ Duration::from_secs(5),
+ Duration::from_secs(2),
+ )
+ .await;
+
+ assert_eq!(r.sent, 3, "all three events delivered");
+ assert_eq!(r.remaining, 0);
+ assert!(list_entries(&spool).unwrap().is_empty(), "spool emptied");
+ assert_eq!(
+ req_count.load(std::sync::atomic::Ordering::SeqCst),
+ 1,
+ "three events ride ONE /hook/batch request (RTT amortized)"
+ );
+ }
+
+ #[tokio::test]
+ async fn drain_falls_back_to_per_event_when_batch_unsupported() {
+ // Pre-upgrade server: /hook/batch is 404, per-event /hook is 202.
+ let req_count = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
+ let addr = serve_counting_hook(req_count.clone(), "404 Not Found").await;
+ let tmp = tempfile::tempdir().unwrap();
+ let spool = spool_dir(tmp.path());
+ for i in 0..2 {
+ write_spool_entry(&spool, &format!("evt-{i}.json"), format!("http://{addr}/hook?event=e{i}"));
+ }
+
+ let r = drain(
+ &spool,
+ tmp.path(),
+ Duration::from_secs(5),
+ Duration::from_secs(2),
+ )
+ .await;
+
+ assert_eq!(r.sent, 2, "both events delivered via per-event fallback");
+ assert_eq!(r.remaining, 0);
+ assert!(list_entries(&spool).unwrap().is_empty());
+ // 1 rejected batch probe + 2 per-event POSTs.
+ assert_eq!(
+ req_count.load(std::sync::atomic::Ordering::SeqCst),
+ 3,
+ "one /hook/batch 404, then a per-event POST per remaining event"
+ );
+ }
+
+ #[test]
+ fn batch_endpoint_derives_from_event_url() {
+ assert_eq!(
+ batch_endpoint("https://h/hook?event=stop&agent=claude-code"),
+ "https://h/hook/batch"
+ );
+ assert_eq!(batch_endpoint("https://h/hook"), "https://h/hook/batch");
+ }
+
#[test]
fn spool_len_counts_entries() {
let tmp = tempfile::tempdir().unwrap();
diff --git a/crates/ai-memory-hooks/Cargo.toml b/crates/ai-memory-hooks/Cargo.toml
index ff71361a..a092f8ad 100644
--- a/crates/ai-memory-hooks/Cargo.toml
+++ b/crates/ai-memory-hooks/Cargo.toml
@@ -17,6 +17,9 @@ anyhow.workspace = true
thiserror.workspace = true
serde.workspace = true
serde_json.workspace = true
+# Parse the per-event `?event=…` query of each spooled URL in `/hook/batch`,
+# the same crate (and version) axum's `Query` extractor uses for `/hook`.
+serde_urlencoded = "0.7"
tokio.workspace = true
tracing.workspace = true
jiff.workspace = true
diff --git a/crates/ai-memory-hooks/src/router.rs b/crates/ai-memory-hooks/src/router.rs
index 704fa55f..38c827eb 100644
--- a/crates/ai-memory-hooks/src/router.rs
+++ b/crates/ai-memory-hooks/src/router.rs
@@ -26,7 +26,7 @@ use axum::http::StatusCode;
use axum::response::IntoResponse;
use axum::routing::{get, post};
use jiff::Timestamp;
-use serde::Deserialize;
+use serde::{Deserialize, Serialize};
use tracing::{debug, info, warn};
use uuid::Uuid;
@@ -190,6 +190,7 @@ pub struct HookState {
pub fn hook_router(state: HookState) -> Router {
Router::new()
.route("/hook", post(handle_hook))
+ .route("/hook/batch", post(handle_hook_batch))
.route("/handoff", get(handle_handoff))
.with_state(Arc::new(state))
}
@@ -220,6 +221,84 @@ async fn handle_hook(
(StatusCode::ACCEPTED, "queued")
}
+/// One event in a `POST /hook/batch` request — the same `{url, body}` pair a
+/// single `POST /hook` would carry, so the server reuses the per-event query
+/// parsing instead of inventing a second wire shape.
+#[derive(Debug, Deserialize)]
+pub struct HookBatchItem {
+ /// Full hook URL including the `?event=…&agent=…` query (as the client
+ /// spooled it); only the query is read here — the host/path are the
+ /// client's record of where the event was bound.
+ pub url: String,
+ /// Raw JSON event payload.
+ #[serde(default)]
+ pub body: serde_json::Value,
+}
+
+/// Response to `POST /hook/batch`: the length of the contiguous leading prefix
+/// of items that committed (equals the request length on full success).
+#[derive(Debug, Serialize)]
+pub struct HookBatchAck {
+ /// Items committed, oldest-first. The client deletes exactly this many
+ /// spool entries and re-sends the rest next pass.
+ pub accepted: usize,
+}
+
+/// Batch sibling of [`handle_hook`]. Accepts many spooled events in ONE request
+/// so a draining client amortizes the per-request cost (TLS + network RTT + the
+/// edge auth hop) over the whole batch instead of paying it per event — the
+/// dominant cost when a backlog drains to a remote, gated server, and the reason
+/// a sequential per-event drain falls behind under parallel load.
+///
+/// Unlike `handle_hook` (which spawns and answers `202` immediately), the batch
+/// is processed INLINE and FAIL-FAST: items run in order and the first error
+/// stops the batch, returning `accepted = <committed prefix>`. Inline + fail-fast
+/// keeps every item's side effects (a SessionEnd writes a session page + a
+/// handoff) inside the response window, so a partially-applied batch never
+/// commits beyond what `accepted` reports — the client deletes only that prefix.
+async fn handle_hook_batch(
+ State(state): State<Arc<HookState>>,
+ actor_ext: Option<axum::Extension<ai_memory_core::ActorContext>>,
+ Json(items): Json<Vec<HookBatchItem>>,
+) -> impl IntoResponse {
+ // All items in a batch share the drain's single identity, so the actor is
+ // captured once from the batch request (mirrors `handle_hook`).
+ let actor_user = actor_ext
+ .map(|axum::Extension(ctx)| ctx.user)
+ .unwrap_or_default();
+ // One permit for the whole batch — it holds ingest capacity for its
+ // duration, exactly as a single in-flight `/hook` request would.
+ let Ok(permit) = state.ingest_semaphore.clone().try_acquire_owned() else {
+ warn!("hook batch ingest saturated; rejecting with 429");
+ return (
+ StatusCode::TOO_MANY_REQUESTS,
+ Json(HookBatchAck { accepted: 0 }),
+ );
+ };
+ let _permit = permit;
+ let mut accepted = 0usize;
+ for item in items {
+ let query = parse_hook_query(&item.url);
+ let env = HookEnvelope::from_query_and_body(query, item.body);
+ if let Err(e) = process(&state, env, actor_user.clone()).await {
+ warn!(error = %e, accepted, "hook batch item failed; stopping (fail-fast)");
+ break;
+ }
+ accepted += 1;
+ }
+ (StatusCode::OK, Json(HookBatchAck { accepted }))
+}
+
+/// Parse the `?event=…&agent=…` query of a spooled hook URL into [`HookQuery`],
+/// mirroring axum's `Query` extractor (both use `serde_urlencoded`). A URL with
+/// no query, or an unparseable one, yields the default (empty `event`) — which
+/// `from_query_and_body` maps to an unknown event that `process` skips, so a
+/// malformed item can't error the whole batch.
+fn parse_hook_query(url: &str) -> HookQuery {
+ let qs = url.split_once('?').map_or("", |(_, q)| q);
+ serde_urlencoded::from_str(qs).unwrap_or_default()
+}
+
/// Query params for `GET /handoff`.
#[derive(Debug, Clone, Default, Deserialize)]
pub struct HandoffQuery {
@@ -1114,6 +1193,64 @@ mod tests {
assert_eq!(response.status(), StatusCode::TOO_MANY_REQUESTS);
}
+ #[tokio::test]
+ async fn handle_hook_batch_acks_processed_count() {
+ let tmp = TempDir::new().unwrap();
+ let state = make_state(&tmp).await;
+ // Two events sharing a session, carried in ONE batch request — the per
+ // event `?event=…&agent=…` query is parsed from each item's `url`.
+ let items = vec![
+ HookBatchItem {
+ url: "http://h/hook?event=session-start&agent=claude-code".into(),
+ body: serde_json::json!({ "session_id": "batch-s1" }),
+ },
+ HookBatchItem {
+ url: "http://h/hook?event=user-prompt-submit&agent=claude-code".into(),
+ body: serde_json::json!({ "session_id": "batch-s1", "prompt": "hello" }),
+ },
+ ];
+
+ let response = handle_hook_batch(State(Arc::new(state)), None, Json(items))
+ .await
+ .into_response();
+ assert_eq!(response.status(), StatusCode::OK);
+
+ let bytes = axum::body::to_bytes(response.into_body(), usize::MAX)
+ .await
+ .unwrap();
+ let ack: serde_json::Value = serde_json::from_slice(&bytes).unwrap();
+ assert_eq!(ack["accepted"], 2, "both events committed, oldest-first");
+ }
+
+ #[tokio::test]
+ async fn handle_hook_batch_returns_429_when_saturated() {
+ let tmp = TempDir::new().unwrap();
+ let mut state = make_state(&tmp).await;
+ state.ingest_semaphore = Arc::new(tokio::sync::Semaphore::new(0));
+
+ let response = handle_hook_batch(
+ State(Arc::new(state)),
+ None,
+ Json(vec![HookBatchItem {
+ url: "http://h/hook?event=session-start&agent=claude-code".into(),
+ body: serde_json::json!({}),
+ }]),
+ )
+ .await
+ .into_response();
+ assert_eq!(response.status(), StatusCode::TOO_MANY_REQUESTS);
+ }
+
+ #[test]
+ fn parse_hook_query_reads_event_and_agent() {
+ let q = parse_hook_query("http://h/hook?event=stop&agent=claude-code&cwd=%2Ftmp");
+ assert_eq!(q.event, "stop");
+ assert_eq!(q.agent.as_deref(), Some("claude-code"));
+ assert_eq!(q.cwd.as_deref(), Some("/tmp"));
+ // No query string at all → default (empty event), which `process` skips.
+ assert_eq!(parse_hook_query("http://h/hook").event, "");
+ }
+
/// An event without a cwd must fall back to the server defaults.
#[tokio::test]
async fn process_with_missing_cwd_falls_back_to_state_defaults() {