Repository navigation
fix: scope plugin manager by resolved hermes home (keyed cache) #63702
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
terry197913
wants to merge
1
commit into
NousResearch:main
Choose a base branch
from
terry197913:luna/pr-28109-profile-isolation-fix
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| # Architecture Decision Records | ||
|
|
||
| ## 2026-07-13: Scope plugin manager state by Hermes home/profile (keyed cache) | ||
|
|
||
| Status: Accepted | ||
|
|
||
| Context: | ||
| Hermes supports multiple profiles via different Hermes home directories. | ||
| Homes are switched two ways in a running process: the `HERMES_HOME` | ||
| environment variable (single-profile CLI/gateway processes), and the | ||
| context-local `set_hermes_home_override()` (`hermes_constants.py`), which | ||
| the multiplexed gateway worker (`gateway/run.py`'s `_profile_scope`) and | ||
| subagent/embedded callers use to serve several profiles from one | ||
| long-lived process. The override is a `ContextVar` and deliberately does | ||
| **not** mutate `os.environ`, since that would leak one profile's home | ||
| into every other concurrent task in the same process. | ||
|
|
||
| The plugin manager was a process-global single-slot singleton | ||
| (`_plugin_manager`). User-installed plugins are discovered from | ||
| `get_hermes_home() / "plugins"`, and context-engine plugins (e.g. | ||
| `hermes-lcm`) capture profile-scoped state — such as the LCM database | ||
| path — at registration time. A single-slot cache meant: | ||
|
|
||
| 1. Switching homes via `set_hermes_home_override()` was invisible to a | ||
| naive "did `HERMES_HOME` change" check, so the singleton silently kept | ||
| serving the first profile's manager to every other profile in the | ||
| process. | ||
| 2. Even when a fresh `PluginManager` *was* created for a new home, plugin | ||
| modules are imported into `sys.modules` as `hermes_plugins.<slug>` by | ||
| `_load_directory_module`, and only that top-level module was ever | ||
| replaced. A same-slug plugin's *relative* imports | ||
| (`from . import state`) are cached separately under | ||
| `hermes_plugins.<slug>.<submodule>`, and Python's import machinery | ||
| resolves those from `sys.modules` first — so a profile switch could | ||
| silently keep serving a previous profile's already-imported submodule | ||
| code/state instead of re-executing the new profile's plugin. | ||
|
|
||
| Decision: | ||
| - Replace the single-slot singleton with a cache keyed on the *resolved* | ||
| Hermes home path (`_plugin_managers_by_home: Dict[Path, PluginManager]`). | ||
| `get_plugin_manager()` resolves the current home via `get_hermes_home()` | ||
| (which itself already consults `get_hermes_home_override()` before | ||
| `os.environ`), so both the env-var and context-local override paths are | ||
| covered uniformly. | ||
| - `_plugin_manager` (the old single-slot name) is kept as a thin "last | ||
| manager returned" pointer purely for backward compatibility with | ||
| existing test code that does | ||
| `monkeypatch.setattr(plugins_mod, "_plugin_manager", some_manager)`. | ||
| When that name is monkeypatched to a manager the keyed cache doesn't | ||
| know about, `get_plugin_manager()` treats it as an explicit injection | ||
| and adopts it into the cache under the *current* resolved home, rather | ||
| than discarding it. | ||
| - Both `PluginManager._load_directory_module` (initial/`force=True` | ||
| reload within the same home) and the shared `_clear_plugin_submodules` | ||
| helper (profile switch / test teardown) evict `sys.modules[module_name]` | ||
| **and every name prefixed with `module_name + "."`** before a plugin | ||
| slug is (re-)imported, so relative-import submodules can never survive | ||
| a reload or a home switch. | ||
| - Test isolation (`tests/conftest.py`'s `_hermetic_environment` fixture) | ||
| calls a new `_reset_plugin_managers_for_tests()` helper that drops the | ||
| entire keyed cache and purges every plugin submodule from `sys.modules` | ||
| between tests, instead of only resetting the single-slot pointer. | ||
|
|
||
| Consequences: | ||
| - Per-profile LCM instances (and any other context-engine plugin) use | ||
| their own `{home}/lcm.db` regardless of whether the profile switch went | ||
| through `HERMES_HOME` or `set_hermes_home_override()`. | ||
| - Plugin discovery remains cached within a profile for normal | ||
| performance, and re-entering a previously-seen profile reuses its | ||
| cached manager instead of rebuilding from scratch. | ||
| - Sequential *and* interleaved profile switching — in tests, the gateway | ||
| multiplexer worker, or embedded callers using the context-local | ||
| override — no longer leaks context-engine state, plugin module state, | ||
| or stale relative-import submodules across profiles. | ||
| - Regression coverage exercises the real production path | ||
| (`set_hermes_home_override()`) rather than only the env-var path, and | ||
| includes a dedicated relative-import leak test. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This cache isolates only PluginManager-owned fields.
PluginContext.register_tool()still mutates the process-globaltools.registry.registry, andregister_platform()mutates the global platform registry. Loading profile B can therefore overwrite or reject profile A registrations even when the managers differ; the registration lifecycle must be profile-safe too.