Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(setup): distinguish foreign listeners from healthy servers
Samir Hanna Verzaf6c4e7fc67d6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c6a02aca..a1331e0e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -13,6 +13,11 @@ version in [`docs/changelog/`](docs/changelog/):### Fixed+- Fixed `ai-memory setup` treating another service's HTTP 200 response as a+ healthy ai-memory server. Setup now checks the bounded `/healthz` JSON,+ reports an occupied address with port/configuration remedies, and skips+ MCP/admin probes when the health response is unrecognized (#1647).+- `ai-memory user list` and `ai-memory api-key list` now size their columnsby terminal display width rather than bytes, as `list-projects` and thegrants tables already do. An accented username, display name or key labeldiff --git a/crates/ai-memory-cli/src/commands/setup.rs b/crates/ai-memory-cli/src/commands/setup.rsindex 7abe8167..4f3a4c27 100644--- a/crates/ai-memory-cli/src/commands/setup.rs+++ b/crates/ai-memory-cli/src/commands/setup.rs@@ -92,6 +92,13 @@ enum ServicePlan {Skip(String),}+#[derive(Debug)]+enum SetupProbe {+ Healthy,+ Unreachable(String),+ Unexpected(String),+}+#[derive(Debug, Clone, PartialEq, Eq)]struct AgentPlan {agent: AgentChoice,@@ -262,15 +269,13 @@ pub async fn run(config: &Config, args: SetupArgs, config_path: Option<&Path>) -home: home.clone(),xdg_config_home: env("XDG_CONFIG_HOME").map(PathBuf::from),};- let reachable = matches!(- probe_server(&ServerEndpoint::from_config_resolving_auth(config).await).await,- ServerProbe::Reachable- );+ let probe =+ probe_setup_server(&ServerEndpoint::from_config_resolving_auth(config).await).await;plan_service(ServiceManager::current(),&spec,&config.server_url,- reachable,+ &probe,&user_service::SystemRunner,)};@@ -498,14 +503,15 @@ fn homebrew_links(resolved: &Path) -> Vec<PathBuf> {]}-/// Decide the service step. A server already answering with no unit of ours+/// Decide the service step. An ai-memory server answering with no unit of ours/// in place is left in charge (Docker, a packaged unit, a foreground-/// `serve`): a second server could not bind the port anyway.+/// `serve`). An unrecognized listener also prevents a bind, but needs an+/// actionable diagnostic rather than being treated as our server.fn plan_service(manager: Option<ServiceManager>,spec: &user_service::ServiceSpec,server_url: &str,- reachable: bool,+ probe: &SetupProbe,runner: &dyn CommandRunner,) -> ServicePlan {let Some(manager) = manager else {@@ -520,11 +526,24 @@ fn plan_service("the configured server {server_url} is not on this machine; no local service"));}+ if let SetupProbe::Unexpected(reason) = probe {+ return ServicePlan::Skip(format!(+ "{server_url} did not return ai-memory's /healthz JSON ({reason}); leaving the \+ listener and any existing service unchanged. Check which process owns this address, \+ then free it or set `bind = \"127.0.0.1:<free-port>\"` in {} and re-run \+ `ai-memory setup` (update an explicit server_url too). OpenCode's background \+ service also uses port 49374 by default; move it with \+ `opencode service set port <free-port>` if it is the occupant.",+ spec.config_path.display()+ ));+ }match user_service::render(manager, spec) {- Ok(unit) if reachable && !unit.exists(runner) => ServicePlan::Skip(format!(- "a server already answers at {server_url}; leaving it in charge (pass --no-service \+ Ok(unit) if matches!(probe, SetupProbe::Healthy) && !unit.exists(runner) => {+ ServicePlan::Skip(format!(+ "an ai-memory server already answers at {server_url}; leaving it in charge (pass --no-service \to skip this check)"- )),+ ))+ }Ok(unit) => ServicePlan::Install(unit),Err(error) => ServicePlan::Skip(format!("cannot render the service: {error:#}")),}@@ -1056,19 +1075,20 @@ fn wire_mcp_and_hooks(async fn self_check(config: &Config, endpoint: &ServerEndpoint) -> Vec<String> {let mut problems = Vec::new();let healthz = endpoint.build_url("/healthz");- match reqwest::Client::new()- .get(&healthz)- .timeout(Duration::from_secs(5))- .send()- .await- {- Ok(response) if response.status().is_success() => println!("healthz: ok ({healthz})"),- Ok(response) => problems.push(format!("{healthz} answered {}", response.status())),- Err(error) => {+ match probe_setup_server(endpoint).await {+ SetupProbe::Healthy => println!("healthz: ok ({healthz})"),+ SetupProbe::Unreachable(error) => {problems.push(format!("{healthz} did not answer: {error}"));// Nothing else can pass without a server.return problems;}+ SetupProbe::Unexpected(reason) => {+ problems.push(format!(+ "{healthz} did not return ai-memory's /healthz JSON ({reason}); check the \+ configured server URL and the process listening there"+ ));+ return problems;+ }}match memory_status(config).await {Ok(()) => println!("memory_status: ok"),@@ -1086,6 +1106,55 @@ async fn self_check(config: &Config, endpoint: &ServerEndpoint) -> Vec<String> {problems}+/// Setup needs the health response before it can leave an existing server+/// in charge or report success. The shared launch probe remains presence-only+/// for compatibility with servers that predate `/healthz`.+async fn probe_setup_server(endpoint: &ServerEndpoint) -> SetupProbe {+ let response = reqwest::Client::new()+ .get(endpoint.build_url("/healthz"))+ .timeout(Duration::from_secs(5))+ .send()+ .await;+ let response = match response {+ Ok(response) => response,+ Err(error) => return SetupProbe::Unreachable(error.to_string()),+ };+ match validate_healthz(response).await {+ Ok(()) => SetupProbe::Healthy,+ Err(reason) => SetupProbe::Unexpected(reason),+ }+}++async fn validate_healthz(mut response: reqwest::Response) -> Result<(), String> {+ if !response.status().is_success() {+ return Err(format!("HTTP {}", response.status()));+ }+ if !response+ .headers()+ .get(reqwest::header::CONTENT_TYPE)+ .and_then(|value| value.to_str().ok())+ .and_then(|value| value.split(';').next())+ .is_some_and(|mime| mime.trim().eq_ignore_ascii_case("application/json"))+ {+ return Err("expected Content-Type application/json".to_owned());+ }+ // A foreign listener can return a whole page (or a stream). Bound its+ // body and never echo it into the terminal.+ let mut body = Vec::new();+ while let Some(chunk) = response.chunk().await.map_err(|error| error.to_string())? {+ if body.len() + chunk.len() > 1024 {+ return Err("health response exceeds 1024 bytes".to_owned());+ }+ body.extend_from_slice(&chunk);+ }+ if serde_json::from_slice::<serde_json::Value>(&body).is_ok_and(|value| value["status"] == "ok")+ {+ Ok(())+ } else {+ Err("expected JSON with status \"ok\"".to_owned())+ }+}+/// One `memory_status` call over the server's MCP endpoint, authenticated the/// way `mcp-bridge` authenticates, so a refused credential shows here rather/// than in the agent's first session.@@ -1666,7 +1735,7 @@ mod tests {None,&spec(tmp.path()),"http://127.0.0.1:49374",- false,+ &SetupProbe::Unreachable(String::new()),&user_service::SystemRunner,) else {panic!("expected a skip");@@ -1702,11 +1771,11 @@ mod tests {..spec(tmp.path())};assert!(matches!(- plan_service(manager, &spec, url, false, &Reg(None)),+ plan_service(manager, &spec, url, &SetupProbe::Unreachable(String::new()), &Reg(None)),ServicePlan::Install(unit) if unit.manager == ServiceManager::WindowsRun));assert!(matches!(- plan_service(manager, &spec, url, true, &Reg(None)),+ plan_service(manager, &spec, url, &SetupProbe::Healthy, &Reg(None)),ServicePlan::Skip(reason) if reason.contains("already answers")));assert!(matches!(@@ -1714,7 +1783,7 @@ mod tests {manager,&spec,url,- true,+ &SetupProbe::Healthy,&Reg(Some("\"C:\\ai\\ai-memory.exe\" service-host"))),ServicePlan::Install(_)@@ -1728,7 +1797,7 @@ mod tests {Some(ServiceManager::SystemdUser),&spec(tmp.path()),"https://memory.example.com",- true,+ &SetupProbe::Healthy,&user_service::SystemRunner,);assert!(@@ -1750,7 +1819,7 @@ mod tests {Some(ServiceManager::SystemdUser),&spec,url,- true,+ &SetupProbe::Healthy,&user_service::SystemRunner,);assert!(matches!(plan, ServicePlan::Skip(reason) if reason.contains("already answers")));@@ -1759,7 +1828,7 @@ mod tests {Some(ServiceManager::SystemdUser),&spec,url,- false,+ &SetupProbe::Unreachable(String::new()),&user_service::SystemRunner,) else {panic!("expected an install when nothing answers");@@ -1771,10 +1840,114 @@ mod tests {Some(ServiceManager::SystemdUser),&spec,url,- true,+ &SetupProbe::Healthy,&user_service::SystemRunner),ServicePlan::Install(_)));}++ #[tokio::test]+ async fn setup_health_probe_requires_successful_bounded_json() {+ use axum::http::StatusCode;++ for (status, content_type, body, healthy) in [+ (+ StatusCode::OK,+ "application/json",+ r#"{"status":"ok"}"#.to_owned(),+ true,+ ),+ (+ StatusCode::OK,+ "application/json; charset=utf-8",+ r#"{"status":"ok","extra":1}"#.to_owned(),+ true,+ ),+ (+ StatusCode::OK,+ "text/html",+ r#"{"status":"ok"}"#.to_owned(),+ false,+ ),+ (+ StatusCode::OK,+ "application/json",+ "<!doctype html>".to_owned(),+ false,+ ),+ (+ StatusCode::OK,+ "application/json",+ r#"{"status":"down"}"#.to_owned(),+ false,+ ),+ (+ StatusCode::OK,+ "application/json",+ r#"{"other":"ok"}"#.to_owned(),+ false,+ ),+ (StatusCode::OK, "application/json", " ".repeat(1025), false),+ (+ StatusCode::SERVICE_UNAVAILABLE,+ "application/json",+ r#"{"status":"ok"}"#.to_owned(),+ false,+ ),+ ] {+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();+ let address = listener.local_addr().unwrap();+ let app = axum::Router::new().route(+ "/memory/healthz",+ axum::routing::get(move || async move {+ (+ status,+ [(axum::http::header::CONTENT_TYPE, content_type)],+ body,+ )+ }),+ );+ let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });+ let endpoint =+ ServerEndpoint::from_pair(Some(format!("http://{address}/memory")), None);+ let probe = probe_setup_server(&endpoint).await;+ server.abort();+ assert_eq!(+ matches!(probe, SetupProbe::Healthy),+ healthy,+ "{status} {content_type}: {probe:?}"+ );+ if !healthy {+ assert!(matches!(probe, SetupProbe::Unexpected(_)), "{probe:?}");+ }+ }+ }++ /// An unhealthy response still means the port is occupied. Do not+ /// install a second service or restart an existing one over that listener.+ #[cfg(unix)]+ #[test]+ fn an_unrecognized_listener_prevents_service_changes_even_with_an_existing_unit() {+ let tmp = tempfile::tempdir().unwrap();+ let spec = spec(tmp.path());+ let unit = user_service::render(ServiceManager::SystemdUser, &spec).unwrap();+ for existing in [false, true] {+ if existing {+ std::fs::create_dir_all(unit.path.parent().unwrap()).unwrap();+ std::fs::write(&unit.path, &unit.contents).unwrap();+ }+ let plan = plan_service(+ Some(ServiceManager::SystemdUser),+ &spec,+ "http://127.0.0.1:49374",+ &SetupProbe::Unexpected("HTTP 503 Service Unavailable".to_owned()),+ &user_service::SystemRunner,+ );+ assert!(+ matches!(plan, ServicePlan::Skip(reason) if reason.contains("did not return ai-memory's /healthz"))+ );+ assert_eq!(unit.path.exists(), existing);+ }+ }}diff --git a/crates/ai-memory-cli/tests/suite/setup_e2e.rs b/crates/ai-memory-cli/tests/suite/setup_e2e.rsindex 81a243a0..b4989038 100644--- a/crates/ai-memory-cli/tests/suite/setup_e2e.rs+++ b/crates/ai-memory-cli/tests/suite/setup_e2e.rs@@ -171,6 +171,74 @@ fn setup_plan_json_prints_the_plan_and_changes_nothing() {assert_eq!(sandbox.snapshot(), before, "a refused setup wrote");}+/// An SPA can answer every unknown route with HTML and HTTP 200. It is not+/// an existing ai-memory install, and its MCP/admin errors are not useful+/// setup diagnostics.+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]+async fn setup_identifies_a_foreign_listener_in_the_plan_and_self_check() {+ let sandbox = Sandbox::new();+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();+ let port = listener.local_addr().unwrap().port();+ let paths = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));+ let seen = paths.clone();+ let app = axum::Router::new().fallback(move |uri: axum::http::Uri| {+ seen.lock().unwrap().push(uri.path().to_owned());+ async { axum::response::Html("<!doctype html><title>Another service</title>") }+ });+ let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });++ let planned = sandbox+ .cmd(Some(port))+ .args(["setup", "--plan", "--json"])+ .output()+ .unwrap();+ assert!(planned.status.success(), "{}", text(&planned));+ let plan: serde_json::Value = serde_json::from_slice(&planned.stdout).unwrap();+ assert_eq!(plan["service"]["action"], "skip", "{plan}");+ let reason = plan["service"]["reason"].as_str().unwrap();+ assert!(+ reason.contains("did not return ai-memory's /healthz"),+ "{reason}"+ );+ assert!(reason.contains(&format!("127.0.0.1:{port}")), "{reason}");+ assert!(+ reason.contains("config.toml") && reason.contains("bind"),+ "{reason}"+ );++ let applied = sandbox+ .cmd(Some(port))+ .args(["setup", "--yes"])+ .output()+ .unwrap();+ server.abort();+ assert!(!applied.status.success(), "{}", text(&applied));+ let stdout = String::from_utf8_lossy(&applied.stdout);+ assert!(!stdout.contains("healthz: ok"), "{}", text(&applied));+ assert!(+ stdout.contains("did not return ai-memory's /healthz"),+ "{}",+ text(&applied)+ );+ assert!(+ paths.lock().unwrap().iter().all(|path| path == "/healthz"),+ "setup sent unrelated probes to the foreign listener: {:?}",+ paths.lock().unwrap()+ );+ assert!(+ !sandbox+ .home+ .join("Library/LaunchAgents/com.github.akitaonrails.ai-memory.plist")+ .exists()+ );+ assert!(+ !sandbox+ .home+ .join(".config/systemd/user/ai-memory.service")+ .exists()+ );+}+/// The generic `opencode` agent, named or found by the session store both/// majors share, is wired in the major `opencode --version` reports: OpenCode/// 2 gets the `{ id, setup }` plugin and the nested `mcp.servers` entry, notdiff --git a/docs/install.md b/docs/install.mdindex 98c2b673..3118fda2 100644--- a/docs/install.md+++ b/docs/install.md@@ -146,10 +146,17 @@ runs, in order, the commands a native install otherwise needs one by one:and restarts it after a failure, giving up after five failures within tenseconds of starting; see[`docs/windows.md`](windows.md#scenario-e-keep-the-server-running-native-windows-service).- The step is skipped when a server already answers at the configured+ The step is skipped when an ai-memory server already answers at the configuredURL and no unit or logon entry of ours exists yet (Docker, a packaged systemunit, a foreground `serve`), when the configured server is not on this- machine, and with `--no-service`.+ machine, and with `--no-service`. Setup requires a successful+ `application/json` response with `{"status":"ok"}` from `/healthz` before+ treating a listener as healthy. An unrecognized response leaves any local+ service unchanged and fails the self-check with a diagnostic. Check which+ process owns the address, then free it or change `bind` in the named+ `config.toml` and re-run setup; update an explicit `server_url` too.+ OpenCode's background service also defaults to port 49374 and can be moved+ with `opencode service set port <free-port>`.3. For each agent: `install-mcp --apply`, `install-hooks --apply` and`install-skills --scope global`. With no `--agent`, `setup` wires everyharness whose session store or MCP config exists under your home, using the