run_turn_runner_clarify_delivery.py 9.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184
  1. """Clarify prompt delivery on messaging platforms: send disposition, plain-text fallback, bounded wait.
  2. A native clarify card (Telegram inline keyboard, Slack blocks, …) can fail to render in three ways
  3. the user never sees (#112684): the platform rejects it at once, the send outruns the 15 s
  4. disposition window and only then fails (pool / connect timeouts, a stale-thread retry), or there
  5. is no chat surface at all. Each used to end as a full ``clarify_timeout`` of silence reported as
  6. "the user did not respond". Here every definitive failure of the native card falls back to the
  7. adapter's plain-text ``send_clarify`` (numbered list + text capture), and a card that fails AFTER
  8. the window releases the wait with the delivery notice instead of the inactivity one.
  9. """
  10. from __future__ import annotations
  11. import logging
  12. from typing import Any, Callable, Optional
  13. logger = logging.getLogger(__name__)
  14. UNDELIVERED = "[clarify prompt could not be delivered]"
  15. UNDELIVERED_DECLINED = "[clarify prompt could not be delivered: destination refused]"
  16. # No status adapter (a run whose chat surface is gone).
  17. UNDELIVERED_NO_SURFACE = "[clarify prompt could not be delivered: no chat surface]"
  18. # Seconds a scheduled card send may take before it is classified ``ambiguous`` (possibly posted).
  19. SEND_ACK_WINDOW = 15
  20. def text_fallback_coro(adapter, **send_kwargs):
  21. """The base numbered-text ``send_clarify`` as a fresh coroutine, or ``None`` when the adapter has
  22. no native override — its ``send_clarify`` already IS the text path, so retrying it would only
  23. repeat the failure."""
  24. from gateway.platforms.base import BasePlatformAdapter
  25. if not isinstance(adapter, BasePlatformAdapter) \
  26. or type(adapter).send_clarify is BasePlatformAdapter.send_clarify:
  27. return None
  28. # A human-decision prompt: Telegram's "important" mode must push it, not deliver it silently (#132516).
  29. metadata = {**(send_kwargs.pop("metadata", None) or {}), "is_approval_prompt": True}
  30. return BasePlatformAdapter.send_clarify(adapter, metadata=metadata, **send_kwargs)
  31. def _abort_for_outcome(outcome: str, *, session_key: str, clarify_mod) -> Optional[str]:
  32. """Map a send outcome to the abort sentinel (registration torn down) or ``None`` (proceed to wait).
  33. Only a DEFINITIVE failure tears down the registration; ``ambiguous`` (card may have posted) stays armed
  34. and proceeds to the bounded wait, whose response timeout covers a lost card."""
  35. if outcome == "declined":
  36. # P5(b): a connector DECLINE is MORE definitive than a failure — the
  37. # destination was authorized and refused, so the card cannot arrive and
  38. # no late reply can resolve it. Without this branch `declined` fell
  39. # through to the bounded wait and the agent blocked until
  40. # clarify_timeout (indefinitely when that is configured non-positive).
  41. logger.warning(
  42. "Clarify prompt DECLINED by the connector's egress guard; "
  43. "clearing registration"
  44. )
  45. clarify_mod.clear_session(session_key)
  46. return UNDELIVERED_DECLINED
  47. if outcome == "failed":
  48. # Undeliverable: clear the registration and return the sentinel so the agent falls back, not hangs.
  49. logger.warning("Clarify send failed definitively; clearing registration")
  50. clarify_mod.clear_session(session_key)
  51. return UNDELIVERED
  52. if outcome == "ambiguous":
  53. logger.warning(
  54. "Clarify prompt send timed out — treating as possibly-delivered "
  55. "(no teardown; the registration stays armed for a late reply)")
  56. return None
  57. def _clarify_send_disposition(fut, *, session_key: str, clarify_mod) -> Optional[str]:
  58. """Decide whether a clarify prompt send aborts the wait; returns the abort sentinel or ``None``."""
  59. from gateway.run import _approval_send_outcome
  60. return _abort_for_outcome(
  61. _approval_send_outcome(fut, timeout=SEND_ACK_WINDOW), session_key=session_key, clarify_mod=clarify_mod)
  62. def _clarify_send_then_wait(fut, *, clarify_id: str, session_key: str, clarify_mod,
  63. fallback: Optional[Callable[[], Any]] = None) -> tuple[str, bool]:
  64. """Resolve a clarify prompt: send disposition, plain-text fallback, then the bounded wait.
  65. ``fallback()`` schedules the plain-text ``send_clarify`` and returns its future (or ``None``);
  66. it runs when the native card failed definitively — at once, or late, after the ack window —
  67. and never on a connector DECLINE (re-sending refused content as text is the exfiltration the
  68. egress guard exists to stop). A card that fails after the window releases the wait with the
  69. delivery notice, not the inactivity one.
  70. Returns ``(response, answered)``. ``answered`` is the only signal that a user reply arrived;
  71. callers must not infer it from the text (a real answer may start with '[' like a sentinel)."""
  72. from gateway.run import _approval_send_outcome
  73. outcome = _approval_send_outcome(fut, timeout=SEND_ACK_WINDOW)
  74. if outcome == "failed" and fallback is not None:
  75. # The text prompt is the last resort: a late failure of ITS send has nothing to retry.
  76. fut, fallback = fallback(), None
  77. # ``None`` = the fallback could not even be scheduled; the card failure already stands,
  78. # so re-classifying would only log a misleading "no scheduling future".
  79. if fut is not None:
  80. outcome = _approval_send_outcome(fut, timeout=SEND_ACK_WINDOW)
  81. if outcome == "sent":
  82. logger.info("Clarify card undeliverable; plain-text prompt sent instead (id=%s)", clarify_id)
  83. abort = _abort_for_outcome(outcome, session_key=session_key, clarify_mod=clarify_mod)
  84. if abort is not None:
  85. return abort, False
  86. late = _LateFailureWatch(fut, clarify_id=clarify_id, session_key=session_key,
  87. clarify_mod=clarify_mod, fallback=fallback)
  88. timeout = clarify_mod.get_clarify_timeout()
  89. response = clarify_mod.wait_for_response(clarify_id, timeout=float(timeout))
  90. late.disarm()
  91. if late.undeliverable:
  92. return late.undeliverable, False
  93. if response == clarify_mod.CANCELLED:
  94. return response, False
  95. if response is None or response == "":
  96. return f"[user did not respond within {int(timeout / 60)}m]", False
  97. return response, True
  98. class _LateFailureWatch:
  99. """Watch a possibly-delivered card send: when it resolves as a definitive failure after the
  100. ack window, try the text fallback once, then release the waiter with the delivery notice.
  101. Callbacks run on the gateway loop thread (the send future completes there); ``clear_session``
  102. wakes the agent thread blocked in ``wait_for_response`` and ``undeliverable`` (the delivery
  103. sentinel, or ``None`` while nothing definitive happened) tells it why.
  104. Armed only while the future is still pending: a sent card needs no watch."""
  105. def __init__(self, fut, *, clarify_id: str, session_key: str, clarify_mod, fallback) -> None:
  106. self.undeliverable: Optional[str] = None
  107. self._armed = False
  108. self._clarify_id = clarify_id
  109. self._session_key = session_key
  110. self._clarify_mod = clarify_mod
  111. self._fallback = fallback
  112. # Test doubles hand the runner a bare ``.result()`` object; only a real pending
  113. # concurrent future can still resolve late.
  114. done = getattr(fut, "done", None)
  115. if callable(done) and not done():
  116. self._armed = True
  117. fut.add_done_callback(self._on_card_done)
  118. def disarm(self) -> None:
  119. self._armed = False
  120. @staticmethod
  121. def _outcome(fut) -> str:
  122. from gateway.run import _approval_send_outcome
  123. return _approval_send_outcome(fut, timeout=0)
  124. def _on_card_done(self, fut) -> None:
  125. if not self._armed:
  126. return
  127. outcome = self._outcome(fut)
  128. if outcome == "sent":
  129. return
  130. logger.warning("Clarify card send resolved %s after the ack window (id=%s)", outcome, self._clarify_id)
  131. if outcome == "ambiguous":
  132. # Lost ack (``raw_response.ambiguous``): the card may well have posted. Same invariant as
  133. # ``_abort_for_outcome`` — stay armed for the late button tap, never re-send, never
  134. # release; the bounded wait's own timeout covers a card that truly never arrived.
  135. return
  136. if outcome == "declined":
  137. # Refused destination: no text retry (see ``_clarify_send_then_wait``), and the notice
  138. # says so rather than the generic delivery failure.
  139. self._release(UNDELIVERED_DECLINED)
  140. return
  141. fallback_fut = self._fallback() if self._fallback is not None else None
  142. if fallback_fut is None:
  143. self._release()
  144. return
  145. fallback_fut.add_done_callback(self._on_fallback_done)
  146. def _on_fallback_done(self, fut) -> None:
  147. if not self._armed:
  148. return
  149. if self._outcome(fut) == "sent":
  150. logger.info("Clarify card undeliverable; plain-text prompt sent instead (id=%s)", self._clarify_id)
  151. return
  152. self._release()
  153. def _release(self, notice: str = UNDELIVERED) -> None:
  154. self.undeliverable = notice
  155. self._clarify_mod.clear_session(self._session_key)