memory_caller_scope.py 7.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154
  1. """Which profile a memory-provider call or hook belongs to (#140058).
  2. On a multiplexed gateway every served profile's turns run in one process. Each agent's manager owns
  3. its own provider instance, bound by ``initialize_all`` to one profile home; the provider-side half of
  4. the rule is the multiplexing contract in ``agent/memory_provider.py``. The manager's half lives here:
  5. - a tool call or lifecycle hook runs only when the caller explicitly names the profile the manager was
  6. initialized for (the context's HERMES_HOME override, or the home its secret scope was built for).
  7. On a multiplexed process a caller that names no profile is refused, never resolved to the process's
  8. own profile; a single-profile process falls back to its home as before;
  9. - one provider instance serves one profile: a plugin that hands several agents the same instance is
  10. refused for every profile after the first, instead of being rebound to it.
  11. Refusals log the check's code and both homes (errors.log on every host, gateway.log on a gateway); the
  12. model/chat only ever sees a generic refusal.
  13. """
  14. from __future__ import annotations
  15. import logging
  16. import threading
  17. import weakref
  18. from typing import Any, Callable, Optional
  19. logger = logging.getLogger(__name__)
  20. CALLER_PROFILE_REFUSAL = "memory_caller_profile_unresolved"
  21. SHARED_INSTANCE_REFUSAL = "memory_provider_instance_shared"
  22. # id(provider) -> (weak reference to that very instance, profile home key). Keyed by identity, never
  23. # by the provider's own __hash__/__eq__: an unhashable or value-equal provider is still tracked.
  24. _claims: dict[int, tuple[weakref.ref, str]] = {}
  25. _claims_lock = threading.RLock() # reentrant: a weakref callback can fire from GC inside the lock
  26. def refused_tool_message(tool_name: str) -> str:
  27. """What the model/chat sees for a refused memory tool call: no check name, no home paths."""
  28. return f"Memory tool '{tool_name}' refused. Ask the operator to check `hermes logs errors`."
  29. def _home_key(home: Any) -> Optional[str]:
  30. if not home:
  31. return None
  32. from hermes_constants import hermes_home_key
  33. try:
  34. return hermes_home_key(home)
  35. except (OSError, RuntimeError, ValueError): # unresolvable path: no key, so the call is refused
  36. return None
  37. def _explicit_caller_home() -> Optional[str]:
  38. """The profile the caller's context names: its HERMES_HOME override, else the home its secret
  39. scope was built for. None when the context names no profile (``get_hermes_home()`` would only fall
  40. back to the process home, which proves nothing on a multiplexed process)."""
  41. from agent.secret_scope import current_secret_scope_home
  42. from hermes_constants import get_hermes_home_override
  43. return get_hermes_home_override() or current_secret_scope_home()
  44. def _refuse(label: str, reason: str, caller_home: Any, bound_home: Any, multiplexed: bool) -> None:
  45. logger.warning("Memory %s refused (%s): %s; caller profile home %r, provider bound to %r, multiplexed=%s",
  46. label, CALLER_PROFILE_REFUSAL, reason, caller_home, bound_home, multiplexed)
  47. def bound_scope(hermes_home: Any, agent_identity: Any = None) -> dict[str, Any]:
  48. """What ``initialize_all`` records for ``caller_scope``: the bound home's key is resolved once
  49. here, so each call only resolves the caller's."""
  50. return {"hermes_home": hermes_home, "agent_identity": agent_identity, "home_key": _home_key(hermes_home)}
  51. def caller_scope(bound: Optional[dict[str, Any]], label: str) -> Optional[dict[str, Any]]:
  52. """Provider kwargs naming the calling profile, or None when the call/hook must be refused.
  53. ``bound`` is what ``initialize_all`` recorded (``bound_scope``); ``label`` names the call in the
  54. log (``tool <name>`` / ``hook <name>``)."""
  55. from agent.secret_scope import is_multiplex_active
  56. bound = bound or {}
  57. bound_home = bound.get("hermes_home")
  58. multiplexed = is_multiplex_active()
  59. caller_home = _explicit_caller_home()
  60. if caller_home is None:
  61. if multiplexed:
  62. _refuse(label, "the caller names no profile on a process serving several", None, bound_home, multiplexed)
  63. return None
  64. from hermes_constants import get_hermes_home
  65. caller_home = str(get_hermes_home()) # single-profile process: its own home is the only one
  66. if not bound_home:
  67. if multiplexed:
  68. _refuse(label, "the memory manager recorded no profile", caller_home, None, multiplexed)
  69. return None
  70. return {"hermes_home": str(caller_home)}
  71. caller_key = _home_key(caller_home)
  72. if caller_key is None or caller_key != (bound.get("home_key") or _home_key(bound_home)):
  73. _refuse(label, "the caller's profile is not the one its provider was initialized for",
  74. caller_home, bound_home, multiplexed)
  75. return None
  76. scope: dict[str, Any] = {"hermes_home": str(bound_home)}
  77. if bound.get("agent_identity"):
  78. scope["agent_identity"] = bound["agent_identity"]
  79. return scope
  80. def _forget(pid: int, ref: weakref.ref) -> None:
  81. # Only this dead instance's own entry: once it is collected its id() can be reused by a new
  82. # provider whose claim already replaced the entry, and that claim must survive.
  83. with _claims_lock:
  84. if _claims.get(pid, (None,))[0] is ref:
  85. del _claims[pid]
  86. def claim_instance(provider: Any, home: Any) -> bool:
  87. """Record that ``provider`` (the instance) is bound to ``home``. False on a multiplexed process
  88. when another profile already bound this same instance (initializing it again would rebind the
  89. other profile's store), or when the instance can't be tracked at all (no weak reference)."""
  90. from agent.secret_scope import is_multiplex_active
  91. key = _home_key(home) or str(home)
  92. multiplexed = is_multiplex_active()
  93. pid = id(provider)
  94. with _claims_lock:
  95. entry = _claims.get(pid)
  96. owner = entry[1] if entry is not None and entry[0]() is provider else None
  97. if owner is not None and owner != key and multiplexed:
  98. logger.warning("Memory provider '%s' refused for profile home %r (%s): this same provider instance "
  99. "is already bound to %r; a provider must give every agent its own instance",
  100. getattr(provider, "name", "?"), str(home), SHARED_INSTANCE_REFUSAL, owner)
  101. return False
  102. try:
  103. ref = weakref.ref(provider, lambda dead, pid=pid: _forget(pid, dead))
  104. except TypeError:
  105. if multiplexed:
  106. logger.warning("Memory provider '%s' refused for profile home %r (%s): the instance can't be "
  107. "tracked (no weak reference support), so sharing it can't be ruled out",
  108. getattr(provider, "name", "?"), str(home), SHARED_INSTANCE_REFUSAL)
  109. return False
  110. return True
  111. _claims[pid] = (ref, key)
  112. return True
  113. def in_owner_home(bound: Optional[dict[str, Any]], fn: Callable[[], Any]) -> Callable[[], Any]:
  114. """``fn`` run under the owning profile's HERMES_HOME override, set explicitly: a background
  115. worker must not depend on the submitter's context having carried it."""
  116. home = (bound or {}).get("hermes_home")
  117. if not home:
  118. return fn
  119. def _run() -> Any:
  120. from hermes_constants import reset_hermes_home_override, set_hermes_home_override
  121. token = set_hermes_home_override(str(home))
  122. try:
  123. return fn()
  124. finally:
  125. reset_hermes_home_override(token)
  126. return _run