Add Honcho runtime peer mapping

(cherry picked from commit 864cdb3d2e)

agent/agent_init.py

@@ -183,6 +183,7 @@ def init_agent(
     prefill_messages: List[Dict[str, Any]] = None,
     platform: str = None,
     user_id: str = None,
+    user_id_alt: str = None,
     user_name: str = None,
     chat_id: str = None,
     chat_name: str = None,
@@ -265,6 +266,7 @@ def init_agent(
     agent.ephemeral_system_prompt = ephemeral_system_prompt
     agent.platform = platform  # "cli", "telegram", "discord", "whatsapp", etc.
     agent._user_id = user_id  # Platform user identifier (gateway sessions)
+    agent._user_id_alt = user_id_alt  # Optional stable alternate platform identifier
     agent._user_name = user_name
     agent._chat_id = chat_id
     agent._chat_name = chat_name
@@ -1119,6 +1121,8 @@ def init_agent(
                     # Thread gateway user identity for per-user memory scoping
                     if agent._user_id:
                         _init_kwargs["user_id"] = agent._user_id
+                    if agent._user_id_alt:
+                        _init_kwargs["user_id_alt"] = agent._user_id_alt
                     if agent._user_name:
                         _init_kwargs["user_name"] = agent._user_name
                     if agent._chat_id:

agent/memory_provider.py

@@ -78,6 +78,7 @@ class MemoryProvider(ABC):
           - agent_workspace (str): Shared workspace name (e.g. "hermes").
           - parent_session_id (str): For subagents, the parent's session_id.
           - user_id (str): Platform user identifier (gateway sessions).
+          - user_id_alt (str): Optional alternate stable platform user identifier.
         """
 
     def system_prompt_block(self) -> str:

gateway/run.py

@@ -11768,6 +11768,7 @@ class GatewayRunner:
                     session_id=task_id,
                     platform=platform_key,
                     user_id=source.user_id,
+                    user_id_alt=source.user_id_alt,
                     user_name=source.user_name,
                     chat_id=source.chat_id,
                     chat_name=source.chat_name,
@@ -16700,6 +16701,7 @@ class GatewayRunner:
                     session_id=session_id,
                     platform=platform_key,
                     user_id=source.user_id,
+                    user_id_alt=source.user_id_alt,
                     user_name=source.user_name,
                     chat_id=source.chat_id,
                     chat_name=source.chat_name,

plugins/memory/honcho/__init__.py

@@ -360,6 +360,7 @@ class HonchoMemoryProvider(MemoryProvider):
             config=cfg,
             context_tokens=cfg.context_tokens,
             runtime_user_peer_name=kwargs.get("user_id") or None,
+            runtime_user_peer_name_alt=kwargs.get("user_id_alt") or None,
         )
 
         # ----- B3: resolve_session_name -----

plugins/memory/honcho/client.py

@@ -122,6 +122,34 @@ def _parse_int_config(host_val, root_val, default: int) -> int:
     return default
 
 
+def _parse_string_map(host_obj: dict, root_obj: dict, key: str) -> dict[str, str]:
+    """Parse a string-to-string map with host-level whole-map override."""
+    source = host_obj[key] if key in host_obj else root_obj.get(key)
+    if not isinstance(source, dict):
+        return {}
+
+    result: dict[str, str] = {}
+    for raw_key, raw_value in source.items():
+        alias_key = str(raw_key).strip()
+        alias_value = str(raw_value).strip() if raw_value is not None else ""
+        if alias_key and alias_value:
+            result[alias_key] = alias_value
+    return result
+
+
+def _parse_optional_string(
+    host_obj: dict, root_obj: dict, key: str, default: str = ""
+) -> str:
+    """Parse a string field where host-level empty string can override root."""
+    if key in host_obj:
+        value = host_obj.get(key)
+    else:
+        value = root_obj.get(key, default)
+    if value is None:
+        return default
+    return str(value).strip()
+
+
 def _parse_dialectic_depth(host_val, root_val) -> int:
     """Parse dialecticDepth: host wins, then root, then 1. Clamped to 1-3."""
     for val in (host_val, root_val):
@@ -259,6 +287,12 @@ class HonchoClientConfig:
     # each platform would fork memory into its own peer (#14984).  Default
     # ``False`` preserves existing multi-user behaviour.
     pin_peer_name: bool = False
+    # Map gateway runtime user IDs to stable Honcho user peers. Host-level
+    # config replaces the root map as a whole so profiles can intentionally
+    # own their identity mappings.
+    user_peer_aliases: dict[str, str] = field(default_factory=dict)
+    # Optional prefix for unknown gateway runtime user IDs, e.g. "telegram_".
+    runtime_peer_prefix: str = ""
     # Toggles
     enabled: bool = False
     save_messages: bool = True
@@ -458,6 +492,16 @@ class HonchoClientConfig:
                 raw.get("pinPeerName"),
                 default=False,
             ),
+            user_peer_aliases=_parse_string_map(
+                host_block,
+                raw,
+                "userPeerAliases",
+            ),
+            runtime_peer_prefix=_parse_optional_string(
+                host_block,
+                raw,
+                "runtimePeerPrefix",
+            ),
             enabled=enabled,
             save_messages=save_messages,
             write_frequency=write_frequency,

plugins/memory/honcho/session.py

@@ -79,6 +79,7 @@ class HonchoSessionManager:
         context_tokens: int | None = None,
         config: Any | None = None,
         runtime_user_peer_name: str | None = None,
+        runtime_user_peer_name_alt: str | None = None,
     ):
         """
         Initialize the session manager.
@@ -89,11 +90,13 @@ class HonchoSessionManager:
             config: HonchoClientConfig from global config (provides peer_name, ai_peer,
                     write_frequency, observation, etc.).
             runtime_user_peer_name: Gateway user identity for per-user memory scoping.
+            runtime_user_peer_name_alt: Optional stable alternate gateway identity.
         """
         self._honcho = honcho
         self._context_tokens = context_tokens
         self._config = config
         self._runtime_user_peer_name = runtime_user_peer_name
+        self._runtime_user_peer_name_alt = runtime_user_peer_name_alt
         self._cache: dict[str, HonchoSession] = {}
         self._cache_lock = threading.RLock()
         self._peers_cache: dict[str, Any] = {}
@@ -267,6 +270,55 @@ class HonchoSessionManager:
         """Sanitize an ID to match Honcho's pattern: ^[a-zA-Z0-9_-]+"""
         return re.sub(r'[^a-zA-Z0-9_-]', '-', id_str)
 
+    def _runtime_user_ids(self) -> list[str]:
+        """Return runtime identity candidates in lookup order."""
+        candidates: list[str] = []
+        for value in (self._runtime_user_peer_name, self._runtime_user_peer_name_alt):
+            if value is None:
+                continue
+            candidate = str(value).strip()
+            if candidate and candidate not in candidates:
+                candidates.append(candidate)
+        return candidates
+
+    def _session_key_fallback_peer_id(self, key: str) -> str:
+        parts = key.split(":", 1)
+        channel = parts[0] if len(parts) > 1 else "default"
+        chat_id = parts[1] if len(parts) > 1 else key
+        return self._sanitize_id(f"user-{channel}-{chat_id}")
+
+    def _resolve_user_peer_id(self, key: str) -> str:
+        """Resolve the Honcho user peer ID for this manager/session."""
+        pin_peer_name = (
+            self._config is not None
+            and bool(getattr(self._config, "peer_name", None))
+            and getattr(self._config, "pin_peer_name", False) is True
+        )
+        if pin_peer_name:
+            return self._sanitize_id(self._config.peer_name)
+
+        runtime_ids = self._runtime_user_ids()
+        if runtime_ids:
+            aliases = getattr(self._config, "user_peer_aliases", {}) if self._config else {}
+            if not isinstance(aliases, dict):
+                aliases = {}
+            for runtime_id in runtime_ids:
+                alias = aliases.get(runtime_id)
+                if isinstance(alias, str) and alias.strip():
+                    return self._sanitize_id(alias.strip())
+
+            primary_runtime_id = runtime_ids[0]
+            prefix = getattr(self._config, "runtime_peer_prefix", "") if self._config else ""
+            prefix = prefix.strip() if isinstance(prefix, str) else ""
+            if prefix:
+                return self._sanitize_id(f"{prefix}{primary_runtime_id}")
+            return self._sanitize_id(primary_runtime_id)
+
+        if self._config and self._config.peer_name:
+            return self._sanitize_id(self._config.peer_name)
+
+        return self._session_key_fallback_peer_id(key)
+
     def get_or_create(self, key: str) -> HonchoSession:
         """
         Get an existing session or create a new one.
@@ -285,31 +337,11 @@ class HonchoSessionManager:
         # Determine peer IDs — no lock needed (read-only, no shared state mutation).
         # Gateway sessions normally use the runtime user identity (the
         # platform-native ID: Telegram UID, Discord snowflake, Slack user,
-        # etc.) so multi-user bots scope memory per user.  For a single-user
-        # deployment the config-supplied ``peer_name`` is an unambiguous
-        # identity and we should keep it unified across platforms — see
-        # #14984.  Opt into that with ``hosts.<host>.pinPeerName: true`` in
-        # ``honcho.json`` (or root-level ``pinPeerName: true``).
-        # `is True` (not `bool(...)`) is deliberate: several multi-user tests
-        # pass a ``MagicMock`` for ``config`` where ``mock.pin_peer_name``
-        # silently returns another MagicMock — truthy by default.  Requiring
-        # strict ``True`` keeps pinning as opt-in even for callers that
-        # haven't updated their mocks yet; real configs built via
-        # ``from_global_config`` always produce a proper boolean.
-        pin_peer_name = (
-            self._config is not None
-            and bool(getattr(self._config, "peer_name", None))
-            and getattr(self._config, "pin_peer_name", False) is True
-        )
-        if self._runtime_user_peer_name and not pin_peer_name:
-            user_peer_id = self._sanitize_id(self._runtime_user_peer_name)
-        elif self._config and self._config.peer_name:
-            user_peer_id = self._sanitize_id(self._config.peer_name)
-        else:
-            parts = key.split(":", 1)
-            channel = parts[0] if len(parts) > 1 else "default"
-            chat_id = parts[1] if len(parts) > 1 else key
-            user_peer_id = self._sanitize_id(f"user-{channel}-{chat_id}")
+        # etc.) so multi-user bots scope memory per user.  Config can alias
+        # known runtime IDs or prefix unknown IDs.  For a single-user
+        # deployment, ``pinPeerName`` still pins all runtime identities to
+        # ``peerName`` (see #14984).
+        user_peer_id = self._resolve_user_peer_id(key)
 
         assistant_peer_id = self._sanitize_id(
             self._config.ai_peer if self._config else "hermes-assistant"

run_agent.py

@@ -394,6 +394,7 @@ class AIAgent:
         prefill_messages: List[Dict[str, Any]] = None,
         platform: str = None,
         user_id: str = None,
+        user_id_alt: str = None,
         user_name: str = None,
         chat_id: str = None,
         chat_name: str = None,
@@ -463,6 +464,7 @@ class AIAgent:
             prefill_messages=prefill_messages,
             platform=platform,
             user_id=user_id,
+            user_id_alt=user_id_alt,
             user_name=user_name,
             chat_id=chat_id,
             chat_name=chat_name,

tests/honcho_plugin/test_pin_peer_name.py

@@ -99,6 +99,90 @@ class TestPinPeerNameConfigParsing:
         assert config.pin_peer_name is False
 
 
+class TestRuntimePeerMappingConfigParsing:
+    def test_defaults_are_empty(self):
+        config = HonchoClientConfig()
+        assert config.user_peer_aliases == {}
+        assert config.runtime_peer_prefix == ""
+
+    def test_root_level_aliases_and_prefix_parse(self, tmp_path):
+        config_file = tmp_path / "honcho.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "k",
+            "userPeerAliases": {
+                " 86701400 ": " Igor ",
+                "": "ignored",
+                "empty-value": " ",
+                "null-value": None,
+            },
+            "runtimePeerPrefix": "telegram_",
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+
+        assert config.user_peer_aliases == {"86701400": "Igor"}
+        assert config.runtime_peer_prefix == "telegram_"
+
+    def test_host_aliases_override_root_aliases_as_whole_map(self, tmp_path):
+        config_file = tmp_path / "honcho.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "k",
+            "userPeerAliases": {"root-user": "root-peer"},
+            "hosts": {
+                "hermes": {
+                    "userPeerAliases": {"host-user": "host-peer"},
+                },
+            },
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+
+        assert config.user_peer_aliases == {"host-user": "host-peer"}
+
+    def test_host_empty_aliases_disable_root_aliases(self, tmp_path):
+        config_file = tmp_path / "honcho.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "k",
+            "userPeerAliases": {"root-user": "root-peer"},
+            "hosts": {
+                "hermes": {
+                    "userPeerAliases": {},
+                },
+            },
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+
+        assert config.user_peer_aliases == {}
+
+    def test_host_empty_prefix_disables_root_prefix(self, tmp_path):
+        config_file = tmp_path / "honcho.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "k",
+            "runtimePeerPrefix": "telegram_",
+            "hosts": {
+                "hermes": {
+                    "runtimePeerPrefix": "",
+                },
+            },
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+
+        assert config.runtime_peer_prefix == ""
+
+    def test_malformed_alias_config_is_ignored(self, tmp_path):
+        config_file = tmp_path / "honcho.json"
+        config_file.write_text(json.dumps({
+            "apiKey": "k",
+            "userPeerAliases": ["not", "a", "map"],
+        }))
+
+        config = HonchoClientConfig.from_global_config(config_path=config_file)
+
+        assert config.user_peer_aliases == {}
+
+
 # ---------------------------------------------------------------------------
 # Peer resolution (the actual bug fix)
 # ---------------------------------------------------------------------------
@@ -119,13 +203,22 @@ def _patch_manager_for_resolution_test(mgr: HonchoSessionManager) -> None:
 class TestPeerResolutionOrder:
     """Matrix of (runtime_id, pin_peer_name, peer_name) → expected user_peer_id."""
 
-    def _config(self, *, peer_name: str | None, pin_peer_name: bool) -> HonchoClientConfig:
+    def _config(
+        self,
+        *,
+        peer_name: str | None,
+        pin_peer_name: bool,
+        user_peer_aliases: dict[str, str] | None = None,
+        runtime_peer_prefix: str = "",
+    ) -> HonchoClientConfig:
         # The test doesn't need auth / Honcho — disable the provider so
         # the manager doesn't try to open a real client.
         return HonchoClientConfig(
             api_key="test-key",
             peer_name=peer_name,
             pin_peer_name=pin_peer_name,
+            user_peer_aliases=user_peer_aliases or {},
+            runtime_peer_prefix=runtime_peer_prefix,
             enabled=False,
             write_frequency="turn",  # avoid spawning the async writer thread
         )
@@ -148,11 +241,64 @@ class TestPeerResolutionOrder:
             "bot immediately merges memory across users."
         )
 
+    def test_alias_wins_for_known_runtime_id(self):
+        """Known platform IDs can preserve an existing stable Honcho peer."""
+        mgr = HonchoSessionManager(
+            honcho=MagicMock(),
+            config=self._config(
+                peer_name="Igor",
+                pin_peer_name=False,
+                user_peer_aliases={"86701400": "Igor"},
+                runtime_peer_prefix="telegram_",
+            ),
+            runtime_user_peer_name="86701400",
+        )
+        _patch_manager_for_resolution_test(mgr)
+
+        session = mgr.get_or_create("telegram:86701400")
+        assert session.user_peer_id == "Igor"
+
+    def test_unknown_runtime_id_uses_prefix(self):
+        """Unknown gateway users stay isolated but become platform-scoped."""
+        mgr = HonchoSessionManager(
+            honcho=MagicMock(),
+            config=self._config(
+                peer_name="Igor",
+                pin_peer_name=False,
+                runtime_peer_prefix="telegram_",
+            ),
+            runtime_user_peer_name="86701400",
+        )
+        _patch_manager_for_resolution_test(mgr)
+
+        session = mgr.get_or_create("telegram:86701400")
+        assert session.user_peer_id == "telegram_86701400"
+
+    def test_alias_value_is_sanitized_after_selection(self):
+        mgr = HonchoSessionManager(
+            honcho=MagicMock(),
+            config=self._config(
+                peer_name=None,
+                pin_peer_name=False,
+                user_peer_aliases={"86701400": "Alice Smith!"},
+            ),
+            runtime_user_peer_name="86701400",
+        )
+        _patch_manager_for_resolution_test(mgr)
+
+        session = mgr.get_or_create("telegram:86701400")
+        assert session.user_peer_id == "Alice-Smith-"
+
     def test_config_wins_when_pin_is_true(self):
         """The #14984 fix: single-user deployments opt into config pinning."""
         mgr = HonchoSessionManager(
             honcho=MagicMock(),
-            config=self._config(peer_name="Igor", pin_peer_name=True),
+            config=self._config(
+                peer_name="Igor",
+                pin_peer_name=True,
+                user_peer_aliases={"86701400": "Alias"},
+                runtime_peer_prefix="telegram_",
+            ),
             runtime_user_peer_name="86701400",  # Telegram pushes this in
         )
         _patch_manager_for_resolution_test(mgr)
@@ -167,7 +313,23 @@ class TestPeerResolutionOrder:
     def test_pin_noop_when_peer_name_missing(self):
         """Safety: pinPeerName alone (no peer_name) must not silently drop
         the runtime identity.  Without a configured peer_name there's
-        nothing to pin to — fall back to runtime as before."""
+        nothing to pin to — fall through to runtime mapping."""
+        mgr = HonchoSessionManager(
+            honcho=MagicMock(),
+            config=self._config(
+                peer_name=None,
+                pin_peer_name=True,
+                user_peer_aliases={"86701400": "Igor"},
+                runtime_peer_prefix="telegram_",
+            ),
+            runtime_user_peer_name="86701400",
+        )
+        _patch_manager_for_resolution_test(mgr)
+
+        session = mgr.get_or_create("telegram:86701400")
+        assert session.user_peer_id == "Igor"
+
+    def test_pin_noop_without_peer_name_or_mapping_preserves_runtime(self):
         mgr = HonchoSessionManager(
             honcho=MagicMock(),
             config=self._config(peer_name=None, pin_peer_name=True),
@@ -176,11 +338,42 @@ class TestPeerResolutionOrder:
         _patch_manager_for_resolution_test(mgr)
 
         session = mgr.get_or_create("telegram:86701400")
-        assert session.user_peer_id == "86701400", (
-            "pin_peer_name=True with no peer_name set must not strip the "
-            "runtime ID — otherwise the user peer would collapse to the "
-            "session-key fallback and lose per-user scoping entirely"
+        assert session.user_peer_id == "86701400"
+
+    def test_alt_runtime_id_can_match_alias_without_changing_raw_fallback(self):
+        """Stable alternate IDs can map known users while primary ID fallback stays unchanged."""
+        mgr = HonchoSessionManager(
+            honcho=MagicMock(),
+            config=self._config(
+                peer_name=None,
+                pin_peer_name=False,
+                user_peer_aliases={"union-user": "Igor"},
+                runtime_peer_prefix="feishu_",
+            ),
+            runtime_user_peer_name="open-id",
+            runtime_user_peer_name_alt="union-user",
         )
+        _patch_manager_for_resolution_test(mgr)
+
+        session = mgr.get_or_create("feishu:chat")
+        assert session.user_peer_id == "Igor"
+
+    def test_alt_runtime_id_does_not_replace_primary_prefix_fallback(self):
+        mgr = HonchoSessionManager(
+            honcho=MagicMock(),
+            config=self._config(
+                peer_name=None,
+                pin_peer_name=False,
+                user_peer_aliases={"other-union": "Igor"},
+                runtime_peer_prefix="feishu_",
+            ),
+            runtime_user_peer_name="open-id",
+            runtime_user_peer_name_alt="union-user",
+        )
+        _patch_manager_for_resolution_test(mgr)
+
+        session = mgr.get_or_create("feishu:chat")
+        assert session.user_peer_id == "feishu_open-id"
 
     def test_runtime_missing_falls_back_to_peer_name(self):
         """CLI-mode (no gateway runtime identity) uses config peer_name —

tests/honcho_plugin/test_session.py

@@ -573,7 +573,7 @@ class TestToolsModeInitBehavior:
     """Verify initOnSessionStart controls session init timing in tools mode."""
 
     def _make_provider_with_config(self, recall_mode="tools", init_on_session_start=False,
-                                    peer_name=None, user_id=None):
+                                    peer_name=None, user_id=None, user_id_alt=None):
         """Create a HonchoMemoryProvider with mocked config and dependencies."""
         from plugins.memory.honcho.client import HonchoClientConfig
 
@@ -598,6 +598,8 @@ class TestToolsModeInitBehavior:
         init_kwargs = {}
         if user_id:
             init_kwargs["user_id"] = user_id
+        if user_id_alt:
+            init_kwargs["user_id_alt"] = user_id_alt
 
         with patch("plugins.memory.honcho.client.HonchoClientConfig.from_global_config", return_value=cfg), \
              patch("plugins.memory.honcho.client.get_honcho_client", return_value=MagicMock()), \
@@ -655,6 +657,15 @@ class TestToolsModeInitBehavior:
         assert cfg.peer_name is None
         assert mock_manager_cls.call_args.kwargs["runtime_user_peer_name"] == "8439114563"
 
+    def test_user_id_alt_is_passed_to_session_manager(self):
+        """Gateway alternate user IDs are available for Honcho alias matching."""
+        _, _, mock_manager_cls = self._make_provider_with_config(
+            recall_mode="tools", init_on_session_start=True,
+            peer_name=None, user_id="open-id", user_id_alt="union-id",
+        )
+        assert mock_manager_cls.call_args.kwargs["runtime_user_peer_name"] == "open-id"
+        assert mock_manager_cls.call_args.kwargs["runtime_user_peer_name_alt"] == "union-id"
+
 
 class TestPerSessionMigrateGuard:
     """Verify migrate_memory_files is skipped under per-session strategy.

tests/run_agent/test_memory_provider_init.py

@@ -4,6 +4,27 @@ from types import SimpleNamespace
 from unittest.mock import patch
 
 
+class RecordingMemoryProvider:
+    name = "recording"
+
+    def __init__(self):
+        self.init_kwargs = None
+        self.init_session_id = None
+
+    def is_available(self):
+        return True
+
+    def initialize(self, session_id, **kwargs):
+        self.init_session_id = session_id
+        self.init_kwargs = dict(kwargs)
+
+    def get_tool_schemas(self):
+        return []
+
+    def shutdown(self):
+        pass
+
+
 def test_blank_memory_provider_does_not_auto_enable_honcho():
     """Blank memory.provider should remain opt-out even if Honcho fallback looks configured."""
     cfg = {"memory": {"provider": ""}, "agent": {}}
@@ -37,3 +58,35 @@ def test_blank_memory_provider_does_not_auto_enable_honcho():
     load_memory_provider.assert_not_called()
     save_config.assert_not_called()
 
+
+def test_aiagent_forwards_user_id_alt_to_memory_provider():
+    provider = RecordingMemoryProvider()
+    cfg = {"memory": {"provider": "recording"}, "agent": {}}
+
+    with (
+        patch("hermes_cli.config.load_config", return_value=cfg),
+        patch("plugins.memory.load_memory_provider", return_value=provider),
+        patch("agent.model_metadata.get_model_context_length", return_value=204_800),
+        patch("run_agent.get_tool_definitions", return_value=[]),
+        patch("run_agent.check_toolset_requirements", return_value={}),
+        patch("run_agent.OpenAI"),
+    ):
+        from run_agent import AIAgent
+
+        agent = AIAgent(
+            api_key="test-key-1234567890",
+            base_url="https://openrouter.ai/api/v1",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=False,
+            session_id="sess-alt",
+            platform="feishu",
+            user_id="open-id",
+            user_id_alt="union-id",
+        )
+
+    assert agent._memory_manager is not None
+    assert provider.init_session_id == "sess-alt"
+    assert provider.init_kwargs["user_id"] == "open-id"
+    assert provider.init_kwargs["user_id_alt"] == "union-id"
+    assert provider.init_kwargs["platform"] == "feishu"