Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(install-hooks): generated TS integrations spool failed deliveries
AkitaOnRails6498ac57036d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex b9b80342..80675baf 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -77,6 +77,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0||||||| a613bf6d### Fixed+- The generated TypeScript integrations (OpenCode, OMP, Pi, OpenClaw)+ no longer silently drop lifecycle events when the server is+ unreachable (#580). A failed or 5xx delivery is spooled to+ `<data_dir>/hook-spool/` in the CLI's exact on-disk format — so+ `ai-memory hook-drain` and the shell hooks' piggyback drain deliver+ the backlog too — and each integration drains its own spool once the+ server is reachable again. Entries carry an idempotency key minted at+ spool time, so concurrent drains cannot double-ingest an event.- `memory_read_page` no longer ships a root-level `anyOf` in its toolschema (#577): the Anthropic Messages API rejects root combinatorsoutright, so any provider-agnostic client routing tools through itdiff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rsindex 14f1d879..595199ca 100644--- a/crates/ai-memory-cli/src/commands/install_hooks.rs+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs@@ -2873,6 +2873,84 @@ pub(crate) const TS_TOML_FLAG: &str = r#"function tomlFlag(text: string, key: streturn undefined;}"#;+/// Post-process a generated TypeScript integration so failed hook+/// deliveries SPOOL instead of vanishing (#580). The shell hooks have+/// spooled since day one; the TS plugins fire-and-forgot, so a laptop+/// off the server's network lost whole sessions of capture. Entries are+/// written in the CLI spool's exact on-disk contract+/// (`{ms:013}-{pid}-{seq:016x}.json`, `SpoolEntry` fields, 0700 dir /+/// 0600 files, tmp+rename) so `ai-memory hook-drain` and the shell+/// hooks' piggyback drain deliver them too; the plugin also drains its+/// own spool on first use and after any queue flush. An `ingest_key`+/// is minted at spool time, so a double drain (plugin + CLI) dedupes+/// server-side instead of double-ingesting.+///+/// Implemented as a transformation over the rendered source (rather+/// than another copy of the template) so all TS integrations share one+/// audited implementation; it fails loudly if the delivery block it+/// patches ever drifts.+fn add_hook_spooling(source: String) -> Result<String> {+ const FETCH_BLOCK: &str = r#" try {+ await fetch(item.url, {+ method: "POST",+ headers: { "Content-Type": "application/json", ...authHeaders() },+ body: JSON.stringify(item.payload),+ signal: timeoutSignal(HOOK_REQUEST_TIMEOUT_MS),+ }).catch(() => undefined);+ } catch (_e) {+ // Best-effort capture. Hooks must never block the agent.+ }"#;+ const FETCH_REPLACEMENT: &str = r#" try {+ const resp = await fetch(item.url, {+ method: "POST",+ headers: { "Content-Type": "application/json", ...authHeaders() },+ body: JSON.stringify(item.payload),+ signal: timeoutSignal(HOOK_REQUEST_TIMEOUT_MS),+ }).catch(() => undefined);+ // Unreachable server or 5xx: keep the event on disk for a later+ // drain (#580). 4xx is permanent - spooling it would retry a+ // rejection forever.+ if (!resp || resp.status >= 500) spoolFailedHook(item.url, item.payload);+ } catch (_e) {+ try { spoolFailedHook(item.url, item.payload); } catch (_e2) {}+ }"#;+ const ENQUEUE_ANCHOR: &str = "function enqueueHook(";+ let runtime = crate::commands::render_shared::ts_spool_runtime();+ if !source.contains(FETCH_BLOCK) {+ anyhow::bail!(+ "TS integration template drifted: the hook delivery block the \+ spool patch targets was not found"+ );+ }+ if source.matches(ENQUEUE_ANCHOR).count() != 1 {+ anyhow::bail!("TS integration template drifted: enqueueHook anchor not unique");+ }+ let mut out = source.replacen(FETCH_BLOCK, FETCH_REPLACEMENT, 1);+ out = out.replacen(ENQUEUE_ANCHOR, &format!("{runtime}{ENQUEUE_ANCHOR}"), 1);+ // Drain the offline spool alongside every queue flush, and extend the+ // imports the runtime needs.+ let drain_anchor =+ "async function drainHookQueue(): Promise<void> {\n if (hookDraining) return;";+ if out.matches(drain_anchor).count() != 1 {+ anyhow::bail!("TS integration template drifted: drainHookQueue anchor not unique");+ }+ out = out.replacen(+ drain_anchor,+ "async function drainHookQueue(): Promise<void> {\n if (hookDraining) return;\n requestSpoolDrain();",+ 1,+ );+ let import_anchor = "import { closeSync, existsSync, openSync, readFileSync as readMarkerText, readSync } from \"node:fs\";";+ if out.matches(import_anchor).count() != 1 {+ anyhow::bail!("TS integration template drifted: node:fs import anchor not unique");+ }+ out = out.replacen(+ import_anchor,+ "import { closeSync, existsSync, mkdirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, renameSync, unlinkSync, writeFileSync } from \"node:fs\";",+ 1,+ );+ Ok(out)+}+fn build_opencode_plugin(server_url: &str,auth_token: Option<&str>,@@ -2883,7 +2961,7 @@ fn build_opencode_plugin(.unwrap_or_else(|| "const TOKEN: string | null = null;\n".to_string());let apply_marker_params = ts_apply_marker_params(project_strategy);let capture_policy = ts_capture_policy_v1();- format!(+ let body = format!(r#"// Auto-generated by `ai-memory install-hooks --agent opencode --apply`.// Edit by re-running the command, not by hand — install-hooks// will overwrite this file (with a `.bak-<ts>` backup) on each@@ -3246,7 +3324,10 @@ export default AiMemoryHooks;"#,server_literal = ts_string_literal(server_url),token_line = token_line,- )+ );+ // Anchors are compile-time constants over this same file's template;+ // a mismatch is a template edit that forgot the spool patch.+ add_hook_spooling(body).expect("generated TS integration lost its hook-spool anchors")}/// Warn when Pi and OMP resolve to the same extensions directory.@@ -3611,7 +3692,7 @@ fn build_omp_extension(.unwrap_or_else(|| "const TOKEN: string | null = null;\n".to_string());let apply_marker_params = ts_apply_marker_params(project_strategy);let capture_policy = ts_capture_policy_v1();- format!(+ let body = format!(r#"// Auto-generated by `ai-memory install-hooks --agent omp --apply`.// Edit by re-running the command, not by hand — install-hooks// will overwrite this file (with a `.bak-<ts>` backup) on each@@ -3937,7 +4018,10 @@ export default function AiMemoryExtension(api: any): void {{"#,server_literal = ts_string_literal(server_url),token_line = token_line,- )+ );+ // Anchors are compile-time constants over this same file's template;+ // a mismatch is a template edit that forgot the spool patch.+ add_hook_spooling(body).expect("generated TS integration lost its hook-spool anchors")}fn render_agent(@@ -7136,6 +7220,108 @@ model = "gpt-5"assert!(!generated.contains("void fetch(url, {"));}+ #[test]+ fn generated_ts_integrations_spool_failed_deliveries() {+ // #580: every queue-based TS integration must persist a failed+ // delivery instead of dropping it, and must self-drain the spool.+ for (name, source) in [+ (+ "opencode",+ build_opencode_plugin("http://127.0.0.1:49374", Some("tok"), None),+ ),+ (+ "omp",+ build_omp_extension("http://127.0.0.1:49374", Some("tok"), None),+ ),+ (+ "pi",+ build_pi_extension("http://127.0.0.1:49374", Some("tok"), None),+ ),+ ] {+ // The fire-and-forget delivery must be gone...+ assert!(+ !source.contains("}).catch(() => undefined);\n } catch (_e) {"),+ "{name}: still fire-and-forgets failed deliveries"+ );+ // ...replaced by capture + spool of network failures and 5xx.+ assert!(+ source.contains(+ "if (!resp || resp.status >= 500) spoolFailedHook(item.url, item.payload);"+ ),+ "{name}: missing spool-on-failure"+ );+ // The spool runtime is present and CLI-compatible.+ assert!(source.contains("function spoolFailedHook("), "{name}");+ assert!(source.contains("async function drainHookSpool()"), "{name}");+ assert!(+ source.contains(r#"return join(env, "hook-spool");"#),+ "{name}: spool dir must honour AI_MEMORY_DATA_DIR"+ );+ // Every queue flush also kicks a spool drain.+ assert!(+ source.contains("if (hookDraining) return;\n requestSpoolDrain();"),+ "{name}: drainHookQueue must trigger the spool drain"+ );+ // The runtime's fs needs made it into the import line.+ for f in [+ "mkdirSync",+ "writeFileSync",+ "renameSync",+ "readdirSync",+ "unlinkSync",+ ] {+ assert!(+ source.contains(&format!("{f},")) || source.contains(&format!("{f} }}")),+ "{name}: node:fs import missing {f}"+ );+ }+ }+ }++ #[test]+ fn ts_spool_entries_are_readable_by_the_cli_drain() {+ // The TS runtime writes the CLI hook-spool's exact on-disk contract.+ // Mirror the bytes the generated code produces and prove the CLI+ // side parses them: entry JSON deserializes, the filename's+ // timestamp is honoured, and the body survives round-tripping.+ let created_ms: u64 = 1_756_800_000_000;+ // Filename exactly as the TS builds it:+ // `${String(createdMs).padStart(13, "0")}-${process.pid}-${seq}.json`+ let name = format!("{created_ms:013}-4242-{:016x}.json", 7u64);+ // Entry JSON exactly as the TS `JSON.stringify` emits it (key order+ // irrelevant to serde, but the shapes and enum strings are load-bearing).+ let json = format!(+ r#"{{"url":"http://127.0.0.1:49374/hook?event=stop&agent=open-code&ingest_key=ts18f3","body":"{{\"session_id\":\"s1\"}}","created_ms":{created_ms},"auth_mode":"static","token":"tok","attempts":0}}"#+ );+ let entry: crate::commands::hook_spool::SpoolEntry =+ serde_json::from_str(&json).expect("CLI drain must parse a TS-written entry");+ assert_eq!(entry.created_ms, created_ms);+ assert_eq!(entry.token.as_deref(), Some("tok"));+ assert_eq!(entry.attempts, 0);+ assert!(entry.url.contains("ingest_key=ts18f3"));+ serde_json::from_str::<serde_json::Value>(&entry.body)+ .expect("TS body must be raw JSON, not double-encoded");++ // And the anonymous variant (no token installed).+ let anon = r#"{"url":"http://h/hook?event=stop&agent=omp","body":"{}","created_ms":1,"auth_mode":"none","attempts":0}"#;+ serde_json::from_str::<crate::commands::hook_spool::SpoolEntry>(anon)+ .expect("auth_mode none must parse");++ // The timestamp-bearing filename is one the spool reader accepts:+ // spool_health derives oldest-age from names without reading files.+ let dir = tempfile::tempdir().expect("tempdir");+ let spool = dir.path().join("hook-spool");+ std::fs::create_dir_all(&spool).expect("mkdir");+ std::fs::write(spool.join(&name), json.as_bytes()).expect("write");+ assert_eq!(crate::commands::hook_spool::spool_len(&spool), 1);+ let health = crate::commands::hook_spool::spool_health(&spool);+ assert_eq!(health.pending, 1);+ assert!(+ health.oldest_age_ms.is_some(),+ "TS filename's 13-digit timestamp must be readable: {name}"+ );+ }+#[test]fn opencode_plugin_uses_real_plugin_hooks() {let plugin = build_opencode_plugin("http://127.0.0.1:49374", Some("tok"), None);diff --git a/crates/ai-memory-cli/src/commands/openclaw_plugin.rs b/crates/ai-memory-cli/src/commands/openclaw_plugin.rsindex f05201c3..e3df6881 100644--- a/crates/ai-memory-cli/src/commands/openclaw_plugin.rs+++ b/crates/ai-memory-cli/src/commands/openclaw_plugin.rs@@ -8,7 +8,7 @@ use anyhow::{Context, Result};use crate::cli::InstallHooksArgs;use crate::commands::apply_shared::{ApplyOutcome, apply_atomic};-use crate::commands::render_shared::{ts_capture_policy_v1, ts_string_literal};+use crate::commands::render_shared::{ts_capture_policy_v1, ts_spool_runtime, ts_string_literal};pub(crate) const PLUGIN_ID: &str = "ai-memory";pub(crate) const PACKAGE_NAME: &str = "@ai-memory/openclaw-plugin";@@ -311,7 +311,7 @@ fn build_plugin(import {{ definePluginEntry }} from "openclaw/plugin-sdk/plugin-entry";import {{ execFileSync }} from "node:child_process";-import {{ closeSync, existsSync, openSync, readFileSync as readMarkerText, readSync }} from "node:fs";+import {{ closeSync, existsSync, mkdirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, renameSync, unlinkSync, writeFileSync }} from "node:fs";import {{ basename, dirname, join, resolve, sep }} from "node:path";import {{ homedir }} from "node:os";@@ -446,7 +446,7 @@ function postPreCompact(event: any, ctx: any): void {{postHook("pre-compact", payload(event, ctx, {{ reason: event?.reason }}));}}-function postHook(eventName: string, body: Record<string, unknown>): void {{+{spool_runtime}function postHook(eventName: string, body: Record<string, unknown>): void {{const url = new URL(`${{SERVER}}/hook`);url.searchParams.set("event", eventName);url.searchParams.set("agent", AGENT);@@ -454,14 +454,23 @@ function postHook(eventName: string, body: Record<string, unknown>): void {{const policy = capturePolicy(body, typeof body.cwd === "string" ? body.cwd : undefined);if (policy.disposition === "drop") return;try {{+ // Fire-and-forget, but never silent loss: an unreachable server or+ // 5xx spools the event in the CLI hook-spool format for a later+ // drain (#580); a delivered post opportunistically drains backlog.void fetch(url, {{method: "POST",headers: {{ "Content-Type": "application/json", ...authHeaders() }},body: JSON.stringify(policy.payload),signal: timeoutSignal(500),- }}).catch(() => undefined);+ }})+ .catch(() => undefined)+ .then((resp) => {{+ if (!resp || resp.status >= 500) spoolFailedHook(url, policy.payload);+ else requestSpoolDrain();+ }})+ .catch(() => undefined);}} catch (_e) {{- // Fire-and-forget. Hooks must never block OpenClaw.+ try {{ spoolFailedHook(url, policy.payload); }} catch (_e2) {{}}}}}}@@ -546,6 +555,7 @@ export default definePluginEntry({{"#,server_literal = ts_string_literal(server_url),token_line = token_line,+ spool_runtime = ts_spool_runtime(),)}@@ -554,6 +564,33 @@ mod tests {use super::*;use tempfile::TempDir;+ #[test]+ fn openclaw_plugin_spools_failed_deliveries() {+ // #580: OpenClaw's fire-and-forget postHook must persist failures+ // in the CLI hook-spool format and drain the backlog on success.+ let plugin = build_plugin("http://127.0.0.1:49374", Some("tok"), None);+ assert!(plugin.contains("function spoolFailedHook("));+ assert!(plugin.contains("async function drainHookSpool()"));+ assert!(+ plugin+ .contains("if (!resp || resp.status >= 500) spoolFailedHook(url, policy.payload);")+ );+ assert!(plugin.contains("else requestSpoolDrain();"));+ assert!(plugin.contains(r#"return join(env, "hook-spool");"#));+ for f in [+ "mkdirSync",+ "writeFileSync",+ "renameSync",+ "readdirSync",+ "unlinkSync",+ ] {+ assert!(+ plugin.contains(&format!("{f},")) || plugin.contains(&format!("{f} }}")),+ "node:fs import missing {f}"+ );+ }+ }+#[test]fn package_has_manifest_and_hook_entrypoint() {let package = package_json();diff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rsindex af13982f..12110310 100644--- a/crates/ai-memory-cli/src/commands/render_shared.rs+++ b/crates/ai-memory-cli/src/commands/render_shared.rs@@ -1759,6 +1759,114 @@ fn claude_code_windows_command_is_unchanged_by_the_codex_fix() {assert!(cmd.starts_with('"'), "expected a quoted exe path: {cmd}");}+/// TypeScript runtime shared by every generated integration that must+/// survive an unreachable server (#580): a spool writer emitting the CLI+/// `hook-spool` on-disk contract (same filenames, same `SpoolEntry` JSON,+/// same permissions) plus a self-drain. Callers only need `TOKEN`,+/// `timeoutSignal`, and the node `join`/`homedir`/fs imports in scope.+pub(crate) fn ts_spool_runtime() -> &'static str {+ r#"+// ---- offline spool (#580): the same on-disk contract as `ai-memory hook` ----+// <data_dir>/hook-spool, entries the CLI's hook-drain understands. Written on+// delivery failure, drained here on first use and after each queue flush; the+// ingest_key minted at spool time makes a double drain idempotent server-side.+function hookSpoolDir(): string {+ const env = process.env.AI_MEMORY_DATA_DIR;+ if (env && env.trim()) return join(env, "hook-spool");+ const home = homedir();+ const base =+ process.platform === "darwin"+ ? join(home, "Library", "Application Support", "ai-memory")+ : process.platform === "win32"+ ? join(process.env.LOCALAPPDATA ?? join(home, "AppData", "Local"), "ai-memory")+ : join(process.env.XDG_DATA_HOME?.trim() || join(home, ".local", "share"), "ai-memory");+ return join(base, "hook-spool");+}++let spoolSeq = 0;++function spoolFailedHook(url: URL | string, payload: Record<string, unknown>): void {+ try {+ const dir = hookSpoolDir();+ mkdirSync(dir, { recursive: true, mode: 0o700 });+ const createdMs = Date.now();+ // Idempotency key minted ONCE at spool time and baked into the URL,+ // so this plugin's drain and the CLI's drain can both deliver the+ // entry without double-ingesting.+ const key = `ts${createdMs.toString(16)}${Math.floor(Math.random() * 0xffffffff).toString(16)}`;+ const u = new URL(String(url));+ if (!u.searchParams.has("ingest_key")) u.searchParams.set("ingest_key", key);+ const token = TOKEN;+ const entry = {+ url: u.toString(),+ body: JSON.stringify(payload),+ created_ms: createdMs,+ auth_mode: token ? "static" : "none",+ ...(token ? { token } : {}),+ attempts: 0,+ };+ const seq = (spoolSeq++ & 0xffffffff).toString(16).padStart(16, "0");+ const name = `${String(createdMs).padStart(13, "0")}-${process.pid}-${seq}.json`;+ const tmp = join(dir, `${name}.tmp`);+ writeFileSync(tmp, JSON.stringify(entry), { mode: 0o600 });+ renameSync(tmp, join(dir, name));+ } catch (_e) {+ // Spooling is best-effort on top of best-effort capture.+ }+}++let spoolDrainPromise: Promise<void> | undefined;++function requestSpoolDrain(): void {+ if (spoolDrainPromise) return;+ spoolDrainPromise = drainHookSpool().finally(() => {+ spoolDrainPromise = undefined;+ });+}++async function drainHookSpool(): Promise<void> {+ let names: string[];+ try {+ names = readdirSync(hookSpoolDir()).filter((n) => n.endsWith(".json"));+ } catch (_e) {+ return; // no spool dir = nothing queued+ }+ names.sort();+ for (const name of names.slice(0, 500)) {+ const file = join(hookSpoolDir(), name);+ let entry: { url?: string; body?: string; token?: string };+ try {+ entry = JSON.parse(readMarkerText(file, "utf8"));+ } catch (_e) {+ continue; // torn or foreign file; leave it for the CLI drain+ }+ if (!entry.url || typeof entry.body !== "string") continue;+ try {+ const headers: Record<string, string> = { "Content-Type": "application/json" };+ if (entry.token) headers["Authorization"] = `Bearer ${entry.token}`;+ const resp = await fetch(entry.url, {+ method: "POST",+ headers,+ body: entry.body,+ signal: timeoutSignal(2000),+ }).catch(() => undefined);+ if (!resp) return; // still unreachable; stop, keep the backlog+ if (resp.ok || (resp.status >= 400 && resp.status < 500)) {+ // Delivered, or permanently rejected - either way, done with it.+ try { unlinkSync(file); } catch (_e) {}+ } else {+ return; // 5xx: server unhappy; retry a later drain+ }+ } catch (_e) {+ return;+ }+ await new Promise<void>((r) => setTimeout(r, 50));+ }+}++"#+}+#[cfg(test)]mod tests {use super::*;diff --git a/docs/install.md b/docs/install.mdindex 39a08576..b0243069 100644--- a/docs/install.md+++ b/docs/install.md@@ -1353,6 +1353,17 @@ OpenClaw, OMP / Oh My Pi, and Pi do not need script extraction because`install-hooks` generates TypeScript plugin/extension files for theminstead. For Pi, the generated extension also provides the MCP bridge.+The generated TypeScript integrations survive an unreachable server the+same way the native hooks do: a delivery that fails at the network level+(or gets a 5xx) is written to `<data_dir>/hook-spool/` in the exact+format `ai-memory hook-drain` reads, and the plugin drains that backlog+itself once the server is reachable again — so a day of laptop work off+the server's network is captured, not silently dropped. Each spooled+entry carries an idempotency key, so the plugin's own drain and a+manual `hook-drain` can race without double-ingesting. Note the spool+lands in the *agent host's* data dir (`AI_MEMORY_DATA_DIR` or the+platform default), which is where a native `ai-memory` install looks.+This path is friction-free when:- You have curl + bash but not docker- You don't need to run a local ai-memory server (you're a client of