stream_consumer.py 57 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038
  1. """Gateway streaming consumer — bridges sync agent callbacks to async platform delivery.
  2. on_delta() queues deltas from the agent's worker thread; the async run() task buffers,
  3. rate-limits and progressively edits one platform message (send, then editMessageText;
  4. draft/native transports are optional per adapter).
  5. Credit: jobless0x (#774, #1312), OutThisLife (#798), clicksingh (#697).
  6. """
  7. from __future__ import annotations
  8. import asyncio
  9. import concurrent.futures
  10. import contextlib
  11. import inspect
  12. import logging
  13. import queue
  14. import secrets
  15. import threading
  16. import time
  17. import uuid
  18. from dataclasses import dataclass
  19. from typing import Any, Callable, Optional
  20. from gateway.platforms.base import BasePlatformAdapter as _BasePlatformAdapter
  21. from gateway.platforms.base import _custom_unit_to_cp
  22. from gateway.config import (
  23. DEFAULT_STREAMING_EDIT_INTERVAL as _DEFAULT_STREAMING_EDIT_INTERVAL,
  24. DEFAULT_STREAMING_BUFFER_THRESHOLD as _DEFAULT_STREAMING_BUFFER_THRESHOLD,
  25. DEFAULT_STREAMING_CURSOR as _DEFAULT_STREAMING_CURSOR)
  26. from gateway.response_filters import (
  27. is_intentional_silence_response as _is_intentional_silence_response,
  28. is_partial_silence_marker as _is_partial_silence_marker,
  29. ends_with_partial_silence_marker as _ends_with_partial_silence_marker,
  30. strip_trailing_silence_marker as _strip_trailing_silence_marker)
  31. from gateway.stream_consumer_directives import has_pending_media_directive, strip_image_tags_for_display
  32. from gateway.stream_consumer_fences import ensure_closed_code_fences
  33. from gateway.stream_consumer_transport import StreamTransportMixin
  34. from gateway.stream_consumer_fallback import StreamFallbackMixin
  35. from gateway.stream_consumer_think import StreamThinkFilterMixin
  36. logger = logging.getLogger("gateway.stream_consumer")
  37. # Queue sentinels (see _drain_queue()). Bare: _DONE, _NEW_SEGMENT (finalize, start a
  38. # fresh message), _REOPEN_SEED (EAGER native re-seed after a clarify answer — WeCom
  39. # typing is driven by the seed frame; lazy re-seed measured 48s of dead air). Tuples:
  40. # (_COMMENTARY, text); (_TOOL_PROGRESS, line) native-bubble overlay; (_FINAL_TEXT, text)
  41. # authoritative final_response incl. post-stream augmentation, queued just before _DONE;
  42. # (_FLUSH, threading.Event) barrier; (_APPROVAL_BOUNDARY, future, cancelled_flag).
  43. _DONE = object()
  44. _NEW_SEGMENT = object()
  45. _COMMENTARY = object()
  46. _TOOL_PROGRESS = object()
  47. _FINAL_TEXT = object()
  48. _FLUSH = object()
  49. _APPROVAL_BOUNDARY = object()
  50. _REOPEN_SEED = object()
  51. _FUTURE_TYPES = (asyncio.Future, concurrent.futures.Future)
  52. # Boundary finalize text when nothing has accumulated yet (overridable per boundary).
  53. _DEFAULT_BOUNDARY_PLACEHOLDER = "⏸ 等待审批中..."
  54. @dataclass
  55. class StreamConsumerConfig:
  56. """Runtime config for a single stream consumer instance."""
  57. edit_interval: float = _DEFAULT_STREAMING_EDIT_INTERVAL
  58. buffer_threshold: int = _DEFAULT_STREAMING_BUFFER_THRESHOLD
  59. cursor: str = _DEFAULT_STREAMING_CURSOR
  60. buffer_only: bool = False
  61. # >0: final goes out as a fresh message once the preview has been visible this
  62. # long (timestamp reflects completion); 0 = always edit in place.
  63. # This makes the platform's visible timestamp reflect completion time instead of first-token time for
  64. # long-running responses (e.g. reasoning models that stream slowly). Ported from
  65. # openclaw/openclaw#72038. The gateway enables this selectively per-platform.
  66. fresh_final_after_seconds: float = 0.0
  67. # "auto"/"draft": native drafts when adapter+chat support it, else "edit"
  68. # (progressive editMessageText). "off" is handled by the gateway.
  69. transport: str = "edit"
  70. chat_type: str = "" # originating chat type; gates platform-specific drafts
  71. @dataclass
  72. class _Tick:
  73. """Everything one drain of the queue decided."""
  74. got_done: bool = False
  75. got_segment_break: bool = False
  76. got_flush: bool = False
  77. flush_event: Any = None
  78. got_reopen_seed: bool = False
  79. approval_boundary: Optional[tuple] = None # (future, cancelled_flag)
  80. commentary_text: Optional[str] = None
  81. # Set by _push_update for _finalize_turn / _end_segment.
  82. update_visible: bool = False
  83. draft_final_fresh_send: bool = False
  84. @property
  85. def is_interim(self) -> bool:
  86. """Mid-stream tick: not finalizing, not a segment break, no commentary."""
  87. return not self.got_done and not self.got_segment_break and self.commentary_text is None
  88. class GatewayStreamConsumer(StreamTransportMixin, StreamFallbackMixin, StreamThinkFilterMixin):
  89. """Async consumer that progressively edits a platform message with streamed tokens.
  90. Usage: ``agent.stream_delta_callback = consumer.on_delta``; ``create_task(consumer.run())``;
  91. after the agent finishes ``consumer.finish()`` then ``await task`` for the final edit."""
  92. _MAX_FLOOD_STRIKES = 3 # consecutive flood failures before edits are disabled
  93. # Class-wide monotonic draft-id counter (Telegram animates a draft only when the
  94. # same non-zero draft_id is reused). RANDOM seed: draft_id keys the relay
  95. # connector's sealed-stream tombstones, which outlive this process — a replayed id
  96. # is answered out of the OLD tombstone and dropped. 49 bits stays inside JS 2^53.
  97. _draft_id_counter: int = secrets.randbits(49)
  98. def __init__(
  99. self,
  100. adapter: Any,
  101. chat_id: str,
  102. config: Optional[StreamConsumerConfig] = None,
  103. metadata: Optional[dict] = None,
  104. on_new_message: Optional[callable] = None,
  105. on_before_finalize: Optional[Callable[[], Any]] = None,
  106. initial_reply_to_id: Optional[str] = None,
  107. run_still_current: Optional[Callable[[], bool]] = None):
  108. self.adapter = adapter
  109. self.chat_id = chat_id
  110. self.cfg = config or StreamConsumerConfig()
  111. self.metadata = metadata
  112. # Hooks (exceptions swallowed): on_new_message per fresh content bubble (next
  113. # tool-progress bubble goes BELOW it); on_before_finalize once (pause typing).
  114. self._on_new_message = on_new_message
  115. self._on_before_finalize = on_before_finalize
  116. self._initial_reply_to_id = initial_reply_to_id
  117. self._turn_id = str(uuid.uuid4()) # keys send_stream_frame() per concurrent consumer
  118. # Returns False after /new or /stop; run() then abandons the stream.
  119. self._run_still_current = run_still_current or (lambda: True)
  120. # Whether this consumer is fed the final reply's stream deltas. A consumer built only to
  121. # relay interim commentary (text streaming off, ``display.interim_assistant_messages`` on)
  122. # never receives the final's deltas, so the duplicate-risk diagnostic in
  123. # ``_run_agent_mark_streamed_delivery`` must not fire for it (#105341). Default True: every
  124. # other construction site (incl. the proxy path) creates consumers only when streaming is on.
  125. self.stream_deltas_enabled = True
  126. # Only platforms needing an explicit finalize call (DingTalk AI Cards) force a
  127. # redundant final edit; ``is True`` keeps MagicMock adapters out.
  128. self._adapter_requires_finalize = getattr(adapter, "REQUIRES_EDIT_FINALIZE", False) is True
  129. # Telegram bounds edit retries at 5s; a fallback must not wait longer.
  130. self._max_fallback_flood_retry_seconds = 5.0
  131. self._queue: queue.Queue = queue.Queue()
  132. # Every real preview id on screen this response (fresh-final deletes them all);
  133. # the per-segment set holds only the active segment so failure recovery never
  134. # deletes an earlier finalized preamble/commentary.
  135. # Wall-clock timestamp (time.monotonic) when ``_message_id`` was first assigned from a successful
  136. # first-send. Used by the fresh-final logic to detect long-lived previews whose edit timestamps
  137. # would be stale by completion time. Ported from openclaw/openclaw#72038.
  138. self._preview_message_ids: set[str] = set()
  139. self._already_sent = False
  140. self._edit_supported = True # False once progressive edits stop working
  141. self._last_edit_time = 0.0
  142. self._last_edit_overflowed = False # last _send_or_edit split into continuations
  143. self._flood_strikes = 0
  144. self._current_edit_interval = self.cfg.edit_interval # adaptive backoff
  145. self._delivered_commentary_texts: list[str] = []
  146. self._delivered_segment_texts: list[str] = [] # finalized text per past segment
  147. self._last_segment_delivery: Optional[tuple[str, Optional[float], str, set[str]]] = None
  148. self._superseded_reply_ids: set[str] = set()
  149. self._in_think_block = False # think-tag filter state (mirrors CLI _stream_delta)
  150. self._think_buffer = ""
  151. self._before_finalize_notified = False
  152. self._reset_message_state()
  153. # Transports, resolved in run(). Draft: animated frames via adapter.send_draft;
  154. # the final still uses first-send; the first failure disables drafts. Native
  155. # (WeCom msgtype "stream"): the ONLY channel — any failure falls back to edit/send.
  156. self._use_draft_streaming = False
  157. self._draft_id: Optional[int] = None
  158. self._draft_failures = 0
  159. # TERMINAL authorization refusal for THIS RUN (see _send_draft_frame).
  160. # Per-run state, constructed fresh each turn, so a refusal can never
  161. # mute a healthy destination on a later turn.
  162. self._egress_declined = False
  163. self._use_native_streaming = False
  164. self._native_stream_opened = False # seed sent: bubble open, zero content
  165. self._native_last_pushed_len = 0 # throttle under WeCom's 30 frames/min
  166. # Boundary state from close_for_approval_prompt() (boundaries are processed
  167. # serially). reopen=True (clarify) keeps native enabled so post-prompt output
  168. # re-opens a fresh stream; approval degrades to send().
  169. self._boundary_placeholder = _DEFAULT_BOUNDARY_PLACEHOLDER
  170. self._boundary_reason = "Approval"
  171. self._boundary_reopen = False
  172. # Reopen requested but nothing re-seeded: got_done must not open a stream just
  173. # to emit a lone "✅"; an EAGER re-seed opened a bubble that got_done MUST close.
  174. self._awaiting_reopen_after_boundary = False
  175. self._reopen_seeded_eagerly = False
  176. def _reset_message_state(self) -> None:
  177. """Per-message (segment) state: fresh at construction and after each segment break."""
  178. self._message_id: Optional[str] = None
  179. self._message_created_ts: Optional[float] = None # fresh-final age
  180. # ``_stream_ledger`` mirrors ``_accumulated`` but is NOT truncated when
  181. # overflow splits seal head chunks (reconcilable turn-final payload).
  182. self._accumulated = self._stream_ledger = ""
  183. self._last_sent_text = "" # skip redundant edits
  184. self._fallback_final_send = False
  185. self._fallback_prefix = ""
  186. # Fallback sends only the missing tail after a partial overflow delivery.
  187. self._fallback_preserve_partial_messages = False
  188. self._segment_preview_message_ids: set[str] = set()
  189. # Tool-progress overlay (native only): shown in the bubble until text arrives.
  190. self._tool_progress_lines: list[str] = []
  191. self._tool_progress_active: bool = False
  192. self._clear_turn_final_flags()
  193. def _clear_turn_final_flags(self) -> None:
  194. """Reset every turn-final delivery flag to "nothing delivered yet".
  195. ``_delivered_final_text`` is the cleaned turn-final payload the gateway compares to
  196. the completed final_response before trusting the flags (a successful finalize edit
  197. may carry a stale preview); None = legacy trust. A payload-less
  198. ``_turn_split_delivery`` must NOT inherit legacy trust; ``_delivery_ambiguous`` (a
  199. full-final send timed out but MAY have landed) is the only case that does."""
  200. # #29346: a tool/segment boundary means what we delivered was an interim preamble, not the final
  201. # answer — clear the flags so a premature setter can't fool the gateway. Safe: got_done returns
  202. # before any reset, and run.py reads these only after the consumer task exits.
  203. self._final_response_sent = False
  204. self._final_content_delivered = False # content landed even if the cosmetic edit failed
  205. self._delivered_final_text: Optional[str] = None
  206. self._turn_split_delivery = False
  207. # True when a full-final send timed out in a way that MAY have reached the platform
  208. # (``_send_empty_fallback_final`` → "ambiguous"). The only case where a payload-less delivery flag
  209. # keeps legacy trust in ``delivered_final_matches`` (#95382 tightening) — re-sending there risks a
  210. # duplicate rather than recovering a loss.
  211. self._delivery_ambiguous = False
  212. def _stream_is_message(self) -> bool:
  213. """Whether THIS chat's transport treats the stream as the message: per-chat probe
  214. first (a relay adapter's class attribute only reflects its primary identity), else
  215. the legacy attribute; both on the CLASS (MagicMock-safe)."""
  216. probe = getattr(type(self.adapter), "stream_is_message_for_chat", None)
  217. if not callable(probe):
  218. return getattr(self.adapter, "draft_stream_is_message", False) is True
  219. try:
  220. return probe(self.adapter, str(self.chat_id)) is True
  221. except Exception:
  222. return False
  223. @property
  224. def accepts_tool_progress(self) -> bool:
  225. """True only when native streaming is active (gates in-stream tool progress)."""
  226. return self._use_native_streaming
  227. def on_tool_progress(self, line: str) -> None:
  228. """Thread-safe: overlay a tool-progress line in the native bubble until the next delta."""
  229. if line:
  230. self._queue.put((_TOOL_PROGRESS, line))
  231. def _compose_frame_content(self) -> str:
  232. """Native frame content: text, with any tool-progress lines below a rule."""
  233. progress = "\n".join(self._tool_progress_lines)
  234. return "\n\n---\n".join(p for p in (self._accumulated, progress) if p)
  235. def _metadata_for_send(self, *, final: bool = False, expect_edits: bool = False) -> dict | None:
  236. """Per-send metadata. ``final`` → notify=True (Mattermost treats notify-worthy sends
  237. as final when a broken thread root may fall back flat); ``expect_edits`` keeps
  238. editable previews on Telegram's legacy send path."""
  239. meta = dict(self.metadata) if self.metadata else {}
  240. if self._initial_reply_to_id:
  241. meta["reply_to_message_id"] = self._initial_reply_to_id
  242. if expect_edits:
  243. meta["expect_edits"] = True
  244. if final:
  245. meta["notify"] = True
  246. return meta or None
  247. # Read-only views for the gateway (flag semantics: see _clear_turn_final_flags).
  248. already_sent = property(lambda self: self._already_sent)
  249. final_response_sent = property(lambda self: self._final_response_sent)
  250. message_id = property(lambda self: self._message_id)
  251. final_content_delivered = property(lambda self: self._final_content_delivered)
  252. async def _notify_before_finalize(self) -> None:
  253. """Run the pre-finalize hook exactly once, swallowing hook errors."""
  254. if self._before_finalize_notified:
  255. return
  256. self._before_finalize_notified = True
  257. if self._on_before_finalize is not None:
  258. with contextlib.suppress(Exception):
  259. result = self._on_before_finalize()
  260. if inspect.isawaitable(result):
  261. await result
  262. def _append_accumulated(self, text: str) -> None:
  263. """Append to the live buffer and the split-stable stream ledger."""
  264. if not text:
  265. return
  266. if self._tool_progress_lines: # real text overwrites the overlay
  267. self._tool_progress_lines.clear()
  268. self._tool_progress_active = False
  269. self._accumulated += text
  270. self._stream_ledger += text
  271. def _mark_skip_redundant_finalize(self) -> None:
  272. """Mark the turn final as delivered by a prior mid-stream edit. Records what was
  273. ACKED on the wire, not ``_accumulated``: a throttled stream's last ack may be an
  274. older cursor-suffixed preview, which must not suppress the corrective send."""
  275. acked = self._last_sent_text or self._accumulated
  276. if self.cfg.cursor and acked.endswith(self.cfg.cursor):
  277. acked = acked[: -len(self.cfg.cursor)]
  278. self._mark_final_delivered(record=acked)
  279. def _mark_final_delivered(self, record: Optional[str] = None) -> None:
  280. """Set both turn-final flags; ``record`` also records the delivered payload."""
  281. self._final_response_sent = True
  282. # Only claim final delivery if the sealed chunks and final tail actually landed. ``_already_sent``
  283. # may be True from prior progress/fallback state (#10748).
  284. # The final clean-up edit failed, but the complete answer is already visible from the last streaming
  285. # frame (usually with only the cursor still stuck on screen). Mark the content delivered so the
  286. # gateway suppresses its normal full final send; otherwise users see the same long answer twice when
  287. # Telegram/Discord rate-limit this cosmetic final edit (#36965, #25349).
  288. self._final_content_delivered = True
  289. if record is not None:
  290. self._record_turn_final_payload(record)
  291. def _display_payload(self, text: str) -> str:
  292. """Normalize like ``_send_or_edit`` output: directive strip + fence close + strip."""
  293. return ensure_closed_code_fences(self._clean_for_display(text or "")).strip()
  294. def _record_turn_final_payload(self, text: str) -> None:
  295. """Record what the user actually saw as this turn's final answer. On a split ``text``
  296. is only the trailing chunk, so the un-truncated ``_stream_ledger`` is recorded — else
  297. the gateway sees a mismatch and re-sends an answer the user already received."""
  298. if self._turn_split_delivery and self._stream_ledger:
  299. text = self._stream_ledger
  300. self._delivered_final_text = self._display_payload(text)
  301. def delivered_final_matches(self, final_text: str) -> Optional[bool]:
  302. """Tri-state reconcile of the recorded turn-final payload against ``final_text`` (a
  303. *successful* finalize edit can still carry a stale preview, so call success alone
  304. must not confirm delivery). True: recorded payload (or an earlier segment /
  305. commentary) matches. False: payload differs, or payload-less split. None: nothing
  306. recorded on a legacy/ambiguous path (caller trusts flags)."""
  307. target = self._display_payload(final_text)
  308. if not target:
  309. return None
  310. if self._delivered_final_text is not None:
  311. # A segment break / commentary may have delivered it under another record.
  312. return (self._delivered_final_text.strip() == target
  313. or self.has_delivered_text(final_text))
  314. if self._turn_split_delivery:
  315. return False
  316. # No recorded payload: judge against the FINAL content, not the flag.
  317. # ``_already_sent`` gates the match: draft frames set ``_last_sent_text`` but
  318. # deliberately not ``_already_sent``.
  319. # #95382 / #98552 class fix: a delivery flag with NO recorded payload must still be judged against
  320. # the FINAL content, not trusted blindly. Every internal flag-setting site records a payload; a
  321. # record-less consumer whose visible/streamed text does not contain the completed response has
  322. # demonstrably NOT delivered it (first-edit prefix, mid-stream truncation) — the flag alone must not
  323. # suppress the corrective send. ``_already_sent`` gates the visible-text match: draft frames set
  324. # ``_last_sent_text`` for dedupe but are ephemeral (they deliberately do not set ``_already_sent``),
  325. # so draft-only visibility must not count as durable delivery.
  326. if self._already_sent and self.has_delivered_text(final_text):
  327. return True
  328. # Only a timed-out full-final send that MAY have landed keeps legacy trust.
  329. return None if self._delivery_ambiguous else False
  330. def has_delivered_text(self, text: str) -> bool:
  331. """Return True if *text* was already delivered as visible chat content."""
  332. target = self._clean_for_display(text or "").strip()
  333. seen = (self._visible_prefix(), *self._delivered_commentary_texts,
  334. *self._delivered_segment_texts)
  335. return bool(target) and any(sent.strip() == target for sent in seen)
  336. def has_durably_delivered_text(self, text: str) -> bool:
  337. """``has_delivered_text`` restricted to deliveries that outlive the turn: commentary and
  338. finalized segments always count; the visible prefix only once ``_already_sent`` (a draft frame
  339. sets ``_last_sent_text`` but is ephemeral — a failed finalize send after it must still fall
  340. back to the gateway's real final send, same gate as ``delivered_final_matches``)."""
  341. target = self._clean_for_display(text or "").strip()
  342. seen = [*self._delivered_commentary_texts, *self._delivered_segment_texts]
  343. if self._already_sent:
  344. seen.append(self._visible_prefix())
  345. return bool(target) and any(sent.strip() == target for sent in seen)
  346. def on_segment_break(self) -> None:
  347. """Finalize the current stream segment and start a fresh message."""
  348. self._queue.put(_NEW_SEGMENT)
  349. def close_for_approval_prompt(
  350. self, placeholder: str | None = None, reason: str = "Approval", reopen: bool = False,
  351. ) -> asyncio.Future:
  352. """Queue an interaction boundary (approval / clarify prompt) from sync context.
  353. run() finalizes the current native stream (``placeholder`` when empty), then per
  354. ``reopen``: False (approval; unbounded waits) degrades to one send() at got_done;
  355. True (clarify) keeps native enabled so post-prompt output re-opens a fresh stream.
  356. Returns (Future, cancelled_flag); the Future resolves True once processed
  357. (cancelled_flag is legacy, no longer read). Without native streaming returns a
  358. bare, already-resolved Future."""
  359. loop = None
  360. with contextlib.suppress(RuntimeError):
  361. loop = asyncio.get_running_loop()
  362. boundary_future = loop.create_future() if loop else concurrent.futures.Future()
  363. if not self._use_native_streaming:
  364. boundary_future.set_result(True)
  365. return boundary_future
  366. # Instance attributes are race-free: boundaries are processed one at a time.
  367. self._boundary_placeholder = placeholder or _DEFAULT_BOUNDARY_PLACEHOLDER
  368. self._boundary_reason = reason or "Approval"
  369. self._boundary_reopen = bool(reopen)
  370. cancelled_flag = {"cancelled": False}
  371. self._queue.put((_APPROVAL_BOUNDARY, boundary_future, cancelled_flag))
  372. return boundary_future, cancelled_flag
  373. def on_commentary(self, text: str) -> None:
  374. """Queue a completed interim assistant commentary message."""
  375. if text:
  376. self._queue.put((_COMMENTARY, text))
  377. def flush_pending_sync(self, timeout: float = 5.0) -> bool:
  378. """Block the agent worker thread until everything queued so far is delivered:
  379. ``(_FLUSH, Event)`` barrier — run() drains earlier items (FIFO), finalizes the
  380. segment, sets the event. False on timeout (consumer task may not be running)."""
  381. evt = threading.Event()
  382. try:
  383. self._queue.put((_FLUSH, evt))
  384. except Exception:
  385. return False
  386. return evt.wait(timeout=max(0.0, float(timeout)))
  387. def _reopen_seed_pending(self) -> bool:
  388. """Native stream, reopen requested after a boundary, nothing open yet."""
  389. return (self._use_native_streaming and self._awaiting_reopen_after_boundary
  390. and not self._native_stream_opened)
  391. def request_reopen_seed(self) -> None:
  392. """Thread-safe: request an EAGER native re-seed after a clarify answer. No-op unless
  393. reopen-pending, so a stray call can't open a spurious bubble mid-stream or on approval."""
  394. if self._reopen_seed_pending():
  395. self._queue.put(_REOPEN_SEED)
  396. def _notify_new_message(self) -> None:
  397. """Fire the on_new_message callback, swallowing any errors."""
  398. try:
  399. if self._on_new_message is not None:
  400. self._on_new_message()
  401. except Exception:
  402. logger.debug("on_new_message callback error", exc_info=True)
  403. @staticmethod
  404. def _signal_flush(flush_event) -> None:
  405. """Wake a thread blocked in flush_pending_sync(), swallowing errors. Every loop path
  406. that consumed a ``_FLUSH`` barrier (incl. early ``continue``) must call this; a
  407. missed set stalls the caller for the full timeout."""
  408. if flush_event is not None:
  409. with contextlib.suppress(Exception):
  410. flush_event.set()
  411. def _reset_segment_state(self, *, preserve_no_edit: bool = False) -> None:
  412. if preserve_no_edit and self._message_id == "__no_edit__":
  413. return
  414. # Retain the segment's visible text so has_delivered_text still matches.
  415. finalized = self._clean_for_display(self._last_sent_text).strip()
  416. if finalized:
  417. self._delivered_segment_texts.append(finalized)
  418. self._last_segment_delivery = None
  419. if self._message_id and self._message_id != "__no_edit__":
  420. self._last_segment_delivery = (
  421. self._message_id, self._message_created_ts, self._last_sent_text,
  422. self._stale_preview_ids(segment_only=True),
  423. )
  424. # Also clears the final flags: what we delivered was an interim preamble. Safe:
  425. # got_done returns before any reset; run.py reads flags after the task exits.
  426. self._reset_message_state()
  427. # Telegram-shaped drafts: bump draft_id so the next segment animates as a fresh
  428. # preview below the tool-progress bubbles. Stream-is-the-message adapters keep
  429. # ONE stream per turn — a bump there left one frozen message per segment.
  430. if self._use_draft_streaming and not self._stream_is_message():
  431. self._bump_draft_id()
  432. def _bump_draft_id(self) -> None:
  433. type(self)._draft_id_counter += 1
  434. self._draft_id = type(self)._draft_id_counter
  435. async def _handle_approval_boundary(self, boundary_future, cancelled_flag=None) -> None:
  436. """Serially process an interaction boundary dequeued by run(). The stream is never
  437. kept open across a prompt: the WeCom finalize ack only confirms server receipt, and
  438. after a long idle gap the client may stop tracking the stream."""
  439. _reason = self._boundary_reason or "Approval"
  440. try:
  441. boundary_ok = True
  442. if self._native_stream_opened:
  443. boundary_ok = await self._finalize_boundary_stream(_reason)
  444. if self._boundary_reopen:
  445. # Clarify: keep native enabled (NOT buffer_only); the closed stream
  446. # makes the next post-prompt delta re-open via the lazy re-seed. The
  447. # gap to the "Re-opened native stream" INFO is the typing latency.
  448. self._close_native_state()
  449. self._awaiting_reopen_after_boundary = True
  450. else:
  451. # Approval: post-approval output goes via one send() at got_done.
  452. self._degrade_native_to_buffered_send()
  453. self._reset_segment_state()
  454. if self._boundary_reopen:
  455. logger.info("[latency] Clarify boundary finalized, awaiting first "
  456. "post-answer delta to re-seed (chat=%s, turn=%s)",
  457. self.chat_id, self._turn_id)
  458. except Exception as e:
  459. logger.warning("%s boundary processing failed: %s", _reason, e)
  460. boundary_ok = False
  461. finally:
  462. with contextlib.suppress(Exception):
  463. if isinstance(boundary_future, _FUTURE_TYPES) and not boundary_future.done():
  464. boundary_future.set_result(boundary_ok)
  465. async def _finalize_boundary_stream(self, _reason: str) -> bool:
  466. """Close the open native stream at a boundary; send() the pre-prompt text if that
  467. fails. False only when both finalize and the fallback send failed."""
  468. finalize_text = self._accumulated or self._boundary_placeholder
  469. try:
  470. if await self._send_frame(finalize_text, finalize=True):
  471. logger.debug("%s boundary: finalized stream (chat=%s, turn=%s)",
  472. _reason, self.chat_id, self._turn_id)
  473. return True
  474. except Exception as e:
  475. logger.warning("%s boundary: finalize failed: %s", _reason, e)
  476. # Typing bubble may still show partial content; deliver via send().
  477. logger.warning("%s boundary: finalize not confirmed, "
  478. "falling back to send() for pre-prompt text (chat=%s)",
  479. _reason, self.chat_id)
  480. try:
  481. if getattr(await self.adapter.send(self.chat_id, finalize_text), "success", False):
  482. return True
  483. except Exception as send_err:
  484. logger.warning("%s boundary: fallback send also failed: %s", _reason, send_err)
  485. logger.error("%s boundary: both finalize and fallback send failed "
  486. "(chat=%s) — pre-prompt text may not have been delivered",
  487. _reason, self.chat_id)
  488. return False
  489. def on_delta(self, text: str) -> None:
  490. """Thread-safe callback from the agent's worker thread. ``None`` signals a tool
  491. boundary: the current message is finalized and subsequent text goes out as a new
  492. message below any tool-progress messages."""
  493. if text:
  494. self._queue.put(text)
  495. elif text is None:
  496. self.on_segment_break()
  497. def finish(self, final_text: Optional[str] = None) -> None:
  498. """Signal stream completion. ``final_text`` is the AUTHORITATIVE completed
  499. final_response (incl. post-stream augmentation the accumulator never saw); the drain
  500. loop adopts it as the finalize payload. Interrupt/error paths call ``finish()`` bare."""
  501. if final_text is not None:
  502. self._queue.put((_FINAL_TEXT, final_text))
  503. self._queue.put(_DONE)
  504. async def run(self) -> None:
  505. """Async task that drains the queue and edits the platform message."""
  506. self._len_fn, self._safe_limit = self._resolve_length_budget()
  507. await self._start_transports()
  508. try:
  509. while True:
  510. # Session reset (/new, /stop): abandon rather than deliver stale deltas.
  511. if not self._run_still_current():
  512. await self._abandon_native_stream()
  513. return
  514. tick = self._drain_queue()
  515. # Boundary produces its own finalize and resets state, so it must
  516. # run before got_done/segment_break processing.
  517. if tick.approval_boundary is not None:
  518. await self._handle_approval_boundary(*tick.approval_boundary)
  519. continue
  520. if tick.got_reopen_seed:
  521. await self._eager_reopen_seed()
  522. continue
  523. if tick.got_done:
  524. self._flush_think_buffer()
  525. # A bare intentional-silence marker (NO_REPLY / [SILENT]): the
  526. # gateway's whole-response filter runs too late for a streamed
  527. # preview, so retract it here instead of finalizing.
  528. if _is_intentional_silence_response(self._clean_for_display(self._accumulated)):
  529. await self._suppress_silence_marker()
  530. return
  531. # Drop a closing marker before any overflow split: cut off on its own, it
  532. # would read as a bare marker the cleaner keeps. The transcript keeps it.
  533. self._accumulated = _strip_trailing_silence_marker(self._accumulated)
  534. if self._should_edit(tick) and (
  535. self._accumulated or (self._use_native_streaming and self._tool_progress_active)
  536. ):
  537. # Seal first: it clears the message id, so a remainder still over the limit
  538. # is split again below. A plain first send would let the adapter split it and
  539. # adopt only the LAST chunk as the preview; the next seal then overwrites that
  540. # chunk with the head of the whole remainder (duplicated + lost text, #25349).
  541. await self._seal_overflow_heads()
  542. # Overflow split. Native streaming bypasses this: the adapter
  543. # truncates against the stream protocol's own limit.
  544. if not self._use_native_streaming and self._first_send_overflows():
  545. if await self._split_first_send(tick):
  546. return
  547. if self._first_send_overflows():
  548. # A head send failed: keep the full text for the fallback final, and
  549. # skip the boundary reset below that would clear it. Still yield: the
  550. # buffer stays over the debounce threshold, so `continue` alone re-enters
  551. # the split on every pass and spins the loop without ever sleeping.
  552. self._signal_flush(tick.flush_event)
  553. await asyncio.sleep(0.05)
  554. continue
  555. # The split tail goes out now, so a commentary or tool boundary drained in
  556. # this tick still lands after it instead of being dropped.
  557. await self._push_update(tick)
  558. if tick.got_done:
  559. await self._finalize_turn(tick)
  560. return
  561. if tick.commentary_text is not None:
  562. await self._deliver_commentary(tick.commentary_text)
  563. if tick.got_segment_break:
  564. await self._end_segment(tick)
  565. # Done last so the waiter unblocks only once everything queued
  566. # before the barrier is on screen.
  567. if tick.got_flush:
  568. self._signal_flush(tick.flush_event)
  569. await asyncio.sleep(0.05) # Small yield to not busy-loop
  570. except asyncio.CancelledError:
  571. await self._on_cancelled()
  572. except Exception as e:
  573. logger.error("Stream consumer error: %s", e)
  574. finally:
  575. self._wake_flush_waiters()
  576. # ── run() collaborators ─────────────────────────────────────────────
  577. def _resolve_length_budget(self) -> tuple[Callable[[str], int], int]:
  578. """Per-chat length function (relay adapters differ per chat, e.g. utf16) + budget.
  579. isinstance gate: MagicMock auto-attributes aren't callables; test doubles use len."""
  580. # Shares the guarded ladder with the fallback path: a git pull while the gateway
  581. # runs can pair new consumer code with an old in-memory adapter lacking
  582. # message_len_fn_for_chat (#72628), which then falls back to message_len_fn.
  583. len_fn, _ = self._fallback_len_budget()
  584. return len_fn, max(500, self._raw_message_limit() - len_fn(self.cfg.cursor) - 100)
  585. async def _start_transports(self) -> None:
  586. """Resolve native/draft transport; native wins (adapters declaring it can't edit).
  587. The empty seed frame shows "typing" before the first token; on failure → edit path."""
  588. self._use_native_streaming = self._resolve_native_streaming()
  589. if self._use_native_streaming:
  590. logger.debug("Stream consumer using native-stream transport (chat=%s)", self.chat_id)
  591. if await self._try_seed_frame("Native streaming seed frame raised; disabling native",
  592. exc_info=True):
  593. self._native_stream_opened = True
  594. self._use_draft_streaming = False
  595. return
  596. self._use_native_streaming = False
  597. self._use_draft_streaming = self._resolve_draft_streaming()
  598. # Native draft streaming: bump the draft_id so the next text segment animates as a fresh preview
  599. # below the tool-progress bubbles, not over the prior segment's already-finalized draft. This is how
  600. # we avoid the "inter-tool-call text leak" failure mode openclaw documented in their issue #32535 —
  601. # each text block becomes its own visible message via the finalize, then a new draft animates for
  602. # the next one.
  603. if self._use_draft_streaming:
  604. self._bump_draft_id()
  605. logger.debug("Stream consumer using native-draft transport (chat=%s draft_id=%s)",
  606. self.chat_id, self._draft_id)
  607. def _drain_queue(self) -> _Tick:
  608. """Drain everything queued so far into one tick. Control sentinels stop the drain
  609. (they take effect this tick); _FINAL_TEXT / _TOOL_PROGRESS / text deltas fold into
  610. state so simultaneous items batch."""
  611. tick = _Tick()
  612. while True:
  613. try:
  614. item = self._queue.get_nowait()
  615. except queue.Empty:
  616. return tick
  617. if item is _DONE:
  618. tick.got_done = True
  619. return tick
  620. if item is _NEW_SEGMENT:
  621. tick.got_segment_break = True
  622. return tick
  623. if item is _REOPEN_SEED:
  624. tick.got_reopen_seed = True
  625. return tick
  626. kind = item[0] if isinstance(item, tuple) and item else None
  627. if kind is _FINAL_TEXT:
  628. self._adopt_final_text(item[1])
  629. elif kind is _TOOL_PROGRESS: # keep draining to batch simultaneous lines
  630. if self._use_native_streaming:
  631. self._tool_progress_lines.append(item[1])
  632. self._tool_progress_active = True
  633. elif kind is _APPROVAL_BOUNDARY:
  634. tick.approval_boundary = (item[1], item[2])
  635. return tick
  636. elif kind is _COMMENTARY:
  637. tick.commentary_text = item[1]
  638. return tick
  639. elif kind is _FLUSH:
  640. # Barrier: finalize like a tool boundary, signal at the end of the tick.
  641. tick.got_flush = tick.got_segment_break = True
  642. tick.flush_event = item[1]
  643. return tick
  644. else:
  645. self._filter_and_accumulate(item)
  646. def _adopt_recovered_reply(self, final_raw: str) -> bool:
  647. """Reconcile a marker-followed reply against its own prior segment, not older commentary."""
  648. if (self._message_id or self._cumulative_transport() or self._last_segment_delivery is None
  649. or not _is_intentional_silence_response(self._clean_for_display(self._accumulated))
  650. or _is_intentional_silence_response(self._clean_for_display(final_raw))):
  651. return False
  652. message_id, created_ts, prior_text, prior_ids = self._last_segment_delivery
  653. if len(prior_ids) == 1 and self._display_payload(prior_text) == self._display_payload(final_raw):
  654. self._accumulated = self._stream_ledger = ""
  655. self._mark_final_delivered(record=final_raw)
  656. return True
  657. # The final may be transformed or augmented. Reopen its own message so the
  658. # normal edit/fallback path replaces it; retire old split heads only after success.
  659. self._message_id, self._message_created_ts = message_id, created_ts
  660. self._last_sent_text = prior_text
  661. self._already_sent = True
  662. self._segment_preview_message_ids = {message_id}
  663. # Every replacement path, including fresh-final, owns only this segment.
  664. self._preview_message_ids = set(prior_ids)
  665. self._superseded_reply_ids = prior_ids - {message_id}
  666. self._delivered_segment_texts.pop()
  667. self._last_segment_delivery = None
  668. self._accumulated = self._stream_ledger = final_raw
  669. return True
  670. def _adopt_final_text(self, final_raw: str) -> None:
  671. """Adopt the authoritative final (see finish()) as the finalize content — only if this
  672. consumer streamed something (a no-stream turn keeps the gateway's final-send
  673. ownership). Split delivery: wholesale adoption would repeat sealed heads, refusing
  674. makes the gateway resend the ENTIRE body — so append only the suffix when the final
  675. strictly prefix-extends the ledger."""
  676. if not (self._accumulated or self._message_id or self._last_sent_text):
  677. return
  678. if self._adopt_recovered_reply(final_raw):
  679. return
  680. if not self._turn_split_delivery:
  681. final_payload = self._clean_for_display(final_raw)
  682. if final_payload and final_payload != self._clean_for_display(self._accumulated):
  683. self._accumulated = final_raw
  684. self._stream_ledger = final_raw
  685. return
  686. ledger = self._stream_ledger
  687. if ledger and final_raw.startswith(ledger) and len(final_raw) > len(ledger):
  688. self._accumulated += final_raw[len(ledger):]
  689. self._stream_ledger = final_raw
  690. async def _eager_reopen_seed(self) -> None:
  691. """Eager re-seed after a clarify answer (gate re-checked: state may have advanced).
  692. Trade-off: WeCom's ~6-minute stream limit (errcode 846608, from the FIRST frame)
  693. now starts at the reply instant; on expiry we degrade to send()."""
  694. if not self._reopen_seed_pending():
  695. return
  696. if await self._try_seed_frame("Eager reopen seed raised, disabling native: %s"):
  697. self._native_stream_opened = True
  698. self._native_last_pushed_len = 0
  699. self._awaiting_reopen_after_boundary = False
  700. self._reopen_seeded_eagerly = True
  701. logger.info("[latency] Eager re-seed after clarify answer "
  702. "(typing bubble reopened immediately, turn=%s)", self._turn_id)
  703. else:
  704. # Degrade to a single buffered send(), like the approval path.
  705. self._degrade_native_to_buffered_send()
  706. def _should_edit(self, tick: _Tick) -> bool:
  707. """Decide whether this tick flushes an edit/frame."""
  708. if not tick.is_interim:
  709. return True
  710. if self.cfg.buffer_only:
  711. return False
  712. if self._use_native_streaming:
  713. # No platform edit-rate limit: push every delta immediately.
  714. should_edit = bool(self._accumulated) or self._tool_progress_active
  715. else:
  716. elapsed = time.monotonic() - self._last_edit_time
  717. # buffer_threshold is a codepoint debounce heuristic, not a
  718. # platform-limit check (_len_fn is for overflow). It must not
  719. # override an active flood backoff: while a refusal is being
  720. # waited out, only the (server-requested) interval may fire an edit.
  721. should_edit = bool((elapsed >= self._current_edit_interval and self._accumulated)
  722. or (len(self._accumulated) >= self.cfg.buffer_threshold
  723. and not self._flood_strikes))
  724. # Defer mid-stream edits while the buffer could still resolve to a silence
  725. # marker ("NO"→"NO_REPLY"), or a reply's last line could still become a trailing one
  726. # ("answer\n\nNO"); got_done always resolves the buffer.
  727. # Likewise defer while a MEDIA:/[[…]] directive is still being typed: the cleaner
  728. # only strips complete deliverable tags, so a half-streamed one would be shown, and
  729. # a media-only reply cleans to "" at finish, which never edits the bubble away.
  730. cleaned = self._clean_for_display(self._accumulated)
  731. return (should_edit and not _is_partial_silence_marker(cleaned)
  732. # Raw buffer: the cleaner already drops a COMPLETE trailing marker, but an interim
  733. # frame carries the cursor after it, which hides the marker from the cleaner.
  734. and not _ends_with_partial_silence_marker(self._accumulated)
  735. and not has_pending_media_directive(cleaned))
  736. async def _split_first_send(self, tick: _Tick) -> bool:
  737. """No message to edit yet and the buffer overflows: seal only the head chunks; the
  738. tail stays in _accumulated as the active preview later deltas edit in place.
  739. True when the turn finished here (the run loop returns)."""
  740. chunks = self._truncate_for_stream(self._accumulated, self._safe_limit, self._len_fn)
  741. if len(chunks) <= 1:
  742. # Malformed/legacy adapter result must still be splittable.
  743. chunks = self._split_text_chunks(self._accumulated, self._safe_limit, self._len_fn)
  744. reply_to = self._initial_reply_to_id
  745. heads_delivered = len(chunks) > 1
  746. for chunk in chunks[:-1]:
  747. new_id = await self._send_new_chunk(chunk, reply_to, final=tick.got_done)
  748. if new_id is None or new_id == reply_to:
  749. heads_delivered = False # keep the full text intact for the gateway fallback
  750. break
  751. reply_to = new_id
  752. if heads_delivered:
  753. # truncate_message suffixes multi-chunk output with " (n/n)"; the tail is the LIVE
  754. # preview later deltas extend, so a kept indicator ends up embedded mid-reply.
  755. tail = chunks[-1]
  756. indicator = f" ({len(chunks)}/{len(chunks)})"
  757. self._accumulated = tail.removesuffix(indicator)
  758. # Flag BEFORE the tail send: fresh-final replaces every tracked preview
  759. # with one message, which is only valid while the active message holds
  760. # the whole answer — deleting sealed heads drops delivered text.
  761. self._turn_split_delivery = True
  762. # Heads are sealed (or a later head failed): never edit a sealed message with
  763. # the unsplit payload — the tail is sent fresh, or the fallback path retries.
  764. self._message_id = None
  765. self._message_created_ts = None
  766. self._last_sent_text = ""
  767. self._last_edit_time = time.monotonic()
  768. if tick.got_done:
  769. tail_delivered = (not self._accumulated
  770. or await self._send_or_edit(self._accumulated, finalize=True))
  771. # ``_already_sent`` may be True from prior state — only heads + tail count.
  772. self._final_response_sent = heads_delivered and tail_delivered
  773. if self._final_response_sent:
  774. self._turn_split_delivery = True
  775. self._mark_final_delivered(record=self._accumulated)
  776. return True
  777. if tick.got_segment_break:
  778. self._fallback_final_send = False
  779. self._fallback_prefix = ""
  780. return False
  781. def _overflows(self) -> bool:
  782. return self._len_fn(self._accumulated) > self._safe_limit
  783. def _first_send_overflows(self) -> bool:
  784. return self._message_id is None and self._overflows()
  785. async def _seal_overflow_heads(self) -> None:
  786. """Existing message overflowing: seal it with the head, start a new message for the rest."""
  787. while self._overflows() and self._message_id is not None and self._edit_supported:
  788. cp_budget = _custom_unit_to_cp(self._accumulated, self._safe_limit, self._len_fn)
  789. split_at = self._accumulated.rfind("\n", 0, cp_budget)
  790. if split_at < cp_budget // 2:
  791. split_at = cp_budget
  792. chunk = self._accumulated[:split_at]
  793. # finalize=True: the sealed chunk is never edited again, so it needs its
  794. # rich-text pass now. is_turn_final=False: a split head is not the
  795. # answer, so fresh-final must not mark the turn delivered on it.
  796. ok = await self._send_or_edit(chunk, finalize=True, is_turn_final=False)
  797. if self._fallback_final_send or not ok:
  798. break # keep the full text intact for the fallback final send
  799. self._accumulated = self._accumulated[split_at:].lstrip("\n")
  800. self._message_id = None
  801. self._last_sent_text = ""
  802. self._turn_split_delivery = True
  803. async def _push_update(self, tick: _Tick) -> None:
  804. """Send/edit this tick's visible text (cursor-suffixed unless finalizing)."""
  805. display_text = self._accumulated
  806. if tick.is_interim:
  807. if self._use_native_streaming:
  808. display_text = self._compose_frame_content()
  809. if display_text and self.cfg.cursor:
  810. display_text += self.cfg.cursor
  811. else:
  812. display_text += self.cfg.cursor
  813. # A got_done FRESH send via the draft transport already carries finalize=True,
  814. # unlike an EDIT, which REQUIRES_EDIT_FINALIZE adapters still need a pass for.
  815. tick.draft_final_fresh_send = (tick.got_done and self._use_draft_streaming
  816. and self._message_id is None)
  817. # Segment break finalizes so platforms needing explicit closure (DingTalk AI
  818. # Cards) don't leave the segment stuck loading; it closes a preamble, not the
  819. # answer.
  820. tick.update_visible = await self._send_or_edit(
  821. display_text, finalize=tick.got_done or tick.got_segment_break,
  822. is_turn_final=tick.got_done)
  823. self._last_edit_time = time.monotonic()
  824. # Lines stay in _tool_progress_lines for the next compose.
  825. self._tool_progress_active = False
  826. async def _finalize_turn(self, tick: _Tick) -> None:
  827. """got_done: final edit without cursor, or one continuation send if edits failed."""
  828. if self._accumulated or self._message_id is not None or self._already_sent:
  829. await self._notify_before_finalize()
  830. if self._reopen_seed_pending() and not self._accumulated:
  831. # Lazy reopen, no post-prompt content: nothing is open on screen, so
  832. # don't re-seed just to emit a lone "✅".
  833. logger.debug("Clarify reopen boundary with no post-prompt content "
  834. "— skipping lone-placeholder finalize (turn=%s)", self._turn_id)
  835. elif (self._reopen_seeded_eagerly and self._native_stream_opened
  836. and not self._accumulated and not tick.update_visible):
  837. # Eager seed, no content: the typing bubble IS on screen and would hang
  838. # forever — close it with an empty finalize. Delivery flags untouched.
  839. await self._close_empty_native_bubble("Eager-seed empty finalize failed: %s")
  840. logger.debug("Eager reopen seed but no post-answer content — "
  841. "closed empty typing bubble (turn=%s)", self._turn_id)
  842. elif self._use_native_streaming:
  843. # Native streams MUST close with finish=true even when empty (tool-only
  844. # turns) — placeholder if needed.
  845. if not tick.update_visible:
  846. await self._finalize_edit(self._accumulated or "✅", record=False)
  847. else:
  848. self._mark_final_delivered()
  849. elif self._accumulated:
  850. await self._finalize_edit_path(tick)
  851. if self._final_content_delivered and self._superseded_reply_ids:
  852. await self._delete_previews(self._superseded_reply_ids, skip=self._message_id,
  853. label="Recovered reply")
  854. self._superseded_reply_ids.clear()
  855. async def _finalize_edit_path(self, tick: _Tick) -> None:
  856. """Edit-transport finalize (the non-native got_done branches, in priority order)."""
  857. if self._fallback_final_send:
  858. await self._send_fallback_final(self._accumulated)
  859. elif self._final_response_sent:
  860. # Fresh-final already delivered; a second finalize would duplicate.
  861. self._mark_final_delivered(record=self._accumulated)
  862. elif tick.update_visible and (not self._adapter_requires_finalize
  863. or self._last_edit_overflowed or tick.draft_final_fresh_send):
  864. # The update already delivered the final. A second finalize would re-edit
  865. # it (Telegram: editMessageText after sendRichMessage falls back to the
  866. # legacy formatter) or overflow-split again, duplicating chunks.
  867. self._mark_skip_redundant_finalize()
  868. elif self._message_id:
  869. # No visible update this tick, or the adapter needs explicit finalize=True.
  870. # The edit may exhaust flood strikes → fallback mode: send the unsent tail.
  871. if not await self._finalize_edit(self._accumulated) and self._fallback_final_send:
  872. await self._send_fallback_final(self._accumulated)
  873. elif not self._already_sent:
  874. # Retry after the finalize tick failed. finalize=True keeps stream-is-the-
  875. # message adapters out of the draft-frame branch, whose dedupe against the
  876. # last UNSEALED frame would report success with no transport call.
  877. await self._finalize_edit(self._accumulated)
  878. async def _finalize_edit(self, text: str, *, record: bool = True) -> bool:
  879. """finalize=True send_or_edit; on success mark the turn delivered (+ record payload)."""
  880. self._final_response_sent = await self._send_or_edit(text, finalize=True)
  881. if self._final_response_sent:
  882. self._mark_final_delivered(record=text if record else None)
  883. return self._final_response_sent
  884. def _cumulative_transport(self) -> bool:
  885. """Stream-is-the-message drafts and WeCom native: one append-only stream per turn."""
  886. stream_draft = self._stream_is_message() and self._use_draft_streaming
  887. return stream_draft or self._use_native_streaming
  888. async def _deliver_commentary(self, commentary_text: str) -> None:
  889. """Post commentary as its own message. Cumulative transports keep the stream going —
  890. resetting _accumulated would break the append-only invariant / lose text."""
  891. cumulative = self._cumulative_transport()
  892. if not cumulative:
  893. self._reset_segment_state()
  894. await self._send_commentary(commentary_text)
  895. self._last_edit_time = time.monotonic()
  896. if not cumulative:
  897. self._reset_segment_state()
  898. async def _end_segment(self, tick: _Tick) -> None:
  899. """Tool boundary: edit-based transports reset so the next chunk is a fresh message.
  900. Cumulative transports must NOT reset — clearing _accumulated makes the next frame a
  901. non-prefix snapshot and the connector re-appends the whole answer. preserve_no_edit:
  902. "__no_edit__" (platform never returned a real id — Signal, github_comment webhook)
  903. must keep its sentinel or every tool boundary posts a new message; the
  904. continuation goes out once via _send_fallback_final."""
  905. if self._cumulative_transport():
  906. return
  907. # If the segment-break edit or send didn't land (flood control / fallback mode, or a
  908. # failed first send of a split tail with no message id yet), _accumulated holds unseen
  909. # pre-boundary text — flush it before the reset clears it.
  910. if (self._accumulated and not tick.update_visible
  911. and self._message_id != "__no_edit__"):
  912. await self._flush_segment_tail_on_edit_failure()
  913. self._reset_segment_state(preserve_no_edit=True)
  914. async def _on_cancelled(self) -> None:
  915. """Best-effort final edit on task cancel: finalize=True so REQUIRES_EDIT_FINALIZE
  916. platforms apply formatting; is_turn_final=False because this handler owns the flags.
  917. Only a successful edit confirms delivery — a partial send may be just "Let me
  918. search…", not the answer."""
  919. best_effort_ok = False
  920. if self._accumulated and self._message_id:
  921. with contextlib.suppress(Exception):
  922. best_effort_ok = bool(await self._send_or_edit(
  923. self._accumulated, finalize=True, is_turn_final=False))
  924. elif self._message_id is None:
  925. # Draft path keeps _message_id=None; seal in place (else the stream stays
  926. # visibly live and the adapter keeps armed interception state).
  927. await self._abandon_native_stream()
  928. if best_effort_ok and not self._final_response_sent:
  929. self._mark_final_delivered(record=self._accumulated)
  930. def _wake_flush_waiters(self) -> None:
  931. """Wake still-queued _FLUSH waiters so a consumer dying mid-flush
  932. doesn't stall flush_pending_sync() for its full timeout."""
  933. with contextlib.suppress(Exception):
  934. while True:
  935. item = self._queue.get_nowait()
  936. if isinstance(item, tuple) and len(item) == 2 and item[0] is _FLUSH:
  937. self._signal_flush(item[1])
  938. @staticmethod
  939. # Strip MEDIA:<path> tags before display. Uses the shared anchored MEDIA_TAG_CLEANUP_RE from
  940. # gateway/platforms/base.py — only tags whose path ends in a deliverable extension are removed, so an
  941. # unknown-extension path stays visible instead of being silently dropped (issue #34517). Streaming and
  942. # non-streaming paths share the same regex, so a tag is treated identically whichever path delivered the
  943. # text.
  944. def _clean_for_display(text: str) -> str:
  945. """Hide MEDIA:<path> / [[audio_as_voice]] directives and markdown/HTML image tags; both are
  946. delivered post-stream as native attachments.
  947. Image tags are the ones the non-streaming path's ``extract_images`` split attaches: once a
  948. tag becomes an attachment it must not also render as text — on Discord ``![alt](url)``
  949. shows as ``!alt`` plus an unfurl (#141806). The tag is removed without trimming the text
  950. around it, so interim frames stay prefix-stable. A silence marker closing the reply on its own
  951. line is dropped (``strip_trailing_silence_marker``); a bare marker is left for the silence check.
  952. """
  953. return _strip_trailing_silence_marker(
  954. strip_image_tags_for_display(_BasePlatformAdapter.strip_media_directives_for_display(text)))