Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(admission): non-blocking webhooks (blocking=false, fire-and-forget)
Djalma Júniorca114e672432
diff --git a/crates/ai-memory-mcp/src/admin.rs b/crates/ai-memory-mcp/src/admin.rsindex 52af6286..3df3c76c 100644--- a/crates/ai-memory-mcp/src/admin.rs+++ b/crates/ai-memory-mcp/src/admin.rs@@ -2166,6 +2166,7 @@ mod tests {timeout_ms: 2_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage, AdmissionOp::PurgeProject],+ blocking: true,}]).unwrap();let wiki = Wiki::new(tmp.path(), store.writer.clone())diff --git a/crates/ai-memory-wiki/src/admission.rs b/crates/ai-memory-wiki/src/admission.rsindex 4bd71fb5..33fd8a49 100644--- a/crates/ai-memory-wiki/src/admission.rs+++ b/crates/ai-memory-wiki/src/admission.rs@@ -87,6 +87,10 @@ fn default_timeout_ms() -> u64 {2_000}+fn default_blocking() -> bool {+ true+}+/// One webhook entry in the chain. Loaded from operator config/// (`[[admission_webhooks]]`).#[derive(Debug, Clone, Serialize, Deserialize)]@@ -104,6 +108,15 @@ pub struct WebhookConfig {/// Subset of [`AdmissionOp`] this webhook subscribes to. If empty,/// the webhook is effectively disabled (it'll never fire).pub events: Vec<AdmissionOp>,+ /// When `true` (default), the webhook runs **synchronously** inside the+ /// write path — it can mutate the page (`run`) and a `Reject` failure+ /// aborts the write. When `false`, it's dispatched **fire-and-forget**+ /// AFTER the page has landed: the engine doesn't wait for it and ignores+ /// its response (so it can't mutate or reject). Use `false` for pure+ /// observers/mirrors (e.g. `git-mirror`) so a slow/down backup never adds+ /// latency to writes.+ #[serde(default = "default_blocking")]+ pub blocking: bool,}/// Per-write context passed to each webhook. Cheap to construct@@ -243,6 +256,12 @@ impl AdmissionChain {if !hook.events.contains(&ctx.op) {continue;}+ // Non-blocking webhooks are fired fire-and-forget after the write+ // (see `dispatch_async`); they never run in the synchronous,+ // mutation-capable path.+ if !hook.blocking {+ continue;+ }let payload = WebhookRequestBody {page: WebhookPagePayload {@@ -356,6 +375,9 @@ impl AdmissionChain {if !hook.events.contains(&ctx.op) {continue;}+ if !hook.blocking {+ continue;+ }let payload = WebhookRequestBody {page: WebhookPagePayload {path: page_path.unwrap_or(""),@@ -400,6 +422,69 @@ impl AdmissionChain {}Ok(())}++ /// Fire the chain's **non-blocking** webhooks for this op WITHOUT awaiting+ /// them. Called AFTER the page has landed on disk + in the index, so these+ /// are pure observers/mirrors: each is spawned fire-and-forget and its+ /// response is ignored (a non-blocking webhook can't mutate or reject).+ /// Honours the skip-list and op-subscription. For a write the caller passes+ /// the FINAL (post-mutation) page; for a delete/purge, an empty body.+ pub fn dispatch_async(+ &self,+ page_path: Option<&str>,+ frontmatter: &serde_json::Value,+ body: &str,+ ctx: &AdmissionContext,+ ) {+ for hook in self.webhooks.iter() {+ if hook.blocking {+ continue;+ }+ if ctx.skip_webhooks.iter().any(|n| n == &hook.name) {+ continue;+ }+ if !hook.events.contains(&ctx.op) {+ continue;+ }+ let client = self.client.clone();+ let url = hook.url.clone();+ let name = hook.name.clone();+ let timeout = hook.timeout_ms;+ let op = ctx.op;+ let owned_ctx = ctx.clone();+ let path = page_path.map(str::to_string);+ let frontmatter = frontmatter.clone();+ let body = body.to_string();+ tokio::spawn(async move {+ let payload = WebhookRequestBody {+ page: WebhookPagePayload {+ path: path.as_deref().unwrap_or(""),+ frontmatter: &frontmatter,+ body: &body,+ },+ ctx: &owned_ctx,+ };+ match client+ .post(&url)+ .header("X-Memory-Op", op.as_header_value())+ .timeout(Duration::from_millis(timeout))+ .json(&payload)+ .send()+ .await+ {+ Ok(resp) if resp.status().is_success() => {+ tracing::debug!(webhook = %name, op = op.as_header_value(), "admission async ok");+ }+ Ok(resp) => {+ tracing::warn!(webhook = %name, status = %resp.status(), "admission async error response");+ }+ Err(e) => {+ tracing::warn!(webhook = %name, error = %e, "admission async request failed");+ }+ }+ });+ }+ }}#[cfg(test)]diff --git a/crates/ai-memory-wiki/src/wiki.rs b/crates/ai-memory-wiki/src/wiki.rsindex 47a7661b..efd42bbf 100644--- a/crates/ai-memory-wiki/src/wiki.rs+++ b/crates/ai-memory-wiki/src/wiki.rs@@ -238,6 +238,7 @@ impl Wiki {self.resolve_admission_names(workspace_id, project_id, &mut ctx).await;chain.notify(Some(path.as_str()), &ctx).await?;+ chain.dispatch_async(Some(path.as_str()), &serde_json::Value::Null, "", &ctx);}let abs = self.abs_path(workspace_id, project_id, path);match std::fs::remove_file(&abs) {@@ -274,6 +275,7 @@ impl Wiki {self.resolve_admission_names(workspace_id, project_id, &mut ctx).await;chain.notify(None, &ctx).await?;+ chain.dispatch_async(None, &serde_json::Value::Null, "", &ctx);}let root = self.project_root(workspace_id, project_id);match std::fs::remove_dir_all(&root) {@@ -447,7 +449,7 @@ impl Wiki {// frontmatter/body here propagate to both the on-disk markdown// (via emit below) and the store's `frontmatter_json` / `body`// (via the upsert below) atomically. See `crate::admission`.- if let Some(chain) = &self.admission_chain {+ let resolved_ctx = if let Some(chain) = &self.admission_chain {let mut ctx = admission_ctx.unwrap_or_default();// Single identity source: the webhook actor is the same// `ActorContext` used for on-disk attribution (req.actor),@@ -471,8 +473,12 @@ impl Wiki {ctx.project = name;}}+ // Blocking webhooks run synchronously (they may mutate / reject).chain.run(&path, &mut markdown, &ctx).await?;- }+ Some(ctx)+ } else {+ None+ };// Re-derive title + links from the (possibly mutated) markdown.// We do this after the chain so explicit title overrides survive@@ -491,6 +497,18 @@ impl Wiki {}atomic::write_atomic(&abs, emitted.as_bytes())?;+ // Non-blocking webhooks fire-and-forget AFTER the page has landed on+ // disk (the markdown-in-git source of truth). They only observe/mirror+ // the final page — never block the write or mutate it.+ if let (Some(chain), Some(ctx)) = (&self.admission_chain, &resolved_ctx) {+ chain.dispatch_async(+ Some(path.as_str()),+ &markdown.frontmatter,+ &markdown.body,+ ctx,+ );+ }+let Markdown {frontmatter: final_frontmatter,body: final_body,@@ -1030,6 +1048,7 @@ mod tests {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();diff --git a/crates/ai-memory-wiki/tests/admission.rs b/crates/ai-memory-wiki/tests/admission.rsindex 8a868ed2..79e3d901 100644--- a/crates/ai-memory-wiki/tests/admission.rs+++ b/crates/ai-memory-wiki/tests/admission.rs@@ -71,6 +71,7 @@ async fn webhook_mutating_frontmatter_is_applied() {timeout_ms: 2_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -96,6 +97,7 @@ async fn webhook_204_is_noop() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -123,6 +125,7 @@ async fn failure_policy_ignore_swallows_error() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -150,6 +153,7 @@ async fn failure_policy_reject_aborts_write() {timeout_ms: 1_000,failure_policy: FailurePolicy::Reject,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -184,6 +188,7 @@ async fn skip_webhooks_short_circuits_named_hook() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -221,6 +226,7 @@ async fn op_filter_skips_webhook_not_subscribed_to_event() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::Consolidate],+ blocking: true,}]).unwrap();@@ -274,6 +280,7 @@ async fn chain_runs_in_order_each_sees_previous_mutation() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,},WebhookConfig {name: "second".into(),@@ -281,6 +288,7 @@ async fn chain_runs_in_order_each_sees_previous_mutation() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,},]).unwrap();@@ -324,6 +332,7 @@ async fn x_memory_op_header_is_sent() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::Consolidate],+ blocking: true,}]).unwrap();@@ -358,6 +367,7 @@ async fn actor_context_is_propagated_in_payload() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -401,6 +411,7 @@ async fn webhook_can_mutate_body_too() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -426,6 +437,7 @@ async fn chain_rejects_more_than_max_admission_webhooks() {timeout_ms: 100,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}).collect();let err = AdmissionChain::new(too_many).expect_err("should refuse");@@ -456,6 +468,7 @@ async fn oversized_response_is_treated_as_noop() {timeout_ms: 5_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -494,6 +507,7 @@ async fn workspace_and_project_names_propagate_in_payload() {timeout_ms: 1_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -540,6 +554,7 @@ async fn notify_delete_sends_op_and_path() {timeout_ms: 2_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::Delete],+ blocking: true,}]).unwrap();@@ -565,6 +580,7 @@ async fn notify_purge_has_op_and_no_path() {timeout_ms: 2_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::PurgeProject],+ blocking: true,}]).unwrap();@@ -592,6 +608,7 @@ async fn notify_respects_op_subscription() {timeout_ms: 2_000,failure_policy: FailurePolicy::Ignore,events: vec![AdmissionOp::WritePage],+ blocking: true,}]).unwrap();@@ -606,3 +623,63 @@ async fn notify_respects_op_subscription() {"delete must not reach a write-only webhook");}++#[tokio::test]+async fn non_blocking_webhook_skipped_by_run_but_dispatched_async() {+ // A `blocking: false` webhook must NOT run in the synchronous `run`+ // path (it can't mutate/reject and shouldn't add write latency), and+ // MUST fire via `dispatch_async` after the page has landed.+ let fired = Arc::new(AtomicBool::new(false));+ let fired_in_handler = fired.clone();+ let app = Router::new().route(+ "/sync",+ post(move || {+ let fired = fired_in_handler.clone();+ async move {+ fired.store(true, Ordering::SeqCst);+ StatusCode::NO_CONTENT+ }+ }),+ );+ let base = spawn_server(app).await;+ let chain = AdmissionChain::new(vec![WebhookConfig {+ name: "mirror".into(),+ url: format!("{base}/sync"),+ timeout_ms: 1_000,+ failure_policy: FailurePolicy::Ignore,+ events: vec![AdmissionOp::WritePage],+ blocking: false,+ }])+ .unwrap();++ let (path, mut md) = page();++ // run() must NOT fire a non-blocking webhook.+ chain+ .run(&path, &mut md, &AdmissionContext::default())+ .await+ .unwrap();+ tokio::time::sleep(Duration::from_millis(50)).await;+ assert!(+ !fired.load(Ordering::SeqCst),+ "run() must skip a non-blocking webhook"+ );++ // dispatch_async fires it (fire-and-forget; poll for the spawned task).+ chain.dispatch_async(+ Some(path.as_str()),+ &md.frontmatter,+ &md.body,+ &AdmissionContext::default(),+ );+ for _ in 0..40 {+ if fired.load(Ordering::SeqCst) {+ break;+ }+ tokio::time::sleep(Duration::from_millis(25)).await;+ }+ assert!(+ fired.load(Ordering::SeqCst),+ "dispatch_async must fire the non-blocking webhook"+ );+}diff --git a/docs/admission-webhooks.md b/docs/admission-webhooks.mdindex c013c740..1ee37e38 100644--- a/docs/admission-webhooks.md+++ b/docs/admission-webhooks.md@@ -187,15 +187,34 @@ url = "http://contributors.memory.svc.cluster.local:8080/enrich"timeout_ms = 2000 # per requestfailure_policy = "ignore" # ignore | rejectevents = ["write_page", "consolidate"]+blocking = true # runs synchronously; may mutate / reject[[admission_webhooks]]name = "git-mirror"url = "http://git-mirror.memory.svc.cluster.local:8080/sync"timeout_ms = 2000failure_policy = "ignore"-events = ["write_page", "consolidate"]+events = ["write_page", "consolidate", "delete", "purge_project"]+blocking = false # fire-and-forget after the write; never blocks it```+### `blocking` (default `true`)++A webhook is either **blocking** or **non-blocking**:++- **`blocking = true`** (default) — runs *synchronously* inside the write path.+ It can mutate the page (`write_page`/`consolidate`), and a `reject` failure+ aborts the write. The write waits for it (up to `timeout_ms`). Use for+ enrichers/validators (e.g. `contributors`, `validate-no-secrets`).+- **`blocking = false`** — dispatched *fire-and-forget* **after** the page has+ landed on disk. The engine does not wait for it and ignores its response, so+ it **cannot mutate or reject** — it only observes/mirrors the final page. Use+ for pure backups/mirrors (e.g. `git-mirror`) so a slow or down sink never adds+ latency to writes. Still honours `events` and the skip list.++Since the blocking chain is sequential, total worst-case write latency is+`Σ timeout_ms` over the **blocking** webhooks only; non-blocking ones add none.+Env override (figment env layer):```bash