interrupt.py 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129
  1. """Per-thread interrupt signaling for all tools: thread-scoped so interrupting one
  2. agent session does not kill tools in other sessions (the gateway runs many agents in one
  3. process). The agent passes its execution thread id to set_interrupt(); tools call
  4. is_interrupted(), which checks the CURRENT thread."""
  5. import contextvars
  6. import logging
  7. import threading
  8. from collections.abc import Callable
  9. from utils import env_var_enabled
  10. logger = logging.getLogger(__name__)
  11. # Opt-in debug tracing — pairs with HERMES_DEBUG_INTERRUPT in tools/environments/base.py.
  12. _DEBUG_INTERRUPT = env_var_enabled("HERMES_DEBUG_INTERRUPT")
  13. if _DEBUG_INTERRUPT:
  14. # AIAgent's quiet_mode forces the `tools` logger to ERROR on CLI startup;
  15. # force ours back to INFO so the trace is visible in agent.log.
  16. logger.setLevel(logging.INFO)
  17. # Interrupted thread idents + optional user-safe cause (never the user's message text).
  18. _interrupted_threads: set[int] = set()
  19. _interrupt_reasons: dict[int, str] = {}
  20. # Threads asked to YIELD: hand a long-running foreground command to the background
  21. # instead of killing it, so a mid-turn user message is not parked behind it.
  22. _yield_threads: set[int] = set()
  23. _lock = threading.Lock()
  24. # Tool-worker tid a deadline worker acts for. ``run_bounded_sync`` runs its worker under
  25. # ``contextvars.copy_context()``, so a guard chain moved onto that worker still honours
  26. # ``/stop`` aimed at the tool thread that spawned it (``is_interrupted`` checks both).
  27. acting_for_tid: contextvars.ContextVar[int | None] = contextvars.ContextVar(
  28. "hermes_interrupt_acting_for_tid", default=None,
  29. )
  30. def set_interrupt(active: bool, thread_id: int | None = None, *, reason: str | None = None) -> None:
  31. """Set or clear the interrupt for *thread_id* (default: current thread); ``reason`` is
  32. an optional user-safe cause. Clearing also drops a pending yield request."""
  33. tid = thread_id if thread_id is not None else threading.current_thread().ident
  34. with _lock:
  35. (_interrupted_threads.add if active else _interrupted_threads.discard)(tid)
  36. if active and reason:
  37. _interrupt_reasons[tid] = reason
  38. else:
  39. _interrupt_reasons.pop(tid, None)
  40. if not active:
  41. _yield_threads.discard(tid)
  42. _snapshot = set(_interrupted_threads) if _DEBUG_INTERRUPT else None
  43. if _DEBUG_INTERRUPT:
  44. logger.info(
  45. "[interrupt-debug] set_interrupt(active=%s, target_tid=%s) "
  46. "called_from_tid=%s current_set=%s",
  47. active, tid, threading.current_thread().ident, _snapshot)
  48. def is_interrupted() -> bool:
  49. return is_thread_interrupted(threading.current_thread().ident) or is_thread_interrupted(acting_for_tid.get())
  50. def is_thread_interrupted(thread_id: int | None) -> bool:
  51. """Whether *thread_id* has an interrupt bit set (``None`` never is). Used when
  52. a wait moves onto a deadline worker (``run_bounded_sync``) so ``/stop``
  53. targeting the original tool-worker tid still kills the subprocess.
  54. See #94285.
  55. """
  56. if thread_id is None:
  57. return False
  58. with _lock:
  59. return thread_id in _interrupted_threads
  60. def request_yield(thread_id: int) -> None:
  61. """Ask the tool running on *thread_id* to yield: a foreground terminal command hands
  62. its live process to the background registry and returns at once, so a user's mid-turn
  63. message (``redirect()`` during tool execution) is delivered instead of parked behind it.
  64. The command itself is never killed; that is what ``set_interrupt`` is for."""
  65. with _lock:
  66. _yield_threads.add(thread_id)
  67. def is_thread_yield_requested(thread_id: int | None) -> bool:
  68. """Whether a yield is pending for *thread_id* (``None`` never is)."""
  69. if thread_id is None:
  70. return False
  71. with _lock:
  72. return thread_id in _yield_threads
  73. def consume_yield(thread_id: int | None) -> bool:
  74. """Atomically take the pending yield for *thread_id*; True if one was pending."""
  75. if thread_id is None:
  76. return False
  77. with _lock:
  78. if thread_id in _yield_threads:
  79. _yield_threads.discard(thread_id)
  80. return True
  81. return False
  82. def run_if_not_interrupted(callback: Callable[[], None]) -> bool:
  83. """Run a state transition atomically with current-thread interruption.
  84. Returns ``False`` without calling ``callback`` when the current thread is
  85. already interrupted. The callback runs under the interrupt lock and must
  86. not block or re-enter any interrupt API.
  87. """
  88. tid = threading.current_thread().ident
  89. with _lock:
  90. if tid in _interrupted_threads:
  91. return False
  92. callback()
  93. return True
  94. def get_interrupt_reason() -> str | None:
  95. """User-safe interrupt cause for the current thread, if known."""
  96. with _lock:
  97. return _interrupt_reasons.get(threading.current_thread().ident)
  98. def clear_current_thread_interrupt() -> None:
  99. """Clear any interrupt bit on the CURRENT thread: gives a user-approved command a clean
  100. slate right before it spawns its child, so a stale bit that landed during the blocking
  101. approval-wait cannot SIGINT the just-approved run. A *genuine* interrupt arriving after
  102. this call re-sets the bit and is still observed by the executor's poll loop. Call
  103. directly on the executing thread."""
  104. set_interrupt(False)