approval_gateway_wait.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264
  1. """Blocking gateway approval wait for :mod:`tools.approval`.
  2. Mirrors the CLI's synchronous ``input()`` flow: the agent thread enqueues a
  3. pending approval, the gateway notifies the user, and the thread blocks until
  4. ``/approve`` / ``/deny`` resolves it or the approval timeout elapses. Multiple
  5. threads (parallel subagents, execute_code RPC handlers) can block concurrently
  6. — each gets its own ``threading.Event``; ``/approve`` resolves the oldest,
  7. ``/approve all`` every pending entry. Queue state (``_gateway_queues``,
  8. ``_lock``) is owned by ``tools.approval`` and reached through that module at
  9. call time.
  10. """
  11. import logging
  12. import threading
  13. import time
  14. import uuid
  15. from tools.interrupt import get_interrupt_reason, is_interrupted
  16. from tools import approval_context as _ctx
  17. from tools.approval_human_wait import activity_heartbeat, human_wait_window
  18. logger = logging.getLogger("tools.approval")
  19. class _ApprovalEntry:
  20. """One pending dangerous-command approval inside a gateway session."""
  21. __slots__ = ("acknowledged", "cancelled", "data", "event", "expired", "observers", "reason", "result", "settle")
  22. def __init__(self, data: dict):
  23. self.event = threading.Event()
  24. self.data = dict(data)
  25. self.data.setdefault("request_id", uuid.uuid4().hex)
  26. self.acknowledged = False
  27. # Surface hook run once when the wait ends by ANY path (answer, timeout, interrupt, /approve from
  28. # another client): the tui_gateway withdraws its open server→client request through it.
  29. self.settle = None
  30. self.observers = []
  31. self.result: str | None = None # "once"|"session"|"always"|"deny"
  32. # Free-text reason from ``/deny <reason>`` so the agent can adapt, not just hear "denied".
  33. self.reason: str | None = None
  34. # Why the prompt was withdrawn with nobody answering (interrupt cause, session teardown);
  35. # followers and teardown read it so a withdrawn prompt never renders as a user deny.
  36. self.cancelled: str | None = None
  37. # The prompt timed out unanswered; followers woken by its event adopt that timeout.
  38. self.expired = False
  39. def _poll_event(event: threading.Event, session_key: str, *, interrupt_log: str,
  40. timeout_s: int | None = None) -> str:
  41. """Wait on *event* until it fires, the turn is interrupted, or approvals.timeout
  42. elapses; returns ``"set"`` | ``"interrupted"`` | ``"timeout"``. Polls in ~1s
  43. slices so activity heartbeats reach the agent's inactivity tracker every ~10s —
  44. otherwise the gateway watchdog kills the agent while the user is still
  45. responding (mirrors ``_wait_for_process()`` cadence). The loop is recorded as
  46. human-wait time so the concurrent batch deadline excludes it.
  47. Any interrupt (/stop, inactivity timeout, delegation teardown) ends the wait
  48. fail-closed: the command does not run. Who caused it is read from the
  49. per-thread interrupt-cause channel (``get_interrupt_reason()``, a trusted fixed
  50. category), never inferred from message text, so the caller can report a
  51. withdrawn prompt without inventing a user refusal."""
  52. deadline = time.monotonic() + max(_ctx._get_approval_timeout() if timeout_s is None else timeout_s, 0)
  53. heartbeat = activity_heartbeat("waiting for user approval")
  54. with human_wait_window(session_key):
  55. while True:
  56. # The poll loop below is verifiably blocked on a human answer (the user tapping approve/deny on
  57. # the gateway surface), bounded by the approval timeout. Record it as human-wait time so the
  58. # concurrent batch deadline excludes it (#79719).
  59. if is_interrupted():
  60. logger.info(interrupt_log, session_key)
  61. return "interrupted"
  62. remaining = deadline - time.monotonic()
  63. if remaining <= 0:
  64. return "timeout"
  65. if event.wait(timeout=min(1.0, remaining)):
  66. return "set"
  67. heartbeat()
  68. def _cancel_cause(state: str, entry) -> str | None:
  69. """Why the wait ended with nobody answering: the turn was interrupted (cause from the
  70. per-thread channel — a user /stop or a parent's delegation teardown), the entry was
  71. withdrawn with a stamped cause (leader interrupted, session torn down), or the turn ended
  72. under the prompt (notifier unregistered, result never set). ``None`` for a real answer
  73. or a plain timeout."""
  74. if state == "interrupted":
  75. return get_interrupt_reason() or "turn interrupted"
  76. if state == "set" and entry.result is None:
  77. return entry.cancelled or "the turn ended before the prompt was answered"
  78. return None
  79. def _finish(payload: dict, resolved: bool, choice: str | None, reason, **extra) -> dict:
  80. """Fire the post hook and build the decision dict. Unresolved (timeout) and
  81. a None choice both mean the user never answered; ``cancelled`` carries the
  82. cause when the prompt was withdrawn rather than answered."""
  83. _ctx._fire_approval_hook("post_approval_response", **payload, choice=_hook_choice(resolved, choice, extra), **extra)
  84. return {"resolved": resolved, "choice": choice, "reason": reason, **extra}
  85. def _hook_choice(resolved: bool, choice: str | None, extra: dict) -> str:
  86. """Observer-facing outcome of a wait: the choice, else ``cancelled`` / ``timeout``."""
  87. if extra.get("cancelled"):
  88. return "cancelled"
  89. return (choice or "timeout") if resolved else "timeout"
  90. def _await_coalesced_leader(session_key: str, leader, payload: dict):
  91. """Wait on an already-pending identical approval instead of re-prompting.
  92. Adopts the leader's decision: ``session``/``always`` → approval (same dict
  93. shape as a direct resolution; persistence stays the caller's and is
  94. idempotent across leader and followers); ``deny`` → denial carrying the
  95. leader's reason; leader timeout / our own deadline → unresolved. ``once``
  96. returns ``None``: single-use consent covers only the leader's execution,
  97. so the caller must issue a fresh prompt. Hooks fire with ``coalesced=True``
  98. so observers see the follower's lifecycle without a duplicate prompt."""
  99. _ctx._fire_approval_hook("pre_approval_request", **payload, coalesced=True)
  100. # The leader's captured timeout (when stamped), so a config edit mid-wait can't end the follower first.
  101. state = _poll_event(leader.event, session_key, timeout_s=leader.data.get("timeout_s"),
  102. interrupt_log="Coalesced approval wait interrupted — "
  103. "returning deny for session %s")
  104. if state == "set" and leader.result is None and leader.expired:
  105. state = "timeout"
  106. cancelled = _cancel_cause(state, leader)
  107. if state == "interrupted":
  108. # Deny only OUR follower; the leader thread handles its own signal.
  109. choice, resolved = "deny", True
  110. elif state == "timeout":
  111. choice, resolved = None, False
  112. else:
  113. choice = leader.result
  114. resolved = choice is not None
  115. if choice == "once":
  116. # The post hook fires for the fresh prompt's own lifecycle, not here.
  117. return None
  118. extra = {"cancelled": cancelled} if cancelled else {}
  119. return _finish(payload, resolved, choice, getattr(leader, "reason", None), coalesced=True, **extra)
  120. def _await_gateway_decision(session_key: str, notify_cb, approval_data: dict, *, surface: str = "gateway") -> dict:
  121. """Enqueue *approval_data*, notify the user, and block until resolved or timed
  122. out. Shared by the terminal command guard, the execute_code guard, the plugin
  123. escalation gate, and MCP elicitation. Returns ``{"resolved", "choice",
  124. "reason"}`` or ``{"resolved": False, "choice": None, "notify_failed": True}``
  125. when the notify callback raised. Persisting the choice and building the
  126. tool-facing result stay with the caller.
  127. Identical concurrent approvals (same command text + pattern-key set) are
  128. coalesced: parallel tool calls would otherwise fire N identical prompts
  129. the user must /approve N times while the agent sits wedged. Followers adopt
  130. the leader's ``session``/``always``/``deny``/timeout; a ``once`` covers only
  131. the leader, so the followers fall through to ONE fresh prompt they coalesce on."""
  132. from tools import approval as _approval
  133. from agent.terminal_approval_batch import approval_published, preparing_terminal_approval, register_prepared_approval
  134. primary_key = approval_data.get("pattern_key", "")
  135. if surface == "gateway":
  136. surface = _ctx.gateway_approval_surface()
  137. payload = {
  138. "command": approval_data.get("command", ""),
  139. "description": approval_data.get("description", ""),
  140. "pattern_key": primary_key,
  141. "pattern_keys": list(approval_data.get("pattern_keys", [primary_key])),
  142. "session_key": session_key, "surface": surface,
  143. }
  144. keys = list(approval_data.get("pattern_keys") or [])
  145. entry = _ApprovalEntry(approval_data)
  146. # Captured before the entry is published: a coalesced follower can find it while the pre-request
  147. # hooks still run, and must wait this same timeout rather than re-read a since-edited config.
  148. timeout_s = entry.data["timeout_s"] = _ctx._get_approval_timeout()
  149. def _enqueue() -> None:
  150. register_prepared_approval(session_key, entry)
  151. _approval._gateway_queues.setdefault(session_key, []).append(entry)
  152. # The leader lookup and our enqueue are ONE critical section: split, two identical requests both
  153. # miss each other, both enqueue and the user gets duplicate prompts. A ``once`` releases the
  154. # followers to prompt for themselves; they re-coalesce behind whichever re-prompts first, so the
  155. # user still sees one prompt at a time (the answered leader is already off the queue).
  156. while True:
  157. with _approval._lock:
  158. leader = None
  159. if not preparing_terminal_approval():
  160. leader = next((e for e in _approval._gateway_queues.get(session_key, [])
  161. if e.data.get("command") == approval_data.get("command")
  162. and list(e.data.get("pattern_keys") or []) == keys), None)
  163. if leader is None:
  164. _enqueue()
  165. break
  166. adopted = _await_coalesced_leader(session_key, leader, payload)
  167. if adopted is not None:
  168. return adopted
  169. def _drop_entry(state: str) -> str | None:
  170. """Leave the queue and return the choice committed so far. Reading ``entry.result`` and
  171. removing the entry are one critical section under the approval lock: ``resolve_gateway_approval``
  172. commits under the same lock, so a choice that landed after the deadline check but before this
  173. removal is still ours to honour, and one arriving later finds no entry (the client is told
  174. nothing was pending instead of being acked "ok" while the agent denies)."""
  175. with _approval._lock:
  176. choice = entry.result
  177. queue = _approval._gateway_queues.get(session_key, [])
  178. if entry in queue:
  179. queue.remove(entry)
  180. if not queue:
  181. _approval._gateway_queues.pop(session_key, None)
  182. settle, entry.settle = entry.settle, None
  183. observers, entry.observers = entry.observers, []
  184. if choice is None and state in ("timeout", "notify_failed"):
  185. # Coalesced followers block on this event: wake them with the leader's outcome rather than
  186. # leaving them waiting their own full timeout on a prompt that no longer exists.
  187. entry.expired = state == "timeout"
  188. if state == "notify_failed":
  189. entry.cancelled = "the approval prompt could not be delivered"
  190. entry.event.set()
  191. if settle is not None or observers:
  192. # ``request.cancel`` carries a RequestCancelReason: a choice committed from another surface is
  193. # ``resolved``; a withdrawn entry (woken with no choice — session torn down, turn ended, client
  194. # cannot answer) is ``session_closed``; never the raw poll-state token "set".
  195. if state == "timeout" and choice is not None:
  196. reason = "resolved"
  197. elif state == "set":
  198. reason = "resolved" if choice is not None else "session_closed"
  199. else:
  200. reason = state
  201. for callback in ([settle] if settle is not None else []) + observers:
  202. try:
  203. callback(reason)
  204. except Exception:
  205. logger.debug("approval settle hook failed", exc_info=True)
  206. return choice
  207. from tools.human_input_hooks import human_input_request
  208. with human_input_request("approval", prompt=payload["command"], session_key=session_key) as human:
  209. # Plugins hear about the request before the gateway does (real-time observers).
  210. _ctx._fire_approval_hook("pre_approval_request", **payload)
  211. # Bridges sync agent thread → async gateway.
  212. try:
  213. notify_cb(dict(entry.data))
  214. approval_published()
  215. except Exception as exc:
  216. logger.warning("Gateway approval notify failed: %s", exc)
  217. _drop_entry("notify_failed")
  218. _ctx._fire_approval_hook("post_approval_response", **payload, choice="notify_failed")
  219. human.outcome = "notify_failed"
  220. return {"resolved": False, "choice": None, "notify_failed": True}
  221. state = _poll_event(entry.event, session_key, timeout_s=timeout_s,
  222. interrupt_log="Approval wait interrupted — returning deny for session %s")
  223. cancelled = _cancel_cause(state, entry)
  224. if state == "interrupted":
  225. # Coalesced followers wake with the cause instead of a deny nobody issued.
  226. entry.cancelled = cancelled
  227. entry.event.set()
  228. choice = _drop_entry(state)
  229. if state == "interrupted":
  230. # Our own decision stays a fail-closed deny.
  231. choice = "deny"
  232. # A choice that landed in the gap between the deadline check and leaving the queue is an answer,
  233. # not a timeout (#112548) — the same first-settlement rule as server_requests.send().
  234. resolved = state != "timeout" or choice is not None
  235. extra = {"cancelled": cancelled} if cancelled else {}
  236. human.outcome = _hook_choice(resolved, choice, extra)
  237. return _finish(payload, resolved, choice, entry.reason, **extra)