Skip to content

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.md
index 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 tool
schema (#577): the Anthropic Messages API rejects root combinators
outright, so any provider-agnostic client routing tools through it
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index 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: st
return 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.rs
index 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.rs
index 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.md
index 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 them
instead. 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