stream_consumer_transport.py 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610
  1. """Transport layer of GatewayStreamConsumer: native frames, drafts, edit/send.
  2. Mixin methods use only ``self`` state; see gateway/stream_consumer.py for the
  3. state model and the drain loop that calls into these."""
  4. from __future__ import annotations
  5. import asyncio
  6. import inspect
  7. import logging
  8. import time
  9. from typing import Any, Optional
  10. from gateway.platforms.base import BasePlatformAdapter as _BasePlatformAdapter
  11. from gateway.stream_consumer_fences import ensure_closed_code_fences
  12. from hermes_cli.observability.shared_metrics_gateway import stops_reply_clock
  13. logger = logging.getLogger("gateway.stream_consumer")
  14. # Longest interim-edit interval flood backoff may reach. Interim edits are skipped (not slept)
  15. # until the interval elapses, so honouring a 30s Telegram retry_after costs nothing but a
  16. # stale preview; anything longer is left to the strike counter and the fallback send path.
  17. _MAX_EDIT_BACKOFF_SECS = 30.0
  18. class StreamTransportMixin:
  19. """Send/edit/frame primitives and the transport-ordered ``_send_or_edit``."""
  20. _MIN_NEW_MSG_CHARS = 4
  21. async def _edit_message(self, *, message_id: str, content: str, finalize: bool = False):
  22. """Edit via the adapter, passing routing metadata when supported."""
  23. # Contract: adapters must accept finalize= even when False (test-guarded).
  24. kwargs = dict(chat_id=self.chat_id, message_id=message_id, content=content,
  25. finalize=finalize)
  26. if self.metadata:
  27. try:
  28. params = inspect.signature(self.adapter.edit_message).parameters
  29. if "metadata" in params or any(
  30. param.kind is inspect.Parameter.VAR_KEYWORD for param in params.values()):
  31. kwargs["metadata"] = self.metadata
  32. except (TypeError, ValueError):
  33. pass
  34. return await self.adapter.edit_message(**kwargs)
  35. async def _try_seed_frame(self, fail_log: str, *, exc_info: bool = False) -> bool:
  36. """Open a native stream with an empty seed frame (typing indicator before any token) as a
  37. bool; a raise logs ``fail_log`` at DEBUG (error formatted in, or the traceback when
  38. ``exc_info``) and reads as False."""
  39. seed = self.adapter.send_stream_frame(
  40. "", chat_id=self.chat_id, reply_to=self._initial_reply_to_id, turn_id=self._turn_id)
  41. return await self._try_frame(seed, fail_log, exc_info=exc_info)
  42. @staticmethod
  43. async def _try_frame(coro, fail_log: str, *, exc_info: bool = False) -> bool:
  44. """Await a frame send as a bool; a raise logs ``fail_log`` at DEBUG and reads as False."""
  45. try:
  46. return bool(await coro)
  47. except Exception as e:
  48. if exc_info:
  49. logger.debug(fail_log, exc_info=True)
  50. else:
  51. logger.debug(fail_log, e)
  52. return False
  53. async def _send_frame(self, text: str, *, finalize: bool):
  54. """One native-stream frame; every frame carries the same chat/reply/turn routing."""
  55. return await self.adapter.send_stream_frame(
  56. text, finalize=finalize, chat_id=self.chat_id, reply_to=self._initial_reply_to_id,
  57. turn_id=self._turn_id)
  58. def _close_native_state(self) -> None:
  59. """Mark the native stream closed (next content re-seeds or falls back)."""
  60. self._native_stream_opened = False
  61. self._native_last_pushed_len = 0
  62. async def _close_empty_native_bubble(self, fail_log: str) -> None:
  63. """Best-effort empty finalize frame to close an open typing bubble, then mark closed."""
  64. await self._try_frame(self._send_frame("", finalize=True), fail_log)
  65. self._close_native_state()
  66. self._reopen_seeded_eagerly = False
  67. def _degrade_native_to_buffered_send(self) -> None:
  68. """Leave native mode; buffer_only so post-boundary output is ONE send() at got_done
  69. (mid-stream flushes would create multiple messages on non-editable platforms)."""
  70. self._use_native_streaming = False
  71. self._close_native_state()
  72. self.cfg.buffer_only = True
  73. def _draft_metadata(self) -> dict | None:
  74. """Draft-frame metadata: same reply_to_message_id as the final send, because the
  75. relay adapter keys draft/seal state on it (flat DMs have no thread metadata)."""
  76. md = dict(self.metadata) if self.metadata else {}
  77. if self._initial_reply_to_id:
  78. md.setdefault("reply_to_message_id", self._initial_reply_to_id)
  79. return md or None
  80. def _stale_preview_ids(self, *, segment_only: bool = False) -> set:
  81. """Preview ids a fresh final replaces; ``segment_only`` spares finalized preambles."""
  82. stale_ids = set(self._segment_preview_message_ids if segment_only
  83. else self._preview_message_ids)
  84. if self._message_id and self._message_id != "__no_edit__":
  85. stale_ids.add(str(self._message_id) if segment_only else self._message_id)
  86. return stale_ids
  87. async def _delete_previews(self, stale_ids, *, skip=None, label: str,
  88. retry_on_false: bool = False, skip_sentinel: bool = True) -> None:
  89. """Best-effort delete of stale previews; never the message just sent (``skip``)."""
  90. delete_fn = getattr(self.adapter, "delete_message", None)
  91. if delete_fn is None:
  92. return
  93. for stale_id in stale_ids:
  94. if not stale_id or stale_id == skip or (skip_sentinel and stale_id == "__no_edit__"):
  95. continue
  96. try:
  97. deleted = await delete_fn(self.chat_id, stale_id)
  98. if retry_on_false and deleted is False:
  99. # Telegram's delete_message reports failure by returning False, not raising. The same
  100. # flood window that broke the finalize edit can reject this delete too, leaving the
  101. # preview bubble next to the fresh final (#71047 Problem B). One short bounded retry
  102. # clears the common transient case; a second failure stays best-effort.
  103. await asyncio.sleep(1.0)
  104. await delete_fn(self.chat_id, stale_id)
  105. except Exception as e:
  106. logger.debug("%s preview cleanup failed (%s): %s", label, stale_id, e)
  107. def _resolve_draft_streaming(self) -> bool:
  108. """cfg.transport "draft"/"auto" → the adapter's supports_draft_streaming probe
  109. ("draft" logs the downgrade); "edit"/"off" → False."""
  110. transport = (self.cfg.transport or "edit").lower()
  111. # MagicMock test adapters default to edit.
  112. if transport in ("edit", "off") or not isinstance(self.adapter, _BasePlatformAdapter):
  113. return False
  114. probe_kwargs = dict(chat_type=self.cfg.chat_type or None, metadata=self.metadata)
  115. try:
  116. try:
  117. # Per-chat probe (relay adapters resolve through the CHAT's
  118. # descriptor); older adapters without the kwarg keep the legacy probe.
  119. supported = self.adapter.supports_draft_streaming(chat_id=self.chat_id,
  120. **probe_kwargs)
  121. except TypeError:
  122. supported = self.adapter.supports_draft_streaming(**probe_kwargs)
  123. except Exception:
  124. logger.debug("supports_draft_streaming probe raised", exc_info=True)
  125. supported = False
  126. if not supported and transport == "draft":
  127. logger.debug("Draft streaming requested but unsupported (chat=%s, type=%r) — "
  128. "falling back to edit", self.chat_id, self.cfg.chat_type)
  129. return bool(supported)
  130. def _resolve_native_streaming(self) -> bool:
  131. """Native streaming (send_stream_frame for ALL frames): a BasePlatformAdapter with
  132. class-level SUPPORTS_NATIVE_STREAMING and a truthy supports_native_streaming probe."""
  133. if not (isinstance(self.adapter, _BasePlatformAdapter)
  134. and getattr(type(self.adapter), "SUPPORTS_NATIVE_STREAMING", False)):
  135. return False
  136. probe = getattr(self.adapter, "supports_native_streaming", None)
  137. if probe is None:
  138. return False
  139. try:
  140. return bool(probe(chat_type=self.cfg.chat_type or None, metadata=self.metadata))
  141. except Exception:
  142. logger.debug("supports_native_streaming probe raised", exc_info=True)
  143. return False
  144. async def _send_draft_frame(self, text: str) -> bool:
  145. """Emit one draft frame; any failure permanently disables drafts for this run.
  146. Drafts have no message_id and clear on the client when the final send lands."""
  147. if self._draft_id is None:
  148. # Should never happen (set in tandem with _use_draft_streaming in run()).
  149. self._use_draft_streaming = False
  150. return False
  151. try:
  152. result = await self.adapter.send_draft(
  153. chat_id=self.chat_id, draft_id=self._draft_id, content=text,
  154. metadata=self._draft_metadata())
  155. except Exception as e:
  156. logger.debug("send_draft raised, disabling draft transport for this run: %s", e)
  157. else:
  158. if getattr(result, "success", False):
  159. self._last_sent_text = text # parity with the edit-based no-op skip
  160. return True
  161. # P5(b): an AUTHORIZATION decline is terminal for the whole run, not
  162. # merely "drafts are unusable". Disabling drafts alone routes the
  163. # turn-final to _first_send — a plain send into the chat the
  164. # connector just refused. Verified: ops were ['draft', 'send'].
  165. from gateway.relay.egress import declined_send
  166. if declined_send(result):
  167. logger.warning(
  168. "send_draft DECLINED by the connector's egress guard; "
  169. "suppressing every later send for this run (the destination "
  170. "is not approved for this connection)"
  171. )
  172. self._egress_declined = True
  173. logger.debug("send_draft returned success=False, disabling draft transport: %s",
  174. getattr(result, "error", "unknown"))
  175. self._draft_failures += 1
  176. self._use_draft_streaming = False
  177. return False
  178. async def _abandon_native_stream(self) -> None:
  179. """Seal an orphaned draft stream on turn death (stale exit / cancel): else the live
  180. indicator stays forever and armed interception state leaks into the next turn.
  181. Never sets delivery flags."""
  182. if not self._use_draft_streaming:
  183. return
  184. if getattr(type(self.adapter), "abandon_open_draft", None) is None:
  185. return
  186. try:
  187. await self.adapter.abandon_open_draft(
  188. self.chat_id, self._last_sent_text or self._clean_for_display(self._accumulated),
  189. metadata=self._draft_metadata())
  190. except Exception as e:
  191. logger.debug("abandon_open_draft failed (best-effort): %s", e)
  192. def _has_real_preview(self) -> bool:
  193. """A real (editable, deletable) preview message id is on screen."""
  194. return bool(self._message_id) and self._message_id != "__no_edit__"
  195. def _should_send_fresh_final(self) -> bool:
  196. """True when fresh-final is enabled and a real preview has been visible ≥ threshold.
  197. Ported from openclaw/openclaw#72038.
  198. """
  199. threshold = getattr(self.cfg, "fresh_final_after_seconds", 0.0) or 0.0
  200. if threshold <= 0 or not self._has_real_preview() or self._message_created_ts is None:
  201. return False
  202. return time.monotonic() - self._message_created_ts >= threshold
  203. def _track_preview_id(self, message_id: Optional[str]) -> None:
  204. """Record a real preview message id for finalization cleanup."""
  205. if message_id and message_id != "__no_edit__":
  206. message_id = str(message_id)
  207. self._preview_message_ids.add(message_id)
  208. self._segment_preview_message_ids.add(message_id)
  209. def _track_preview_ids_from_result(self, result: Any) -> None:
  210. """Record the primary id plus any continuation ids from an oversized split."""
  211. raw = getattr(result, "raw_response", None) or {}
  212. raw_ids = raw.get("message_ids") if isinstance(raw, dict) else None
  213. for mid in (getattr(result, "message_id", None),
  214. *(getattr(result, "continuation_message_ids", None) or ()), *(raw_ids or ())):
  215. self._track_preview_id(mid)
  216. def _adapter_prefers_fresh_final(self, text: str) -> bool:
  217. """Adapter's prefers_fresh_final_streaming hook (Telegram's richer send path);
  218. False without a real preview / hook, or on any error."""
  219. fn = getattr(self.adapter, "prefers_fresh_final_streaming", None)
  220. if fn is None or not self._has_real_preview():
  221. return False
  222. try:
  223. try:
  224. # chat_id lets relay adapters decide via THIS chat's platform;
  225. # otherwise a Slack-primary relay misroutes fronted chats through the
  226. # fresh-send lane (duplicates: no delete op).
  227. result = fn(text, metadata=self.metadata, chat_id=self.chat_id)
  228. except TypeError:
  229. try:
  230. result = fn(text, metadata=self.metadata) # single-platform signature
  231. except TypeError:
  232. result = fn(text) # test doubles without the metadata kwarg
  233. except Exception as e:
  234. logger.debug("prefers_fresh_final_streaming check failed: %s", e)
  235. return False
  236. # ``is True`` keeps MagicMock auto-children from enabling fresh-final.
  237. return result is True
  238. async def _try_fresh_final(self, text: str, *, is_turn_final: bool = True) -> bool:
  239. """Send ``text`` fresh and best-effort delete the preview(s); False on any failure so
  240. the caller falls back to edit. ``is_turn_final=False`` leaves the delivery flag unset.
  241. ``is_turn_final`` is False when finalizing an interim segment at a tool boundary (a preamble) rather
  242. than the turn-final answer; the final-delivery flag is then left unset so the gateway still delivers
  243. the real answer from the next API call (#29346).
  244. Ported from openclaw/openclaw#72038.
  245. """
  246. # Replacing every preview is only sound while ``text`` holds the whole answer;
  247. # after a split, deleting sealed heads would erase delivered text.
  248. if self._turn_split_delivery:
  249. return False
  250. stale_ids = self._stale_preview_ids()
  251. try:
  252. result = await self.adapter.send(
  253. chat_id=self.chat_id, content=text, metadata=self._metadata_for_send(final=True))
  254. except Exception as e:
  255. logger.debug("Fresh-final send failed, falling back to edit: %s", e)
  256. return False
  257. if not getattr(result, "success", False):
  258. return False
  259. new_message_id = getattr(result, "message_id", None)
  260. # Best-effort preview cleanup; never delete the message just sent.
  261. await self._delete_previews(stale_ids, skip=new_message_id, label="Fresh-final")
  262. self._preview_message_ids = set()
  263. self._adopt_message_id(new_message_id)
  264. self._already_sent = True
  265. self._last_sent_text = text
  266. if is_turn_final:
  267. self._final_response_sent = True
  268. self._record_turn_final_payload(text)
  269. return True
  270. def _adopt_message_id(self, message_id) -> None:
  271. """Retarget edits at ``message_id``; None → "__no_edit__" sentinel so we never edit it."""
  272. if message_id:
  273. self._message_id = message_id
  274. self._message_created_ts = time.monotonic()
  275. else:
  276. self._message_id = "__no_edit__"
  277. self._message_created_ts = None
  278. @stops_reply_clock
  279. async def _send_or_edit(
  280. self, text: str, *, finalize: bool = False, is_turn_final: bool = True) -> bool:
  281. """Send or edit the streaming message; True if delivered. ``finalize`` marks the
  282. last edit. Transport order: native frame → draft frame → edit existing → first
  283. send; a transport returns None to fall through to the next."""
  284. text = self._clean_for_display(text)
  285. # Stream-is-the-message draft frames must stay prefix-stable: a closing ```
  286. # on a mid-code-block frame makes frame N not a prefix of N+1 and the
  287. # connector re-appends the whole snapshot. The final is still fence-closed.
  288. pre_fence_text = text
  289. text = ensure_closed_code_fences(text)
  290. # A bare cursor renders as a stray tofu box on some clients.
  291. visible_stripped = (text.replace(self.cfg.cursor, "") if self.cfg.cursor else text).strip()
  292. if not visible_stripped:
  293. # Native streams MUST still get a finalize frame (placeholder) to close
  294. # the thinking bubble, e.g. for a MEDIA-only response.
  295. if (finalize and self._use_native_streaming and self._native_stream_opened
  296. and await self._try_frame(self._send_frame("✅", finalize=True),
  297. "Finalize empty stream failed: %s")):
  298. self._mark_final_delivered()
  299. return True # cursor-only / whitespace-only update
  300. # Don't open a new message for 1-2 tokens + cursor (rapid tool-calling): if
  301. # the cursor-strip edit is then rate-limited, "X ▉" stays forever.
  302. # A segment-break finalize never carries the cursor, so gate it too or a 1-2 token
  303. # preamble lands durably at every tool boundary and resets the progress anchor
  304. # (#99026). Turn finals are exempt: a short complete answer must be delivered.
  305. # Tradeoff: on non-cumulative transports the held preamble is DROPPED, not
  306. # carried — _end_segment sees update_visible=True and resets the segment.
  307. preamble_finalize = finalize and not is_turn_final
  308. if (self._message_id is None and len(visible_stripped) < self._MIN_NEW_MSG_CHARS
  309. and (preamble_finalize or (self.cfg.cursor and self.cfg.cursor in text))):
  310. # Mid-stream: accumulate more. Segment-break finalize: dropped (see above).
  311. return True
  312. # A failed native/draft transport disables itself and falls through so the
  313. # accumulated text still reaches the user via edit/send.
  314. if self._use_native_streaming:
  315. ok = await self._native_push(text, finalize=finalize, is_turn_final=is_turn_final)
  316. if ok is not None:
  317. return ok
  318. if self._use_draft_streaming and self._message_id is None:
  319. ok = await self._draft_push(text, pre_fence_text, finalize=finalize,
  320. is_turn_final=is_turn_final)
  321. if ok is not None:
  322. return ok
  323. self._last_edit_overflowed = False
  324. try:
  325. if self._message_id is None:
  326. if not self._edit_supported and not finalize:
  327. # A failed send disabled edits: a preview sent now could never be updated and
  328. # would stay on screen truncated next to the final reply. Send only the final.
  329. return False
  330. return await self._first_send(text, finalize=finalize)
  331. if not self._edit_supported:
  332. return False # edits unsupported; fallback path sends the final
  333. return await self._edit_existing(text, finalize=finalize, is_turn_final=is_turn_final)
  334. except Exception as e:
  335. logger.error("Stream send/edit error: %s", e)
  336. return False
  337. async def _native_push(self, text: str, *, finalize: bool, is_turn_final: bool,
  338. ) -> Optional[bool]:
  339. """Native streaming: every frame goes through send_stream_frame(); lazy re-seed after
  340. a boundary. None when native was disabled (seed/frame failure) → caller falls through."""
  341. if not self._native_stream_opened and text:
  342. if not await self._try_seed_frame("Re-seed failed, disabling native streaming: %s"):
  343. self._use_native_streaming = False
  344. return None
  345. self._native_stream_opened = True
  346. self._awaiting_reopen_after_boundary = False
  347. # Paired with the boundary-finalize INFO: typing-reappear latency.
  348. logger.info("[latency] Re-opened native stream after boundary "
  349. "(turn=%s, waited for first delta)", self._turn_id)
  350. # WeCom renders each finalize as a separate bubble: only the turn-final and
  351. # boundaries close the stream, not segment breaks.
  352. finalize = finalize and is_turn_final
  353. if not finalize and text == self._last_sent_text:
  354. return True # unchanged — skip
  355. # Mark a finalize frame delivered OPTIMISTICALLY, before the ack wait: WeCom
  356. # renders the bytes before the ack, so a gateway join-cancel mid-wait must not
  357. # strand final_content_delivered=False and duplicate the send (docs/rca-wecom-
  358. # stream-final-ack-timeout-duplicate.md). A definitive failure rolls it back.
  359. if finalize:
  360. self._mark_final_delivered(record=text) # recorded: stale frame can't suppress
  361. if await self._try_frame(self._send_frame(text, finalize=finalize),
  362. "send_stream_frame raised, disabling native streaming: %s"):
  363. self._already_sent = True
  364. self._last_sent_text = text
  365. self._native_last_pushed_len = len(text)
  366. if finalize:
  367. self._mark_final_delivered()
  368. return True
  369. # Definitive failure: roll back the optimistic mark so the edit/send
  370. # fallback delivers exactly once.
  371. if finalize:
  372. self._final_response_sent = False
  373. self._final_content_delivered = False
  374. self._delivered_final_text = None
  375. # Subsequent frames take the edit/send fallback; the adapter marks the chat
  376. # expired so it doesn't retry the dead stream.
  377. self._use_native_streaming = False
  378. # Best-effort close of an opened bubble (the seed frame has zero length but
  379. # still opens it). DO NOT mark delivered: the frame closes the bubble but
  380. # WeCom may not render the content (errcode 6000 race).
  381. if self._native_stream_opened:
  382. try:
  383. await self._send_frame(text, finalize=True)
  384. logger.debug("Native fallback: finalized stream (best-effort close)")
  385. except Exception as e:
  386. logger.debug("Native fallback: failed to finalize stream: %s", e)
  387. return None
  388. async def _draft_push(self, text: str, pre_fence_text: str, *, finalize: bool,
  389. is_turn_final: bool) -> Optional[bool]:
  390. """Draft frame while no message_id exists; None = not applicable / drafts just failed.
  391. Skipped when finalizing (the real send clears the draft), EXCEPT stream-is-the-message
  392. adapters keep ONE stream per turn: a segment-break finalize must not become a real
  393. send (it would seal at every tool boundary)."""
  394. stream_is_msg = self._stream_is_message()
  395. if finalize and not (stream_is_msg and not is_turn_final):
  396. return None
  397. frame_text = pre_fence_text if stream_is_msg else text
  398. # Strip the cursor: native streams render their own indicator, and
  399. # "...text▉" is never a prefix of "...text more▉", which forces the
  400. # connector's whole-text re-append on EVERY tick (stacked copies).
  401. if self.cfg.cursor and frame_text.endswith(self.cfg.cursor):
  402. frame_text = frame_text[: -len(self.cfg.cursor)]
  403. if frame_text == self._last_sent_text:
  404. return True
  405. # Deliberately NOT _already_sent on success: the gateway's fallback final
  406. # send must still fire so the user gets a real message.
  407. return True if await self._send_draft_frame(frame_text) else None
  408. async def _first_send(self, text: str, *, finalize: bool) -> bool:
  409. """First send, threaded to the user's message (correct topic/thread)."""
  410. if getattr(self, "_egress_declined", False):
  411. # The connector refused this destination earlier in the run (see
  412. # _send_draft_frame). This is where every fallback path converges,
  413. # so the check belongs here rather than at each caller.
  414. logger.warning(
  415. "suppressing the plain-send fallback: the connector already "
  416. "declined this destination for this run"
  417. )
  418. return False
  419. result = await self.adapter.send(
  420. chat_id=self.chat_id, content=text, reply_to=self._initial_reply_to_id,
  421. metadata=self._metadata_for_send(final=finalize, expect_edits=not finalize))
  422. if not result.success:
  423. self._edit_supported = False
  424. return False
  425. self._already_sent = True
  426. self._last_sent_text = text
  427. if result.message_id:
  428. self._adopt_message_id(result.message_id)
  429. self._track_preview_ids_from_result(result)
  430. else:
  431. # No editable id: fallback mode + sentinel so we don't re-enter first-send.
  432. self._enter_fallback_mode(self._visible_prefix())
  433. self._message_id = "__no_edit__"
  434. self._notify_new_message()
  435. return True
  436. async def _edit_existing(self, text: str, *, finalize: bool, is_turn_final: bool) -> bool:
  437. """Edit the live preview (or replace it via fresh-final when finalizing)."""
  438. # REQUIRES_EDIT_FINALIZE adapters need the finalize=True edit even when
  439. # unchanged; everyone else short-circuits.
  440. if text == self._last_sent_text and not (finalize and self._adapter_requires_finalize):
  441. return True
  442. # Fresh-final: replace a long-lived preview with a fresh message, or whenever
  443. # the adapter prefers it (Telegram's send path renders richer markdown). An
  444. # explicit hook returning False must NOT be overridden by the time threshold
  445. # (delete is best-effort; both messages would stay on screen). Check the
  446. # CLASS (MagicMock auto-creates attrs) plus instance __dict__ (test doubles).
  447. has_prefers_hook = (
  448. hasattr(type(self.adapter), "prefers_fresh_final_streaming")
  449. or "prefers_fresh_final_streaming" in getattr(self.adapter, "__dict__", {}))
  450. prefers_fresh = self._adapter_prefers_fresh_final(text) # probed every edit (hook contract)
  451. if finalize and (
  452. prefers_fresh or (not has_prefers_hook and self._should_send_fresh_final())
  453. ) and await self._try_fresh_final(text, is_turn_final=is_turn_final):
  454. return True
  455. result = await self._edit_message(message_id=self._message_id, content=text,
  456. finalize=finalize)
  457. if not result.success:
  458. return await self._on_edit_failure(result, text, finalize=finalize,
  459. is_turn_final=is_turn_final)
  460. raw_response = getattr(result, "raw_response", None)
  461. if isinstance(raw_response, dict) and raw_response.get("skipped"):
  462. # Adapter deferred the edit (Telegram's shared send+edit slot was busy): nothing
  463. # changed on screen, so the visible prefix and flood state stay as they were and the
  464. # next tick retries with the newer text.
  465. return True
  466. self._already_sent = True
  467. self._track_preview_ids_from_result(result)
  468. # Oversized edit split across continuations: message_id is now the LAST
  469. # continuation, which holds only the final chunk — retarget edits and reset
  470. # skip-if-same. getattr keeps SimpleNamespace test mocks working.
  471. if ((getattr(result, "continuation_message_ids", ()) or ())
  472. and result.message_id and result.message_id != self._message_id):
  473. self._last_edit_overflowed = True
  474. self._turn_split_delivery = True
  475. self._adopt_message_id(str(result.message_id))
  476. self._last_sent_text = ""
  477. self._notify_new_message()
  478. else:
  479. self._last_sent_text = text
  480. self._flood_strikes = 0
  481. return True
  482. def _enter_fallback_mode(self, prefix: str) -> None:
  483. """Edits are over for this stream: send only the missing tail at got_done."""
  484. self._fallback_prefix = prefix
  485. self._fallback_final_send = True
  486. self._edit_supported = False
  487. self._already_sent = True
  488. async def _on_edit_failure(self, result, text: str, *, finalize: bool, is_turn_final: bool,
  489. ) -> bool:
  490. """Classify a failed edit: partial overflow, flood backoff, or fallback mode. Always
  491. False; the caller's finalize path may still deliver the tail."""
  492. # P5(b): an AUTHORIZATION decline is terminal for the run. Every branch
  493. # below treats a failed edit as "editing is unavailable" and hands the
  494. # unseen tail to the fallback, which SENDS it as a new message to the
  495. # chat the connector just refused. Measured: ops were
  496. # ['edit', 'edit', 'send'].
  497. from gateway.relay.egress import declined_send
  498. if declined_send(result):
  499. logger.warning(
  500. "edit DECLINED by the connector's egress guard; suppressing "
  501. "every later send for this run (the destination is not "
  502. "approved for this connection)"
  503. )
  504. self._egress_declined = True
  505. self._edit_supported = False
  506. return False
  507. turn_final = finalize and is_turn_final
  508. if (turn_final and self.cfg.cursor and self._last_sent_text.endswith(self.cfg.cursor)
  509. and self._visible_prefix() == text):
  510. # Cosmetic final edit was rate-limited but the full answer is already on
  511. # screen (cursor stuck): mark delivered so the gateway doesn't send it
  512. # twice, and record the on-screen payload.
  513. self._final_content_delivered = True
  514. self._record_turn_final_payload(text)
  515. # ``text`` is already cleaned/fence-closed here and equals the visible prefix — the on-screen
  516. # content IS this finalize payload (#71643). Record it on split turns too: post-#78541 an unrecorded
  517. # split reads as a mismatch and would re-send this already-visible answer, reintroducing the
  518. # duplicate #45517 fixed (#36965 / #25349).
  519. raw_response = getattr(result, "raw_response", None)
  520. if isinstance(raw_response, dict) and raw_response.get("partial_overflow"):
  521. # Some overflow chunks landed but not the whole response: preserve the
  522. # visible prefix so got_done sends the missing tail.
  523. self._message_id = str(raw_response.get("last_message_id") or result.message_id
  524. or self._message_id)
  525. delivered_prefix = raw_response.get("delivered_prefix")
  526. if isinstance(delivered_prefix, str) and delivered_prefix:
  527. self._last_sent_text = delivered_prefix
  528. self._fallback_preserve_partial_messages = text.startswith(delivered_prefix)
  529. self._enter_fallback_mode(delivered_prefix)
  530. else:
  531. self._fallback_preserve_partial_messages = False
  532. self._enter_fallback_mode(self._visible_prefix())
  533. if getattr(result, "continuation_message_ids", ()):
  534. self._notify_new_message()
  535. return False
  536. # Flood control: adaptive backoff (double the interval, or the server's own
  537. # retry_after when Telegram hands one back — the penalty is usually 9s+, so
  538. # doubling 0.8s → 1.6s → 3.2s burns all strikes inside it); disable edits only
  539. # after _MAX_FLOOD_STRIKES in a row.
  540. immediate_final_fallback = False
  541. if self._is_flood_error(result):
  542. self._flood_strikes += 1
  543. backoff = min(self._current_edit_interval * 2, 10.0)
  544. retry_after = getattr(result, "retry_after", None)
  545. if isinstance(retry_after, (int, float)) and retry_after > 0:
  546. backoff = max(backoff, min(float(retry_after), _MAX_EDIT_BACKOFF_SECS))
  547. self._current_edit_interval = backoff
  548. logger.debug("Flood control on edit (strike %d/%d), backoff interval → %.1fs",
  549. self._flood_strikes, self._MAX_FLOOD_STRIKES, self._current_edit_interval)
  550. immediate_final_fallback = (
  551. turn_final and getattr(self.adapter, "FALLBACK_ON_FINAL_EDIT_FLOOD", False) is True)
  552. if self._flood_strikes < self._MAX_FLOOD_STRIKES and not immediate_final_fallback:
  553. self._last_edit_time = time.monotonic() # honor the new interval
  554. return False
  555. if immediate_final_fallback:
  556. logger.debug("Turn-final edit hit flood control; entering fallback immediately")
  557. logger.debug("Edit failed (strikes=%d), entering fallback mode", self._flood_strikes)
  558. self._enter_fallback_mode(self._visible_prefix())
  559. # A turn-final flood skips the cosmetic cursor strip: it would burn the same
  560. # flood budget and delay the answer.
  561. if not immediate_final_fallback:
  562. await self._try_strip_cursor()
  563. return False