clarify_gateway.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308
  1. """Gateway-side clarify primitive (blocking event-based queue). The agent runs on a worker
  2. thread while the event loop handles the user's reply, so a pending clarify is stored
  3. module-level (same shape as ``tools.approval``) and the agent thread blocks on an ``Event``
  4. until an adapter button callback or the gateway text-intercept resolves it, or the timeout
  5. fires. Adapters render inline buttons (an "Other" row flips the entry into text-capture
  6. mode) or a numbered-list text fallback."""
  7. from __future__ import annotations
  8. import json
  9. import logging
  10. import threading
  11. import time
  12. from dataclasses import dataclass, field
  13. from typing import Callable, Dict, List, Optional
  14. logger = logging.getLogger(__name__)
  15. @dataclass
  16. class _ClarifyEntry:
  17. """One pending clarify request inside a gateway session."""
  18. clarify_id: str
  19. session_key: str
  20. question: str
  21. choices: Optional[list[str]]
  22. multi_select: bool = False
  23. event: threading.Event = field(default_factory=threading.Event)
  24. response: Optional[str] = None
  25. awaiting_text: bool = False # set when user picked "Other" or clarify is open-ended
  26. _lock = threading.RLock()
  27. _entries: dict[str, _ClarifyEntry] = {} # clarify_id -> entry (button callbacks)
  28. _session_index: dict[str, list[str]] = {} # session_key -> [clarify_id] FIFO (text intercept, cleanup)
  29. # Per-session notify callbacks (gateway -> adapter bridge); mirrors tools.approval. Tests clear it.
  30. _notify_cbs: dict[str, Callable[[_ClarifyEntry], None]] = {}
  31. # Outcomes for typed clarify replies. Gateway cancels the pending prompt on
  32. # free prose (deadlock break) but keeps it armed for a retryable bad selection.
  33. TEXT_RESOLVED = "resolved"
  34. TEXT_REJECTED_PROSE = "rejected_prose"
  35. TEXT_REJECTED_SELECTION = "rejected_selection"
  36. TEXT_NO_PENDING = "no_pending"
  37. SKIP_WORD = "skip"
  38. SKIPPED = "\x00skipped"
  39. CANCELLED = "\x00cancelled"
  40. def register(clarify_id: str, session_key: str, question: str, choices: Optional[list[str]],
  41. multi_select: bool = False) -> _ClarifyEntry:
  42. """Register a pending clarify request; caller then blocks on ``wait_for_response``.
  43. Open-ended (no choices) entries start in text mode: the next message IS the response."""
  44. entry = _ClarifyEntry(clarify_id, session_key, question, list(choices) if choices else None,
  45. bool(multi_select) and bool(choices), awaiting_text=not bool(choices))
  46. with _lock:
  47. _entries[clarify_id] = entry
  48. _session_index.setdefault(session_key, []).append(clarify_id)
  49. return entry
  50. def wait_for_response(clarify_id: str, timeout: float) -> Optional[str]:
  51. """Block until the entry resolves or ``timeout`` (``<= 0`` = unlimited) elapses; None on
  52. timeout/unknown id. Polls in 1s slices so the inactivity heartbeat keeps firing (a
  53. single long ``Event.wait`` would let the gateway watchdog kill a live prompt)."""
  54. with _lock:
  55. entry = _entries.get(clarify_id)
  56. if entry is None:
  57. return None
  58. try:
  59. from tools.environments.base import touch_activity_if_due
  60. except Exception: # pragma: no cover - optional
  61. touch_activity_if_due = None
  62. from tools.interrupt import is_interrupted
  63. deadline = None if timeout is None or float(timeout) <= 0.0 else time.monotonic() + float(timeout)
  64. activity_state = {"last_touch": time.monotonic(), "start": time.monotonic()}
  65. while True:
  66. remaining = 1.0 if deadline is None else deadline - time.monotonic()
  67. if remaining <= 0 or entry.event.wait(timeout=min(1.0, remaining)):
  68. break
  69. if is_interrupted():
  70. # /stop or gateway shutdown on this turn's thread: withdraw the prompt the way the
  71. # approval wait does, or a planned stop sits out the whole clarify timeout and the
  72. # turn is left started (unknown after restart). A real answer that won the race stays.
  73. with _lock:
  74. if not entry.event.is_set():
  75. entry.response = CANCELLED
  76. break
  77. # Periodic activity touch so the gateway's inactivity timeout doesn't kill the agent during long
  78. # code execution (#10807).
  79. if touch_activity_if_due is not None:
  80. touch_activity_if_due(activity_state, "waiting for user clarify response")
  81. with _lock:
  82. _entries.pop(clarify_id, None) # regardless of outcome
  83. entry.event.set() # Timeout also retires shared projections of this waiter.
  84. ids = _session_index.get(entry.session_key) or []
  85. if clarify_id in ids:
  86. ids.remove(clarify_id)
  87. if not ids:
  88. _session_index.pop(entry.session_key, None)
  89. return entry.response
  90. def resolve_gateway_clarify(clarify_id: str, response: str) -> bool:
  91. """Unblock the waiter on ``clarify_id``; False if already resolved/expired/unknown."""
  92. with _lock:
  93. entry = _entries.get(clarify_id)
  94. if entry is None or entry.event.is_set():
  95. return False
  96. entry.response = str(response) if response is not None else ""
  97. entry.event.set()
  98. return True
  99. def get_pending(clarify_id: str) -> Optional[_ClarifyEntry]:
  100. """The entry for ``clarify_id`` while it is still awaiting an answer, else None (unknown,
  101. answered, timed out or cleared). Read-only: adapters rendering native choice cards compare it
  102. by identity with the entry they rendered and read ``session_key`` / ``choices`` /
  103. ``multi_select`` from it; answering goes through ``resolve_gateway_clarify``."""
  104. with _lock:
  105. entry = _entries.get(clarify_id)
  106. return entry if entry is not None and not entry.event.is_set() else None
  107. def get_pending_for_session(session_key: str, *, include_choice_prompts: bool = False) -> Optional[_ClarifyEntry]:
  108. """Oldest pending entry awaiting free text (open-ended, or after "Other");
  109. ``include_choice_prompts=True`` returns the oldest unresolved entry of any kind (user
  110. typed at an active choice prompt: resolve it rather than queue a follow-up turn)."""
  111. with _lock:
  112. for cid in _session_index.get(session_key) or []:
  113. entry = _entries.get(cid)
  114. if entry is not None and (include_choice_prompts or entry.awaiting_text):
  115. return entry
  116. return None
  117. def _match_label(text: str, choices: list[str]) -> Optional[str]:
  118. """Stripped choice text matching ``text`` case-insensitively, ignoring the '(Recommended)'
  119. suffix the first choice carries by the time it reaches adapters; None if no match."""
  120. from tools.clarify_tool import strip_recommended
  121. wanted = strip_recommended(text).casefold()
  122. for choice in choices:
  123. if strip_recommended(str(choice)).casefold() == wanted:
  124. return str(choice).strip()
  125. return None
  126. def _split_tokens(text: str) -> Optional[list[str]]:
  127. """Comma-separated tokens, or space-separated all-numeric tokens ("1 3"); else None."""
  128. if "," in text:
  129. return [t.strip() for t in text.split(",") if t.strip()]
  130. parts = text.split()
  131. return parts if len(parts) > 1 and all(p.isdigit() for p in parts) else None
  132. def _is_int(text: str) -> bool:
  133. try:
  134. int(text)
  135. return True
  136. except ValueError:
  137. return False
  138. def _selection_attempt_tokens(text: str, choices: Optional[list[str]] = None) -> Optional[list[str]]:
  139. """Tokens when ``text`` looks like a typed selection (bare int, comma list,
  140. all-numeric space list); None for free prose so the gateway can release the
  141. clarify. Comma-list labels may span up to the longest choice's word count."""
  142. stripped = str(text).strip()
  143. if not stripped:
  144. return None
  145. tokens = _split_tokens(stripped)
  146. if tokens is None:
  147. digits = stripped.removeprefix("-")
  148. return [stripped] if digits.isdigit() or _is_int(stripped) else None
  149. if "," not in stripped or not tokens:
  150. return tokens or None
  151. max_words = max(1, max((len(str(c).split()) for c in choices or []), default=1))
  152. return tokens if all(t.isdigit() or len(t.split()) <= max_words for t in tokens) else None
  153. def _coerce_text_response(entry: _ClarifyEntry, response: str) -> Optional[str]:
  154. """Accepted value for a typed reply, or None on any rejection."""
  155. return _coerce_text_response_detailed(entry, response)[0]
  156. def _coerce_text_response_detailed(entry: _ClarifyEntry, response: str) -> tuple[Optional[str], Optional[str]]:
  157. """Map a typed reply to ``(value, None)`` or ``(None, reason)``: ``"invalid_selection"``
  158. (selection-shaped but out of range/unrecognised — keep the clarify armed for a retry) or
  159. ``"prose"`` (free text on a native choice prompt — the gateway may cancel and route normally
  160. so a redirect-to-steer path cannot deadlock behind the waiting tool). Open-ended entries and
  161. ``awaiting_text`` accept any text; numeric picks and exact labels always resolve; multi-select
  162. returns a JSON array string (decoded tool-side); one bad token rejects the whole reply."""
  163. text = str(response).strip()
  164. is_skip = text.casefold() == SKIP_WORD
  165. if not entry.choices:
  166. return (SKIPPED if is_skip else text), None
  167. if entry.multi_select:
  168. coerced = _coerce_multi_select_text(entry, text)
  169. selection_shaped = _selection_attempt_tokens(text, entry.choices) is not None
  170. else:
  171. # Out-of-range / non-canonical integer is a failed selection, not prose.
  172. selection_shaped = _is_int(text)
  173. idx = int(text) - 1 if selection_shaped else -1
  174. coerced = entry.choices[idx] if 0 <= idx < len(entry.choices) else _match_label(text, entry.choices)
  175. if coerced is not None:
  176. return coerced, None
  177. if is_skip:
  178. return SKIPPED, None
  179. if entry.awaiting_text:
  180. return text, None
  181. return None, "invalid_selection" if selection_shaped else "prose"
  182. def _coerce_multi_select_text(entry: _ClarifyEntry, text: str) -> Optional[str]:
  183. """Parse "1,3" / "1 3" / "staging, prod" into a JSON array of choice labels;
  184. None when any token is out of range or unrecognised (reject the whole reply)."""
  185. choices, selected = entry.choices or [], []
  186. if not text:
  187. return None
  188. tokens = _split_tokens(text)
  189. for token in [text] if tokens is None else tokens:
  190. if token.isdigit():
  191. idx = int(token) - 1
  192. label = str(choices[idx]).strip() if 0 <= idx < len(choices) else None
  193. else:
  194. label = _match_label(token, choices)
  195. if label is None:
  196. return None
  197. if label not in selected:
  198. selected.append(label)
  199. return json.dumps(selected, ensure_ascii=False) if selected else None
  200. def attempt_text_response_for_session(session_key: str, response: str) -> str:
  201. """Try to resolve the oldest pending clarify from typed text; returns a TEXT_* outcome."""
  202. entry = get_pending_for_session(session_key, include_choice_prompts=True)
  203. if entry is None:
  204. return TEXT_NO_PENDING
  205. coerced, reason = _coerce_text_response_detailed(entry, response)
  206. if coerced is None:
  207. return TEXT_REJECTED_SELECTION if reason == "invalid_selection" else TEXT_REJECTED_PROSE
  208. if resolve_gateway_clarify(entry.clarify_id, coerced):
  209. return TEXT_RESOLVED
  210. return TEXT_NO_PENDING # lost a race with a button/callback resolution — no work left
  211. def resolve_text_response_for_session(session_key: str, response: str) -> bool:
  212. """True only when the typed reply was accepted and the waiter unblocked."""
  213. return attempt_text_response_for_session(session_key, response) == TEXT_RESOLVED
  214. def mark_awaiting_text(clarify_id: str) -> bool:
  215. """Flip an entry into text-capture mode (user picked 'Other'); False if unknown."""
  216. with _lock:
  217. entry = _entries.get(clarify_id)
  218. if entry is not None:
  219. entry.awaiting_text = True
  220. return entry is not None
  221. def has_pending(session_key: str) -> bool:
  222. """True when this session has at least one pending clarify entry."""
  223. with _lock:
  224. return any(_entries.get(cid) is not None for cid in _session_index.get(session_key) or [])
  225. def clear_session(session_key: str) -> int:
  226. """Drop every pending clarify for a session (``/new``, shutdown, cached-agent eviction) so
  227. blocked agent threads don't outlive it; returns how many were cancelled. First-writer-wins: an already-set entry was answered for
  228. real, so it is dropped but its response preserved. The loop stays inside the lock so a button
  229. callback cannot slip between pop and check; entries go regardless of state so a cleared
  230. session is never resurrected by late callbacks."""
  231. with _lock:
  232. cancelled = 0
  233. for entry in (_entries.pop(cid, None) for cid in list(_session_index.pop(session_key, []) or [])):
  234. if entry is None or entry.event.is_set():
  235. continue
  236. entry.response = CANCELLED
  237. entry.event.set()
  238. cancelled += 1
  239. return cancelled
  240. def resolve_clarify_timeout(config: dict) -> int:
  241. """Clarify timeout (seconds): legacy ``clarify.timeout`` if explicitly set, else
  242. ``agent.clarify_timeout``, else 3600 — the single source of truth for every surface
  243. (gateway, CLI, TUI). ``<= 0`` is kept verbatim (unlimited); non-numeric -> 3600."""
  244. raw = (config.get("clarify") or {}).get("timeout")
  245. if raw is None:
  246. raw = (config.get("agent") or {}).get("clarify_timeout", 3600)
  247. try:
  248. return int(raw)
  249. except (TypeError, ValueError):
  250. return 3600
  251. def get_clarify_timeout() -> int:
  252. """Clarify timeout from config.yaml; 0/negative = unlimited. Default 3600: long enough
  253. that a user who stepped away still finds a live entry when they tap, short enough that
  254. an abandoned prompt eventually unblocks the agent thread instead of pinning the guard.
  255. The old 600s default evicted the entry mid-think, so a late tap landed on a dead entry and the agent
  256. hung on ``running: clarify`` (#32762).
  257. """
  258. try:
  259. from hermes_cli.config import load_config
  260. return resolve_clarify_timeout(load_config() or {})
  261. except Exception:
  262. return 3600