| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154 |
- """Which profile a memory-provider call or hook belongs to (#140058).
- On a multiplexed gateway every served profile's turns run in one process. Each agent's manager owns
- its own provider instance, bound by ``initialize_all`` to one profile home; the provider-side half of
- the rule is the multiplexing contract in ``agent/memory_provider.py``. The manager's half lives here:
- - a tool call or lifecycle hook runs only when the caller explicitly names the profile the manager was
- initialized for (the context's HERMES_HOME override, or the home its secret scope was built for).
- On a multiplexed process a caller that names no profile is refused, never resolved to the process's
- own profile; a single-profile process falls back to its home as before;
- - one provider instance serves one profile: a plugin that hands several agents the same instance is
- refused for every profile after the first, instead of being rebound to it.
- Refusals log the check's code and both homes (errors.log on every host, gateway.log on a gateway); the
- model/chat only ever sees a generic refusal.
- """
- from __future__ import annotations
- import logging
- import threading
- import weakref
- from typing import Any, Callable, Optional
- logger = logging.getLogger(__name__)
- CALLER_PROFILE_REFUSAL = "memory_caller_profile_unresolved"
- SHARED_INSTANCE_REFUSAL = "memory_provider_instance_shared"
- # id(provider) -> (weak reference to that very instance, profile home key). Keyed by identity, never
- # by the provider's own __hash__/__eq__: an unhashable or value-equal provider is still tracked.
- _claims: dict[int, tuple[weakref.ref, str]] = {}
- _claims_lock = threading.RLock() # reentrant: a weakref callback can fire from GC inside the lock
- def refused_tool_message(tool_name: str) -> str:
- """What the model/chat sees for a refused memory tool call: no check name, no home paths."""
- return f"Memory tool '{tool_name}' refused. Ask the operator to check `hermes logs errors`."
- def _home_key(home: Any) -> Optional[str]:
- if not home:
- return None
- from hermes_constants import hermes_home_key
- try:
- return hermes_home_key(home)
- except (OSError, RuntimeError, ValueError): # unresolvable path: no key, so the call is refused
- return None
- def _explicit_caller_home() -> Optional[str]:
- """The profile the caller's context names: its HERMES_HOME override, else the home its secret
- scope was built for. None when the context names no profile (``get_hermes_home()`` would only fall
- back to the process home, which proves nothing on a multiplexed process)."""
- from agent.secret_scope import current_secret_scope_home
- from hermes_constants import get_hermes_home_override
- return get_hermes_home_override() or current_secret_scope_home()
- def _refuse(label: str, reason: str, caller_home: Any, bound_home: Any, multiplexed: bool) -> None:
- logger.warning("Memory %s refused (%s): %s; caller profile home %r, provider bound to %r, multiplexed=%s",
- label, CALLER_PROFILE_REFUSAL, reason, caller_home, bound_home, multiplexed)
- def bound_scope(hermes_home: Any, agent_identity: Any = None) -> dict[str, Any]:
- """What ``initialize_all`` records for ``caller_scope``: the bound home's key is resolved once
- here, so each call only resolves the caller's."""
- return {"hermes_home": hermes_home, "agent_identity": agent_identity, "home_key": _home_key(hermes_home)}
- def caller_scope(bound: Optional[dict[str, Any]], label: str) -> Optional[dict[str, Any]]:
- """Provider kwargs naming the calling profile, or None when the call/hook must be refused.
- ``bound`` is what ``initialize_all`` recorded (``bound_scope``); ``label`` names the call in the
- log (``tool <name>`` / ``hook <name>``)."""
- from agent.secret_scope import is_multiplex_active
- bound = bound or {}
- bound_home = bound.get("hermes_home")
- multiplexed = is_multiplex_active()
- caller_home = _explicit_caller_home()
- if caller_home is None:
- if multiplexed:
- _refuse(label, "the caller names no profile on a process serving several", None, bound_home, multiplexed)
- return None
- from hermes_constants import get_hermes_home
- caller_home = str(get_hermes_home()) # single-profile process: its own home is the only one
- if not bound_home:
- if multiplexed:
- _refuse(label, "the memory manager recorded no profile", caller_home, None, multiplexed)
- return None
- return {"hermes_home": str(caller_home)}
- caller_key = _home_key(caller_home)
- if caller_key is None or caller_key != (bound.get("home_key") or _home_key(bound_home)):
- _refuse(label, "the caller's profile is not the one its provider was initialized for",
- caller_home, bound_home, multiplexed)
- return None
- scope: dict[str, Any] = {"hermes_home": str(bound_home)}
- if bound.get("agent_identity"):
- scope["agent_identity"] = bound["agent_identity"]
- return scope
- def _forget(pid: int, ref: weakref.ref) -> None:
- # Only this dead instance's own entry: once it is collected its id() can be reused by a new
- # provider whose claim already replaced the entry, and that claim must survive.
- with _claims_lock:
- if _claims.get(pid, (None,))[0] is ref:
- del _claims[pid]
- def claim_instance(provider: Any, home: Any) -> bool:
- """Record that ``provider`` (the instance) is bound to ``home``. False on a multiplexed process
- when another profile already bound this same instance (initializing it again would rebind the
- other profile's store), or when the instance can't be tracked at all (no weak reference)."""
- from agent.secret_scope import is_multiplex_active
- key = _home_key(home) or str(home)
- multiplexed = is_multiplex_active()
- pid = id(provider)
- with _claims_lock:
- entry = _claims.get(pid)
- owner = entry[1] if entry is not None and entry[0]() is provider else None
- if owner is not None and owner != key and multiplexed:
- logger.warning("Memory provider '%s' refused for profile home %r (%s): this same provider instance "
- "is already bound to %r; a provider must give every agent its own instance",
- getattr(provider, "name", "?"), str(home), SHARED_INSTANCE_REFUSAL, owner)
- return False
- try:
- ref = weakref.ref(provider, lambda dead, pid=pid: _forget(pid, dead))
- except TypeError:
- if multiplexed:
- logger.warning("Memory provider '%s' refused for profile home %r (%s): the instance can't be "
- "tracked (no weak reference support), so sharing it can't be ruled out",
- getattr(provider, "name", "?"), str(home), SHARED_INSTANCE_REFUSAL)
- return False
- return True
- _claims[pid] = (ref, key)
- return True
- def in_owner_home(bound: Optional[dict[str, Any]], fn: Callable[[], Any]) -> Callable[[], Any]:
- """``fn`` run under the owning profile's HERMES_HOME override, set explicitly: a background
- worker must not depend on the submitter's context having carried it."""
- home = (bound or {}).get("hermes_home")
- if not home:
- return fn
- def _run() -> Any:
- from hermes_constants import reset_hermes_home_override, set_hermes_home_override
- token = set_hermes_home_override(str(home))
- try:
- return fn()
- finally:
- reset_hermes_home_override(token)
- return _run
|