The architecture has been updated

hermes_code/tests/honcho_integration/test_async_memory.py

@@ -0,0 +1,560 @@
+"""Tests for the async-memory Honcho improvements.
+
+Covers:
+  - write_frequency parsing (async / turn / session / int)
+  - memory_mode parsing
+  - resolve_session_name with session_title
+  - HonchoSessionManager.save() routing per write_frequency
+  - async writer thread lifecycle and retry
+  - flush_all() drains pending messages
+  - shutdown() joins the thread
+  - memory_mode gating helpers (unit-level)
+"""
+
+import json
+import queue
+import threading
+import time
+from pathlib import Path
+from unittest.mock import MagicMock, patch, call
+
+import pytest
+
+from honcho_integration.client import HonchoClientConfig
+from honcho_integration.session import (
+    HonchoSession,
+    HonchoSessionManager,
+    _ASYNC_SHUTDOWN,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _make_session(**kwargs) -> HonchoSession:
+    return HonchoSession(
+        key=kwargs.get("key", "cli:test"),
+        user_peer_id=kwargs.get("user_peer_id", "eri"),
+        assistant_peer_id=kwargs.get("assistant_peer_id", "hermes"),
+        honcho_session_id=kwargs.get("honcho_session_id", "cli-test"),
+        messages=kwargs.get("messages", []),
+    )
+
+
+def _make_manager(write_frequency="turn", memory_mode="hybrid") -> HonchoSessionManager:
+    cfg = HonchoClientConfig(
+        write_frequency=write_frequency,
+        memory_mode=memory_mode,
+        api_key="test-key",
+        enabled=True,
+    )
+    mgr = HonchoSessionManager(config=cfg)
+    mgr._honcho = MagicMock()
+    return mgr
+
+
+# ---------------------------------------------------------------------------
+# write_frequency parsing from config file
+# ---------------------------------------------------------------------------
+
+class TestWriteFrequencyParsing:
+    def test_string_async(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k", "writeFrequency": "async"}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.write_frequency == "async"
+
+    def test_string_turn(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k", "writeFrequency": "turn"}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.write_frequency == "turn"
+
+    def test_string_session(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k", "writeFrequency": "session"}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.write_frequency == "session"
+
+    def test_integer_frequency(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k", "writeFrequency": 5}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.write_frequency == 5
+
+    def test_integer_string_coerced(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k", "writeFrequency": "3"}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.write_frequency == 3
+
+    def test_host_block_overrides_root(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({
+            "apiKey": "k",
+            "writeFrequency": "turn",
+            "hosts": {"hermes": {"writeFrequency": "session"}},
+        }))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.write_frequency == "session"
+
+    def test_defaults_to_async(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k"}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.write_frequency == "async"
+
+
+# ---------------------------------------------------------------------------
+# memory_mode parsing from config file
+# ---------------------------------------------------------------------------
+
+class TestMemoryModeParsing:
+    def test_hybrid(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k", "memoryMode": "hybrid"}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.memory_mode == "hybrid"
+
+    def test_honcho_only(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k", "memoryMode": "honcho"}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.memory_mode == "honcho"
+
+    def test_defaults_to_hybrid(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({"apiKey": "k"}))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.memory_mode == "hybrid"
+
+    def test_host_block_overrides_root(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({
+            "apiKey": "k",
+            "memoryMode": "hybrid",
+            "hosts": {"hermes": {"memoryMode": "honcho"}},
+        }))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.memory_mode == "honcho"
+
+    def test_object_form_sets_default_and_overrides(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({
+            "apiKey": "k",
+            "hosts": {"hermes": {"memoryMode": {
+                "default": "hybrid",
+                "hermes": "honcho",
+            }}},
+        }))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.memory_mode == "hybrid"
+        assert cfg.peer_memory_mode("hermes") == "honcho"
+        assert cfg.peer_memory_mode("unknown") == "hybrid"  # falls through to default
+
+    def test_object_form_no_default_falls_back_to_hybrid(self, tmp_path):
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({
+            "apiKey": "k",
+            "hosts": {"hermes": {"memoryMode": {"hermes": "honcho"}}},
+        }))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.memory_mode == "hybrid"
+        assert cfg.peer_memory_mode("hermes") == "honcho"
+        assert cfg.peer_memory_mode("other") == "hybrid"
+
+    def test_global_string_host_object_override(self, tmp_path):
+        """Host object form overrides global string."""
+        cfg_file = tmp_path / "config.json"
+        cfg_file.write_text(json.dumps({
+            "apiKey": "k",
+            "memoryMode": "honcho",
+            "hosts": {"hermes": {"memoryMode": {"default": "hybrid", "hermes": "honcho"}}},
+        }))
+        cfg = HonchoClientConfig.from_global_config(config_path=cfg_file)
+        assert cfg.memory_mode == "hybrid"  # host default wins over global "honcho"
+        assert cfg.peer_memory_mode("hermes") == "honcho"
+
+
+# ---------------------------------------------------------------------------
+# resolve_session_name with session_title
+# ---------------------------------------------------------------------------
+
+class TestResolveSessionNameTitle:
+    def test_manual_override_beats_title(self):
+        cfg = HonchoClientConfig(sessions={"/my/project": "manual-name"})
+        result = cfg.resolve_session_name("/my/project", session_title="the-title")
+        assert result == "manual-name"
+
+    def test_title_beats_dirname(self):
+        cfg = HonchoClientConfig()
+        result = cfg.resolve_session_name("/some/dir", session_title="my-project")
+        assert result == "my-project"
+
+    def test_title_with_peer_prefix(self):
+        cfg = HonchoClientConfig(peer_name="eri", session_peer_prefix=True)
+        result = cfg.resolve_session_name("/some/dir", session_title="aeris")
+        assert result == "eri-aeris"
+
+    def test_title_sanitized(self):
+        cfg = HonchoClientConfig()
+        result = cfg.resolve_session_name("/some/dir", session_title="my project/name!")
+        # trailing dashes stripped by .strip('-')
+        assert result == "my-project-name"
+
+    def test_title_all_invalid_chars_falls_back_to_dirname(self):
+        cfg = HonchoClientConfig()
+        result = cfg.resolve_session_name("/some/dir", session_title="!!! ###")
+        # sanitized to empty → falls back to dirname
+        assert result == "dir"
+
+    def test_none_title_falls_back_to_dirname(self):
+        cfg = HonchoClientConfig()
+        result = cfg.resolve_session_name("/some/dir", session_title=None)
+        assert result == "dir"
+
+    def test_empty_title_falls_back_to_dirname(self):
+        cfg = HonchoClientConfig()
+        result = cfg.resolve_session_name("/some/dir", session_title="")
+        assert result == "dir"
+
+    def test_per_session_uses_session_id(self):
+        cfg = HonchoClientConfig(session_strategy="per-session")
+        result = cfg.resolve_session_name("/some/dir", session_id="20260309_175514_9797dd")
+        assert result == "20260309_175514_9797dd"
+
+    def test_per_session_with_peer_prefix(self):
+        cfg = HonchoClientConfig(session_strategy="per-session", peer_name="eri", session_peer_prefix=True)
+        result = cfg.resolve_session_name("/some/dir", session_id="20260309_175514_9797dd")
+        assert result == "eri-20260309_175514_9797dd"
+
+    def test_per_session_no_id_falls_back_to_dirname(self):
+        cfg = HonchoClientConfig(session_strategy="per-session")
+        result = cfg.resolve_session_name("/some/dir", session_id=None)
+        assert result == "dir"
+
+    def test_title_beats_session_id(self):
+        cfg = HonchoClientConfig(session_strategy="per-session")
+        result = cfg.resolve_session_name("/some/dir", session_title="my-title", session_id="20260309_175514_9797dd")
+        assert result == "my-title"
+
+    def test_manual_beats_session_id(self):
+        cfg = HonchoClientConfig(session_strategy="per-session", sessions={"/some/dir": "pinned"})
+        result = cfg.resolve_session_name("/some/dir", session_id="20260309_175514_9797dd")
+        assert result == "pinned"
+
+    def test_global_strategy_returns_workspace(self):
+        cfg = HonchoClientConfig(session_strategy="global", workspace_id="my-workspace")
+        result = cfg.resolve_session_name("/some/dir")
+        assert result == "my-workspace"
+
+
+# ---------------------------------------------------------------------------
+# save() routing per write_frequency
+# ---------------------------------------------------------------------------
+
+class TestSaveRouting:
+    def _make_session_with_message(self, mgr=None):
+        sess = _make_session()
+        sess.add_message("user", "hello")
+        sess.add_message("assistant", "hi")
+        if mgr:
+            mgr._cache[sess.key] = sess
+        return sess
+
+    def test_turn_flushes_immediately(self):
+        mgr = _make_manager(write_frequency="turn")
+        sess = self._make_session_with_message(mgr)
+        with patch.object(mgr, "_flush_session") as mock_flush:
+            mgr.save(sess)
+            mock_flush.assert_called_once_with(sess)
+
+    def test_session_mode_does_not_flush(self):
+        mgr = _make_manager(write_frequency="session")
+        sess = self._make_session_with_message(mgr)
+        with patch.object(mgr, "_flush_session") as mock_flush:
+            mgr.save(sess)
+            mock_flush.assert_not_called()
+
+    def test_async_mode_enqueues(self):
+        mgr = _make_manager(write_frequency="async")
+        sess = self._make_session_with_message(mgr)
+        with patch.object(mgr, "_flush_session") as mock_flush:
+            mgr.save(sess)
+            # flush_session should NOT be called synchronously
+            mock_flush.assert_not_called()
+        assert not mgr._async_queue.empty()
+
+    def test_int_frequency_flushes_on_nth_turn(self):
+        mgr = _make_manager(write_frequency=3)
+        sess = self._make_session_with_message(mgr)
+        with patch.object(mgr, "_flush_session") as mock_flush:
+            mgr.save(sess)  # turn 1
+            mgr.save(sess)  # turn 2
+            assert mock_flush.call_count == 0
+            mgr.save(sess)  # turn 3
+            assert mock_flush.call_count == 1
+
+    def test_int_frequency_skips_other_turns(self):
+        mgr = _make_manager(write_frequency=5)
+        sess = self._make_session_with_message(mgr)
+        with patch.object(mgr, "_flush_session") as mock_flush:
+            for _ in range(4):
+                mgr.save(sess)
+            assert mock_flush.call_count == 0
+            mgr.save(sess)  # turn 5
+            assert mock_flush.call_count == 1
+
+
+# ---------------------------------------------------------------------------
+# flush_all()
+# ---------------------------------------------------------------------------
+
+class TestFlushAll:
+    def test_flushes_all_cached_sessions(self):
+        mgr = _make_manager(write_frequency="session")
+        s1 = _make_session(key="s1", honcho_session_id="s1")
+        s2 = _make_session(key="s2", honcho_session_id="s2")
+        s1.add_message("user", "a")
+        s2.add_message("user", "b")
+        mgr._cache = {"s1": s1, "s2": s2}
+
+        with patch.object(mgr, "_flush_session") as mock_flush:
+            mgr.flush_all()
+            assert mock_flush.call_count == 2
+
+    def test_flush_all_drains_async_queue(self):
+        mgr = _make_manager(write_frequency="async")
+        sess = _make_session()
+        sess.add_message("user", "pending")
+        mgr._async_queue.put(sess)
+
+        with patch.object(mgr, "_flush_session") as mock_flush:
+            mgr.flush_all()
+            # Called at least once for the queued item
+            assert mock_flush.call_count >= 1
+
+    def test_flush_all_tolerates_errors(self):
+        mgr = _make_manager(write_frequency="session")
+        sess = _make_session()
+        mgr._cache = {"key": sess}
+        with patch.object(mgr, "_flush_session", side_effect=RuntimeError("oops")):
+            # Should not raise
+            mgr.flush_all()
+
+
+# ---------------------------------------------------------------------------
+# async writer thread lifecycle
+# ---------------------------------------------------------------------------
+
+class TestAsyncWriterThread:
+    def test_thread_started_on_async_mode(self):
+        mgr = _make_manager(write_frequency="async")
+        assert mgr._async_thread is not None
+        assert mgr._async_thread.is_alive()
+        mgr.shutdown()
+
+    def test_no_thread_for_turn_mode(self):
+        mgr = _make_manager(write_frequency="turn")
+        assert mgr._async_thread is None
+        assert mgr._async_queue is None
+
+    def test_shutdown_joins_thread(self):
+        mgr = _make_manager(write_frequency="async")
+        assert mgr._async_thread.is_alive()
+        mgr.shutdown()
+        assert not mgr._async_thread.is_alive()
+
+    def test_async_writer_calls_flush(self):
+        mgr = _make_manager(write_frequency="async")
+        sess = _make_session()
+        sess.add_message("user", "async msg")
+
+        flushed = []
+
+        def capture(s):
+            flushed.append(s)
+            return True
+
+        mgr._flush_session = capture
+        mgr._async_queue.put(sess)
+        # Give the daemon thread time to process
+        deadline = time.time() + 2.0
+        while not flushed and time.time() < deadline:
+            time.sleep(0.05)
+
+        mgr.shutdown()
+        assert len(flushed) == 1
+        assert flushed[0] is sess
+
+    def test_shutdown_sentinel_stops_loop(self):
+        mgr = _make_manager(write_frequency="async")
+        thread = mgr._async_thread
+        mgr.shutdown()
+        thread.join(timeout=3)
+        assert not thread.is_alive()
+
+
+# ---------------------------------------------------------------------------
+# async retry on failure
+# ---------------------------------------------------------------------------
+
+class TestAsyncWriterRetry:
+    def test_retries_once_on_failure(self):
+        mgr = _make_manager(write_frequency="async")
+        sess = _make_session()
+        sess.add_message("user", "msg")
+
+        call_count = [0]
+
+        def flaky_flush(s):
+            call_count[0] += 1
+            if call_count[0] == 1:
+                raise ConnectionError("network blip")
+            # second call succeeds silently
+
+        mgr._flush_session = flaky_flush
+
+        with patch("time.sleep"):  # skip the 2s sleep in retry
+            mgr._async_queue.put(sess)
+            deadline = time.time() + 3.0
+            while call_count[0] < 2 and time.time() < deadline:
+                time.sleep(0.05)
+
+        mgr.shutdown()
+        assert call_count[0] == 2
+
+    def test_drops_after_two_failures(self):
+        mgr = _make_manager(write_frequency="async")
+        sess = _make_session()
+        sess.add_message("user", "msg")
+
+        call_count = [0]
+
+        def always_fail(s):
+            call_count[0] += 1
+            raise RuntimeError("always broken")
+
+        mgr._flush_session = always_fail
+
+        with patch("time.sleep"):
+            mgr._async_queue.put(sess)
+            deadline = time.time() + 3.0
+            while call_count[0] < 2 and time.time() < deadline:
+                time.sleep(0.05)
+
+        mgr.shutdown()
+        # Should have tried exactly twice (initial + one retry) and not crashed
+        assert call_count[0] == 2
+        assert not mgr._async_thread.is_alive()
+
+    def test_retries_when_flush_reports_failure(self):
+        mgr = _make_manager(write_frequency="async")
+        sess = _make_session()
+        sess.add_message("user", "msg")
+
+        call_count = [0]
+
+        def fail_then_succeed(_session):
+            call_count[0] += 1
+            return call_count[0] > 1
+
+        mgr._flush_session = fail_then_succeed
+
+        with patch("time.sleep"):
+            mgr._async_queue.put(sess)
+            deadline = time.time() + 3.0
+            while call_count[0] < 2 and time.time() < deadline:
+                time.sleep(0.05)
+
+        mgr.shutdown()
+        assert call_count[0] == 2
+
+
+class TestMemoryFileMigrationTargets:
+    def test_soul_upload_targets_ai_peer(self, tmp_path):
+        mgr = _make_manager(write_frequency="turn")
+        session = _make_session(
+            key="cli:test",
+            user_peer_id="custom-user",
+            assistant_peer_id="custom-ai",
+            honcho_session_id="cli-test",
+        )
+        mgr._cache[session.key] = session
+
+        user_peer = MagicMock(name="user-peer")
+        ai_peer = MagicMock(name="ai-peer")
+        mgr._peers_cache[session.user_peer_id] = user_peer
+        mgr._peers_cache[session.assistant_peer_id] = ai_peer
+
+        honcho_session = MagicMock()
+        mgr._sessions_cache[session.honcho_session_id] = honcho_session
+
+        (tmp_path / "MEMORY.md").write_text("memory facts", encoding="utf-8")
+        (tmp_path / "USER.md").write_text("user profile", encoding="utf-8")
+        (tmp_path / "SOUL.md").write_text("ai identity", encoding="utf-8")
+
+        uploaded = mgr.migrate_memory_files(session.key, str(tmp_path))
+
+        assert uploaded is True
+        assert honcho_session.upload_file.call_count == 3
+
+        peer_by_upload_name = {}
+        for call_args in honcho_session.upload_file.call_args_list:
+            payload = call_args.kwargs["file"]
+            peer_by_upload_name[payload[0]] = call_args.kwargs["peer"]
+
+        assert peer_by_upload_name["consolidated_memory.md"] is user_peer
+        assert peer_by_upload_name["user_profile.md"] is user_peer
+        assert peer_by_upload_name["agent_soul.md"] is ai_peer
+
+
+# ---------------------------------------------------------------------------
+# HonchoClientConfig dataclass defaults for new fields
+# ---------------------------------------------------------------------------
+
+class TestNewConfigFieldDefaults:
+    def test_write_frequency_default(self):
+        cfg = HonchoClientConfig()
+        assert cfg.write_frequency == "async"
+
+    def test_memory_mode_default(self):
+        cfg = HonchoClientConfig()
+        assert cfg.memory_mode == "hybrid"
+
+    def test_write_frequency_set(self):
+        cfg = HonchoClientConfig(write_frequency="turn")
+        assert cfg.write_frequency == "turn"
+
+    def test_memory_mode_set(self):
+        cfg = HonchoClientConfig(memory_mode="honcho")
+        assert cfg.memory_mode == "honcho"
+
+    def test_peer_memory_mode_falls_back_to_global(self):
+        cfg = HonchoClientConfig(memory_mode="honcho")
+        assert cfg.peer_memory_mode("any-peer") == "honcho"
+
+    def test_peer_memory_mode_override(self):
+        cfg = HonchoClientConfig(memory_mode="hybrid", peer_memory_modes={"hermes": "honcho"})
+        assert cfg.peer_memory_mode("hermes") == "honcho"
+        assert cfg.peer_memory_mode("other") == "hybrid"
+
+
+class TestPrefetchCacheAccessors:
+    def test_set_and_pop_context_result(self):
+        mgr = _make_manager(write_frequency="turn")
+        payload = {"representation": "Known user", "card": "prefers concise replies"}
+
+        mgr.set_context_result("cli:test", payload)
+
+        assert mgr.pop_context_result("cli:test") == payload
+        assert mgr.pop_context_result("cli:test") == {}
+
+    def test_set_and_pop_dialectic_result(self):
+        mgr = _make_manager(write_frequency="turn")
+
+        mgr.set_dialectic_result("cli:test", "Resume with toolset cleanup")
+
+        assert mgr.pop_dialectic_result("cli:test") == "Resume with toolset cleanup"
+        assert mgr.pop_dialectic_result("cli:test") == ""

hermes_code/tests/honcho_integration/test_cli.py

@@ -0,0 +1,29 @@
+"""Tests for Honcho CLI helpers."""
+
+from honcho_integration.cli import _resolve_api_key
+
+
+class TestResolveApiKey:
+    def test_prefers_host_scoped_key(self):
+        cfg = {
+            "apiKey": "root-key",
+            "hosts": {
+                "hermes": {
+                    "apiKey": "host-key",
+                }
+            },
+        }
+        assert _resolve_api_key(cfg) == "host-key"
+
+    def test_falls_back_to_root_key(self):
+        cfg = {
+            "apiKey": "root-key",
+            "hosts": {"hermes": {}},
+        }
+        assert _resolve_api_key(cfg) == "root-key"
+
+    def test_falls_back_to_env_key(self, monkeypatch):
+        monkeypatch.setenv("HONCHO_API_KEY", "env-key")
+        assert _resolve_api_key({}) == "env-key"
+        monkeypatch.delenv("HONCHO_API_KEY", raising=False)
+

hermes_code/tests/honcho_integration/test_client.py

@@ -0,0 +1,381 @@
+"""Tests for honcho_integration/client.py — Honcho client configuration."""
+
+import json
+import os
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from honcho_integration.client import (
+    HonchoClientConfig,
+    get_honcho_client,
+    reset_honcho_client,
+    resolve_config_path,
+    GLOBAL_CONFIG_PATH,
+    HOST,
+)
+
+
+class TestHonchoClientConfigDefaults:
+    def test_default_values(self):
+        config = HonchoClientConfig()
+        assert config.host == "hermes"
+        assert config.workspace_id == "hermes"
+        assert config.api_key is None
+        assert config.environment == "production"
+        assert config.enabled is False
+        assert config.save_messages is True
+        assert config.session_strategy == "per-directory"
+        assert config.recall_mode == "hybrid"
+        assert config.session_peer_prefix is False
+        assert config.linked_hosts == []
+        assert config.sessions == {}
+
+
+class TestFromEnv:
+    def test_reads_api_key_from_env(self):
+        with patch.dict(os.environ, {"HONCHO_API_KEY": "test-key-123"}):
+            config = HonchoClientConfig.from_env()
+        assert config.api_key == "test-key-123"
+        assert config.enabled is True
+
+    def test_reads_environment_from_env(self):
+        with patch.dict(os.environ, {
+            "HONCHO_API_KEY": "key",
+            "HONCHO_ENVIRONMENT": "staging",
+        }):
+            config = HonchoClientConfig.from_env()
+        assert config.environment == "staging"
+
+    def test_defaults_without_env(self):
+        with patch.dict(os.environ, {}, clear=True):
+            # Remove HONCHO_API_KEY if it exists
+            os.environ.pop("HONCHO_API_KEY", None)
+            os.environ.pop("HONCHO_ENVIRONMENT", None)
+            config = HonchoClientConfig.from_env()
+        assert config.api_key is None
+        assert config.environment == "production"
+
+    def test_custom_workspace(self):
+        config = HonchoClientConfig.from_env(workspace_id="custom")
+        assert config.workspace_id == "custom"
+
+    def test_reads_base_url_from_env(self):
+        with patch.dict(os.environ, {"HONCHO_BASE_URL": "http://localhost:8000"}, clear=False):
+            config = HonchoClientConfig.from_env()
+        assert config.base_url == "http://localhost:8000"
+        assert config.enabled is True
+
+    def test_enabled_without_api_key_when_base_url_set(self):
+        """base_url alone (no API key) is sufficient to enable a local instance."""
+        with patch.dict(os.environ, {"HONCHO_BASE_URL": "http://localhost:8000"}, clear=False):
+            os.environ.pop("HONCHO_API_KEY", None)
+            config = HonchoClientConfig.from_env()
+        assert config.api_key is None
+        assert config.base_url == "http://localhost:8000"
+        assert config.enabled is True
+
+
+class TestFromGlobalConfig:
+    def test_missing_config_falls_back_to_env(self, tmp_path):
+        with patch.dict(os.environ, {}, clear=True):
+            config = HonchoClientConfig.from_global_config(
+                config_path=tmp_path / "nonexistent.json"
+            )
+        # Should fall back to from_env
+        assert config.enabled is False
+        assert config.api_key is None
+
+    def test_reads_full_config(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "my-honcho-key",
+            "workspace": "my-workspace",
+            "environment": "staging",
+            "peerName": "alice",
+            "aiPeer": "hermes-custom",
+            "enabled": True,
+            "saveMessages": False,
+            "contextTokens": 2000,
+            "sessionStrategy": "per-project",
+            "sessionPeerPrefix": True,
+            "sessions": {"/home/user/proj": "my-session"},
+            "hosts": {
+                "hermes": {
+                    "workspace": "override-ws",
+                    "aiPeer": "override-ai",
+                    "linkedHosts": ["cursor"],
+                }
+            }
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.api_key == "my-honcho-key"
+        # Host block workspace overrides root workspace
+        assert config.workspace_id == "override-ws"
+        assert config.ai_peer == "override-ai"
+        assert config.linked_hosts == ["cursor"]
+        assert config.environment == "staging"
+        assert config.peer_name == "alice"
+        assert config.enabled is True
+        assert config.save_messages is False
+        assert config.session_strategy == "per-project"
+        assert config.session_peer_prefix is True
+
+    def test_host_block_overrides_root(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "key",
+            "workspace": "root-ws",
+            "aiPeer": "root-ai",
+            "hosts": {
+                "hermes": {
+                    "workspace": "host-ws",
+                    "aiPeer": "host-ai",
+                }
+            }
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.workspace_id == "host-ws"
+        assert config.ai_peer == "host-ai"
+
+    def test_root_fields_used_when_no_host_block(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "key",
+            "workspace": "root-ws",
+            "aiPeer": "root-ai",
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.workspace_id == "root-ws"
+        assert config.ai_peer == "root-ai"
+
+    def test_session_strategy_default_from_global_config(self, tmp_path):
+        """from_global_config with no sessionStrategy should match dataclass default."""
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({"apiKey": "key"}))
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.session_strategy == "per-directory"
+
+    def test_context_tokens_host_block_wins(self, tmp_path):
+        """Host block contextTokens should override root."""
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "key",
+            "contextTokens": 1000,
+            "hosts": {"hermes": {"contextTokens": 2000}},
+        }))
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.context_tokens == 2000
+
+    def test_recall_mode_from_config(self, tmp_path):
+        """recallMode is read from config, host block wins."""
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "key",
+            "recallMode": "tools",
+            "hosts": {"hermes": {"recallMode": "context"}},
+        }))
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.recall_mode == "context"
+
+    def test_recall_mode_default(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({"apiKey": "key"}))
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.recall_mode == "hybrid"
+
+    def test_corrupt_config_falls_back_to_env(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_file.write_text("not valid json{{{")
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        # Should fall back to from_env without crashing
+        assert isinstance(config, HonchoClientConfig)
+
+    def test_api_key_env_fallback(self, tmp_path):
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({"enabled": True}))
+
+        with patch.dict(os.environ, {"HONCHO_API_KEY": "env-key"}):
+            config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.api_key == "env-key"
+
+    def test_base_url_env_fallback(self, tmp_path):
+        """HONCHO_BASE_URL env var is used when no baseUrl in config JSON."""
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({"workspace": "local"}))
+
+        with patch.dict(os.environ, {"HONCHO_BASE_URL": "http://localhost:8000"}, clear=False):
+            config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.base_url == "http://localhost:8000"
+        assert config.enabled is True
+
+    def test_base_url_from_config_root(self, tmp_path):
+        """baseUrl in config root is read and takes precedence over env var."""
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({"baseUrl": "http://config-host:9000"}))
+
+        with patch.dict(os.environ, {"HONCHO_BASE_URL": "http://localhost:8000"}, clear=False):
+            config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.base_url == "http://config-host:9000"
+
+    def test_base_url_not_read_from_host_block(self, tmp_path):
+        """baseUrl is a root-level connection setting, not overridable per-host (consistent with apiKey)."""
+        config_file = tmp_path / "config.json"
+        config_file.write_text(json.dumps({
+            "baseUrl": "http://root:9000",
+            "hosts": {"hermes": {"baseUrl": "http://host-block:9001"}},
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+        assert config.base_url == "http://root:9000"
+
+
+class TestResolveSessionName:
+    def test_manual_override(self):
+        config = HonchoClientConfig(sessions={"/home/user/proj": "custom-session"})
+        assert config.resolve_session_name("/home/user/proj") == "custom-session"
+
+    def test_derive_from_dirname(self):
+        config = HonchoClientConfig()
+        result = config.resolve_session_name("/home/user/my-project")
+        assert result == "my-project"
+
+    def test_peer_prefix(self):
+        config = HonchoClientConfig(peer_name="alice", session_peer_prefix=True)
+        result = config.resolve_session_name("/home/user/proj")
+        assert result == "alice-proj"
+
+    def test_no_peer_prefix_when_no_peer_name(self):
+        config = HonchoClientConfig(session_peer_prefix=True)
+        result = config.resolve_session_name("/home/user/proj")
+        assert result == "proj"
+
+    def test_default_cwd(self):
+        config = HonchoClientConfig()
+        result = config.resolve_session_name()
+        # Should use os.getcwd() basename
+        assert result == Path.cwd().name
+
+    def test_per_repo_uses_git_root(self):
+        config = HonchoClientConfig(session_strategy="per-repo")
+        with patch.object(
+            HonchoClientConfig, "_git_repo_name", return_value="hermes-agent"
+        ):
+            result = config.resolve_session_name("/home/user/hermes-agent/subdir")
+        assert result == "hermes-agent"
+
+    def test_per_repo_with_peer_prefix(self):
+        config = HonchoClientConfig(
+            session_strategy="per-repo", peer_name="eri", session_peer_prefix=True
+        )
+        with patch.object(
+            HonchoClientConfig, "_git_repo_name", return_value="groudon"
+        ):
+            result = config.resolve_session_name("/home/user/groudon/src")
+        assert result == "eri-groudon"
+
+    def test_per_repo_falls_back_to_dirname_outside_git(self):
+        config = HonchoClientConfig(session_strategy="per-repo")
+        with patch.object(
+            HonchoClientConfig, "_git_repo_name", return_value=None
+        ):
+            result = config.resolve_session_name("/home/user/not-a-repo")
+        assert result == "not-a-repo"
+
+    def test_per_repo_manual_override_still_wins(self):
+        config = HonchoClientConfig(
+            session_strategy="per-repo",
+            sessions={"/home/user/proj": "custom-session"},
+        )
+        result = config.resolve_session_name("/home/user/proj")
+        assert result == "custom-session"
+
+
+class TestGetLinkedWorkspaces:
+    def test_resolves_linked_hosts(self):
+        config = HonchoClientConfig(
+            workspace_id="hermes-ws",
+            linked_hosts=["cursor", "windsurf"],
+            raw={
+                "hosts": {
+                    "cursor": {"workspace": "cursor-ws"},
+                    "windsurf": {"workspace": "windsurf-ws"},
+                }
+            },
+        )
+        workspaces = config.get_linked_workspaces()
+        assert "cursor-ws" in workspaces
+        assert "windsurf-ws" in workspaces
+
+    def test_excludes_own_workspace(self):
+        config = HonchoClientConfig(
+            workspace_id="hermes-ws",
+            linked_hosts=["other"],
+            raw={"hosts": {"other": {"workspace": "hermes-ws"}}},
+        )
+        workspaces = config.get_linked_workspaces()
+        assert workspaces == []
+
+    def test_uses_host_key_as_fallback(self):
+        config = HonchoClientConfig(
+            workspace_id="hermes-ws",
+            linked_hosts=["cursor"],
+            raw={"hosts": {"cursor": {}}},  # no workspace field
+        )
+        workspaces = config.get_linked_workspaces()
+        assert "cursor" in workspaces
+
+
+class TestResolveConfigPath:
+    def test_prefers_hermes_home_when_exists(self, tmp_path):
+        hermes_home = tmp_path / "hermes"
+        hermes_home.mkdir()
+        local_cfg = hermes_home / "honcho.json"
+        local_cfg.write_text('{"apiKey": "local"}')
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            result = resolve_config_path()
+        assert result == local_cfg
+
+    def test_falls_back_to_global_when_no_local(self, tmp_path):
+        hermes_home = tmp_path / "hermes"
+        hermes_home.mkdir()
+        # No honcho.json in HERMES_HOME
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            result = resolve_config_path()
+        assert result == GLOBAL_CONFIG_PATH
+
+    def test_falls_back_to_global_without_hermes_home_env(self):
+        with patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("HERMES_HOME", None)
+            result = resolve_config_path()
+        assert result == GLOBAL_CONFIG_PATH
+
+    def test_from_global_config_uses_local_path(self, tmp_path):
+        hermes_home = tmp_path / "hermes"
+        hermes_home.mkdir()
+        local_cfg = hermes_home / "honcho.json"
+        local_cfg.write_text(json.dumps({
+            "apiKey": "local-key",
+            "workspace": "local-ws",
+        }))
+
+        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
+            config = HonchoClientConfig.from_global_config()
+        assert config.api_key == "local-key"
+        assert config.workspace_id == "local-ws"
+
+
+class TestResetHonchoClient:
+    def test_reset_clears_singleton(self):
+        import honcho_integration.client as mod
+        mod._honcho_client = MagicMock()
+        assert mod._honcho_client is not None
+        reset_honcho_client()
+        assert mod._honcho_client is None

hermes_code/tests/honcho_integration/test_session.py

@@ -0,0 +1,189 @@
+"""Tests for honcho_integration/session.py — HonchoSession and helpers."""
+
+from datetime import datetime
+from unittest.mock import MagicMock
+
+from honcho_integration.session import (
+    HonchoSession,
+    HonchoSessionManager,
+)
+
+
+# ---------------------------------------------------------------------------
+# HonchoSession dataclass
+# ---------------------------------------------------------------------------
+
+
+class TestHonchoSession:
+    def _make_session(self):
+        return HonchoSession(
+            key="telegram:12345",
+            user_peer_id="user-telegram-12345",
+            assistant_peer_id="hermes-assistant",
+            honcho_session_id="telegram-12345",
+        )
+
+    def test_initial_state(self):
+        session = self._make_session()
+        assert session.key == "telegram:12345"
+        assert session.messages == []
+        assert isinstance(session.created_at, datetime)
+        assert isinstance(session.updated_at, datetime)
+
+    def test_add_message(self):
+        session = self._make_session()
+        session.add_message("user", "Hello!")
+        assert len(session.messages) == 1
+        assert session.messages[0]["role"] == "user"
+        assert session.messages[0]["content"] == "Hello!"
+        assert "timestamp" in session.messages[0]
+
+    def test_add_message_with_kwargs(self):
+        session = self._make_session()
+        session.add_message("assistant", "Hi!", source="gateway")
+        assert session.messages[0]["source"] == "gateway"
+
+    def test_add_message_updates_timestamp(self):
+        session = self._make_session()
+        original = session.updated_at
+        session.add_message("user", "test")
+        assert session.updated_at >= original
+
+    def test_get_history(self):
+        session = self._make_session()
+        session.add_message("user", "msg1")
+        session.add_message("assistant", "msg2")
+        history = session.get_history()
+        assert len(history) == 2
+        assert history[0] == {"role": "user", "content": "msg1"}
+        assert history[1] == {"role": "assistant", "content": "msg2"}
+
+    def test_get_history_strips_extra_fields(self):
+        session = self._make_session()
+        session.add_message("user", "hello", extra="metadata")
+        history = session.get_history()
+        assert "extra" not in history[0]
+        assert set(history[0].keys()) == {"role", "content"}
+
+    def test_get_history_max_messages(self):
+        session = self._make_session()
+        for i in range(10):
+            session.add_message("user", f"msg{i}")
+        history = session.get_history(max_messages=3)
+        assert len(history) == 3
+        assert history[0]["content"] == "msg7"
+        assert history[2]["content"] == "msg9"
+
+    def test_get_history_max_messages_larger_than_total(self):
+        session = self._make_session()
+        session.add_message("user", "only one")
+        history = session.get_history(max_messages=100)
+        assert len(history) == 1
+
+    def test_clear(self):
+        session = self._make_session()
+        session.add_message("user", "msg1")
+        session.add_message("user", "msg2")
+        session.clear()
+        assert session.messages == []
+
+    def test_clear_updates_timestamp(self):
+        session = self._make_session()
+        session.add_message("user", "msg")
+        original = session.updated_at
+        session.clear()
+        assert session.updated_at >= original
+
+
+# ---------------------------------------------------------------------------
+# HonchoSessionManager._sanitize_id
+# ---------------------------------------------------------------------------
+
+
+class TestSanitizeId:
+    def test_clean_id_unchanged(self):
+        mgr = HonchoSessionManager()
+        assert mgr._sanitize_id("telegram-12345") == "telegram-12345"
+
+    def test_colons_replaced(self):
+        mgr = HonchoSessionManager()
+        assert mgr._sanitize_id("telegram:12345") == "telegram-12345"
+
+    def test_special_chars_replaced(self):
+        mgr = HonchoSessionManager()
+        result = mgr._sanitize_id("user@chat#room!")
+        assert "@" not in result
+        assert "#" not in result
+        assert "!" not in result
+
+    def test_alphanumeric_preserved(self):
+        mgr = HonchoSessionManager()
+        assert mgr._sanitize_id("abc123_XYZ-789") == "abc123_XYZ-789"
+
+
+# ---------------------------------------------------------------------------
+# HonchoSessionManager._format_migration_transcript
+# ---------------------------------------------------------------------------
+
+
+class TestFormatMigrationTranscript:
+    def test_basic_transcript(self):
+        messages = [
+            {"role": "user", "content": "Hello", "timestamp": "2026-01-01T00:00:00"},
+            {"role": "assistant", "content": "Hi!", "timestamp": "2026-01-01T00:01:00"},
+        ]
+        result = HonchoSessionManager._format_migration_transcript("telegram:123", messages)
+        assert isinstance(result, bytes)
+        text = result.decode("utf-8")
+        assert "<prior_conversation_history>" in text
+        assert "user: Hello" in text
+        assert "assistant: Hi!" in text
+        assert 'session_key="telegram:123"' in text
+        assert 'message_count="2"' in text
+
+    def test_empty_messages(self):
+        result = HonchoSessionManager._format_migration_transcript("key", [])
+        text = result.decode("utf-8")
+        assert "<prior_conversation_history>" in text
+        assert "</prior_conversation_history>" in text
+
+    def test_missing_fields_handled(self):
+        messages = [{"role": "user"}]  # no content, no timestamp
+        result = HonchoSessionManager._format_migration_transcript("key", messages)
+        text = result.decode("utf-8")
+        assert "user: " in text  # empty content
+
+
+# ---------------------------------------------------------------------------
+# HonchoSessionManager.delete / list_sessions
+# ---------------------------------------------------------------------------
+
+
+class TestManagerCacheOps:
+    def test_delete_cached_session(self):
+        mgr = HonchoSessionManager()
+        session = HonchoSession(
+            key="test", user_peer_id="u", assistant_peer_id="a",
+            honcho_session_id="s",
+        )
+        mgr._cache["test"] = session
+        assert mgr.delete("test") is True
+        assert "test" not in mgr._cache
+
+    def test_delete_nonexistent_returns_false(self):
+        mgr = HonchoSessionManager()
+        assert mgr.delete("nonexistent") is False
+
+    def test_list_sessions(self):
+        mgr = HonchoSessionManager()
+        s1 = HonchoSession(key="k1", user_peer_id="u", assistant_peer_id="a", honcho_session_id="s1")
+        s2 = HonchoSession(key="k2", user_peer_id="u", assistant_peer_id="a", honcho_session_id="s2")
+        s1.add_message("user", "hi")
+        mgr._cache["k1"] = s1
+        mgr._cache["k2"] = s2
+        sessions = mgr.list_sessions()
+        assert len(sessions) == 2
+        keys = {s["key"] for s in sessions}
+        assert keys == {"k1", "k2"}
+        s1_info = next(s for s in sessions if s["key"] == "k1")
+        assert s1_info["message_count"] == 1