Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
"""Ownership, restart and installer regressions through the external package."""
import hashlib
import importlib
import os
import subprocess
import sys
from concurrent.futures import ThreadPoolExecutor
from unittest.mock import MagicMock
import pytest
@pytest.fixture
def modules(external_provider):
home, provider, module, _settings = external_provider("lifecycle")
ql = importlib.import_module(module.__name__ + ".quick_local")
lifecycle = importlib.import_module(module.__name__ + ".local_server")
packages = importlib.import_module(module.__name__ + ".local_packages")
return home, provider, module, ql, lifecycle, packages
@pytest.fixture
def servers(modules, monkeypatch):
home, _provider, _module, ql, lifecycle, _packages = modules
monkeypatch.setattr(ql, "_pm_available", lambda: False)
available = ql.find_available_port
first_port = 20000 + int(hashlib.sha256(str(home).encode()).hexdigest()[:8], 16) % 40000
monkeypatch.setattr(
ql,
"find_available_port",
lambda **kwargs: available(first_port=first_port, attempts=20, **kwargs),
)
children = []
def spawn(endpoint, config, hermes_home, command):
host, port = ql._endpoint_bind(endpoint)
process = subprocess.Popen(
[
sys.executable,
str(command),
"--config",
str(config),
"--host",
host,
"--port",
str(port),
],
stdin=subprocess.DEVNULL,
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
children.append(process)
return process
monkeypatch.setattr(ql, "_start_validation_server", spawn)
def create(name):
server = lifecycle.LocalServer(home.parent / name)
command = server.paths.server_command
command.parent.mkdir(parents=True)
command.write_text(
"""import argparse,json,os,subprocess,sys,time
from pathlib import Path
from http.server import BaseHTTPRequestHandler,HTTPServer
p=argparse.ArgumentParser();p.add_argument('--config');p.add_argument('--host');p.add_argument('--port',type=int);a=p.parse_args()
c=json.load(open(a.config));key=c['server']['root_api_key']
if c['vlm'].get('crash'):time.sleep(.2);raise SystemExit(9)
if c['vlm'].get('child'):
child=subprocess.Popen([sys.executable,'-c','import time;time.sleep(120)'])
Path(a.config+'.child').write_text(str(child.pid))
class Handler(BaseHTTPRequestHandler):
def log_message(self,*args):pass
def do_GET(self):
ok=self.path=='/health' or self.headers.get('X-API-Key')==key
self.send_response(200 if ok else 401);self.end_headers()
self.wfile.write(json.dumps({'status':'ok','healthy':True,'version':'0.5.0','auth_mode':'trusted','root_api_key_required':True}).encode())
# Match asyncio/Uvicorn: Windows listeners do not share an active address.
HTTPServer.allow_reuse_address = os.name != 'nt'
HTTPServer((a.host,a.port),Handler).serve_forever()
""",
encoding="utf-8",
)
config = ql.build_server_config(server.paths, {"model": "first"}, port=1933)
server.configure(config)
return server
yield create
for process in children:
if process.poll() is None:
process.terminate()
process.wait(timeout=10)
def ready(server):
# Windows connection-refused probes can each take over one second.
return server.wait_ready(server.start(), lambda _url: (True, ""), timeout=20)
@pytest.mark.parametrize("action", ["start", "restart"])
@pytest.mark.parametrize("memory", [
{"provider": "openviking", "openviking": {"deployment": "cloud"}},
{"provider": "openviking", "openviking": {}},
{"provider": "honcho", "openviking": {"deployment": "quick_local"}},
])
def test_cli_refuses_start_when_quick_local_is_not_selected(servers, modules, monkeypatch, capsys, action, memory):
import json
from argparse import Namespace
from hermes_constants import reset_hermes_home_override, set_hermes_home_override
server = servers("inactive-cli")
home = server.paths.root.parent
config = home / "config.yaml"
config.write_text(json.dumps({"memory": memory}), encoding="utf-8")
before = config.read_bytes()
cli = importlib.import_module(modules[3].__package__ + ".cli")
monkeypatch.setattr(cli, "get_hermes_home", lambda: home)
token = set_hermes_home_override(home)
try:
with pytest.raises(SystemExit) as caught:
cli._run(Namespace(local_action=action))
assert caught.value.code == 1
assert "not using Quick Local" in capsys.readouterr().out
assert server.status()["state"] == "stopped"
assert config.read_bytes() == before
finally:
reset_hermes_home_override(token)
def test_cli_controls_selected_and_retained_server(servers, modules, monkeypatch, capsys):
import json
from argparse import Namespace
from hermes_constants import reset_hermes_home_override, set_hermes_home_override
server = servers("selected-cli")
home = server.paths.root.parent
config = home / "config.yaml"
config.write_text(json.dumps({"memory": {"provider": "openviking", "openviking": {
"deployment": "quick_local"}}}), encoding="utf-8")
cli = importlib.import_module(modules[3].__package__ + ".cli")
monkeypatch.setattr(cli, "get_hermes_home", lambda: home)
token = set_hermes_home_override(home)
try:
cli._run(Namespace(local_action="start"))
assert server.status()["state"] == "ready"
old_pid = server.status()["pid"]
cli._run(Namespace(local_action="restart"))
assert server.status()["state"] == "ready"
assert server.status()["pid"] != old_pid
config.write_text(json.dumps({"memory": {"provider": "openviking", "openviking": {
"deployment": "cloud"}}}), encoding="utf-8")
cli._run(Namespace(local_action="status"))
assert "Quick Local: ready" in capsys.readouterr().out
cli._run(Namespace(local_action="stop"))
assert server.status()["state"] == "stopped"
finally:
reset_hermes_home_override(token)
def test_restart_keeps_data_and_changes_only_owned_process(servers):
a, b = servers("a"), servers("b")
ready(a)
ready(b)
old_a, old_b = a.status()["pid"], b.status()["pid"]
a.paths.workspace.mkdir()
marker = a.paths.workspace / "existing-memory"
marker.write_text("keep")
config = a._config()
config["vlm"]["model"] = "second"
a.configure(config)
restarted = ready(a)
assert not restarted.reused
assert a.status()["pid"] != old_a
assert b.status()["pid"] == old_b
assert marker.read_text() == "keep"
assert not a.paths.restart_required_marker.exists()
@pytest.mark.parametrize("failure_stage", ["validation", "port"])
def test_runtime_upgrade_retries_restart_after_failed_setup(
servers, modules, monkeypatch, capsys, failure_stage
):
from argparse import Namespace
_home, provider, _module, ql, _lifecycle, packages = modules
server = servers("upgrade-retry")
ready(server)
home = server.paths.root.parent
cli = importlib.import_module(ql.__package__ + ".cli")
monkeypatch.setattr(cli, "get_hermes_home", lambda: home)
old_pid = server.status()["pid"]
assert server.status()["runtime_validation_pending"] is False
endpoint = server.status()["endpoint"]
saved = {
path: path.read_bytes() for path in (server.paths.server_config, server.paths.ovcli_config)
}
server.paths.workspace.mkdir()
data = server.paths.workspace / "retained-memory"
data.write_text("keep")
monkeypatch.setattr(ql, "resolve_hermes_vlm_config", lambda: server._config()["vlm"])
monkeypatch.setattr(ql, "openviking_install_satisfies_requirement", lambda _paths: True)
monkeypatch.setattr(packages, "verified_requirements", lambda values, _cache: values)
monkeypatch.setattr(
packages, "resolve_server_requirement", lambda **_kw: "openviking[local-embed]==0.5.0"
)
install = MagicMock()
validate = MagicMock()
monkeypatch.setattr(ql.QuickLocalSetup, "_install_with_uv", install)
monkeypatch.setattr(ql.QuickLocalSetup, "_validate_generated_config", validate)
with monkeypatch.context() as failed:
if failure_stage == "validation":
validate.side_effect = ql.QuickLocalSetupError("validation failed")
error = "validation failed"
else:
failed.setattr(ql, "find_available_port", lambda: None)
error = "No free port"
setup = ql.QuickLocalSetup(health_check=lambda _url: (True, ""))
with pytest.raises(ql.QuickLocalSetupError, match=error):
setup.provision(hermes_home=home)
status = server.status()
assert status["pid"] == old_pid
assert status["state"] == "ready"
assert status["runtime_validation_pending"] is True
assert status["restart_required"] is False
cli._run(Namespace(local_action="status"))
output = capsys.readouterr().out
assert "Quick Local: ready" in output
assert "Runtime update needs validation" in output
assert "hermes memory setup openviking" in output
assert "choose Quick Local" in output
assert "hermes openviking local restart" not in output
assert server.status()["pid"] == old_pid
assert all(path.read_bytes() == value for path, value in saved.items())
assert (server.paths.root / "runtime-requirements.json").is_file()
provider._profile_config_and_env = lambda: ({"deployment": ql.DEPLOYMENT}, {})
provider.initialize("after-failed-setup", hermes_home=str(home), platform="cli")
assert server.status()["pid"] == old_pid
assert provider._ensure_client() is not None
assert server.paths.runtime_validation_pending_marker.is_file()
assert not server.paths.restart_required_marker.exists()
def validate_pending_runtime(**_kwargs):
assert server.paths.runtime_validation_pending_marker.is_file()
assert not server.paths.restart_required_marker.exists()
assert provider._ensure_client() is not None
assert server.status()["pid"] == old_pid
validate.side_effect = validate_pending_runtime
validate.reset_mock()
progress = []
retry = ql.QuickLocalSetup(health_check=lambda _url: (True, ""), progress=progress.append)
assert retry.provision(hermes_home=home).endpoint == endpoint
assert progress[-1].message == "Quick Local is ready with the updated settings."
validate.assert_called_once()
assert install.call_count == 1
new_pid = server.status()["pid"]
assert new_pid != old_pid
assert not server.paths.restart_required_marker.exists()
assert not server.paths.runtime_validation_pending_marker.exists()
assert server.status()["runtime_validation_pending"] is False
cli._run(Namespace(local_action="status"))
output = capsys.readouterr().out
assert "Quick Local: ready" in output
assert "Runtime update needs validation" not in output
assert all(path.read_bytes() == value for path, value in saved.items())
assert data.read_text() == "keep"
retry.provision(hermes_home=home)
assert server.status()["pid"] == new_pid
assert install.call_count == 1
validate.assert_called_once()
def test_foreign_saved_port_moves_endpoint_without_stopping_foreign_server(servers):
a, b = servers("a"), servers("b")
ready(a)
endpoint = a.status()["endpoint"]
ready(b)
a.stop()
config = b._config()
config["server"]["port"] = a.ql._endpoint_port(endpoint)
b.configure(config)
ready(b)
foreign_pid = b.status()["pid"]
moved = ready(a)
assert moved.endpoint != endpoint
assert a.ql.connection_config({}, a.paths.root.parent)["url"] == moved.endpoint
assert b.status()["pid"] == foreign_pid
assert a.status()["state"] == "ready"
def test_concurrent_starts_of_one_profile_create_one_process(servers):
a = servers("a")
with ThreadPoolExecutor(max_workers=2) as executor:
first, second = list(executor.map(lambda _: a.start(), range(2)))
assert first.process.pid == second.process.pid
a.wait_ready(first, lambda _url: (True, ""), timeout=20)
def test_two_profiles_can_recover_a_concurrent_port_race(servers):
a, b = servers("a"), servers("b")
with ThreadPoolExecutor(max_workers=2) as executor:
first, second = list(executor.map(ready, (a, b)))
assert first.endpoint != second.endpoint
assert a.status()["state"] == b.status()["state"] == "ready"
@pytest.mark.parametrize("alter", ["pid", "created", "command", "port"])
def test_process_record_cannot_authorize_stopping_a_different_process(servers, alter):
a, b = servers("a"), servers("b")
ready(a)
ready(b)
record = a._read_record()
foreign = b._read_record()
record[alter] = foreign[alter] if alter != "created" else record[alter] + 1
# Both servers can use the same port only before recovery. Ensure port differs.
if alter == "port":
record["port"] += 100
assert a._verified_process(record) is None
assert b.status()["state"] == "ready"
def test_early_server_exit_fails_promptly_and_clears_process_record(servers):
a = servers("a")
config = a._config()
config["vlm"]["crash"] = True
a.configure(config)
started = a.start()
assert started.process.wait(timeout=10) == 9
health = MagicMock()
with pytest.raises(a.ql.QuickLocalSetupError, match="did not become ready"):
a.wait_ready(started, health, timeout=600)
health.assert_not_called()
assert not a.record_path.exists()
def test_temporary_validation_stop_also_stops_launcher_child(servers):
import psutil
a = servers("a")
config = a._config()
config["vlm"]["child"] = True
a.configure(config)
started = ready(a)
child = psutil.Process(int(a.paths.server_config.with_name("ov.conf.child").read_text()))
assert child.is_running()
assert a.ql._stop_process(started.process)
assert started.process.poll() is not None
assert not child.is_running() or child.status() == psutil.STATUS_ZOMBIE
def test_restore_repairs_private_modes_without_touching_external_paths(modules, tmp_path):
home, _p, _m, ql, lifecycle, _packages = modules
server = lifecycle.LocalServer(home)
server.configure(ql.build_server_config(server.paths, {"model": "first"}))
server.paths.root.chmod(0o755)
server.paths.server_config.chmod(0o644)
server.paths.ovcli_config.chmod(0o644)
ql.connection_config({}, home)
if os.name != "nt":
assert server.paths.root.stat().st_mode & 0o777 == 0o700
assert server.paths.server_config.stat().st_mode & 0o777 == 0o600
assert server.paths.ovcli_config.stat().st_mode & 0o777 == 0o600
outside = tmp_path / "outside"
outside.write_text("unrelated")
server.paths.ovcli_config.unlink()
try:
server.paths.ovcli_config.symlink_to(outside)
except OSError:
pytest.skip("symlinks unavailable")
with pytest.raises(ql.QuickLocalSetupError, match="private files"):
ql.connection_config({}, home)
assert outside.read_text() == "unrelated"
@pytest.mark.parametrize("error", [OSError("spawn"), RuntimeError("installer")])
def test_unexpected_start_failure_clears_flag_and_reaches_cli(modules, monkeypatch, error):
home, provider, _module, ql, lifecycle, _packages = modules
provider._hermes_home = str(home)
provider._endpoint = "http://127.0.0.1:1933"
monkeypatch.setattr(
provider, "_profile_config_and_env", lambda: ({"deployment": ql.DEPLOYMENT}, {})
)
monkeypatch.setattr(lifecycle.LocalServer, "start", MagicMock(side_effect=error))
warnings = []
provider._handle_runtime_openviking_unreachable(warning_callback=warnings.append)
assert not provider._runtime_start_pending
assert len(warnings) == 1 and type(error).__name__ in warnings[0]
provider._handle_runtime_openviking_unreachable(warning_callback=warnings.append)
assert len(warnings) == 2
def test_cold_import_timeout_does_not_trigger_reinstallation(modules, monkeypatch):
home, _p, _m, ql, _life, _packages = modules
paths = ql.managed_paths(home)
monkeypatch.setattr(ql, "_pm_available", lambda: False)
paths.runtime_python.parent.mkdir(parents=True)
paths.runtime_python.touch()
paths.server_command.touch()
monkeypatch.setattr(
ql.subprocess, "run", MagicMock(side_effect=subprocess.TimeoutExpired("probe", 120))
)
engine = ql.QuickLocalSetup(health_check=lambda _url: (False, ""))
install = MagicMock()
monkeypatch.setattr(engine, "_install_with_uv", install)
with pytest.raises(ql.QuickLocalSetupError, match="not reinstalled"):
engine._ensure_openviking_installed(paths)
install.assert_not_called()
@pytest.mark.parametrize("failure", [1, subprocess.TimeoutExpired("embedding", 660)])
def test_failed_native_embedding_does_not_activate_setup(modules, monkeypatch, failure):
home, _p, _m, ql, _life, _packages = modules
monkeypatch.setattr(ql, "_validate_vlm", lambda *_args: None)
monkeypatch.setattr(ql, "_pm_available", lambda: False)
monkeypatch.setattr(ql, "_private_child_env", lambda target: {"HERMES_HOME": str(target)})
run = MagicMock()
if isinstance(failure, Exception):
run.side_effect = failure
else:
run.return_value.returncode = failure
monkeypatch.setattr(ql.subprocess, "run", run)
start = MagicMock()
monkeypatch.setattr(ql, "_start_validation_server", start)
paths = ql.managed_paths(home)
engine = ql.QuickLocalSetup(health_check=lambda _url: (True, ""))
with pytest.raises(ql.QuickLocalSetupError, match="embedding"):
engine._validate_generated_config(
paths=paths,
endpoint="http://127.0.0.1:1933",
server_config=ql.build_server_config(paths, {"model": "test"}),
)
start.assert_not_called()
assert not paths.server_config.exists() and not paths.ovcli_config.exists()
assert run.call_args.kwargs["timeout"] == ql._HEALTH_TIMEOUT_SECONDS
assert run.call_args.kwargs["env"]["HERMES_HOME"] == str(home)
assert "math.isfinite" in run.call_args.args[0][-1]
def test_platform_without_reviewed_binary_requires_explicit_consent(modules, monkeypatch):
_home, _p, _m, ql, _life, packages = modules
monkeypatch.setattr(packages.platform, "system", lambda: "Darwin")
monkeypatch.setattr(packages.platform, "machine", lambda: "x86_64")
monkeypatch.setattr(packages.platform, "mac_ver", lambda: ("15.0", (), ""))
with pytest.raises(ql.SourceBuildRequired, match="explicitly allow"):
packages.install_requirements()
assert "llama-cpp-python==0.3.30" in packages.install_requirements(allow_source_build=True)
def test_broken_pm_import_never_calls_legacy_uv_shim(modules, monkeypatch):
import builtins
home, _p, _m, ql, _life, _packages = modules
monkeypatch.setattr(ql, "openviking_install_satisfies_requirement", lambda _paths: False)
monkeypatch.setattr(ql, "_pm_available", lambda: True)
original = builtins.__import__
def import_module(name, *args, **kwargs):
if name == "pm.client":
raise ImportError("broken transitive PM dependency")
return original(name, *args, **kwargs)
monkeypatch.setattr(builtins, "__import__", import_module)
engine = ql.QuickLocalSetup(health_check=lambda _url: (False, ""))
fallback = MagicMock()
monkeypatch.setattr(engine, "_install_with_uv", fallback)
with pytest.raises(ImportError, match="transitive"):
engine._ensure_openviking_installed(ql.managed_paths(home))
fallback.assert_not_called()
@pytest.mark.parametrize("served_profiles", [False, True])
def test_legacy_installer_uses_profile_child_environment(modules, monkeypatch, served_profiles):
from hermes_cli import managed_uv
from tools.environments import local as subprocess_env
home, _p, _m, ql, _life, _packages = modules
source_env = {
"PATH": os.defpath,
"HERMES_HOME": "launch-profile",
"OPENVIKING_API_KEY": "profile-key",
"PYTHONPATH": "host-pythonpath",
"PYTHONHOME": "host-pythonhome",
"VIRTUAL_ENV": "host-runtime",
}
child_env = MagicMock(return_value=source_env.copy())
if served_profiles:
source_env["HERMES_HOME"] = str(home)
child_env.return_value = source_env.copy()
monkeypatch.setattr(subprocess_env, "served_profile_child_env", child_env, raising=False)
else:
monkeypatch.delattr(subprocess_env, "served_profile_child_env", raising=False)
monkeypatch.setattr(subprocess_env, "hermes_subprocess_env", child_env)
monkeypatch.setattr(managed_uv, "resolve_uv", lambda: "uv")
repair = MagicMock(side_effect=AssertionError("must not repair the Hermes runtime"))
monkeypatch.setattr(managed_uv, "ensure_uv", repair)
run = MagicMock(return_value=MagicMock(returncode=0))
monkeypatch.setattr(ql.subprocess, "run", run)
engine = ql.QuickLocalSetup(health_check=lambda _url: (False, ""))
engine._install_with_uv(ql.managed_paths(home), ["reviewed-package"])
if served_profiles:
child_env.assert_called_once_with(target_home=home)
else:
child_env.assert_called_once_with()
assert run.call_count == 2
for call in run.call_args_list:
env = call.kwargs["env"]
assert env["HERMES_HOME"] == str(home)
assert env["OPENVIKING_API_KEY"] == "profile-key"
assert not any(key in env for key in ("PYTHONPATH", "PYTHONHOME", "VIRTUAL_ENV"))
assert source_env["PYTHONPATH"] == "host-pythonpath"
def test_pending_recovery_identity_survives_managed_port_move(modules, monkeypatch):
home, provider, _module, ql, _life, _packages = modules
provider._hermes_home = str(home)
monkeypatch.setattr(
provider, "_profile_config_and_env", lambda: ({"deployment": ql.DEPLOYMENT}, {})
)
provider._client = MagicMock(
_conn_snapshot=("http://127.0.0.1:1933", "key", "default", "default", "hermes")
)
first = provider._capture_commit_scope()
provider._client = MagicMock(
_conn_snapshot=("http://127.0.0.1:1934", "key", "default", "default", "hermes")
)
moved = provider._capture_commit_scope()
assert first.connection_key == moved.connection_key
assert first.marker_id != moved.marker_id
provider._client = MagicMock(
_conn_snapshot=("http://127.0.0.1:1934", "key", "default", "other", "hermes")
)
assert provider._capture_commit_scope().connection_key != moved.connection_key
@pytest.mark.parametrize("consent", [False, True])
def test_source_build_prompt_defaults_to_cancel(modules, monkeypatch, consent):
home, _provider, _module, ql, lifecycle, _packages = modules
setup_module = importlib.import_module(ql.__package__ + "._setup")
server = lifecycle.LocalServer(home)
server.configure(ql.build_server_config(server.paths, {"model": "test"}))
engine = MagicMock()
error = ql.SourceBuildRequired("A source build needs native development tools.")
engine.provision.side_effect = [
error,
ql.QuickLocalSetupResult(server.paths, "http://127.0.0.1:1933", False),
]
monkeypatch.setattr(ql, "QuickLocalSetup", lambda **_kwargs: engine)
select = MagicMock(return_value=int(consent))
config = {"memory": {}}
provider_config = {}
result = setup_module._run_quick_local_setup(
config=config,
provider_config=provider_config,
env_path=home / ".env",
select=select,
cancelled=object(),
)
assert result is consent
assert select.call_args.kwargs["default"] == 0
assert engine.provision.call_count == (2 if consent else 1)
if consent:
assert engine.allow_source_build is True
assert provider_config["deployment"] == ql.DEPLOYMENT
else:
assert provider_config == {}
def test_port_probe_rejects_active_listener(modules):
import socket
_home, _p, _m, ql, _life, _packages = modules
with socket.socket() as listener:
if os.name == "nt":
listener.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
else:
listener.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
listener.bind(("0.0.0.0", 0))
port = listener.getsockname()[1]
listener.listen()
assert not ql._can_bind_local_port("127.0.0.1", port)
assert ql._can_bind_local_port("127.0.0.1", port)
@pytest.mark.parametrize(
"system,machine",
[("Darwin", "arm64"), ("Linux", "x86_64"), ("Linux", "aarch64"), ("Windows", "AMD64")],
)
def test_supported_binary_requirements_keep_native_embedding_hash(
modules, monkeypatch, system, machine
):
_home, _p, _m, ql, _life, packages = modules
monkeypatch.setattr(packages.platform, "system", lambda: system)
monkeypatch.setattr(packages.platform, "machine", lambda: machine)
monkeypatch.setattr(packages.platform, "mac_ver", lambda: ("14.0", (), ""))
monkeypatch.setattr(packages.platform, "libc_ver", lambda: ("glibc", "2.31"))
requirements = packages.install_requirements()
assert requirements[0] == ql.OPENVIKING_REQUIREMENT
assert "#sha256=" in requirements[1]
assert "metal" in requirements[1] if system == "Darwin" else "metal" not in requirements[1]
@pytest.mark.parametrize("action", ["kill", "stop"])
def test_live_provider_recovers_a_stopped_server_in_the_same_session(servers, modules, action):
import time
import psutil
_home, provider, _module, ql, _life, _packages = modules
server = servers("live-provider")
ready(server)
callbacks = []
provider._profile_config_and_env = lambda: ({"deployment": ql.DEPLOYMENT}, {})
provider.initialize(
"retained-session",
hermes_home=str(server.paths.root.parent),
platform="cli",
status_callback=callbacks.append,
warning_callback=callbacks.append,
)
old_client = provider._ensure_client()
old_pid = server.status()["pid"]
assert old_client is not None
if action == "kill":
psutil.Process(old_pid).kill()
else:
server.stop()
assert provider._ensure_client() is None
deadline = time.monotonic() + 20
while provider._ensure_client() is None and time.monotonic() < deadline:
time.sleep(0.05)
assert provider._client is not None and provider._client is not old_client
assert server.status()["pid"] != old_pid
assert any("Starting Quick Local" in message for message in callbacks)
def test_configure_refuses_unverifiable_server_before_changing_live_files(servers, monkeypatch):
server = servers("unverified")
ready(server)
before = {
path: path.read_bytes() for path in (server.paths.server_config, server.paths.ovcli_config)
}
monkeypatch.setattr(server, "_verified_process", lambda _record: None)
monkeypatch.setattr(server, "_adopt", lambda *_args: None)
config = server._config()
config["server"]["root_api_key"] = "rotated-test-key"
with pytest.raises(server.ql.QuickLocalSetupError, match="cannot verify"):
server.configure(config)
assert all(path.read_bytes() == value for path, value in before.items())
assert not server.paths.restart_required_marker.exists()
assert server.ql.server_belongs_to_profile(server.paths, server.status()["endpoint"])
def test_configure_adopts_a_lost_record_before_changing_the_key(servers):
import psutil
server = servers("lost-record")
ready(server)
old_pid = server.status()["pid"]
old_family = {old_pid, *(p.pid for p in psutil.Process(old_pid).children(recursive=True))}
server.record_path.unlink()
config = server._config()
config["server"]["root_api_key"] = "rotated-test-key"
server.configure(config)
# Windows venv redirectors expose a launcher and a child with the same
# command. Either verified member can own the recovered record.
assert server._read_record()["pid"] in old_family
ready(server)
assert server.status()["pid"] not in old_family
assert server.ql.server_belongs_to_profile(server.paths, server.status()["endpoint"])
def test_new_managed_ports_leave_the_openviking_default_free(modules, monkeypatch):
_home, _p, _m, ql, _life, _packages = modules
monkeypatch.setattr(ql, "_can_bind_local_port", lambda *_args: True)
assert ql.find_available_port() == 1934
# Existing Quick Local profiles retain their original port.
assert ql.find_available_port(preferred_endpoint="http://127.0.0.1:1933") == 1933
def test_retained_provider_recovers_a_port_taken_by_another_profile(servers, modules):
import time
_h, provider, _module, ql, _life, _packages = modules
a, b = servers("retained-a"), servers("retained-b")
ready(a)
old_endpoint = a.status()["endpoint"]
provider._profile_config_and_env = lambda: ({"deployment": ql.DEPLOYMENT}, {})
provider.initialize("retained-port", hermes_home=str(a.paths.root.parent), platform="cli")
assert provider._ensure_client() is not None
a.stop()
config = b._config()
config["server"]["port"] = ql._endpoint_port(old_endpoint)
b.configure(config)
ready(b)
foreign_pid = b.status()["pid"]
assert provider._ensure_client() is None
deadline = time.monotonic() + 20
while provider._ensure_client() is None and time.monotonic() < deadline:
time.sleep(0.05)
assert provider._client is not None
assert provider._endpoint != old_endpoint
assert provider._endpoint == ql.connection_config({}, a.paths.root.parent)["url"]
assert b.status()["pid"] == foreign_pid
def test_switching_away_stops_only_the_previous_managed_server(servers, modules, capsys):
_h, _p, _m, ql, _life, _packages = modules
setup = importlib.import_module(ql.__package__ + "._setup")
a, b = servers("switch-a"), servers("switch-b")
ready(a)
ready(b)
b_pid = b.status()["pid"]
config = {"memory": {}}
provider_config = {"deployment": ql.DEPLOYMENT}
a.paths.workspace.mkdir()
marker = a.paths.workspace / "retained-memory"
marker.write_text("keep")
setup._save_hermes_only_config(
config=config,
provider_config=provider_config,
env_path=a.paths.root.parent / ".env",
values={"endpoint": "https://custom.example", "api_key": "synthetic-key"},
)
assert a.status()["state"] == "stopped"
assert b.status()["pid"] == b_pid
assert marker.read_text() == "keep"
assert "data is retained" in capsys.readouterr().out
def test_unconfigured_status_does_not_create_managed_storage(modules, monkeypatch, capsys):
from argparse import Namespace
home, _p, _m, ql, _life, _packages = modules
cli = importlib.import_module(ql.__package__ + ".cli")
monkeypatch.setattr(cli, "get_hermes_home", lambda: home)
cli._run(Namespace(local_action="status"))
assert "not configured" in capsys.readouterr().out
assert not ql.managed_paths(home).root.exists()
def test_changed_native_pins_reinstall_an_existing_runtime(modules, monkeypatch):
home, _p, _m, ql, _life, packages = modules
paths = ql.managed_paths(home)
paths.root.mkdir()
(paths.root / "runtime-requirements.json").write_text('["older-pins"]')
monkeypatch.setattr(ql, "openviking_install_satisfies_requirement", lambda _paths: True)
monkeypatch.setattr(ql, "_pm_available", lambda: False)
monkeypatch.setattr(packages, "verified_requirements", lambda values, _cache: values)
monkeypatch.setattr(
packages, "resolve_server_requirement", lambda **_kw: "openviking[local-embed]==0.5.0"
)
engine = ql.QuickLocalSetup(health_check=lambda _url: (False, ""))
install = MagicMock()
monkeypatch.setattr(engine, "_install_with_uv", install)
assert engine._ensure_openviking_installed(paths)
requirements = packages.install_requirements()
requirements[0] = packages.resolve_server_requirement()
install.assert_called_once_with(paths, requirements)
assert not engine._ensure_openviking_installed(paths)
assert install.call_count == 1
def test_legacy_install_without_uv_fails_without_repairing_hermes(modules, monkeypatch):
import hermes_constants
from hermes_cli import managed_uv
home, _p, _m, ql, _life, _packages = modules
monkeypatch.setattr(hermes_constants, "get_default_hermes_root", lambda: home)
monkeypatch.setattr(managed_uv, "resolve_uv", lambda: None)
monkeypatch.setattr(ql.shutil, "which", lambda _name: None)
repair = MagicMock(side_effect=SystemExit("must not rebuild Hermes"))
monkeypatch.setattr(managed_uv, "ensure_uv", repair)
engine = ql.QuickLocalSetup(health_check=lambda _url: (False, ""))
with pytest.raises(ql.QuickLocalSetupError, match="needs uv"):
engine._install_with_uv(ql.managed_paths(home), ["isolated-package"])
repair.assert_not_called()
def test_lost_record_adoption_survives_a_selected_runtime_upgrade(servers, modules, monkeypatch):
import psutil
_home, _p, _m, ql, _life, _packages = modules
server = servers("old-runtime")
ready(server)
old_pid = server.status()["pid"]
old_family = {old_pid, *(p.pid for p in psutil.Process(old_pid).children(recursive=True))}
server.record_path.unlink()
old_command = server.paths.server_command
new_command = server.paths.runtime / "new-generation/bin/openviking-server"
new_command.parent.mkdir(parents=True)
new_command.write_bytes(old_command.read_bytes())
monkeypatch.setattr(ql.QuickLocalPaths, "server_command", property(lambda _self: new_command))
config = server._config()
config["server"]["root_api_key"] = "rotated-test-key"
server.configure(config, runtime_changed=True)
assert server._read_record()["pid"] in old_family
assert server._read_record()["command"] == str(old_command)
ready(server)
assert server.status()["pid"] not in old_family
assert server._read_record()["command"] == str(new_command)
def test_stop_from_another_process_accepts_a_terminated_child(servers, modules):
"""A CLI cannot reap a server whose parent is a running Hermes process."""
import json
from pathlib import Path
_home, _p, module, _ql, _life, _packages = modules
server = servers("external-stop")
ready(server)
script = f"""
import importlib.util,sys
from pathlib import Path
sys.path[:0] = {json.dumps(sys.path)}
spec=importlib.util.spec_from_file_location("external_stop_provider", {json.dumps(module.__file__)}, submodule_search_locations=[{json.dumps(str(Path(module.__file__).parent))}])
package=importlib.util.module_from_spec(spec);sys.modules[spec.name]=package;spec.loader.exec_module(package)
from external_stop_provider.local_server import LocalServer
assert LocalServer(Path({json.dumps(str(server.paths.root.parent))})).stop()
"""
result = subprocess.run(
[sys.executable, "-c", script], capture_output=True, text=True, timeout=30
)
assert result.returncode == 0, result.stderr