interrupt_scope.py 2.7 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273
  1. """Host-owned cancellation for agents created deep inside synchronous work.
  2. A host that runs a blocking command on a worker thread (Hermes Console) never sees
  3. the ``AIAgent`` a CLI subcommand forks inside it, so it cannot call ``interrupt()``
  4. when the user cancels. The host binds an :class:`InterruptScope` around the work;
  5. every ``run_conversation()`` under that scope registers its agent, and
  6. ``scope.cancel()`` hard-interrupts them from any thread. Agents registering after
  7. the cancel are interrupted immediately, so a cancel never loses the race with a
  8. turn that has not started yet (#106179).
  9. """
  10. from __future__ import annotations
  11. import threading
  12. from contextlib import contextmanager, nullcontext
  13. from contextvars import ContextVar
  14. from typing import Any, Iterator, Optional
  15. from agent.interrupt_compat import request_hard_interrupt
  16. _ACTIVE_SCOPE: ContextVar[Optional[InterruptScope]] = ContextVar("hermes_interrupt_scope", default=None)
  17. _TOOL_REASON_HOST_CANCELLED = "host cancelled the command"
  18. class InterruptScope:
  19. def __init__(self) -> None:
  20. self._lock = threading.Lock()
  21. self._agents: list[Any] = []
  22. self.reason: Optional[str] = None
  23. self._tool_reason: Optional[str] = _TOOL_REASON_HOST_CANCELLED
  24. def cancel(self, reason: str, *, tool_reason: Optional[str] = _TOOL_REASON_HOST_CANCELLED) -> None:
  25. """Latch ``reason`` and hard-interrupt every agent running under this scope.
  26. ``tool_reason`` names the system issuer; pass ``None`` for a human stop so the turn is
  27. attributed to the user rather than to the host (#112647)."""
  28. with self._lock:
  29. self.reason = reason
  30. self._tool_reason = tool_reason
  31. agents = list(self._agents)
  32. for agent in agents:
  33. request_hard_interrupt(agent, reason, tool_reason=tool_reason)
  34. @contextmanager
  35. def track(self, agent: Any) -> Iterator[None]:
  36. with self._lock:
  37. self._agents.append(agent)
  38. reason, tool_reason = self.reason, self._tool_reason
  39. if reason is not None:
  40. request_hard_interrupt(agent, reason, tool_reason=tool_reason)
  41. try:
  42. yield
  43. finally:
  44. with self._lock:
  45. self._agents.remove(agent)
  46. @contextmanager
  47. def bind_interrupt_scope(scope: Optional[InterruptScope]) -> Iterator[None]:
  48. """Make ``scope`` the owner of every agent turn started in this context."""
  49. token = _ACTIVE_SCOPE.set(scope)
  50. try:
  51. yield
  52. finally:
  53. _ACTIVE_SCOPE.reset(token)
  54. def track_in_interrupt_scope(agent: Any):
  55. """Register ``agent`` with the bound scope for the duration of its turn (no-op without one)."""
  56. scope = _ACTIVE_SCOPE.get()
  57. return nullcontext() if scope is None else scope.track(agent)