Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! Generated OpenClaw lifecycle plugin support.
use std::io::ErrorKind;
use std::path::{Path, PathBuf};
use std::process::Command;
use anyhow::{Context, Result};
use crate::cli::InstallHooksArgs;
use crate::commands::apply_shared::{ApplyOutcome, apply_atomic};
use crate::commands::render_shared::{
ts_auth_headers_fn, ts_capture_policy_v1, ts_resolve_token_fn, ts_spool_runtime,
ts_string_literal, ts_timeout_signal,
};
pub(crate) const PLUGIN_ID: &str = "ai-memory";
pub(crate) const PACKAGE_NAME: &str = "@ai-memory/openclaw-plugin";
pub(crate) const PACKAGE_JSON: &str = "package.json";
pub(crate) const MANIFEST_JSON: &str = "openclaw.plugin.json";
pub(crate) const ENTRYPOINT_TS: &str = "index.ts";
const OPENCLAW_BIN: &str = "openclaw";
/// Write and install the generated OpenClaw plugin package.
pub(crate) fn apply(
server_url: &str,
auth_token: Option<&str>,
args: &InstallHooksArgs,
capture_mode: &str,
) -> Result<()> {
let plugin_dir = resolve_plugin_dir(args)?;
let strategy = args
.project_strategy
.and_then(crate::cli::ProjectStrategyArg::baked);
let outcomes = write_package(&plugin_dir, server_url, auth_token, strategy, capture_mode)?;
for (path, outcome) in &outcomes {
println!(
"✓ {} {} ({})",
outcome.verb(),
path.display(),
outcome_detail(*outcome)
);
}
match install_plugin(&plugin_dir)? {
InstallStatus::Installed => {
println!();
println!("OpenClaw plugin installed from {}.", plugin_dir.display());
println!(
"If your OpenClaw gateway did not auto-restart, run `openclaw gateway restart`."
);
println!("Verify with `openclaw plugins inspect ai-memory --runtime --json`.");
}
InstallStatus::CliMissing => {
println!();
println!("OpenClaw CLI not found on PATH; plugin package was written only.");
println!("Install it with:");
println!(
" openclaw plugins install --link {} --force",
plugin_dir.display()
);
println!(" openclaw gateway restart");
println!(" openclaw plugins inspect ai-memory --runtime --json");
}
}
Ok(())
}
/// Print the generated package for manual installation.
pub(crate) fn render(
server_url: &str,
auth_token: Option<&str>,
project_strategy: Option<&str>,
capture_mode: &str,
) {
println!("# OpenClaw native plugin package");
println!("# Re-run with `--apply` to write the package and call:");
println!("# openclaw plugins install --link <package-dir> --force");
println!("# OpenClaw loads plugin code at gateway startup; restart if your");
println!("# managed gateway does not auto-restart after install.");
println!();
println!("## {PACKAGE_JSON}");
println!("{}", package_json());
println!("## {MANIFEST_JSON}");
println!("{}", manifest_json());
println!("## {ENTRYPOINT_TS}");
println!(
"{}",
build_plugin(server_url, auth_token, project_strategy, capture_mode)
);
}
fn outcome_detail(outcome: ApplyOutcome) -> &'static str {
match outcome {
ApplyOutcome::Created => "new file",
ApplyOutcome::Updated => "backup written next to it",
ApplyOutcome::NoOp => "already up to date",
}
}
fn resolve_plugin_dir(args: &InstallHooksArgs) -> Result<PathBuf> {
if let Some(path) = &args.config_file {
return Ok(path.clone());
}
default_plugin_dir()
}
pub(crate) fn default_plugin_dir() -> Result<PathBuf> {
Ok(dirs::data_local_dir()
.context("could not locate the user data-local directory")?
.join("ai-memory")
.join("openclaw-plugin"))
}
fn write_package(
plugin_dir: &Path,
server_url: &str,
auth_token: Option<&str>,
project_strategy: Option<&str>,
capture_mode: &str,
) -> Result<Vec<(PathBuf, ApplyOutcome)>> {
let files = [
(PACKAGE_JSON, package_json()),
(MANIFEST_JSON, manifest_json()),
(
ENTRYPOINT_TS,
build_plugin(server_url, auth_token, project_strategy, capture_mode),
),
];
let mut outcomes = Vec::with_capacity(files.len());
for (name, body) in files {
let path = plugin_dir.join(name);
let outcome = apply_atomic(&path, move |_existing| Ok(body.clone()))?;
outcomes.push((path, outcome));
}
Ok(outcomes)
}
enum InstallStatus {
Installed,
CliMissing,
}
fn install_plugin(plugin_dir: &Path) -> Result<InstallStatus> {
let output = match Command::new(OPENCLAW_BIN)
.args(["plugins", "install", "--link"])
.arg(plugin_dir)
.arg("--force")
.output()
{
Ok(output) => output,
Err(e) if e.kind() == ErrorKind::NotFound => return Ok(InstallStatus::CliMissing),
Err(e) => return Err(e).context("running openclaw plugins install"),
};
if !output.status.success() {
anyhow::bail!(
"openclaw plugins install failed with status {}\nstdout:\n{}\nstderr:\n{}",
output.status,
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
}
let enable = Command::new(OPENCLAW_BIN)
.args(["plugins", "enable", PLUGIN_ID])
.output()
.context("running openclaw plugins enable")?;
if !enable.status.success() {
eprintln!(
"# warning: `openclaw plugins enable ai-memory` exited with {}\n# stdout:\n{}\n# stderr:\n{}",
enable.status,
String::from_utf8_lossy(&enable.stdout),
String::from_utf8_lossy(&enable.stderr)
);
}
Ok(InstallStatus::Installed)
}
pub(crate) fn package_json() -> String {
serde_json::to_string_pretty(&serde_json::json!({
"name": PACKAGE_NAME,
"version": env!("CARGO_PKG_VERSION"),
"private": true,
"type": "module",
"openclaw": {
"extensions": [format!("./{ENTRYPOINT_TS}")]
}
}))
.expect("OpenClaw package metadata serializes")
+ "\n"
}
pub(crate) fn manifest_json() -> String {
serde_json::to_string_pretty(&serde_json::json!({
"id": PLUGIN_ID,
"name": "ai-memory",
"description": "Capture OpenClaw session lifecycle, tool use, compaction, and handoffs into ai-memory.",
"activation": {
"onCapabilities": ["hook"]
},
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}))
.expect("OpenClaw manifest serializes")
+ "\n"
}
/// Emit OpenClaw's `applyMarkerParams` TypeScript from the shared generator.
///
/// OpenClaw omits managed-run forwarding but otherwise uses the shared
/// repository-identity/default-path routing generated for TypeScript clients.
fn apply_marker_params_ts(default_strategy: Option<&str>) -> String {
super::install_hooks::ts_apply_marker_params(default_strategy, true).replacen(
" const managedRun = process.env.AI_MEMORY_RUN_ID;\n if (managedRun) url.searchParams.set(\"managed_run\", managedRun);\n",
"",
1,
)
}
fn build_plugin(
server_url: &str,
auth_token: Option<&str>,
project_strategy: Option<&str>,
capture_mode: &str,
) -> String {
let token_line = auth_token
.map(|t| format!("const TOKEN: string | null = {};\n", ts_string_literal(t)))
.unwrap_or_else(|| "const TOKEN: string | null = null;\n".to_string());
let resolve_fn = ts_resolve_token_fn();
let apply_marker_params = apply_marker_params_ts(project_strategy);
let capture_policy = ts_capture_policy_v1(capture_mode);
format!(
r#"// Auto-generated by `ai-memory install-hooks --agent openclaw --apply`.
// Edit by re-running the command, not by hand. install-hooks owns
// this local OpenClaw plugin package.
import {{ definePluginEntry }} from "openclaw/plugin-sdk/plugin-entry";
import {{ execFileSync }} from "node:child_process";
import {{ closeSync, existsSync, mkdirSync, opendirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync }} from "node:fs";
import {{ basename, dirname, join, resolve, sep }} from "node:path";
import {{ homedir }} from "node:os";
const SERVER = {server_literal}.replace(/\/+$/, "");
const AGENT = "openclaw";
{token_line}{resolve_fn}
{capture_policy}
{timeout_signal}
{auth_headers}
function findMarker(cwd: string | undefined): string | undefined {{
if (!cwd) return undefined;
let dir = resolve(cwd);
const home = homedir();
let boundary: string | undefined;
if (home && (dir === home || dir.startsWith(home.endsWith(sep) ? home : home + sep))) {{
boundary = home;
}} else if (home) {{
let probe = dir;
while (probe && probe !== dirname(probe)) {{
if (existsSync(join(probe, ".git"))) {{
boundary = probe;
break;
}}
probe = dirname(probe);
}}
boundary ??= dir;
}}
while (dir && dir !== dirname(dir)) {{
const marker = join(dir, ".ai-memory.toml");
if (existsSync(marker)) return marker;
if (boundary && dir === boundary) return undefined;
dir = dirname(dir);
}}
return undefined;
}}
function tomlKey(text: string, key: string): string | undefined {{
const re = new RegExp(`^\\s*${{key}}\\s*=\\s*"([^"]*)"`);
for (const line of text.split(/\r?\n/)) {{
const match = re.exec(line);
if (match) return match[1];
}}
return undefined;
}}
{repo_root_project}
{apply_marker_params}
function textFrom(value: unknown): string {{
if (value === null || value === undefined) return "";
if (typeof value === "string") return value;
if (Array.isArray(value)) return value.map(textFrom).filter(Boolean).join("\n\n").trim();
const obj = value as any;
if (typeof obj.text === "string") return obj.text;
if (typeof obj.content === "string") return obj.content;
if (typeof obj.prompt === "string") return obj.prompt;
try {{
return JSON.stringify(value);
}} catch (_e) {{
return String(value);
}}
}}
function sessionID(event: any, ctx: any): string | undefined {{
const value = ctx?.sessionId ?? ctx?.sessionID ?? ctx?.sessionKey ?? event?.sessionId ?? event?.sessionID ?? event?.sessionKey;
return typeof value === "string" && value.length > 0 ? value : undefined;
}}
function cwd(event: any, ctx: any): string | undefined {{
const value = ctx?.workspaceDir ?? ctx?.cwd ?? event?.cwd ?? event?.workspaceDir;
return typeof value === "string" && value.length > 0 ? value : undefined;
}}
function payload(event: any, ctx: any, extra: Record<string, unknown> = {{}}): Record<string, unknown> {{
return {{
sessionID: sessionID(event, ctx),
cwd: cwd(event, ctx),
agentID: ctx?.agentId,
runID: ctx?.runId ?? event?.runId,
jobID: ctx?.jobId,
...extra,
}};
}}
const startedSessions = new Set<string>();
const handoffChecked = new Set<string>();
const preCompactLast = new Map<string, number>();
const HOOK_DISPOSE_DRAIN_BUDGET_MS = 2000;
const pendingHookRequests = new Set<Promise<void>>();
function trackHookRequest(request: Promise<void>): void {{
pendingHookRequests.add(request);
void request.finally(() => pendingHookRequests.delete(request));
}}
function disposeDrainTimeout(): Promise<void> {{
return new Promise((resolve) => {{
const timer = setTimeout(resolve, HOOK_DISPOSE_DRAIN_BUDGET_MS);
timer.unref?.();
}});
}}
async function drainHookQueueForDispose(): Promise<void> {{
await Promise.race([
Promise.allSettled(Array.from(pendingHookRequests)),
disposeDrainTimeout(),
]);
}}
function rememberSession(event: any, ctx: any): void {{
const id = sessionID(event, ctx);
if (!id || startedSessions.has(id)) return;
startedSessions.add(id);
postHook("session-start", payload(event, ctx, {{ reason: event?.reason }}));
}}
function postPreCompact(event: any, ctx: any): void {{
rememberSession(event, ctx);
const key = sessionID(event, ctx) || "unknown";
const now = Date.now();
const last = preCompactLast.get(key) ?? 0;
if (now - last < 1000) return;
preCompactLast.set(key, now);
postHook("pre-compact", payload(event, ctx, {{ reason: event?.reason }}));
}}
{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);
if (!applyMarkerParams(url, typeof body.cwd === "string" ? body.cwd : undefined)) return;
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, a
// 5xx or a transient 4xx spools the event in the CLI hook-spool format
// for a later drain (#580); a delivered post opportunistically drains
// backlog.
// Tracked in pendingHookRequests so session_end can await a bounded
// flush instead of letting teardown kill the in-flight fetch (#676).
// A redirect rejects and spools the event: followed, a gateway's login
// page would count as a delivery.
const request = fetch(url, {{
proxy: false,
redirect: "error",
method: "POST",
headers: {{ "Content-Type": "application/json", ...authHeaders() }},
body: JSON.stringify(policy.payload),
signal: timeoutSignal(500),
}})
.catch(() => undefined)
.then((resp) => {{
if (!resp || hookStatusRetryable(resp.status)) spoolFailedHook(url, policy.payload);
else requestSpoolDrain();
}})
.catch(() => undefined);
trackHookRequest(request);
}} catch (_e) {{
try {{ spoolFailedHook(url, policy.payload); }} catch (_e2) {{}}
}}
}}
async function fetchHandoff(event: any, ctx: any): Promise<string | undefined> {{
const currentCwd = cwd(event, ctx);
if (!currentCwd) return undefined;
if (captureServerRouted(currentCwd)) return undefined;
// An allowlist build captures only marked repositories, and the native hook
// returns before its handoff GET for any other (`hook.rs`). Do the same: the
// server resolves the directory into a project to look the baton up, so a
// request from an unmarked one leaves an empty project behind.
if (CAPTURE_MODE === "allowlist" && !findMarker(currentCwd)) return undefined;
const url = new URL(`${{SERVER}}/handoff`);
url.searchParams.set("agent", AGENT);
if (!applyMarkerParams(url, currentCwd)) return undefined;
try {{
// The body is prepended to the prompt, so a redirect is refused: a
// gateway's login page must never arrive as the handoff.
const response = await fetch(url, {{
proxy: false,
redirect: "error",
headers: authHeaders(),
signal: timeoutSignal(1000),
}});
if (!response.ok) return undefined;
const text = (await response.text()).trim();
return text.length > 0 ? text : undefined;
}} catch (_e) {{
return undefined;
}}
}}
export default definePluginEntry({{
id: "ai-memory",
name: "ai-memory",
description: "Capture OpenClaw lifecycle events into ai-memory.",
register(api) {{
api.on("session_start", (event: any, ctx: any) => {{
rememberSession(event, ctx);
}});
api.on("session_end", async (event: any, ctx: any) => {{
rememberSession(event, ctx);
postHook("session-end", payload(event, ctx, {{ reason: event?.reason }}));
await drainHookQueueForDispose();
}});
api.on("before_prompt_build", async (event: any, ctx: any) => {{
rememberSession(event, ctx);
postHook("user-prompt", payload(event, ctx, {{
prompt: textFrom(event?.prompt ?? event?.userPrompt ?? event?.message ?? event?.messages?.at?.(-1)),
}}));
const id = sessionID(event, ctx);
if (!id || handoffChecked.has(id)) return;
handoffChecked.add(id);
const handoff = await fetchHandoff(event, ctx);
return handoff ? {{ prependContext: handoff }} : undefined;
}});
api.on("before_tool_call", (event: any, ctx: any) => {{
rememberSession(event, ctx);
postHook("pre-tool-use", payload(event, ctx, {{
tool: event?.toolName,
toolKind: event?.toolKind,
callID: event?.toolCallId,
args: event?.params,
}}));
}});
api.on("after_tool_call", (event: any, ctx: any) => {{
rememberSession(event, ctx);
postHook("post-tool-use", payload(event, ctx, {{
tool: event?.toolName,
toolKind: event?.toolKind,
callID: event?.toolCallId,
args: event?.params,
output: textFrom(event?.result ?? event?.output ?? event?.content),
error: event?.error,
durationMs: event?.durationMs,
}}));
}});
api.on("before_compaction", (event: any, ctx: any) => {{
postPreCompact(event, ctx);
}});
api.on("agent_end", (event: any, ctx: any) => {{
rememberSession(event, ctx);
postHook("stop", payload(event, ctx, {{ success: event?.success }}));
}});
}},
}});
"#,
server_literal = ts_string_literal(server_url),
token_line = token_line,
repo_root_project = super::install_hooks::TS_REPO_ROOT_PROJECT,
timeout_signal = ts_timeout_signal(),
auth_headers = ts_auth_headers_fn(),
spool_runtime = ts_spool_runtime(),
)
}
#[cfg(test)]
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, "denylist");
assert!(plugin.contains("function spoolFailedHook("));
assert!(plugin.contains("async function drainHookSpool()"));
assert!(plugin.contains(
"if (!resp || hookStatusRetryable(resp.status)) spoolFailedHook(url, policy.payload);"
));
assert!(plugin.contains("else requestSpoolDrain();"));
crate::commands::render_shared::assert_shared_ts_delivery_runtime("openclaw", &plugin);
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();
let manifest = manifest_json();
let plugin = build_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist");
assert!(package.contains(r#""extensions""#));
assert!(package.contains(r#""./index.ts""#));
assert!(manifest.contains(r#""id": "ai-memory""#));
assert!(manifest.contains(r#""onCapabilities""#));
assert!(manifest.contains(r#""hook""#));
assert!(plugin.contains("definePluginEntry"));
assert!(plugin.contains("api.on(\"session_start\""));
assert!(plugin.contains("api.on(\"session_end\""));
// #676: session_end must be async and await a bounded flush of the
// in-flight postHook fetch, otherwise the gateway tears the plugin
// down before the session-end request reaches the server.
assert!(plugin.contains("const HOOK_DISPOSE_DRAIN_BUDGET_MS = 2000;"));
assert!(plugin.contains("function disposeDrainTimeout(): Promise<void>"));
assert!(plugin.contains("async function drainHookQueueForDispose(): Promise<void>"));
assert!(plugin.contains("function trackHookRequest("));
assert!(plugin.contains("api.on(\"session_end\", async (event: any, ctx: any) => {"));
assert!(plugin.contains("await drainHookQueueForDispose();"));
assert!(
!plugin.contains("api.on(\"session_end\", (event: any, ctx: any) => {"),
"session_end must not regress to the sync fire-and-forget form: {plugin}"
);
assert!(plugin.contains("api.on(\"before_prompt_build\""));
assert!(plugin.contains("api.on(\"before_tool_call\""));
assert!(plugin.contains("api.on(\"after_tool_call\""));
assert!(plugin.contains("api.on(\"before_compaction\""));
assert!(plugin.contains("api.on(\"agent_end\""));
assert!(plugin.contains("postHook(\"session-start\""));
assert!(plugin.contains("postHook(\"user-prompt\""));
assert!(plugin.contains("function applyMarkerParams"));
assert!(plugin.contains("tomlKey(body, \"project_strategy\")"));
assert!(plugin.contains("tomlKey(body, \"drop_subagent_captures\")"));
assert!(plugin.contains("url.searchParams.set(\"drop_subagent\", dropSubagent)"));
assert!(plugin.contains("url.searchParams.set(\"profile_contribute\", profileContribute)"));
assert!(plugin.contains("url.searchParams.set(\"profile_consume\", profileConsume)"));
assert!(plugin.contains("function tomlFlag"));
assert!(plugin.contains("tomlFlag(body, \"default_global\")"));
assert!(plugin.contains("tomlFlag(body, \"inject_on_session_start\")"));
assert!(plugin.contains("url.searchParams.set(\"briefing_budget\", briefingBudget)"));
// #668: same settings-walk as the shared ts_apply_marker_params
// (install_hooks.rs) — the two applyMarkerParams copies stay
// equivalent, so a nested capture-only marker does not shadow an
// outer marker's scope here either.
assert!(plugin.contains("function findSettingsMarker"));
assert!(plugin.contains("function declaresSettings"));
assert!(plugin.contains("let marker = findSettingsMarker(cwd);"));
assert!(plugin.contains("if (declaresSettings(text)) return marker;"));
assert!(plugin.contains("import { execFileSync } from \"node:child_process\";"));
assert!(
plugin.contains("import { basename, dirname, join, resolve, sep } from \"node:path\";")
);
assert!(plugin.contains("if (existsSync(join(probe, \".git\")))"));
assert!(plugin.contains("boundary ??= dir;"));
assert!(plugin.contains("function repoRootProject"));
assert!(plugin.contains("repoProjectCache.set(cwd, project);"));
assert_eq!(plugin.matches("windowsHide: true").count(), 3);
assert!(plugin.contains("--git-common-dir"));
assert!(
plugin
.contains("projectStrategy === \"repo-root\" || projectStrategy === \"repo_root\"")
);
assert!(plugin.contains("project = repoProject;"));
assert!(plugin.contains("projectSource = \"repo-root\";"));
assert!(plugin.contains(
"if (!applyMarkerParams(url, typeof body.cwd === \"string\" ? body.cwd : undefined)) return;"
));
assert!(plugin.contains("if (!applyMarkerParams(url, currentCwd)) return undefined;"));
assert!(plugin.contains("fetchHandoff"));
assert!(plugin.contains("// capture-policy-v1 (generated; do not fork between adapters)"));
assert!(plugin.contains("const policy = capturePolicy(body"));
assert!(plugin.contains("body: JSON.stringify(policy.payload)"));
assert!(plugin.contains("prependContext: handoff"));
assert!(plugin.contains("Bearer ${token}"));
assert!(plugin.contains("tok"));
}
#[test]
fn openclaw_plugin_resolves_token_at_runtime_when_not_embedded() {
let plugin = build_plugin("http://127.0.0.1:49374", None, None, "denylist");
assert!(plugin.contains("function resolveToken("));
assert!(plugin.contains("const token = resolveToken();"));
assert!(plugin.contains("if (!response.ok) return undefined;"));
}
#[test]
fn openclaw_plugin_bakes_repo_root_default() {
let plugin = build_plugin(
"http://127.0.0.1:49374",
Some("tok"),
Some("repo-root"),
"denylist",
);
assert!(
plugin.contains("const DEFAULT_PROJECT_STRATEGY = \"repo-root\";"),
"repo-root install default must bake the const: {plugin}"
);
assert!(
plugin.contains("if (!projectStrategy) projectStrategy = DEFAULT_PROJECT_STRATEGY;"),
"must apply the default when a marker pins no strategy: {plugin}"
);
assert!(
plugin.contains("let marker = findSettingsMarker(cwd);"),
"the default-strategy variant must also walk past a capture-only marker (#668): {plugin}"
);
}
#[test]
fn openclaw_executes_shared_home_route_runtime() {
if !std::process::Command::new("node")
.args(["--experimental-strip-types", "-e", "0"])
.output()
.is_ok_and(|output| output.status.success())
{
return;
}
let tmp = TempDir::new().unwrap();
let home = tmp.path().join("home");
let repo_root = home.join("src/api");
let repo = repo_root.join("lib");
std::fs::create_dir_all(&repo).unwrap();
assert!(
std::process::Command::new("git")
.args(["init", "-q"])
.current_dir(&repo_root)
.status()
.unwrap()
.success()
);
assert!(
std::process::Command::new("git")
.args(["remote", "add", "origin", "[email protected]:acme/api.git"])
.current_dir(&repo_root)
.status()
.unwrap()
.success()
);
let fixture: serde_json::Value = serde_json::from_str(include_str!(
"../../../ai-memory-core/fixtures/home_route_cases.json"
))
.unwrap();
let text = fixture["cases"][0]["toml"]
.as_str()
.unwrap()
.replace("{{HOME}}", &home.to_string_lossy());
std::fs::write(home.join(".ai-memory.toml"), text).unwrap();
let module = tmp.path().join("openclaw-route.ts");
let plugin = build_plugin("http://127.0.0.1:49374", None, None, "denylist");
let helpers = plugin
.split_once("function tomlFlag")
.unwrap()
.1
.split_once("function postHook")
.unwrap()
.0;
let source = format!(
"import {{ execFileSync }} from \"node:child_process\";\nimport {{ closeSync, existsSync, opendirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, statSync }} from \"node:fs\";\nimport {{ basename, dirname, join, resolve, sep }} from \"node:path\";\nimport {{ homedir }} from \"node:os\";\nfunction readFileSync(path:string,encoding?:\"utf8\"):any{{return readMarkerText(path,encoding);}}\nfunction tomlKey(text:string,key:string):string|undefined{{const m=new RegExp(`^\\\\s*${{key}}\\\\s*=\\\\s*\"([^\"]*)\"`,`m`).exec(text);return m?.[1];}}\nfunction tomlFlag{}\nconst routeCwd={1};const direct=homeRoute(readHomeRouteText(join(homedir(),\".ai-memory.toml\")),routeCwd,\"github.com/acme/api\");const url=new URL(\"http://h/hook\");const ok=applyMarkerParams(url,routeCwd);process.stdout.write((direct?.project??\"none\")+\":\"+String(ok)+url.search);",
helpers,
serde_json::to_string(&repo.to_string_lossy()).unwrap()
);
std::fs::write(&module, source).unwrap();
let output = std::process::Command::new("node")
.args(["--experimental-strip-types", "--no-warnings"])
.arg(&module)
.env("HOME", &home)
.env("USERPROFILE", &home)
.output()
.unwrap();
assert!(
output.status.success(),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let query = String::from_utf8(output.stdout).unwrap();
assert!(query.starts_with("identity-api:true?cwd="), "{query}");
for expected in [
"workspace=identity",
"project=identity-api",
"identity=github.com%2Facme%2Fapi",
"identity_src=git_remote",
"identity_style=path",
"aliases=%5B%22main%22%5D",
"drop_subagent=true",
"default_global=true",
"briefing=true",
"briefing_budget=3210",
"profile_consume=0",
] {
assert!(query.contains(expected), "{expected}: {query}");
}
}
#[test]
fn openclaw_executes_every_shared_home_route_fixture() {
if !std::process::Command::new("node")
.args(["--experimental-strip-types", "-e", "0"])
.output()
.is_ok_and(|output| output.status.success())
{
return;
}
let tmp = TempDir::new().unwrap();
let home = tmp.path().join("home");
std::fs::create_dir_all(&home).unwrap();
let fixture: serde_json::Value = serde_json::from_str(include_str!(
"../../../ai-memory-core/fixtures/home_route_cases.json"
))
.unwrap();
let cases = fixture["cases"]
.as_array()
.unwrap()
.iter()
.map(|case| {
let text = match case["generate"].as_str() {
Some("65_routes") => (0..65)
.map(|index| format!("[routes.path.\"/route/{index}\"]\nroute_workspace=\"ws\"\nroute_project=\"p{index}\"\n"))
.collect(),
Some("selector_512") => format!("[routes.path.\"/{}\"]\nroute_workspace=\"bounds\"\nroute_project=\"valid\"\n", "a".repeat(511)),
Some("selector_513") => format!("[routes.path.\"/{}\"]\nroute_workspace=\"bounds\"\nroute_project=\"invalid\"\n", "a".repeat(512)),
Some("oversized_file") => format!("#{}\n", "x".repeat(65_536)),
Some(other) => panic!("unknown fixture generator {other}"),
None => case["toml"]
.as_str()
.unwrap()
.replace("{{HOME}}", &home.to_string_lossy())
.replace("{{LONG_513}}", &"a".repeat(513)),
};
let mut cwd = match case["cwd_generate"].as_str() {
Some("selector_512_child") => format!("/{}/child", "a".repeat(511)),
Some(other) => panic!("unknown cwd fixture generator {other}"),
None => case["cwd"]
.as_str()
.unwrap()
.replace("{{HOME}}", &home.to_string_lossy()),
};
if let Some(identity) = case["identity"].as_str() {
let repo = home
.join("fixture-repos")
.join(case["name"].as_str().unwrap());
std::fs::create_dir_all(&repo).unwrap();
assert!(
std::process::Command::new("git")
.args(["init", "-q"])
.current_dir(&repo)
.status()
.unwrap()
.success()
);
assert!(
std::process::Command::new("git")
.args([
"remote",
"add",
"origin",
&format!("https://{identity}.git"),
])
.current_dir(&repo)
.status()
.unwrap()
.success()
);
cwd = repo.to_string_lossy().into_owned();
} else if cwd.starts_with(&*home.to_string_lossy()) {
std::fs::create_dir_all(&cwd).unwrap();
}
serde_json::json!({
"name": case["name"],
"text": text,
"cwd": cwd,
"identity": case["identity"],
"status": case["status"],
"source": case["source"],
"workspace": case["workspace"],
"project": case["project"],
"style": case["style"],
"aliases": case["aliases"],
"flags": case["flags"]
})
})
.collect::<Vec<_>>();
let plugin = build_plugin("http://127.0.0.1:49374", None, None, "denylist");
let helpers = plugin
.split_once("function tomlFlag")
.unwrap()
.1
.split_once("function postHook")
.unwrap()
.0;
let module = tmp.path().join("openclaw-all-routes.ts");
let source = format!(
"import {{ execFileSync as realExecFileSync }} from \"node:child_process\";\nimport {{ closeSync, existsSync, opendirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, statSync, writeFileSync }} from \"node:fs\";\nimport {{ basename, dirname, join, resolve, sep }} from \"node:path\";\nimport {{ homedir }} from \"node:os\";\nfunction execFileSync(command:string,args:string[],options?:any):string{{return realExecFileSync(command,args,options) as string;}}\nfunction readFileSync(path:string,encoding?:\"utf8\"):any{{return readMarkerText(path,encoding);}}\nfunction tomlKey(text:string,key:string):string|undefined{{const m=new RegExp(`^\\\\s*${{key}}\\\\s*=\\\\s*\"([^\"]*)\"`,`m`).exec(text);return m?.[1];}}\nfunction tomlFlag{}\nconst cases={} as any[];for(const c of cases){{const file=join(homedir(),\".ai-memory.toml\");writeFileSync(file,c.text);const url=new URL(\"http://h/hook\");let applied=false;let helper=\"none\";try{{const route=homeRoute(readHomeRouteText(file),c.cwd,c.identity);helper=route?route.workspace+\"/\"+route.project:\"none\";}}catch{{helper=\"invalid\";}}try{{applied=applyMarkerParams(url,c.cwd);}}catch{{applied=false;}}process.stdout.write(JSON.stringify({{name:c.name,applied,helper,params:Object.fromEntries(url.searchParams)}})+\"\\n\");}}",
helpers,
serde_json::to_string(&cases).unwrap()
);
std::fs::write(&module, source).unwrap();
// A Windows cwd such as `c:/work/api/lib` is relative on Unix, so the
// marker walk starts in node's working directory; run it from the temp
// dir so a contributor's `.ai-memory.toml` in the checkout is not found.
let output = std::process::Command::new("node")
.args(["--experimental-strip-types", "--no-warnings"])
.arg(&module)
.current_dir(tmp.path())
.env("HOME", &home)
.env("USERPROFILE", &home)
.output()
.unwrap();
assert!(
output.status.success(),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let results = String::from_utf8(output.stdout)
.unwrap()
.lines()
.map(|line| {
let result: serde_json::Value = serde_json::from_str(line).unwrap();
(result["name"].as_str().unwrap().to_owned(), result)
})
.collect::<std::collections::HashMap<_, _>>();
for case in &cases {
let name = case["name"].as_str().unwrap();
let result = &results[name];
match case["status"].as_str().unwrap() {
"invalid" => {
assert_eq!(result["helper"], "invalid", "{name}: {result}");
assert_eq!(result["applied"], false, "{name}: {result}");
}
"none" => {
assert_eq!(result["helper"], "none", "{name}: {result}");
assert_eq!(result["applied"], true, "{name}: {result}");
assert!(
result["params"].get("workspace").is_none(),
"{name}: {result}"
);
assert!(
result["params"].get("project").is_none(),
"{name}: {result}"
);
}
"valid" => {
assert_eq!(result["applied"], true, "{name}: {result}");
assert_eq!(
result["params"]["workspace"], case["workspace"],
"{name}: {result}"
);
assert_eq!(
result["params"]["project"], case["project"],
"{name}: {result}"
);
assert_eq!(
result["params"]["project_src"], "marker",
"{name}: {result}"
);
let has_remote = result["params"]["identity_src"] == "git_remote";
if case["source"] == "identity" && has_remote {
assert_eq!(
result["params"]["identity"], case["identity"],
"{name}: {result}"
);
} else if case["source"] == "path" {
assert!(
result["params"].get("aliases").is_none(),
"{name}: {result}"
);
}
if let Some(style) = case["style"].as_str()
&& has_remote
{
assert_eq!(
result["params"]["identity_style"], style,
"{name}: {result}"
);
}
if let Some(aliases) = case["aliases"].as_str()
&& has_remote
{
assert_eq!(result["params"]["aliases"], aliases, "{name}: {result}");
}
if let Some(flags) = case["flags"].as_str() {
for pair in flags.split('&') {
let (key, value) = pair.split_once('=').unwrap();
assert_eq!(result["params"][key], value, "{name}: {result}");
}
}
}
status => panic!("unknown fixture status {status}"),
}
}
}
#[test]
fn openclaw_runtime_preserves_marker_and_home_identity_precedence() {
if !std::process::Command::new("node")
.args(["--experimental-strip-types", "-e", "0"])
.output()
.is_ok_and(|output| output.status.success())
{
return;
}
let tmp = TempDir::new().unwrap();
let home = tmp.path().join("home");
let repo = tmp.path().join("repo");
std::fs::create_dir_all(&home).unwrap();
std::fs::create_dir_all(&repo).unwrap();
assert!(
std::process::Command::new("git")
.args(["init", "-q"])
.current_dir(&repo)
.status()
.unwrap()
.success()
);
assert!(
std::process::Command::new("git")
.args(["remote", "add", "origin", "[email protected]:acme/api.git"])
.current_dir(&repo)
.status()
.unwrap()
.success()
);
let marker = repo.join(".ai-memory.toml");
let home_marker = home.join(".ai-memory.toml");
let module = tmp.path().join("openclaw-identity-gate.ts");
let plugin = build_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist");
let helpers = plugin
.split_once("function tomlFlag")
.unwrap()
.1
.split_once("function postHook")
.unwrap()
.0;
let source = format!(
"import {{ execFileSync }} from \"node:child_process\";\nimport {{ closeSync, existsSync, opendirSync, openSync, readFileSync as readMarkerText, readSync, readdirSync, statSync, unlinkSync, writeFileSync }} from \"node:fs\";\nimport {{ basename, dirname, join, resolve, sep }} from \"node:path\";\nimport {{ homedir }} from \"node:os\";\nfunction readFileSync(path:string,encoding?:\"utf8\"):any{{return readMarkerText(path,encoding);}}\nfunction tomlKey(text:string,key:string):string|undefined{{const m=new RegExp(`^\\\\s*${{key}}\\\\s*=\\\\s*\"([^\"]*)\"`,`m`).exec(text);return m?.[1];}}\nfunction tomlFlag{}\nconst repoCwd={};const marker={};const homeMarker={};const run=(body:string)=>{{writeFileSync(marker,body);const url=new URL(\"http://h/hook\");applyMarkerParams(url,repoCwd);return Object.fromEntries(url.searchParams);}};const noMarkerUrl=new URL(\"http://h/hook\");applyMarkerParams(noMarkerUrl,repoCwd);const noMarker=Object.fromEntries(noMarkerUrl.searchParams);const plain=run('project=\"api\"\\n');const aliases=run('project=\"api\"\\naliases=[\"old-api\"]\\n');unlinkSync(marker);writeFileSync(homeMarker,'[routes.identity.\"github.com/acme/api\"]\\nroute_workspace=\"oss\"\\nroute_project=\"api\"\\n');const routedUrl=new URL(\"http://h/hook\");applyMarkerParams(routedUrl,repoCwd);process.stdout.write(JSON.stringify({{noMarker,plain,aliases,routed:Object.fromEntries(routedUrl.searchParams)}}));",
helpers,
serde_json::to_string(&repo.to_string_lossy()).unwrap(),
serde_json::to_string(&marker.to_string_lossy()).unwrap(),
serde_json::to_string(&home_marker.to_string_lossy()).unwrap(),
);
std::fs::write(&module, source).unwrap();
let output = std::process::Command::new("node")
.args(["--experimental-strip-types", "--no-warnings"])
.arg(&module)
.env("HOME", &home)
.env("USERPROFILE", &home)
.output()
.unwrap();
assert!(
output.status.success(),
"{}",
String::from_utf8_lossy(&output.stderr)
);
let result: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
assert_eq!(result["noMarker"]["identity_src"], "git_remote", "{result}");
assert_eq!(result["noMarker"]["identity_style"], "path", "{result}");
assert!(result["plain"].get("identity").is_none(), "{result}");
assert_eq!(result["aliases"]["identity_src"], "git_remote", "{result}");
assert_eq!(result["aliases"]["aliases"], "[\"old-api\"]", "{result}");
assert_eq!(result["routed"]["identity_src"], "git_remote", "{result}");
assert_eq!(result["routed"]["workspace"], "oss", "{result}");
assert_eq!(result["routed"]["project_src"], "marker", "{result}");
}
#[test]
fn openclaw_plugin_default_omits_baked_strategy() {
let plugin = build_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist");
assert!(
!plugin.contains("DEFAULT_PROJECT_STRATEGY"),
"basename default must bake no strategy: {plugin}"
);
}
#[test]
fn openclaw_plugin_bakes_allowlist_admit_gate() {
// #661: the generated OpenClaw plugin POSTs to `<server>/hook` directly
// and never runs through the native `ai-memory hook` admit gate
// (`repository_admits_capture` in `ai-memory-hooks::capture_policy`), so
// the shared TS template must carry an equivalent gate keyed on marker
// *presence*, baked from `--capture-mode`.
let plugin = build_plugin("http://127.0.0.1:49374", Some("tok"), None, "allowlist");
assert!(
plugin.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"allowlist\";"),
"allowlist mode must be baked into the emitted constant: {plugin}"
);
assert!(
plugin.contains(
"const markerPresent = !!findMarker(cwd); if (CAPTURE_MODE === \"allowlist\" && !markerPresent) return { disposition: \"drop\", payload };"
),
"allowlist build must carry the marker-presence admit gate: {plugin}"
);
}
/// #992: OpenClaw posts to `SERVER` directly and does not route `server`
/// profiles, so a routed repository must emit nothing and fetch no handoff.
#[test]
fn openclaw_plugin_fails_closed_on_a_server_profile_marker() {
let plugin = build_plugin("http://127.0.0.1:49374", None, None, "denylist");
assert!(
plugin.contains(
"if (captureServerRouted(cwd)) return { disposition: \"drop\", payload };"
),
"{plugin}"
);
let handoff = plugin.split_once("async function fetchHandoff(").unwrap().1;
let guard = handoff
.find("if (captureServerRouted(currentCwd)) return undefined;")
.expect("handoff fetch must be gated");
assert!(guard < handoff.find("/handoff`").unwrap());
}
/// The handoff GET makes the server resolve the directory into a project,
/// creating it, so an allowlist build must not send it for an unmarked
/// repository either: the native hook returns before that request too.
#[test]
fn openclaw_allowlist_build_fetches_no_handoff_outside_a_marked_repository() {
let plugin = build_plugin("http://127.0.0.1:49374", Some("tok"), None, "allowlist");
let handoff = plugin.split_once("async function fetchHandoff(").unwrap().1;
let gate = handoff
.find(
"if (CAPTURE_MODE === \"allowlist\" && !findMarker(currentCwd)) return undefined;",
)
.expect("handoff fetch must honour the allowlist");
assert!(gate < handoff.find("/handoff`").unwrap());
}
#[test]
fn openclaw_plugin_denylist_bakes_inert_gate() {
let plugin = build_plugin("http://127.0.0.1:49374", Some("tok"), None, "denylist");
assert!(
plugin.contains("const CAPTURE_MODE: \"allowlist\" | \"denylist\" = \"denylist\";"),
"denylist mode must be baked into the emitted constant: {plugin}"
);
// The gate expression is present in every build (it's part of the one
// shared template) but is inert under denylist, since `CAPTURE_MODE`
// never equals `"allowlist"`.
assert!(
plugin.contains(
"const markerPresent = !!findMarker(cwd); if (CAPTURE_MODE === \"allowlist\" && !markerPresent) return { disposition: \"drop\", payload };"
)
);
}
#[test]
fn package_writes_all_required_files() {
let tmp = TempDir::new().unwrap();
let outcomes =
write_package(tmp.path(), "http://127.0.0.1:49374", None, None, "denylist").unwrap();
assert_eq!(outcomes.len(), 3);
assert!(tmp.path().join(PACKAGE_JSON).is_file());
assert!(tmp.path().join(MANIFEST_JSON).is_file());
assert!(tmp.path().join(ENTRYPOINT_TS).is_file());
assert!(
std::fs::read_to_string(tmp.path().join(ENTRYPOINT_TS))
.unwrap()
.contains("const TOKEN: string | null = null;")
);
}
}