side_question_lease.py 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151
  1. """Turn leases for plugin side questions (``ctx.side_question``).
  2. At turn finalization, when a loaded plugin holds the ``llm.side_question`` capability, the turn
  3. thread captures the request inputs the side call will replay and hands ``post_llm_call`` an
  4. opaque token. A token buys ONE side request shared by every plugin that receives the hook:
  5. redemption pops the lease whether it succeeds or not. It expires after ``LEASE_TTL_SECONDS`` or
  6. as soon as the parent agent starts its next turn. The captured ``contextvars`` context binds the
  7. owning profile and secret scope on whatever thread redeems the token, and only a plugin context
  8. of that same profile can redeem it. Unattended turns (cron jobs, delegated subagents) get no
  9. token: nobody is there to read an answer bought with the main model's tokens.
  10. """
  11. from __future__ import annotations
  12. import contextvars
  13. import copy
  14. import logging
  15. import secrets
  16. import threading
  17. import time
  18. import weakref
  19. from dataclasses import dataclass
  20. from typing import Any, Optional
  21. from agent.side_question_request import SideQuestionCapture, ask_text_only, runtime_key
  22. logger = logging.getLogger(__name__)
  23. SIDE_QUESTION_CAPABILITY = "llm.side_question"
  24. LEASE_TTL_SECONDS = 60.0
  25. MAX_PROMPT_CHARS = 4096
  26. DEFAULT_TIMEOUT_SECONDS = 15.0
  27. MAX_TIMEOUT_SECONDS = 60.0
  28. @dataclass(frozen=True)
  29. class _Lease:
  30. capture: SideQuestionCapture
  31. expires_at: float
  32. home_key: str # hermes_home_key() of the profile the turn ran under
  33. _leases: dict[str, _Lease] = {}
  34. _lock = threading.Lock()
  35. def _consented_plugin_loaded() -> bool:
  36. """True when a loaded, enabled plugin declares ``llm.side_question`` AND it is granted."""
  37. from hermes_cli.plugin_capabilities import plugin_capability_granted
  38. from hermes_cli.plugins import get_plugin_manager
  39. return any(
  40. loaded.enabled
  41. and SIDE_QUESTION_CAPABILITY in loaded.manifest.capabilities
  42. and plugin_capability_granted(key, SIDE_QUESTION_CAPABILITY)
  43. for key, loaded in list(get_plugin_manager()._plugins.items())
  44. )
  45. def _purge_locked(now: float, agent: Any = None) -> None:
  46. """Drop expired leases, leases whose parent is gone, and (on a new turn) ``agent``'s older ones."""
  47. for stale in [t for t, lease in _leases.items()
  48. if lease.expires_at < now or (parent := lease.capture.parent_ref()) is None or parent is agent]:
  49. del _leases[stale]
  50. def is_unattended_turn(agent: Any) -> bool:
  51. """A turn nobody is waiting on: a persistence-detached fork, a cron run, a delegated child."""
  52. return (getattr(agent, "_persist_disabled", False) or getattr(agent, "platform", None) == "cron"
  53. or getattr(agent, "_delegate_depth", 0) > 0)
  54. def issue_side_question_token(agent: Any, messages: list[dict[str, Any]], turn_id: str) -> Optional[str]:
  55. """Capture the finished turn and lease it under a fresh token; None (nothing captured) for an
  56. unattended turn (fork, cron run, subagent) or when no consented plugin is loaded. Turn thread
  57. only: the captured context and profile are the turn's."""
  58. from hermes_constants import hermes_home_key
  59. if is_unattended_turn(agent) or not _consented_plugin_loaded():
  60. return None
  61. capture = SideQuestionCapture(
  62. parent_ref=weakref.ref(agent),
  63. messages=copy.deepcopy(messages),
  64. system_prompt=agent._cached_system_prompt,
  65. system_prompt_static=getattr(agent, "_cached_system_prompt_static", None),
  66. tools=copy.deepcopy(agent.tools or []),
  67. session_id=agent.session_id,
  68. turn_id=turn_id,
  69. runtime=runtime_key(agent),
  70. context=contextvars.copy_context(),
  71. )
  72. token = secrets.token_urlsafe(24)
  73. now = time.monotonic()
  74. with _lock:
  75. # Drop this agent's older leases (a new turn) and every expired or orphaned one (each holds
  76. # a transcript), so the table holds at most one lease per live session agent.
  77. _purge_locked(now, agent)
  78. _leases[token] = _Lease(capture, now + LEASE_TTL_SECONDS, hermes_home_key())
  79. return token
  80. def _redeemable(lease: Optional[_Lease], prompt: Any) -> Optional[str]:
  81. """Why the popped lease cannot be redeemed with ``prompt``, or None."""
  82. if lease is None:
  83. return "unknown_token"
  84. if time.monotonic() > lease.expires_at:
  85. return "expired"
  86. parent = lease.capture.parent_ref()
  87. if parent is None:
  88. return "parent_gone"
  89. if getattr(parent, "_current_turn_id", None) != lease.capture.turn_id:
  90. return "turn_moved_on"
  91. if not isinstance(prompt, str) or not prompt.strip() or len(prompt) > MAX_PROMPT_CHARS:
  92. return "bad_prompt"
  93. return None
  94. def redeem_side_question(
  95. token: Any, prompt: Any, *, plugin_id: str, home: Any = None, timeout: float = DEFAULT_TIMEOUT_SECONDS,
  96. ) -> Optional[str]:
  97. """Spend the lease behind ``token`` on one text-only question; the answer or None.
  98. ``home`` is the redeeming plugin's profile home (the active one when omitted). A lease from
  99. another profile is refused and left for its owner; otherwise this call consumes it whatever
  100. the outcome."""
  101. from hermes_constants import hermes_home_key
  102. home_key = hermes_home_key(home)
  103. with _lock:
  104. lease = _leases.get(token) if isinstance(token, str) else None
  105. if lease is not None and lease.home_key != home_key:
  106. logger.info("side_question plugin=%s outcome=rejected:other_profile", plugin_id)
  107. return None
  108. if lease is not None:
  109. del _leases[token]
  110. _purge_locked(time.monotonic())
  111. reason = _redeemable(lease, prompt)
  112. if reason is not None:
  113. logger.info("side_question plugin=%s outcome=rejected:%s", plugin_id, reason)
  114. return None
  115. try:
  116. timeout = float(timeout)
  117. except (TypeError, ValueError):
  118. timeout = DEFAULT_TIMEOUT_SECONDS
  119. # Clamp to (0, 60]; NaN and non-positive values fall back to the default.
  120. timeout = min(timeout, MAX_TIMEOUT_SECONDS) if timeout > 0 else DEFAULT_TIMEOUT_SECONDS
  121. # A copy: the captured Context may already be entered elsewhere, and entering one Context
  122. # on two threads at once raises.
  123. return lease.capture.context.copy().run(
  124. ask_text_only, lease.capture, prompt, plugin_id=plugin_id, timeout=timeout,
  125. )