Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
test(e2e): restart a spawned serve on a fresh port when another socket took it
Éverton Toffanetto84d4a1e4066e
diff --git a/crates/ai-memory-cli/tests/suite/backfill_e2e.rs b/crates/ai-memory-cli/tests/suite/backfill_e2e.rsindex 1a0123b8..2473da11 100644--- a/crates/ai-memory-cli/tests/suite/backfill_e2e.rs+++ b/crates/ai-memory-cli/tests/suite/backfill_e2e.rs@@ -34,14 +34,11 @@mod slow {use std::fs;use std::path::{Path, PathBuf};- use std::process::Stdio;use std::time::{Duration, Instant};use serde_json::{Value, json};- use crate::e2e_support::{- ServerGuard, free_port, hermetic, run_cli, session_count, write_jsonl,- };+ use crate::e2e_support::{hermetic, run_cli, session_count, start_serve, write_jsonl};const BIN: &str = env!("CARGO_BIN_EXE_ai-memory");const WORKSPACE: &str = "backfill-e2e-ws";@@ -162,51 +159,28 @@ mod slow {// Start the real server (loopback, no auth, hermetic: no embedder, no// wiki watcher — a machine-global inotify instance concurrent server// children can exhaust, #745).- let port = free_port();- let base = format!("http://127.0.0.1:{port}");- let server = ServerGuard(- hermetic(BIN)- .args([- "serve",- "--transport",- "http",- "--bind",- &format!("127.0.0.1:{port}"),- "--workspace",- WORKSPACE,- "--project",- PROJECT,- "--no-watcher",- ])- .current_dir(&cwd)- .env("AI_MEMORY_DATA_DIR", data_dir.path())- .env("AI_MEMORY_HOME", home.path())- .env("AI_MEMORY_EMBEDDING_PROVIDER", "none")- .env("RUST_LOG", "off")- .stdin(Stdio::null())- .stdout(Stdio::null())- .stderr(Stdio::null())- .spawn()- .expect("spawn serve"),- );-let client = reqwest::Client::new();-- // Wait for the server to accept connections.- let deadline = Instant::now() + Duration::from_secs(30);- loop {- if client- .get(format!("{base}/mcp"))- .timeout(Duration::from_secs(2))- .send()- .await- .is_ok()- {- break;- }- assert!(Instant::now() < deadline, "server never became reachable");- tokio::time::sleep(Duration::from_millis(150)).await;- }+ let (server, base) = start_serve(&client, &data_dir.path().join("serve.log"), |port| {+ let mut cmd = hermetic(BIN);+ cmd.args([+ "serve",+ "--transport",+ "http",+ "--bind",+ &format!("127.0.0.1:{port}"),+ "--workspace",+ WORKSPACE,+ "--project",+ PROJECT,+ "--no-watcher",+ ])+ .env("AI_MEMORY_DATA_DIR", data_dir.path())+ .env("AI_MEMORY_HOME", home.path())+ .env("AI_MEMORY_EMBEDDING_PROVIDER", "none");+ cmd.current_dir(&cwd);+ cmd+ })+ .await;// Phase 1 — the store is empty before backfill.assert_eq!(diff --git a/crates/ai-memory-cli/tests/suite/doctor_e2e.rs b/crates/ai-memory-cli/tests/suite/doctor_e2e.rsindex cf373863..74846569 100644--- a/crates/ai-memory-cli/tests/suite/doctor_e2e.rs+++ b/crates/ai-memory-cli/tests/suite/doctor_e2e.rs@@ -36,14 +36,11 @@/// lives in the slow tier (`cargo tf` / CI), not the everyday loop.mod slow {use std::fs;- use std::process::Stdio;use std::time::{Duration, Instant};use serde_json::{Value, json};- use crate::e2e_support::{- ServerGuard, free_port, hermetic, run_cli, session_count, write_jsonl,- };+ use crate::e2e_support::{hermetic, run_cli, session_count, start_serve, write_jsonl};const BIN: &str = env!("CARGO_BIN_EXE_ai-memory");const WORKSPACE: &str = "doctor-e2e-ws";@@ -98,51 +95,28 @@ mod slow {// Start the real server (loopback, no auth, hermetic: no embedder, no// wiki watcher — a machine-global inotify instance concurrent server// children can exhaust, #745).- let port = free_port();- let base = format!("http://127.0.0.1:{port}");- let server = ServerGuard(- hermetic(BIN)- .args([- "serve",- "--transport",- "http",- "--bind",- &format!("127.0.0.1:{port}"),- "--workspace",- WORKSPACE,- "--project",- PROJECT,- "--no-watcher",- ])- .current_dir(&cwd)- .env("AI_MEMORY_DATA_DIR", data_dir.path())- .env("AI_MEMORY_HOME", home.path())- .env("AI_MEMORY_EMBEDDING_PROVIDER", "none")- .env("RUST_LOG", "off")- .stdin(Stdio::null())- .stdout(Stdio::null())- .stderr(Stdio::null())- .spawn()- .expect("spawn serve"),- );-let client = reqwest::Client::new();-- // Wait for the server to accept connections.- let deadline = Instant::now() + Duration::from_secs(30);- loop {- if client- .get(format!("{base}/mcp"))- .timeout(Duration::from_secs(2))- .send()- .await- .is_ok()- {- break;- }- assert!(Instant::now() < deadline, "server never became reachable");- tokio::time::sleep(Duration::from_millis(150)).await;- }+ let (server, base) = start_serve(&client, &data_dir.path().join("serve.log"), |port| {+ let mut cmd = hermetic(BIN);+ cmd.args([+ "serve",+ "--transport",+ "http",+ "--bind",+ &format!("127.0.0.1:{port}"),+ "--workspace",+ WORKSPACE,+ "--project",+ PROJECT,+ "--no-watcher",+ ])+ .env("AI_MEMORY_DATA_DIR", data_dir.path())+ .env("AI_MEMORY_HOME", home.path())+ .env("AI_MEMORY_EMBEDDING_PROVIDER", "none");+ cmd.current_dir(&cwd);+ cmd+ })+ .await;// Precondition: nothing captured yet for this scope.assert_eq!(diff --git a/crates/ai-memory-cli/tests/suite/e2e_support.rs b/crates/ai-memory-cli/tests/suite/e2e_support.rsindex d8dc0a03..ec74aa5f 100644--- a/crates/ai-memory-cli/tests/suite/e2e_support.rs+++ b/crates/ai-memory-cli/tests/suite/e2e_support.rs@@ -3,8 +3,8 @@//! `backfill_e2e`, `doctor_e2e`, and `message_e2e` each drive the shipped//! `ai-memory` binary against a real `ai-memory serve` child, exactly as an//! operator would. These are the pieces they all share: a hermetic `Command`,-//! the server-lifetime guard, ephemeral port allocation, the `by-agent`-//! session count, and the subcommand runner.+//! the server start and lifetime guard, ephemeral port allocation, the+//! `by-agent` session count, and the subcommand runner.//!//! Kept deliberately cfg-agnostic (no `#![cfg(unix)]`) so the non-unix//! `message_e2e` can use it too. The genuinely POSIX-specific fixtures — the@@ -14,7 +14,8 @@use std::fs;use std::net::TcpListener;use std::path::Path;-use std::process::{Child, Command};+use std::process::{Child, Command, Stdio};+use std::time::{Duration, Instant};use serde_json::Value;@@ -44,8 +45,8 @@ impl Drop for ServerGuard {}}-/// A free loopback port. The brief unbind→rebind race is acceptable for a-/// slow-tier test and is the same approach the shell smoke test uses.+/// A free loopback port. It is released before the caller binds it; a spawned+/// server goes through [`start_serve`], which survives losing that race.pub fn free_port() -> u16 {TcpListener::bind("127.0.0.1:0").expect("bind ephemeral port")@@ -54,6 +55,81 @@ pub fn free_port() -> u16 {.port()}+/// What `serve` logs once its HTTP listener is bound, with the address.+const SERVE_READY: &str = "MCP HTTP server ready";++/// Start `ai-memory serve` on a free loopback port and wait until it answers+/// HTTP. `command` builds the configured serve command for a port; the+/// child's stderr goes to `log`, with the serve module's log turned on.+///+/// [`free_port`] releases the port before the server binds it, and under a+/// parallel test load another socket can take it in between. The server then+/// exits at once and a bare readiness loop only times out, hiding why; and+/// another test's server there would answer the probe. So the child must log+/// that it bound the port before an answer counts. A child that failed to+/// bind is restarted on a fresh port; any other exit, or no answer within the+/// deadline, panics with the child's stderr.+pub async fn start_serve(+ client: &reqwest::Client,+ log: &Path,+ command: impl Fn(u16) -> Command,+) -> (ServerGuard, String) {+ start_serve_on(client, log, command, free_port).await+}++async fn start_serve_on(+ client: &reqwest::Client,+ log: &Path,+ command: impl Fn(u16) -> Command,+ mut next_port: impl FnMut() -> u16,+) -> (ServerGuard, String) {+ const ATTEMPTS: usize = 5;+ let output = || fs::read_to_string(log).unwrap_or_default();+ for _ in 0..ATTEMPTS {+ let port = next_port();+ let addr = format!("127.0.0.1:{port}");+ let base = format!("http://{addr}");+ let stderr = fs::File::create(log).expect("create serve log");+ let mut server = ServerGuard(+ command(port)+ .env("RUST_LOG", "ai_memory_cli::commands::serve=info")+ .stdin(Stdio::null())+ .stdout(Stdio::null())+ .stderr(stderr)+ .spawn()+ .expect("spawn serve"),+ );+ let deadline = Instant::now() + Duration::from_secs(30);+ loop {+ let bound = output()+ .lines()+ .any(|line| line.contains(SERVE_READY) && line.contains(&addr));+ // Bounded so a stalled answer cannot hide the child's exit.+ let answered = bound+ && client+ .get(format!("{base}/mcp"))+ .timeout(Duration::from_secs(2))+ .send()+ .await+ .is_ok();+ match server.0.try_wait().expect("poll serve") {+ None if answered => return (server, base),+ None => {}+ // `serve` reports a failed bind as `binding <addr>`.+ Some(_) if output().contains(&format!("binding {addr}")) => break,+ Some(status) => panic!("serve exited ({status}) before answering:\n{}", output()),+ }+ assert!(+ Instant::now() < deadline,+ "serve never answered on {base}:\n{}",+ output()+ );+ tokio::time::sleep(Duration::from_millis(50)).await;+ }+ }+ panic!("serve could not bind a free port in {ATTEMPTS} attempts");+}+/// Write the JSONL lines (each already a `Value`) as one transcript file.////// Only the POSIX-gated fixtures plant transcripts, so this is unused on@@ -133,3 +209,68 @@ pub fn run_cli();String::from_utf8(out.stdout).expect("stdout utf8")}++mod slow {+ use super::*;++ fn serve(root: &Path, port: u16) -> Command {+ let mut cmd = hermetic(BIN);+ cmd.env("HOME", root)+ .env("USERPROFILE", root)+ .env("AI_MEMORY_HOME", root)+ .env("AI_MEMORY_DATA_DIR", root.join("data"))+ .env("AI_MEMORY_EMBEDDING_PROVIDER", "none")+ .env("AI_MEMORY_BACKFILL_ON_START", "false")+ .env("AI_MEMORY_AUTO_IMPROVE__SCHEDULER__ENABLED", "false")+ .env("RUST_LOG", "off")+ .current_dir(root)+ .args(["serve", "--transport", "http", "--bind"])+ .arg(format!("127.0.0.1:{port}"))+ .arg("--no-watcher");+ cmd+ }++ /// A port taken between [`free_port`] and the server's bind makes the+ /// server exit at once; the start moves to a fresh port instead of+ /// waiting out the readiness deadline, and does not take the answer of+ /// whatever holds the port for its own.+ #[tokio::test]+ async fn start_serve_moves_off_a_port_taken_before_the_bind() {+ use std::io::{Read as _, Write as _};++ let root = tempfile::tempdir().unwrap().keep();+ let taken = TcpListener::bind("127.0.0.1:0").unwrap();+ let busy = taken.local_addr().unwrap().port();+ std::thread::spawn(move || {+ for mut stream in taken.incoming().flatten() {+ let _ = stream.read(&mut [0; 1024]);+ let _ = stream.write_all(b"HTTP/1.1 200 OK\r\ncontent-length: 0\r\n\r\n");+ }+ });+ let mut ports = [busy].into_iter();+ let client = reqwest::Client::new();+ let started = Instant::now();+ let (_server, base) = start_serve_on(+ &client,+ &root.join("serve.log"),+ |port| serve(&root, port),+ || ports.next().unwrap_or_else(free_port),+ )+ .await;+ assert_ne!(base, format!("http://127.0.0.1:{busy}"));+ assert!(started.elapsed() < Duration::from_secs(20));+ }++ /// Any other early exit fails at once with the server's own error.+ #[tokio::test]+ #[should_panic(expected = "serve exited")]+ async fn start_serve_reports_an_early_exit() {+ let root = tempfile::tempdir().unwrap().keep();+ start_serve(&reqwest::Client::new(), &root.join("serve.log"), |port| {+ let mut cmd = serve(&root, port);+ cmd.arg("--no-such-flag");+ cmd+ })+ .await;+ }+}diff --git a/crates/ai-memory-cli/tests/suite/external_capture.rs b/crates/ai-memory-cli/tests/suite/external_capture.rsindex 8ecbd93a..6ebca1e1 100644--- a/crates/ai-memory-cli/tests/suite/external_capture.rs+++ b/crates/ai-memory-cli/tests/suite/external_capture.rs@@ -109,13 +109,13 @@ fn capture_inspection_reports_external_ownership_without_side_effects() {mod slow {use super::*;use std::process::Command;- use std::time::{Duration, Instant};+ use std::time::Duration;use ai_memory_core::SessionId;use ai_memory_store::ReaderPool;use sha2::{Digest, Sha256};- use crate::e2e_support::{ServerGuard, free_port};+ use crate::e2e_support::{ServerGuard, start_serve};const TOKEN: &str = "external-capture-local-test-token";const MARKER: &str = "external_capture_handoff_marker";@@ -163,46 +163,27 @@ mod slow {"workspace = \"external-test\"\nproject = \"capture-test\"\n",).unwrap();- let port = free_port();- let base = format!("http://127.0.0.1:{port}");- let server = ServerGuard(- command(root.as_path())- .args([- "serve",- "--transport",- "http",- "--bind",- &format!("127.0.0.1:{port}"),- "--workspace",- "external-test",- "--project",- "capture-test",- "--no-watcher",- ])- .stdin(Stdio::null())- .stdout(Stdio::null())- .stderr(Stdio::null())- .spawn()- .unwrap(),- );let client = reqwest::Client::builder().timeout(Duration::from_secs(15)).build().unwrap();- let deadline = Instant::now() + Duration::from_secs(30);- loop {- if client- .get(format!("{base}/mcp"))- .bearer_auth(TOKEN)- .send()- .await- .is_ok()- {- break;- }- assert!(Instant::now() < deadline, "server readiness timeout");- tokio::time::sleep(Duration::from_millis(50)).await;- }+ let (server, base) = start_serve(&client, &root.as_path().join("serve.log"), |port| {+ let mut cmd = command(root.as_path());+ cmd.args([+ "serve",+ "--transport",+ "http",+ "--bind",+ &format!("127.0.0.1:{port}"),+ "--workspace",+ "external-test",+ "--project",+ "capture-test",+ "--no-watcher",+ ]);+ cmd+ })+ .await;let reader = ReaderPool::new(&root.as_path().join("data/db/memory.sqlite"), 2).unwrap();Self {_server: server,diff --git a/crates/ai-memory-cli/tests/suite/external_capture_ts.rs b/crates/ai-memory-cli/tests/suite/external_capture_ts.rsindex 0ac6db37..ee7174fe 100644--- a/crates/ai-memory-cli/tests/suite/external_capture_ts.rs+++ b/crates/ai-memory-cli/tests/suite/external_capture_ts.rs@@ -104,7 +104,14 @@ const server = createServer((req, res) => {res.writeHead(404);res.end();});-await new Promise<void>((resolve) => server.listen(port, "127.0.0.1", () => resolve()));+await new Promise<void>((resolve, reject) => {+ server.once("error", reject);+ server.listen(port, "127.0.0.1", () => resolve());+}).catch((error) => {+ // Taken before Node could bind it; nothing has run yet, so the test retries.+ if (error?.code === "EADDRINUSE") process.exit(75);+ throw error;+});const hooks: any = await (AiMemoryHooks as any)({ directory });await hooks.event({ event: { type: "session.created", properties: { info: { id: "s1", directory } } } });@@ -124,7 +131,7 @@ console.log(JSON.stringify({ events, handoffs, system: transformed.system }));/// `GIT_CONFIG_*` leaking in from the harness would point it somewhere/// outside the fixture. `PATH` and the rest of the environment stay so/// Node and git still resolve.- fn run_plugin(dir: &Path, port: u16, owner: Option<&str>) -> Value {+ fn run_plugin(dir: &Path, port: u16, owner: Option<&str>) -> Option<Value> {let mut command = hermetic("node");for (key, _) in std::env::vars_os() {if key.to_string_lossy().starts_with("GIT_") {@@ -146,13 +153,41 @@ console.log(JSON.stringify({ events, handoffs, system: transformed.system }));command.env("AI_MEMORY_CAPTURE_OWNER", owner);}let output = command.output().expect("run generated plugin");+ if output.status.code() == Some(PORT_TAKEN) {+ return None;+ }assert!(output.status.success(),"generated plugin run failed (owner={owner:?})\nstdout:\n{}\nstderr:\n{}",String::from_utf8_lossy(&output.stdout),String::from_utf8_lossy(&output.stderr),);- serde_json::from_slice(&output.stdout).expect("harness JSON")+ Some(serde_json::from_slice(&output.stdout).expect("harness JSON"))+ }++ /// The harness's exit code when its port was taken before it could bind.+ const PORT_TAKEN: i32 = 75;++ /// Writes the plugin, rendered for `port`, and the harness into `dir`.+ fn write_fixture(dir: &Path, port: u16) {+ let plugin = render_opencode_plugin(dir, &format!("http://127.0.0.1:{port}"));+ std::fs::write(dir.join("ai-memory.ts"), &plugin).unwrap();+ std::fs::write(dir.join("harness.ts"), HARNESS).unwrap();+ }++ /// One plugin run on `port`. The plugin names its server at render time,+ /// and [`free_port`] releases the port before Node binds it, so under a+ /// parallel test load another socket can take it first. The harness then+ /// stops before the plugin runs and the fixture moves to a fresh port.+ fn run_on_free_port(dir: &Path, port: &mut u16, owner: Option<&str>) -> Value {+ for _ in 0..5 {+ if let Some(run) = run_plugin(dir, *port, owner) {+ return run;+ }+ *port = free_port();+ write_fixture(dir, *port);+ }+ panic!("the harness could not bind a free port in 5 attempts");}fn spooled_entries(dir: &Path) -> usize {@@ -187,12 +222,10 @@ console.log(JSON.stringify({ events, handoffs, system: transformed.system }));return;}let dir = fixture_root();- let port = free_port();- let plugin = render_opencode_plugin(&dir, &format!("http://127.0.0.1:{port}"));- std::fs::write(dir.join("ai-memory.ts"), &plugin).unwrap();- std::fs::write(dir.join("harness.ts"), HARNESS).unwrap();+ let mut port = free_port();+ write_fixture(&dir, port);- let owned = run_plugin(&dir, port, Some("orchestrator-a"));+ let owned = run_on_free_port(&dir, &mut port, Some("orchestrator-a"));assert!(delivered_events(&owned).is_empty(),"owned run must POST nothing: {owned}"@@ -206,7 +239,7 @@ console.log(JSON.stringify({ events, handoffs, system: transformed.system }));// plugin and harness must capture normally. Without them the// assertions above could pass on a harness that never delivers.for (label, owner) in [("unset", None), ("whitespace", Some(" \t\n"))] {- let captured = run_plugin(&dir, port, owner);+ let captured = run_on_free_port(&dir, &mut port, owner);let events = delivered_events(&captured);for expected in ["session-start", "user-prompt", "session-end"] {assert!(@@ -221,4 +254,21 @@ console.log(JSON.stringify({ events, handoffs, system: transformed.system })););}}++ /// A port taken before Node binds it moves the fixture to a fresh one+ /// instead of failing the run.+ #[test]+ fn generated_plugin_fixture_moves_off_a_taken_port() {+ if !node_strip_types_available() {+ return;+ }+ let dir = fixture_root();+ let taken = std::net::TcpListener::bind("127.0.0.1:0").unwrap();+ let busy = taken.local_addr().unwrap().port();+ let mut port = busy;+ write_fixture(&dir, port);+ let run = run_on_free_port(&dir, &mut port, None);+ assert_ne!(port, busy);+ assert!(delivered_events(&run).contains(&"session-start"), "{run}");+ }}diff --git a/crates/ai-memory-cli/tests/suite/message_e2e.rs b/crates/ai-memory-cli/tests/suite/message_e2e.rsindex d344e408..605478b7 100644--- a/crates/ai-memory-cli/tests/suite/message_e2e.rs+++ b/crates/ai-memory-cli/tests/suite/message_e2e.rs@@ -29,12 +29,11 @@/// lives in the slow tier (`cargo tf` / CI), not the everyday loop.mod slow {use std::path::Path;- use std::process::Stdio;use std::time::{Duration, Instant};use serde_json::{Value, json};- use crate::e2e_support::{ServerGuard, free_port, hermetic, run_cli, session_count};+ use crate::e2e_support::{hermetic, run_cli, session_count, start_serve};const BIN: &str = env!("CARGO_BIN_EXE_ai-memory");const WORKSPACE: &str = "message-e2e-ws";@@ -149,50 +148,27 @@ mod slow {// Start the real server (loopback, no auth, hermetic: no embedder, no// wiki watcher — a machine-global inotify instance concurrent server// children can exhaust, #745).- let port = free_port();- let base = format!("http://127.0.0.1:{port}");- let server = ServerGuard(- hermetic(BIN)- .args([- "serve",- "--transport",- "http",- "--bind",- &format!("127.0.0.1:{port}"),- "--workspace",- WORKSPACE,- "--project",- SENDER,- "--no-watcher",- ])- .env("AI_MEMORY_DATA_DIR", data_dir.path())- .env("AI_MEMORY_HOME", home.path())- .env("AI_MEMORY_EMBEDDING_PROVIDER", "none")- .env("RUST_LOG", "off")- .stdin(Stdio::null())- .stdout(Stdio::null())- .stderr(Stdio::null())- .spawn()- .expect("spawn serve"),- );-let client = reqwest::Client::new();-- // Wait for the server to accept connections.- let deadline = Instant::now() + Duration::from_secs(30);- loop {- if client- .get(format!("{base}/mcp"))- .timeout(Duration::from_secs(2))- .send()- .await- .is_ok()- {- break;- }- assert!(Instant::now() < deadline, "server never became reachable");- tokio::time::sleep(Duration::from_millis(150)).await;- }+ let (server, base) = start_serve(&client, &data_dir.path().join("serve.log"), |port| {+ let mut cmd = hermetic(BIN);+ cmd.args([+ "serve",+ "--transport",+ "http",+ "--bind",+ &format!("127.0.0.1:{port}"),+ "--workspace",+ WORKSPACE,+ "--project",+ SENDER,+ "--no-watcher",+ ])+ .env("AI_MEMORY_DATA_DIR", data_dir.path())+ .env("AI_MEMORY_HOME", home.path())+ .env("AI_MEMORY_EMBEDDING_PROVIDER", "none");+ cmd+ })+ .await;// A send is rejected unless the recipient project already exists, so make// all three projects real by "running an agent" in each once.