Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
//! `ai-memory setup` — a native install in one command.
//!
//! A composition of the commands a native install otherwise runs by hand, in
//! order, through their own library functions:
//!
//! 1. `init`, which on a fresh data dir also mints the root bearer token into
//! `<data_dir>/auth-tokens/default` and records `[auth] bearer_token_file`;
//! 2. a per-user service running `serve` on that install
//! ([`super::user_service`]): a systemd `--user` unit or a launchd
//! LaunchAgent, rendered from the packaged templates, or on Windows a
//! logon entry under the per-user `Run` key that starts
//! [`super::service_host`];
//! 3. for each agent (named with `--agent`, else detected from its session
//! store or MCP config under the home, the way `doctor` finds them):
//! `install-mcp --apply`, `install-hooks --apply` and global
//! `install-skills`;
//! 4. a self-check that writes nothing: `/healthz`, a `memory_status` call
//! over MCP with the install's credential, and `doctor`.
//!
//! The token is never printed or passed on a command line. The installers keep
//! it out of every harness config (hooks read the credential files `init`
//! seeds; MCP clients go through `mcp-bridge` or an env-var reference), as
//! they do when run by hand.
//!
//! Every step is idempotent, so a second `setup` changes nothing. Without
//! `--yes` the plan is shown first and confirmed on a terminal, where the
//! operator can also pick which of the planned agents to wire; with no
//! terminal to ask on, `setup` changes nothing and exits non-zero. `--plan`
//! prints the plan (as JSON with `--json`, for a front end to render) and
//! changes nothing. `--web` shows the same plan as a local page and applies
//! the agents picked there through `setup --yes` ([`super::setup_web`]).
use std::collections::BTreeSet;
use std::ffi::OsString;
use std::io::{BufRead as _, IsTerminal as _, Write as _};
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant};
use ai_memory_workstream::{ManagedHarness, OpenCodeDialect, native_store_root};
use anyhow::{Context as _, Result, bail};
use super::user_service::{self, CommandRunner, ServiceChange, ServiceManager, ServiceUnit};
use super::{
agent_plugins, doctor, init, install_hooks, install_mcp, install_skills, run_autowire,
};
use crate::cli::{
AgentChoice, DoctorArgs, HookInstallScope, InitArgs, InstallHooksArgs, InstallMcpArgs,
InstallSkillsAgent, InstallSkillsArgs, InstallSkillsScope, McpClient, SetupArgs,
};
use crate::config::Config;
use crate::http_client::{ServerEndpoint, ServerProbe, probe_server};
/// How long `setup` waits for a service it just started to answer.
const SERVICE_READY_TIMEOUT: Duration = Duration::from_secs(30);
/// The MCP entry name every installer writes by default.
const ENTRY_NAME: &str = "ai-memory";
/// What `setup` tells the operator to ask a restarted agent: answering it
/// takes a call to ai-memory's tools, so the reply shows the wiring works.
const FIRST_QUESTION: &str = "What do you remember about this project?";
/// Bumped when a field of the `--plan --json` document changes meaning or
/// goes away; adding a field does not bump it.
const PLAN_FORMAT: u32 = 1;
/// Harnesses that share a native store with another one, so finding the store
/// cannot tell them apart: OpenCode 2 shares OpenCode's, and the Kiro CLI v3
/// engine's store contains the v2 engine's. Wiring both would write two
/// dialects into one config, so only the stable one is detected; the other is
/// wired when named with `--agent`. A detected OpenCode still gets the major
/// its version probe reports ([`opencode_dialect`]).
const EXPLICIT_ONLY: &[ManagedHarness] = &[ManagedHarness::OpenCode2, ManagedHarness::KiroV3];
/// What `setup` will do.
#[derive(Debug)]
struct SetupPlan {
data_dir: PathBuf,
config_path: PathBuf,
/// No config file yet: `init` writes one (and mints the token when the
/// data dir has no database either).
fresh: bool,
service: ServicePlan,
agents: Vec<AgentPlan>,
/// Agents came from detection, not `--agent`.
detected: bool,
}
#[derive(Debug)]
enum ServicePlan {
Install(ServiceUnit),
Skip(String),
}
#[derive(Debug)]
enum SetupProbe {
Healthy,
Unreachable(String),
Unexpected(String),
}
#[derive(Debug, Clone, PartialEq, Eq)]
struct AgentPlan {
agent: AgentChoice,
/// Where detection found the agent; `None` when it was named with
/// `--agent`.
found: Option<Found>,
mcp: Option<McpClient>,
skills: InstallSkillsAgent,
/// The ai-memory marketplace plugin is enabled for this agent: it carries
/// the hooks, MCP entry and skills, so setup writes none of them (#1166).
plugin: bool,
}
/// The evidence detection found an agent by, shown in the plan so the
/// operator can tell why an agent is listed before agreeing to wire it.
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
#[serde(tag = "kind", content = "path", rename_all = "snake_case")]
enum Found {
SessionStore(PathBuf),
McpConfig(PathBuf),
ConfigDir(PathBuf),
}
impl Found {
fn describe(&self) -> String {
match self {
Self::SessionStore(path) => format!("found its session store at {}", path.display()),
Self::McpConfig(path) => format!("found its MCP config at {}", path.display()),
Self::ConfigDir(path) => format!("found its directory at {}", path.display()),
}
}
}
impl AgentPlan {
fn new(agent: AgentChoice, found: Option<Found>) -> Self {
Self {
agent,
found,
mcp: install_hooks::mcp_client_for_agent(agent),
skills: skills_for(agent),
plugin: false,
}
}
/// [`Self::new`], with the plugin state of `agent` under `home`.
fn detect(
agent: AgentChoice,
found: Option<Found>,
home: &Path,
env: &dyn Fn(&str) -> Option<OsString>,
) -> Self {
let harness = match agent {
AgentChoice::ClaudeCode => Some(agent_plugins::PluginHarness::ClaudeCode),
AgentChoice::Codex => Some(agent_plugins::PluginHarness::Codex),
_ => None,
};
Self {
plugin: harness
.is_some_and(|harness| agent_plugins::enabled(harness, home, env).is_some()),
..Self::new(agent, found)
}
}
fn wiring(&self) -> &'static str {
match (self.plugin, self.mcp.is_some()) {
(true, _) => "plugin",
(false, true) => "mcp+hooks+skills",
(false, false) => "hooks+skills",
}
}
}
/// The `--agent` spelling of an agent, as `--help` lists it.
fn agent_name(agent: AgentChoice) -> String {
use clap::ValueEnum as _;
agent.to_possible_value().map_or_else(
|| agent.kind().as_str().to_owned(),
|value| value.get_name().to_owned(),
)
}
/// The skill directory family an agent reads; agents without one of their
/// own read the cross-client `~/.agents/skills`.
fn skills_for(agent: AgentChoice) -> InstallSkillsAgent {
match agent {
AgentChoice::ClaudeCode => InstallSkillsAgent::ClaudeCode,
AgentChoice::Grok => InstallSkillsAgent::Grok,
AgentChoice::CopilotCli => InstallSkillsAgent::CopilotCli,
AgentChoice::Devin => InstallSkillsAgent::Devin,
AgentChoice::Hermes => InstallSkillsAgent::Hermes,
AgentChoice::AntigravityCli => InstallSkillsAgent::Antigravity,
_ => InstallSkillsAgent::Agents,
}
}
/// The OpenCode major version to wire, resolved once so both installers use
/// the same dialect. The `opencode2` alias names V2 outright; the generic
/// `opencode` (named, or detected by the session store both majors share)
/// probes `opencode --version` the way `install-mcp` and `install-hooks` do
/// by hand, and a failed probe is an error rather than a guess.
fn opencode_dialect(
agent: AgentChoice,
env: &super::run::EffectiveChildEnv,
) -> Result<Option<OpenCodeDialect>> {
match agent {
AgentChoice::OpenCode => {
super::opencode_dialect::resolve_generic(None, env).map(|found| Some(found.dialect))
}
AgentChoice::OpenCode2 => Ok(Some(OpenCodeDialect::V2)),
_ => Ok(None),
}
}
/// Run `setup`.
///
/// # Errors
/// When the plan cannot be built, the operator declines it (or there is no
/// terminal to ask on and no `--yes`), or any step fails; the other steps
/// still run and the error counts the failures.
pub async fn run(config: &Config, args: SetupArgs, config_path: Option<&Path>) -> Result<()> {
let captured = config.runtime_env.process_env().to_vec();
let env = move |name: &str| -> Option<OsString> {
captured
.iter()
.find(|(key, _)| key.as_os_str() == name)
.map(|(_, value)| value.clone())
};
let home = super::run::native_home(config).context("locating your home directory")?;
let exe = std::env::current_exe().context("locating the running ai-memory binary")?;
let exe = service_exe(&exe, &env);
let written_config = init_config_path(config, config_path);
let agents: Vec<(AgentChoice, Option<Found>)> = if args.agents.is_empty() {
let mut found = detect_agents(
&home,
&|harness| doctor::relocated_session_dir_with(harness, &env),
&|client| install_mcp::mcp_config_path_with(client, &env).ok(),
);
if let Some(dir) = muse_detected(&home, &env) {
found.push((AgentChoice::Muse, Found::ConfigDir(dir)));
}
if let Some(dir) = codebuddy_detected(&home) {
found.push((AgentChoice::CodeBuddy, Found::ConfigDir(dir)));
}
if let Some(dir) = ibm_bob_detected(&home) {
found.push((AgentChoice::IbmBob, Found::ConfigDir(dir)));
}
if let Some(dir) = qwen_code_detected(&home) {
found.push((AgentChoice::QwenCode, Found::ConfigDir(dir)));
}
if let Some(dir) = qoder_detected(&home) {
found.push((AgentChoice::Qoder, Found::ConfigDir(dir)));
}
found
.into_iter()
.map(|(agent, found)| (agent, Some(found)))
.collect()
} else {
dedup(args.agents.iter().copied())
.into_iter()
.map(|agent| (agent, None))
.collect()
};
let service = if args.no_service {
ServicePlan::Skip("skipped (--no-service)".to_owned())
} else {
let spec = user_service::ServiceSpec {
exe,
data_dir: config.data_dir.clone(),
config_path: written_config.clone(),
home: home.clone(),
xdg_config_home: env("XDG_CONFIG_HOME").map(PathBuf::from),
};
let probe =
probe_setup_server(&ServerEndpoint::from_config_resolving_auth(config).await).await;
plan_service(
ServiceManager::current(),
&spec,
&config.server_url,
&probe,
&user_service::SystemRunner,
)
};
let mut plan = SetupPlan {
data_dir: config.data_dir.clone(),
fresh: !written_config.exists(),
config_path: written_config,
service,
agents: agents
.into_iter()
.map(|(agent, found)| AgentPlan::detect(agent, found, &home, &env))
.collect(),
detected: args.agents.is_empty(),
};
if args.json {
println!("{}", serde_json::to_string_pretty(&plan_document(&plan))?);
return Ok(());
}
if args.web {
use clap::ValueEnum as _;
let accepted = AgentChoice::value_variants()
.iter()
.map(|agent| agent_name(*agent))
.collect();
let flags = if args.no_service {
vec!["--no-service".into()]
} else {
Vec::new()
};
return super::setup_web::serve(
serde_json::to_value(plan_document(&plan))?,
accepted,
flags,
super::service_host::install_args(config, config_path),
!args.no_open,
args.stop_on_stdin_eof,
)
.await;
}
print_plan(&plan);
if args.plan {
return Ok(());
}
if !args.yes {
plan.agents = choose_agents(confirm(plan.agents.len())?, plan.agents);
}
execute(
config,
config_path,
plan,
&user_service::SystemRunner,
SERVICE_READY_TIMEOUT,
)
.await
}
fn init_config_path(config: &Config, explicit: Option<&Path>) -> PathBuf {
explicit.map_or_else(|| config.data_dir.join("config.toml"), Path::to_path_buf)
}
fn dedup<T: PartialEq>(agents: impl Iterator<Item = T>) -> Vec<T> {
let mut seen = Vec::new();
for agent in agents {
if !seen.contains(&agent) {
seen.push(agent);
}
}
seen
}
/// The agents to wire when none was named: every harness `doctor` scans whose
/// session store exists, or whose MCP config file does, under `home`, each
/// with the evidence it was found by (the store when both exist).
fn detect_agents(
home: &Path,
session_dir_for: &dyn Fn(ManagedHarness) -> Option<PathBuf>,
mcp_config_for: &dyn Fn(McpClient) -> Option<PathBuf>,
) -> Vec<(AgentChoice, Found)> {
let mut found: Vec<(AgentChoice, Found)> = Vec::new();
for harness in doctor::SCANNED_HARNESSES
.iter()
.copied()
.filter(|harness| !EXPLICIT_ONLY.contains(harness))
{
let Some(agent) = run_autowire::agent_choice_for_harness(harness) else {
continue;
};
if found.iter().any(|(seen, _)| *seen == agent) {
continue;
}
let store = native_store_root(harness, home, session_dir_for(harness).as_deref());
let evidence = if store.is_dir() {
Some(Found::SessionStore(store))
} else {
install_hooks::mcp_client_for_agent(agent)
.and_then(mcp_config_for)
.filter(|path| path.is_file())
.map(Found::McpConfig)
};
if let Some(evidence) = evidence {
found.push((agent, evidence));
}
}
found
}
/// Every agent `setup --agent` accepts that is not in the plan, so an agent
/// detection cannot find (no session store or MCP config to look for) is
/// still one name away.
fn other_agents(planned: &[AgentPlan]) -> Vec<String> {
use clap::ValueEnum as _;
AgentChoice::value_variants()
.iter()
.filter(|agent| !planned.iter().any(|plan| plan.agent == **agent))
.map(|agent| agent_name(*agent))
.collect()
}
/// Whether Meta Muse Code has run for this user: its config directory
/// (`${XDG_CONFIG_HOME:-~/.config}/muse`) or its data directory
/// (`${XDG_DATA_HOME:-~/.local/share}/muse`, where its sessions live) exists.
/// Muse has no native-session adapter, so it is found by these directories
/// rather than by [`detect_agents`]. Each XDG variable counts only when it is
/// an absolute path, lexically.
fn muse_detected(home: &Path, env: &dyn Fn(&str) -> Option<OsString>) -> Option<PathBuf> {
let xdg = |name: &str, fallback: &[&str]| {
super::path_util::agent_config_home(env(name))
.filter(|dir| dir.is_absolute())
.unwrap_or_else(|| {
fallback
.iter()
.fold(home.to_path_buf(), |dir, part| dir.join(part))
})
.join("muse")
};
[
xdg("XDG_CONFIG_HOME", &[".config"]),
xdg("XDG_DATA_HOME", &[".local", "share"]),
]
.into_iter()
.find(|dir| dir.is_dir())
}
/// CodeBuddy Code's directory, `~/.codebuddy`, when it exists. CodeBuddy has
/// no native-session adapter, so setup finds it by that directory rather than
/// by [`detect_agents`].
fn codebuddy_detected(home: &Path) -> Option<PathBuf> {
Some(home.join(".codebuddy")).filter(|dir| dir.is_dir())
}
/// IBM Bob's shared configuration directory, `~/.bob`, when it exists.
fn ibm_bob_detected(home: &Path) -> Option<PathBuf> {
Some(home.join(".bob")).filter(|dir| dir.is_dir())
}
/// Qwen Code's directory, `~/.qwen`, when it exists. Qwen has no
/// native-session adapter, so setup finds it by that directory rather than
/// by [`detect_agents`].
fn qwen_code_detected(home: &Path) -> Option<PathBuf> {
Some(home.join(".qwen")).filter(|dir| dir.is_dir())
}
/// Qoder's shared CLI/IDE configuration directory, `~/.qoder`, when present.
fn qoder_detected(home: &Path) -> Option<PathBuf> {
Some(home.join(".qoder")).filter(|dir| dir.is_dir())
}
/// The binary path the service unit runs. A package manager's versioned
/// location (a Homebrew `Cellar/<formula>/<version>` or a `/nix/store` path)
/// disappears on the next upgrade or `brew cleanup` / garbage collection, so a
/// unit naming it stops starting. When the running binary lives in one, the
/// unit names a stable link that resolves to the same file instead: the path
/// as invoked, an `ai-memory` on `PATH` (`/usr/local/bin`, `~/.nix-profile/bin`,
/// `/etc/profiles/per-user/<user>/bin`), or Homebrew's `opt/<formula>` and
/// `bin` links. Without one, the resolved path is kept as before.
fn service_exe(invoked: &Path, env: &dyn Fn(&str) -> Option<OsString>) -> PathBuf {
let Ok(resolved) = std::fs::canonicalize(invoked) else {
return invoked.to_path_buf();
};
if !is_versioned_package_path(&resolved) {
return resolved;
}
let name = resolved.file_name().unwrap_or(invoked.as_os_str());
let on_path = env("PATH")
.map(|path| {
std::env::split_paths(&path)
.map(|dir| dir.join(name))
.collect::<Vec<_>>()
})
.unwrap_or_default();
std::iter::once(invoked.to_path_buf())
.chain(homebrew_links(&resolved))
.chain(on_path)
.find(|candidate| {
candidate.is_absolute()
&& !is_versioned_package_path(candidate)
&& std::fs::canonicalize(candidate).is_ok_and(|target| target == resolved)
})
.unwrap_or(resolved)
}
/// Whether `path` sits in a store a package manager replaces per version.
fn is_versioned_package_path(path: &Path) -> bool {
let parts: Vec<_> = path.components().map(|part| part.as_os_str()).collect();
parts.windows(2).any(|pair| pair == ["nix", "store"]) || cellar_index(&parts).is_some()
}
/// The index of a `Cellar` component followed by `<formula>/<version>/...`.
fn cellar_index(parts: &[&std::ffi::OsStr]) -> Option<usize> {
parts
.iter()
.position(|part| *part == "Cellar")
.filter(|index| parts.len() > index + 3)
}
/// Homebrew's version-independent links to a `<prefix>/Cellar/<formula>/
/// <version>/<rest>` file: `<prefix>/opt/<formula>/<rest>` (what Homebrew's
/// own services use) and `<prefix>/<rest>`.
fn homebrew_links(resolved: &Path) -> Vec<PathBuf> {
let parts: Vec<_> = resolved.components().map(|part| part.as_os_str()).collect();
let Some(index) = cellar_index(&parts) else {
return Vec::new();
};
let prefix: PathBuf = parts[..index].iter().collect();
let rest: PathBuf = parts[index + 3..].iter().collect();
vec![
prefix.join("opt").join(parts[index + 1]).join(&rest),
prefix.join(rest),
]
}
/// 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`). 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,
probe: &SetupProbe,
runner: &dyn CommandRunner,
) -> ServicePlan {
let Some(manager) = manager else {
return ServicePlan::Skip(
"not supported on this platform; start the server with `ai-memory serve \
--transport http`"
.to_owned(),
);
};
if !crate::http_client::is_loopback_url(server_url) {
return ServicePlan::Skip(format!(
"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 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:#}")),
}
}
fn print_plan(plan: &SetupPlan) {
println!("ai-memory setup will:");
if plan.fresh {
println!(
" - create the data dir {} and write {} (with a new root bearer token in \
auth-tokens/default when the data dir is new)",
plan.data_dir.display(),
plan.config_path.display()
);
} else {
println!(
" - keep the existing install at {} ({})",
plan.data_dir.display(),
plan.config_path.display()
);
}
match &plan.service {
ServicePlan::Install(unit) => println!(
" - install and start a {} at {}{}",
unit.manager.describe(),
unit.path.display(),
if unit.manager == ServiceManager::WindowsRun {
" (it starts `ai-memory service-host` at logon, which runs the server with no \
console window and restarts it after a failure)"
} else {
""
}
),
ServicePlan::Skip(reason) => println!(" - service: {reason}"),
}
if plan.agents.is_empty() {
println!(
" - wire no agent: none {}; name one with --agent <name>",
if plan.detected {
"was detected"
} else {
"was named"
}
);
} else {
println!(" - wire these agents:");
}
for (number, agent) in plan.agents.iter().enumerate() {
let name = agent.agent.kind().as_str();
let number = number + 1;
if agent.plugin {
println!(
" {number}. {name}: leave it to its enabled ai-memory plugin ({}), which \
carries the hooks, MCP entry and skills",
agent_plugins::PLUGIN_ID
);
continue;
}
let mcp = if agent.mcp.is_some() {
"MCP + hooks"
} else {
"hooks"
};
let why = agent
.found
.as_ref()
.map_or_else(|| "named with --agent".to_owned(), Found::describe);
println!(" {number}. {name}: {mcp} + skills ({why})");
}
println!(" - check /healthz, memory_status and doctor (read-only)");
let others = other_agents(&plan.agents);
if !others.is_empty() {
println!(
"Also supported, not in this plan (add with --agent <name>): {}",
others.join(", ")
);
}
}
/// What the operator answered at the prompt.
#[derive(Debug, PartialEq, Eq)]
enum Answer {
/// Apply the whole plan.
All,
/// Apply it with only these agents, as 1-based plan numbers in order.
Only(Vec<usize>),
}
/// Ask on a terminal; refuse without one. With more than one planned agent
/// the operator may answer with the numbers of the agents to wire.
fn confirm(agents: usize) -> Result<Answer> {
if !std::io::stdin().is_terminal() {
bail!(
"nothing was changed: there is no terminal to confirm this plan on. Re-run \
`ai-memory setup --yes` to apply it."
);
}
if agents > 1 {
print!("Proceed? [y/N], or type the numbers of the agents to wire (e.g. 1 3): ");
} else {
print!("Proceed? [y/N] ");
}
std::io::stdout().flush().ok();
let mut answer = String::new();
std::io::stdin()
.lock()
.read_line(&mut answer)
.context("reading the answer")?;
parse_answer(&answer, agents)
}
/// Read a prompt answer: yes, or (with more than one agent) a list of agent
/// numbers separated by spaces or commas. Anything else declines, and so does
/// a number outside the plan, so a typo never wires an agent nobody chose.
fn parse_answer(answer: &str, agents: usize) -> Result<Answer> {
let answer = answer.trim();
if matches!(answer, "y" | "Y" | "yes" | "YES" | "Yes") {
return Ok(Answer::All);
}
let numbers: Vec<&str> = answer
.split(|c: char| c == ',' || c.is_whitespace())
.filter(|part| !part.is_empty())
.collect();
if agents < 2 || numbers.is_empty() {
bail!("nothing was changed");
}
let mut chosen = Vec::new();
for part in numbers {
match part.parse::<usize>() {
Ok(number) if (1..=agents).contains(&number) => chosen.push(number),
_ => bail!("nothing was changed: {part} is not an agent number from 1 to {agents}"),
}
}
chosen.sort_unstable();
Ok(Answer::Only(dedup(chosen.into_iter())))
}
/// The planned agents the answer kept, in plan order.
fn choose_agents(answer: Answer, agents: Vec<AgentPlan>) -> Vec<AgentPlan> {
match answer {
Answer::All => agents,
Answer::Only(numbers) => agents
.into_iter()
.enumerate()
.filter(|(index, _)| numbers.contains(&(index + 1)))
.map(|(_, agent)| agent)
.collect(),
}
}
/// The plan as `setup --plan --json` prints it.
#[derive(Debug, serde::Serialize)]
struct PlanDocument {
format: u32,
data_dir: PathBuf,
config_path: PathBuf,
fresh: bool,
service: ServiceDocument,
agents: Vec<AgentDocument>,
/// `--agent` names accepted but not in the plan.
other_agents: Vec<String>,
checks: [&'static str; 3],
first_question: &'static str,
}
#[derive(Debug, serde::Serialize)]
#[serde(tag = "action", rename_all = "snake_case")]
enum ServiceDocument {
Install {
manager: &'static str,
path: PathBuf,
},
Skip {
reason: String,
},
}
#[derive(Debug, serde::Serialize)]
struct AgentDocument {
agent: String,
/// `null` when the agent was named with `--agent`.
found: Option<Found>,
wiring: &'static str,
}
fn plan_document(plan: &SetupPlan) -> PlanDocument {
PlanDocument {
format: PLAN_FORMAT,
data_dir: plan.data_dir.clone(),
config_path: plan.config_path.clone(),
fresh: plan.fresh,
service: match &plan.service {
ServicePlan::Install(unit) => ServiceDocument::Install {
manager: unit.manager.describe(),
path: unit.path.clone(),
},
ServicePlan::Skip(reason) => ServiceDocument::Skip {
reason: reason.clone(),
},
},
agents: plan
.agents
.iter()
.map(|agent| AgentDocument {
agent: agent_name(agent.agent),
found: agent.found.clone(),
wiring: agent.wiring(),
})
.collect(),
other_agents: other_agents(&plan.agents),
checks: ["healthz", "memory_status", "doctor"],
first_question: FIRST_QUESTION,
}
}
/// The closing line once every step passed: restart the wired agents, then
/// ask one of them something only ai-memory can answer.
fn next_step(agents: &[AgentPlan]) -> String {
let names: Vec<&str> = agents
.iter()
.map(|agent| agent.agent.kind().as_str())
.collect();
next_step_for_names(&names)
}
/// [`next_step`] for agents given by name.
pub(crate) fn next_step_for_names(names: &[impl AsRef<str>]) -> String {
let names: Vec<&str> = names.iter().map(AsRef::as_ref).collect();
match names.as_slice() {
[] => "ai-memory is set up, but no agent is wired; run `ai-memory setup --agent <name>`."
.to_owned(),
[one] => format!(
"ai-memory is set up. Restart {one} so it loads the new hooks and MCP entry, then \
ask it: \"{FIRST_QUESTION}\" It answers through ai-memory's tools; a new install \
remembers nothing yet, and every session from now on is captured."
),
many => format!(
"ai-memory is set up. Restart {} so they load the new hooks and MCP entry, then ask \
one of them: \"{FIRST_QUESTION}\" It answers through ai-memory's tools; a new \
install remembers nothing yet, and every session from now on is captured.",
many.join(", ")
),
}
}
/// Apply the plan. Every step runs even when an earlier one failed, so the
/// report names every problem at once.
async fn execute(
config: &Config,
config_path: Option<&Path>,
plan: SetupPlan,
runner: &dyn CommandRunner,
ready_timeout: Duration,
) -> Result<()> {
let mut problems: Vec<String> = Vec::new();
println!("\n== init");
let outcome = init::initialize(config, &InitArgs { force: false }, config_path)?;
let mut config = config.clone();
if let Some(token) = outcome.root_token
&& config.auth.bearer_token.is_none()
{
config.auth.adopt_token_file(token.path, token.token);
}
println!(
"config: {} {}",
if outcome.config_written {
"wrote"
} else {
"kept"
},
outcome.config_path.display()
);
println!("\n== service");
let mut wait_for_server = false;
match &plan.service {
ServicePlan::Skip(reason) => println!("service: {reason}"),
ServicePlan::Install(unit) => match user_service::install(unit, runner) {
Ok(change) => {
wait_for_server = change != ServiceChange::Unchanged;
println!(
"service: {} {}",
match change {
ServiceChange::Installed => "installed and started",
ServiceChange::Updated => "updated and restarted",
ServiceChange::Started => "started",
ServiceChange::Unchanged => "already running from",
},
unit.path.display()
);
}
Err(error) => problems.push(format!(
"service: {error:#}. Start the server yourself with `ai-memory serve --transport \
http`, or re-run with --no-service when it runs some other way."
)),
},
}
let endpoint = ServerEndpoint::from_config_resolving_auth(&config).await;
if wait_for_server && !wait_until_reachable(&endpoint, ready_timeout).await {
problems.push(format!(
"service: the server did not answer at {} within {}s",
endpoint.url,
ready_timeout.as_secs()
));
}
let mut skills_done = BTreeSet::new();
for agent in &plan.agents {
println!("\n== {}", agent.agent.kind().as_str());
for problem in wire_agent(&config, agent, &mut skills_done) {
problems.push(format!("{}: {problem}", agent.agent.kind().as_str()));
}
}
println!("\n== self-check");
for problem in self_check(&config, &endpoint).await {
problems.push(format!("self-check: {problem}"));
}
println!();
if config.auth.bearer_token.is_none() {
println!("auth: none (loopback); run `ai-memory auth enable` to require a bearer token");
} else {
println!("auth: bearer token (owner-only file; never printed)");
}
if let Some(hint) = web_sign_in_hint(&config, &endpoint) {
println!("{hint}");
}
if problems.is_empty() {
let codex = codex_hook_trust(&config, &plan).await;
println!(
"{}",
ready_message(codex.as_ref(), &next_step(&plan.agents))
);
return Ok(());
}
for problem in &problems {
eprintln!("problem: {problem}");
}
bail!(
"setup finished with {} problem(s); fix them and re-run `ai-memory setup`",
problems.len()
)
}
/// Codex's trust state for the ai-memory hooks setup left in place: the
/// hooks file `install-hooks` wrote, or the enabled plugin's hooks. `None`
/// when Codex was not wired or its state is unknown (Codex not installed or
/// not answering).
async fn codex_hook_trust(
config: &Config,
plan: &SetupPlan,
) -> Option<super::codex_hook_trust::CodexHookTrust> {
let codex = plan
.agents
.iter()
.find(|agent| agent.agent == AgentChoice::Codex)?;
let cwd = std::env::current_dir().ok()?;
if codex.plugin {
super::codex_hook_trust::probe(
Path::new("codex"),
super::codex_hook_trust::HookSource::Plugin(agent_plugins::PLUGIN_ID),
&cwd,
)
.await
} else {
doctor::codex_hook_trust(&config.runtime_env, &cwd).await
}
}
/// The closing line of a run with no problems. Codex skips a hook the user
/// has not trusted in its `/hooks` review, so with any skipped the install
/// is not ready for Codex yet. Setup still succeeds: only the user can grant
/// that trust, inside Codex, and re-running setup would not change it.
fn ready_message(codex: Option<&super::codex_hook_trust::CodexHookTrust>, closing: &str) -> String {
// The closing line names the agents to restart and the question to ask;
// with Codex hooks still unapproved it follows the action required
// instead of claiming the install is ready.
let restart = closing
.strip_prefix("ai-memory is set up. ")
.unwrap_or(closing);
match codex.filter(|trust| !trust.skipped.is_empty()) {
None => closing.to_owned(),
Some(trust) => {
let skipped: Vec<String> = trust
.skipped
.iter()
.map(|(event, status)| format!("{event} ({status})"))
.collect();
format!(
"ai-memory is installed, but Codex has not approved its {} ai-memory hook(s) \
yet: {}. Codex skips a hook until you trust it, so Codex sessions are not \
captured until then. Action required: open Codex, run /hooks, and trust \
them. {restart}",
trust.skipped.len(),
skipped.join(", "),
)
}
}
}
/// How a browser signs in to the web UI on a token-file install. With no
/// human accounts the server answers `/web` with a Basic challenge, and the
/// token file's contents are the password. The token itself is never printed.
fn web_sign_in_hint(config: &Config, endpoint: &ServerEndpoint) -> Option<String> {
let file = config.auth.token_file.as_ref().filter(|file| file.loaded)?;
Some(format!(
"web UI: {} (the service runs with --enable-web); when the browser asks \
for a username and password, use any username and the contents of {} \
as the password",
endpoint.build_url("/web"),
file.path.display()
))
}
async fn wait_until_reachable(endpoint: &ServerEndpoint, timeout: Duration) -> bool {
let deadline = Instant::now() + timeout;
loop {
if matches!(probe_server(endpoint).await, ServerProbe::Reachable) {
return true;
}
if Instant::now() >= deadline {
return false;
}
tokio::time::sleep(Duration::from_millis(200)).await;
}
}
/// `install-mcp`, `install-hooks` and `install-skills` for one agent, MCP
/// first so an OpenCode major-version move has one entry before the hook
/// installer reads it (the order `ai-memory run` auto-wire uses). Returns the
/// failures.
fn wire_agent(
config: &Config,
plan: &AgentPlan,
skills_done: &mut BTreeSet<String>,
) -> Vec<String> {
let mut problems = Vec::new();
if plan.plugin {
// Writing the settings-file wiring as well would load every skill
// twice and register a second MCP server; the hook copies would be
// de-duplicated, but nothing would be gained.
println!(
"plugin: {} is enabled; leaving the settings-file hooks, MCP entry and skills \
alone (run `ai-memory install-hooks --agent {} --apply` to add them anyway)",
agent_plugins::PLUGIN_ID,
plan.agent.kind().as_str()
);
return problems;
}
let child_env = super::run::EffectiveChildEnv::from_runtime(&config.runtime_env);
match opencode_dialect(plan.agent, &child_env) {
Ok(dialect) => wire_mcp_and_hooks(config, plan, dialect, &mut problems),
// A guessed major writes a plugin and MCP shape the installed OpenCode
// ignores without an error, so nothing is written instead.
Err(error) => problems.push(format!("skipped install-mcp and install-hooks: {error:#}")),
}
let skills_key = format!("{:?}", plan.skills);
if skills_done.insert(skills_key) {
let args = InstallSkillsArgs {
scope: InstallSkillsScope::Global,
agent: plan.skills,
target_dir: None,
print: false,
force: false,
};
if let Err(error) = install_skills::run(config, args) {
problems.push(format!("install-skills: {error:#}"));
}
}
problems
}
/// `install-mcp` then `install-hooks` for one agent, in one OpenCode dialect.
fn wire_mcp_and_hooks(
config: &Config,
plan: &AgentPlan,
dialect: Option<OpenCodeDialect>,
problems: &mut Vec<String>,
) {
if let Some(client) = plan.mcp {
if install_mcp::existing_entry_is_session_aware(client, None, ENTRY_NAME) {
println!("mcp: keeping the existing session-aware entry");
} else {
let args = InstallMcpArgs {
client,
server_url: None,
name: ENTRY_NAME.to_owned(),
auth_token: None,
apply: true,
config_file: None,
session_aware: false,
flavor: None,
token_env_var: false,
stdio_bridge: false,
bridge_data_dir: None,
};
if let Err(error) = install_mcp::run_with_opencode_dialect(config, args, dialect) {
problems.push(format!("install-mcp: {error:#}"));
}
}
}
let hooks = InstallHooksArgs {
agent: plan.agent,
hooks_dir: None,
server_url: None,
auth_token: None,
as_user: None,
apply: true,
config_file: None,
scope: HookInstallScope::Global,
project_strategy: None,
capture_assistant: false,
capture_mode: None,
no_capture_prompts: false,
capture_prompts: false,
profile: None,
};
if let Err(error) =
install_hooks::run_with_opencode_dialect_and_mcp_path(config, hooks, dialect, None)
{
problems.push(format!("install-hooks: {error:#}"));
}
}
/// `/healthz`, `memory_status` over MCP, and `doctor`; none of them writes a
/// file. Returns the failures.
async fn self_check(config: &Config, endpoint: &ServerEndpoint) -> Vec<String> {
let mut problems = Vec::new();
let healthz = endpoint.build_url("/healthz");
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"),
Err(error) => problems.push(format!("memory_status: {error:#}")),
}
let doctor = DoctorArgs {
workspace: None,
project: None,
since_days: 30,
json: false,
};
if let Err(error) = doctor::run(config, doctor).await {
problems.push(format!("doctor: {error:#}"));
}
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().saturating_add(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.
async fn memory_status(config: &Config) -> Result<()> {
use rmcp::ServiceExt as _;
use rmcp::model::CallToolRequestParams;
let url = install_mcp::mcp_server_url_from_base(&config.server_url);
let transport =
super::mcp_bridge::upstream_transport(&url, None, config.auth.bearer_token.as_deref())?;
let client = ().serve(transport).await.with_context(|| format!("connecting to {url}"))?;
let result = client
.peer()
.call_tool(CallToolRequestParams::new("memory_status"))
.await;
client.cancel().await.ok();
let result = result.context("calling memory_status")?;
if result.is_error == Some(true) {
bail!("memory_status reported an error");
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
/// Muse is detected by its config or data directory under the home or
/// the absolute XDG roots, and not otherwise.
#[test]
fn muse_is_detected_by_its_config_or_data_directory() {
let none = |_: &str| -> Option<OsString> { None };
let home = tempfile::tempdir().unwrap();
assert_eq!(muse_detected(home.path(), &none), None);
std::fs::create_dir_all(home.path().join(".local/share/muse/sessions")).unwrap();
assert_eq!(
muse_detected(home.path(), &none),
Some(home.path().join(".local/share/muse"))
);
let home = tempfile::tempdir().unwrap();
std::fs::create_dir_all(home.path().join(".config/muse")).unwrap();
assert_eq!(
muse_detected(home.path(), &none),
Some(home.path().join(".config/muse"))
);
let home = tempfile::tempdir().unwrap();
let xdg = tempfile::tempdir().unwrap();
std::fs::create_dir_all(xdg.path().join("muse")).unwrap();
let xdg_path = xdg.path().as_os_str().to_owned();
let env = move |name: &str| (name == "XDG_CONFIG_HOME").then(|| xdg_path.clone());
assert_eq!(
muse_detected(home.path(), &env),
Some(xdg.path().join("muse"))
);
assert_eq!(skills_for(AgentChoice::Muse), InstallSkillsAgent::Agents);
assert_eq!(
AgentPlan::new(AgentChoice::Muse, None).mcp,
Some(McpClient::Muse)
);
}
#[test]
fn codebuddy_is_detected_only_when_its_home_directory_exists() {
let home = tempfile::tempdir().unwrap();
assert_eq!(codebuddy_detected(home.path()), None);
std::fs::create_dir_all(home.path().join(".codebuddy")).unwrap();
assert_eq!(
codebuddy_detected(home.path()),
Some(home.path().join(".codebuddy"))
);
assert_eq!(
skills_for(AgentChoice::CodeBuddy),
InstallSkillsAgent::Agents
);
assert_eq!(AgentPlan::new(AgentChoice::CodeBuddy, None).mcp, None);
}
#[test]
fn qwen_code_is_detected_and_wires_hooks_mcp_and_shared_skills() {
let home = tempfile::tempdir().unwrap();
assert_eq!(qwen_code_detected(home.path()), None);
std::fs::create_dir_all(home.path().join(".qwen")).unwrap();
assert_eq!(
qwen_code_detected(home.path()),
Some(home.path().join(".qwen"))
);
assert_eq!(
skills_for(AgentChoice::QwenCode),
InstallSkillsAgent::Agents
);
assert_eq!(
AgentPlan::new(AgentChoice::QwenCode, None).mcp,
Some(McpClient::QwenCode)
);
}
#[test]
fn qoder_is_detected_and_wires_hooks_mcp_and_shared_skills() {
let home = tempfile::tempdir().unwrap();
assert_eq!(qoder_detected(home.path()), None);
std::fs::create_dir_all(home.path().join(".qoder")).unwrap();
assert_eq!(
qoder_detected(home.path()),
Some(home.path().join(".qoder"))
);
assert_eq!(skills_for(AgentChoice::Qoder), InstallSkillsAgent::Agents);
assert_eq!(
AgentPlan::new(AgentChoice::Qoder, None).mcp,
Some(McpClient::Qoder)
);
}
#[test]
fn ibm_bob_is_detected_and_wires_hooks_mcp_and_shared_skills() {
let home = tempfile::tempdir().unwrap();
assert_eq!(ibm_bob_detected(home.path()), None);
std::fs::create_dir_all(home.path().join(".bob/settings")).unwrap();
assert_eq!(
ibm_bob_detected(home.path()),
Some(home.path().join(".bob"))
);
assert_eq!(skills_for(AgentChoice::IbmBob), InstallSkillsAgent::Agents);
assert_eq!(
AgentPlan::new(AgentChoice::IbmBob, None).mcp,
Some(McpClient::IbmBob)
);
}
/// A versioned Homebrew binary is recorded through the `opt/<formula>`
/// link that survives `brew upgrade` and `brew cleanup`, falling back to
/// the `<prefix>/bin` link; a link to some other binary never wins.
#[cfg(unix)]
#[test]
fn a_cellar_binary_is_recorded_through_its_stable_homebrew_link() {
use std::os::unix::fs::symlink;
let root = tempfile::tempdir().unwrap();
let prefix = std::fs::canonicalize(root.path()).unwrap();
let cellar_bin = prefix.join("Cellar/ai-memory/3.0.0/bin");
std::fs::create_dir_all(&cellar_bin).unwrap();
let real = cellar_bin.join("ai-memory");
std::fs::write(&real, "bin").unwrap();
let no_env = |_: &str| None;
// No link at all: the resolved path is all there is.
assert_eq!(service_exe(&real, &no_env), real);
std::fs::create_dir_all(prefix.join("bin")).unwrap();
symlink(&real, prefix.join("bin/ai-memory")).unwrap();
assert_eq!(service_exe(&real, &no_env), prefix.join("bin/ai-memory"));
std::fs::create_dir_all(prefix.join("opt")).unwrap();
symlink("../Cellar/ai-memory/3.0.0", prefix.join("opt/ai-memory")).unwrap();
assert_eq!(
service_exe(&real, &no_env),
prefix.join("opt/ai-memory/bin/ai-memory")
);
// Control: a stable link that points at another version is refused.
let other = tempfile::tempdir().unwrap();
let other = std::fs::canonicalize(other.path()).unwrap();
let old_bin = other.join("Cellar/ai-memory/2.9.0/bin");
std::fs::create_dir_all(&old_bin).unwrap();
let old = old_bin.join("ai-memory");
std::fs::write(&old, "old").unwrap();
std::fs::create_dir_all(other.join("bin")).unwrap();
symlink(&real, other.join("bin/ai-memory")).unwrap();
assert_eq!(service_exe(&old, &no_env), old);
}
/// A `/nix/store` binary is recorded through the profile link on `PATH`
/// that resolves to it, and the path as invoked wins when it is stable.
#[cfg(unix)]
#[test]
fn a_nix_store_binary_is_recorded_through_its_profile_link() {
use std::os::unix::fs::symlink;
let root = tempfile::tempdir().unwrap();
let root = std::fs::canonicalize(root.path()).unwrap();
let store_bin = root.join("nix/store/abc123-ai-memory-3.0.0/bin");
std::fs::create_dir_all(&store_bin).unwrap();
let real = store_bin.join("ai-memory");
std::fs::write(&real, "bin").unwrap();
let profile_bin = root.join("home/.nix-profile/bin");
std::fs::create_dir_all(&profile_bin).unwrap();
symlink(&real, profile_bin.join("ai-memory")).unwrap();
let elsewhere = root.join("elsewhere");
std::fs::create_dir_all(&elsewhere).unwrap();
let path = std::env::join_paths([&elsewhere, &store_bin, &profile_bin]).unwrap();
let env = move |name: &str| (name == "PATH").then(|| path.clone());
assert_eq!(service_exe(&real, &env), profile_bin.join("ai-memory"));
assert_eq!(service_exe(&real, &|_: &str| None), real);
let invoked = root.join("invoked");
symlink(&real, &invoked).unwrap();
assert_eq!(service_exe(&invoked, &env), invoked);
}
/// A binary outside any versioned store keeps the resolved path, as
/// before: a `~/.local/bin` install is already stable.
#[cfg(unix)]
#[test]
fn a_plain_binary_keeps_its_resolved_path() {
let root = tempfile::tempdir().unwrap();
let root = std::fs::canonicalize(root.path()).unwrap();
let real = root.join(".local/bin/ai-memory");
std::fs::create_dir_all(real.parent().unwrap()).unwrap();
std::fs::write(&real, "bin").unwrap();
let link = root.join("link");
std::os::unix::fs::symlink(&real, &link).unwrap();
assert_eq!(service_exe(&link, &|_: &str| None), real);
assert!(!is_versioned_package_path(Path::new(
"/opt/homebrew/bin/ai-memory"
)));
assert!(!is_versioned_package_path(Path::new("/srv/Cellar/x")));
assert!(is_versioned_package_path(Path::new(
"/opt/homebrew/Cellar/ai-memory/3.0.0/bin/ai-memory"
)));
assert!(is_versioned_package_path(Path::new(
"/nix/store/abc-ai-memory/bin/ai-memory"
)));
}
/// An enabled plugin takes an agent's wiring over; a disabled or absent
/// one, and an agent the plugins do not cover, keep the full plan.
#[test]
fn an_enabled_plugin_takes_over_the_agents_wiring() {
use crate::commands::agent_plugins::test_support::{
install_claude_plugin, install_codex_plugin,
};
let home = tempfile::tempdir().unwrap();
let env = |_: &str| None;
assert!(!AgentPlan::detect(AgentChoice::ClaudeCode, None, home.path(), &env).plugin);
install_claude_plugin(home.path(), "3.0.0", false);
assert!(!AgentPlan::detect(AgentChoice::ClaudeCode, None, home.path(), &env).plugin);
install_claude_plugin(home.path(), "3.0.0", true);
assert!(AgentPlan::detect(AgentChoice::ClaudeCode, None, home.path(), &env).plugin);
assert!(!AgentPlan::detect(AgentChoice::Codex, None, home.path(), &env).plugin);
assert!(!AgentPlan::detect(AgentChoice::Grok, None, home.path(), &env).plugin);
install_codex_plugin(home.path());
assert!(AgentPlan::detect(AgentChoice::Codex, None, home.path(), &env).plugin);
}
/// Codex skips an untrusted hook, so a run that left any unapproved says
/// so and names `/hooks` instead of claiming the install is ready; all
/// trusted, or an unknown state, keeps the plain ready line.
#[test]
fn untrusted_codex_hooks_are_not_reported_as_ready() {
use super::super::codex_hook_trust::CodexHookTrust;
let ready = "ai-memory is set up.";
let untrusted = CodexHookTrust {
trusted: vec!["stop".to_owned()],
skipped: vec![
("sessionStart".to_owned(), "untrusted".to_owned()),
("userPromptSubmit".to_owned(), "modified".to_owned()),
],
};
let closing = next_step(&[AgentPlan::new(AgentChoice::Codex, None)]);
let message = ready_message(Some(&untrusted), &closing);
assert!(!message.contains(ready), "{message}");
assert!(message.contains("run /hooks"), "{message}");
assert!(
message.contains("2 ai-memory hook(s)")
&& message.contains("sessionStart (untrusted)")
&& message.contains("userPromptSubmit (modified)"),
"{message}"
);
let trusted = CodexHookTrust {
trusted: vec!["sessionStart".to_owned()],
skipped: Vec::new(),
};
assert!(message.contains(FIRST_QUESTION), "{message}");
assert_eq!(ready_message(Some(&trusted), &closing), closing);
assert_eq!(ready_message(None, &closing), closing);
assert!(closing.starts_with(ready));
}
/// A token-file install learns how to open the web UI: the URL and the
/// file to read, never the token. An inline or absent token prints no hint.
#[test]
fn web_hint_names_the_token_file_and_never_the_token() {
let endpoint = ServerEndpoint::from_pair(Some("http://127.0.0.1:49374".to_owned()), None);
let mut config = Config::default();
assert_eq!(web_sign_in_hint(&config, &endpoint), None);
config.auth.bearer_token = Some("inline-root-token".to_owned());
assert_eq!(web_sign_in_hint(&config, &endpoint), None);
let file = PathBuf::from("/data/auth-tokens/default");
config
.auth
.adopt_token_file(file.clone(), "file-root-token".to_owned());
let hint = web_sign_in_hint(&config, &endpoint).expect("token-file install gets a hint");
assert!(hint.contains("http://127.0.0.1:49374/web"), "{hint}");
assert!(hint.contains(&file.display().to_string()), "{hint}");
assert!(!hint.contains("file-root-token"), "{hint}");
}
fn agents_of(found: &[(AgentChoice, Found)]) -> Vec<AgentChoice> {
found.iter().map(|(agent, _)| *agent).collect()
}
fn plan_with(agents: Vec<AgentPlan>) -> SetupPlan {
SetupPlan {
data_dir: PathBuf::from("/data"),
config_path: PathBuf::from("/data/config.toml"),
fresh: true,
service: ServicePlan::Skip("skipped (--no-service)".to_owned()),
agents,
detected: true,
}
}
/// Yes applies everything; numbers keep only those agents, in plan
/// order and once each. A number outside the plan, a stray word, a blank
/// line, and numbers offered for a single agent all decline, so a typo
/// never wires an agent nobody chose.
#[test]
fn the_prompt_answer_picks_all_some_or_none_of_the_agents() {
assert_eq!(parse_answer("y\n", 3).unwrap(), Answer::All);
assert_eq!(parse_answer("Yes", 1).unwrap(), Answer::All);
assert_eq!(
parse_answer("3, 1 3\n", 3).unwrap(),
Answer::Only(vec![1, 3])
);
assert_eq!(parse_answer("2", 2).unwrap(), Answer::Only(vec![2]));
for declined in ["", "\n", "n", "no", "4", "0", "1 x", "-1"] {
let error = parse_answer(declined, 3).unwrap_err().to_string();
assert!(
error.starts_with("nothing was changed"),
"{declined:?}: {error}"
);
}
assert!(
parse_answer("1", 1).is_err(),
"numbers need two agents to pick from"
);
}
#[test]
fn chosen_numbers_keep_those_agents_in_plan_order() {
let agents = vec![
AgentPlan::new(AgentChoice::ClaudeCode, None),
AgentPlan::new(AgentChoice::Codex, None),
AgentPlan::new(AgentChoice::Grok, None),
];
let kept = choose_agents(Answer::Only(vec![1, 3]), agents.clone());
assert_eq!(
kept.iter().map(|plan| plan.agent).collect::<Vec<_>>(),
vec![AgentChoice::ClaudeCode, AgentChoice::Grok]
);
assert_eq!(choose_agents(Answer::All, agents.clone()), agents);
}
/// The JSON plan names each agent by its `--agent` spelling with the
/// evidence it was found by, lists every other accepted agent, and
/// carries the layout version a front end checks.
#[test]
fn the_json_plan_carries_agents_evidence_and_the_rest() {
let store = PathBuf::from("/home/u/.claude/projects");
let mut codex = AgentPlan::new(AgentChoice::Codex, None);
codex.plugin = true;
let plan = plan_with(vec![
AgentPlan::new(
AgentChoice::ClaudeCode,
Some(Found::SessionStore(store.clone())),
),
codex,
AgentPlan::new(AgentChoice::OpenCode2, None),
]);
let json = serde_json::to_value(plan_document(&plan)).unwrap();
assert_eq!(json["format"], PLAN_FORMAT);
assert_eq!(json["service"]["action"], "skip");
assert_eq!(json["agents"][0]["agent"], "claude-code");
assert_eq!(json["agents"][0]["found"]["kind"], "session_store");
assert_eq!(
json["agents"][0]["found"]["path"],
store.display().to_string()
);
assert_eq!(json["agents"][0]["wiring"], "mcp+hooks+skills");
assert_eq!(json["agents"][1]["wiring"], "plugin");
assert_eq!(json["agents"][2]["agent"], "opencode2");
assert!(json["agents"][2]["found"].is_null());
assert_eq!(json["first_question"], FIRST_QUESTION);
let others: Vec<&str> = json["other_agents"]
.as_array()
.unwrap()
.iter()
.map(|name| name.as_str().unwrap())
.collect();
assert!(
others.contains(&"cursor") && others.contains(&"gemini-cli"),
"{others:?}"
);
assert!(!others.contains(&"claude-code") && !others.contains(&"opencode2"));
{
use clap::ValueEnum as _;
assert_eq!(others.len() + 3, AgentChoice::value_variants().len());
}
}
/// Every accepted `--agent` value round-trips through the name the plan
/// prints, so a name copied from the plan always parses.
#[test]
fn every_listed_agent_name_parses_back() {
use clap::ValueEnum as _;
for agent in AgentChoice::value_variants() {
assert_eq!(
AgentChoice::from_str(&agent_name(*agent), false).ok(),
Some(*agent)
);
}
}
#[test]
fn the_closing_line_names_the_agents_and_the_question() {
let one = next_step(&[AgentPlan::new(AgentChoice::ClaudeCode, None)]);
assert!(one.contains("Restart claude-code so it loads"), "{one}");
assert!(one.contains(FIRST_QUESTION), "{one}");
let two = next_step(&[
AgentPlan::new(AgentChoice::ClaudeCode, None),
AgentPlan::new(AgentChoice::Codex, None),
]);
assert!(
two.contains("Restart claude-code, codex so they load"),
"{two}"
);
assert!(two.contains("ask one of them"), "{two}");
let none = next_step(&[]);
assert!(none.contains("no agent is wired"), "{none}");
assert!(!none.contains(FIRST_QUESTION), "{none}");
}
fn spec(home: &Path) -> user_service::ServiceSpec {
user_service::ServiceSpec {
exe: PathBuf::from("/opt/ai-memory/ai-memory"),
data_dir: home.join("data"),
config_path: home.join("data").join("config.toml"),
home: home.to_path_buf(),
xdg_config_home: None,
}
}
#[test]
fn detection_finds_harness_stores_and_mcp_configs_under_home() {
let tmp = tempfile::tempdir().unwrap();
let home = tmp.path();
// Claude Code by its session store, Codex by its MCP config only.
std::fs::create_dir_all(home.join(".claude").join("projects")).unwrap();
let codex_config = home.join("codex-config.toml");
std::fs::write(&codex_config, "").unwrap();
let mcp = |client: McpClient| (client == McpClient::Codex).then(|| codex_config.clone());
let found = detect_agents(home, &|_| None, &mcp);
assert_eq!(
found,
vec![
(
AgentChoice::ClaudeCode,
Found::SessionStore(home.join(".claude").join("projects"))
),
(AgentChoice::Codex, Found::McpConfig(codex_config.clone())),
]
);
}
/// Control: an empty home detects nothing, and a named-but-missing MCP
/// config path does not count as present.
#[test]
fn an_empty_home_detects_nothing() {
let tmp = tempfile::tempdir().unwrap();
let missing = tmp.path().join("nope.json");
let found = detect_agents(tmp.path(), &|_| None, &|_| Some(missing.clone()));
assert!(found.is_empty(), "{found:?}");
}
/// OpenCode 2 shares OpenCode's store; detection must not wire both
/// dialects into the one config file.
#[test]
fn a_shared_store_detects_only_the_stable_harness() {
let tmp = tempfile::tempdir().unwrap();
let home = tmp.path();
std::fs::create_dir_all(home.join(".local/share/opencode")).unwrap();
std::fs::create_dir_all(home.join(".kiro/sessions/cli")).unwrap();
let found = detect_agents(home, &|_| None, &|_| None);
assert_eq!(
agents_of(&found),
vec![AgentChoice::OpenCode, AgentChoice::KiroCli]
);
}
/// A relocated store (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, …) is looked for
/// where the relocation points, not under the home.
#[test]
fn detection_follows_a_relocated_store() {
let tmp = tempfile::tempdir().unwrap();
let elsewhere = tmp.path().join("relocated-claude");
std::fs::create_dir_all(&elsewhere).unwrap();
let relocate = |harness: ManagedHarness| {
(harness == ManagedHarness::Claude).then(|| elsewhere.clone())
};
let found = detect_agents(&tmp.path().join("home"), &relocate, &|_| None);
assert_eq!(
found,
vec![(
AgentChoice::ClaudeCode,
Found::SessionStore(elsewhere.clone())
)]
);
}
#[test]
fn skills_go_to_each_agents_own_directory_or_the_shared_one() {
assert_eq!(
skills_for(AgentChoice::ClaudeCode),
InstallSkillsAgent::ClaudeCode
);
assert_eq!(skills_for(AgentChoice::Grok), InstallSkillsAgent::Grok);
assert_eq!(
skills_for(AgentChoice::CopilotCli),
InstallSkillsAgent::CopilotCli
);
assert_eq!(skills_for(AgentChoice::Codex), InstallSkillsAgent::Agents);
// Antigravity has no global `~/.agents/skills`; it reads its own roots.
assert_eq!(
skills_for(AgentChoice::AntigravityCli),
InstallSkillsAgent::Antigravity
);
assert_eq!(
skills_for(AgentChoice::KimiCode),
InstallSkillsAgent::Agents
);
}
/// Generic `opencode` takes the probed major; the `opencode2` alias and
/// other agents never run a probe, so an empty `PATH` cannot fail them.
#[cfg(unix)]
#[test]
fn opencode_dialect_probes_only_the_generic_spelling() {
use std::os::unix::fs::PermissionsExt as _;
let empty = super::super::run::EffectiveChildEnv::for_tests([("PATH", "")]);
assert_eq!(
opencode_dialect(AgentChoice::OpenCode2, &empty).unwrap(),
Some(OpenCodeDialect::V2)
);
assert_eq!(opencode_dialect(AgentChoice::Codex, &empty).unwrap(), None);
let error = format!(
"{:#}",
opencode_dialect(AgentChoice::OpenCode, &empty).unwrap_err()
);
assert!(error.contains("was not found"), "{error}");
for (version, expected) in [
("2.0.31", OpenCodeDialect::V2),
("1.18.34", OpenCodeDialect::V1),
] {
let bin = tempfile::tempdir().unwrap();
let opencode = bin.path().join("opencode");
std::fs::write(&opencode, format!("#!/bin/sh\necho '{version}'\n")).unwrap();
std::fs::set_permissions(&opencode, std::fs::Permissions::from_mode(0o755)).unwrap();
let env = super::super::run::EffectiveChildEnv::for_tests([("PATH", bin.path())]);
assert_eq!(
opencode_dialect(AgentChoice::OpenCode, &env).unwrap(),
Some(expected),
"{version}"
);
}
}
#[test]
fn named_agents_are_deduplicated_in_order() {
assert_eq!(
dedup(
[
AgentChoice::Codex,
AgentChoice::ClaudeCode,
AgentChoice::Codex
]
.into_iter()
),
vec![AgentChoice::Codex, AgentChoice::ClaudeCode]
);
}
#[test]
fn a_platform_without_a_manager_has_no_service_step_and_says_so() {
let tmp = tempfile::tempdir().unwrap();
let ServicePlan::Skip(reason) = plan_service(
None,
&spec(tmp.path()),
"http://127.0.0.1:49374",
&SetupProbe::Unreachable(String::new()),
&user_service::SystemRunner,
) else {
panic!("expected a skip");
};
assert!(reason.contains("not supported"), "{reason}");
}
/// The Windows logon entry is planned like a unit: installed when nothing
/// answers, left alone when a server answers and no entry of ours exists
/// (`reg query` finds none), and managed once the entry is there.
#[test]
fn the_windows_logon_entry_is_planned_like_a_unit() {
struct Reg(Option<&'static str>);
impl CommandRunner for Reg {
fn run(&self, program: &str, _args: &[&str]) -> Result<user_service::CommandOutcome> {
assert_eq!(program, "reg");
Ok(user_service::CommandOutcome {
success: self.0.is_some(),
stdout: self.0.map_or_else(String::new, |data| {
format!("\r\nHKEY_CURRENT_USER\\...\\Run\r\n ai-memory REG_SZ {data}\r\n")
}),
stderr: String::new(),
})
}
}
let tmp = tempfile::tempdir().unwrap();
let url = "http://127.0.0.1:49374";
let manager = Some(ServiceManager::WindowsRun);
// The shared spec names a Unix binary path, which is not absolute on
// Windows; this one is absolute on every platform.
let spec = user_service::ServiceSpec {
exe: tmp.path().join("ai-memory.exe"),
..spec(tmp.path())
};
assert!(matches!(
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, &SetupProbe::Healthy, &Reg(None)),
ServicePlan::Skip(reason) if reason.contains("already answers")
));
assert!(matches!(
plan_service(
manager,
&spec,
url,
&SetupProbe::Healthy,
&Reg(Some("\"C:\\ai\\ai-memory.exe\" service-host"))
),
ServicePlan::Install(_)
));
}
#[test]
fn a_remote_server_gets_no_local_service() {
let tmp = tempfile::tempdir().unwrap();
let plan = plan_service(
Some(ServiceManager::SystemdUser),
&spec(tmp.path()),
"https://memory.example.com",
&SetupProbe::Healthy,
&user_service::SystemRunner,
);
assert!(
matches!(plan, ServicePlan::Skip(reason) if reason.contains("not on this machine"))
);
}
/// A server that already answers with no unit of ours in place is not
/// ours to replace; once our unit exists, a running server is the one it
/// started and the unit is managed as usual.
// Windows skips the service step before this decision.
#[cfg(unix)]
#[test]
fn an_answering_server_without_our_unit_is_left_in_charge() {
let tmp = tempfile::tempdir().unwrap();
let spec = spec(tmp.path());
let url = "http://127.0.0.1:49374";
let plan = plan_service(
Some(ServiceManager::SystemdUser),
&spec,
url,
&SetupProbe::Healthy,
&user_service::SystemRunner,
);
assert!(matches!(plan, ServicePlan::Skip(reason) if reason.contains("already answers")));
let ServicePlan::Install(unit) = plan_service(
Some(ServiceManager::SystemdUser),
&spec,
url,
&SetupProbe::Unreachable(String::new()),
&user_service::SystemRunner,
) else {
panic!("expected an install when nothing answers");
};
std::fs::create_dir_all(unit.path.parent().unwrap()).unwrap();
std::fs::write(&unit.path, &unit.contents).unwrap();
assert!(matches!(
plan_service(
Some(ServiceManager::SystemdUser),
&spec,
url,
&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);
}
}
}