diff --git a/frontends/tests/test_tuiapp_v2_sidebar_refresh.py b/frontends/tests/test_tuiapp_v2_sidebar_refresh.py new file mode 100644 index 000000000..1c24143f1 --- /dev/null +++ b/frontends/tests/test_tuiapp_v2_sidebar_refresh.py @@ -0,0 +1,175 @@ +"""Sidebar repaint policy: paint only when what it draws actually changed. + +Background: the streaming path calls `_refresh_sidebar()` on every 50ms paint +batch. Before this policy that rebuilt the whole session table 20x/s. + +A plain time-based throttle is *wrong* for this widget. `render_sidebar()` +draws exactly four things per row — session id, name, status, and the Q/S +preview lines — and all four are covered by `_sidebar_visible_sig()`. So the +correct policy is content-driven, not clock-driven: + +* **While tokens stream**: status and history are frozen (messages are only + appended at turn boundaries), so the signature is stable → strictly zero + repaints, not "one every 5s". +* **The instant something really changes** (running→idle when `done` arrives, a + new prompt, a fresh summary) → a single repaint, with no timer in between. + This is the same edge-triggered behaviour the desktop notifier gets from its + `agent_after` ping. +* `force=True` (switch / rename / rewind / theme) → paint regardless. + +Run: pytest frontends/tests/test_tuiapp_v2_sidebar_refresh.py -v +""" +import asyncio +import sys +import threading +import time +from pathlib import Path +from types import SimpleNamespace + +ROOT = Path(__file__).resolve().parent.parent.parent +sys.path.insert(0, str(ROOT)) +sys.path.insert(0, str(ROOT / "frontends")) + +import tuiapp_v2 as T # noqa: E402 + + +class _StubAgent: + """Minimal stand-in for GenericAgent: idle run loop + attrs add_session sets.""" + + def __init__(self): + self.log_path = "" + self.inc_out = True + self.task_dir = "" + self.extra_sys_prompts = [] + self._rw_store = None + self.history = [] + self._stop = threading.Event() + self.llmclient = None + + def abort(self): + pass + + def run(self): + self._stop.wait(3600) + + +def _attach_history(sess, messages): + sess.agent.llmclient = SimpleNamespace( + backend=SimpleNamespace(history=messages)) + + +def test_sidebar_repaints_only_when_rendered_content_changes(): + async def scenario(): + app = T.GenericAgentTUI(agent_factory=lambda: _StubAgent()) + async with app.run_test(size=(120, 40)) as pilot: + await pilot.pause() + + paints = [] + real_paint = app._paint_sidebar + + def counting_paint(): + paints.append(time.monotonic()) + real_paint() + + app._paint_sidebar = counting_paint + + sid = next(iter(app.sessions)) + sess = app.sessions[sid] + hist = [{"role": "user", "content": "hello"}] + _attach_history(sess, hist) + sess.status = "idle" + + # 0) baseline: force paints once and settles the painted signature + app._refresh_sidebar(force=True) + assert len(paints) == 1 + + # 1) stream hot path: 20 calls, nothing rendered changed → zero paints + for _ in range(20): + app._refresh_sidebar() + assert len(paints) == 1, "unchanged sidebar must not repaint" + + # 2) status flip (task finished) → immediate, no timer involved + sess.status = "running" + app._refresh_sidebar() + assert len(paints) == 2, "status change must paint immediately" + + sess.status = "idle" + started = time.monotonic() + app._refresh_sidebar() + assert len(paints) == 3, "running→idle must paint immediately" + assert time.monotonic() - started < 1.0, \ + "done must land without waiting for any throttle window" + + # 3) turn boundary: Q/S preview changes → immediate repaint + hist.append({"role": "assistant", "content": "did it"}) + app._refresh_sidebar() + assert len(paints) == 4, "new summary preview must paint immediately" + + # 4) streaming into the same turn (backend.history untouched) → no paint + for _ in range(20): + app._refresh_sidebar() + assert len(paints) == 4, "streaming must not repaint the sidebar" + + # 5) user action forces a paint even with an identical signature + app._refresh_sidebar(force=True) + assert len(paints) == 5 + + # 6) no timer machinery: repaint is purely content-driven, so the + # app must never arm a delayed sidebar repaint. + assert not hasattr(app, "_sidebar_timer") + assert not hasattr(app, "_sidebar_dirty") + + asyncio.run(scenario()) + + +def test_sidebar_preview_cache_avoids_rescanning_history(): + """Q/S derivation walks + regexes the history; memoise it per (list, len).""" + app = T.GenericAgentTUI(agent_factory=lambda: _StubAgent()) + sess = T.AgentSession(agent_id=1, name="s", agent=_StubAgent()) + hist = [{"role": "user", "content": "hi"}] + _attach_history(sess, hist) + app.sessions = {1: sess} + + first = app._sidebar_visible_sig() + calls = [] + real_user = T._sidebar_last_user + + def counting_user(s): + calls.append(s) + return real_user(s) + + T._sidebar_last_user = counting_user + try: + second = app._sidebar_visible_sig() + assert second == first + assert calls == [], "unchanged history must hit the cache" + + hist.append({"role": "assistant", "content": "ok"}) + third = app._sidebar_visible_sig() + assert third != second, "appended history must invalidate the cache" + assert len(calls) == 1 + finally: + T._sidebar_last_user = real_user + + +def test_sidebar_signature_covers_everything_render_sidebar_draws(): + """Guard against a future render_sidebar field that the signature ignores.""" + import inspect + src = inspect.getsource(T.render_sidebar) + for token in ('sess.name', 'sess.status', '_sidebar_last_user', + '_sidebar_last_summary', 'sessions.items()'): + assert token in src, f"render_sidebar draws {token}; keep the sig in sync" + + +def test_stream_path_uses_non_forced_refresh(): + """Streaming/fast paths must go through the signature check, not force.""" + src = (ROOT / "frontends" / "tuiapp_v2.py").read_text(encoding="utf-8") + # the 50ms stream flush calls the non-forced form + assert "self._refresh_sidebar()\n self._refresh_topbar()" in src + # the 1s watchdog keeps its cheap (sid, status) pre-check + # the non-forced path compares the full rendered-content signature + assert "self._sidebar_visible_sig()" in src + assert 'if not force and self._sidebar_visible_sig() == getattr(' in src + assert 'self, "_sidebar_painted_sig", None):' in src + assert "SIDEBAR_REFRESH_SEC" not in src, \ + "time-based throttle was removed in favour of content-driven refresh" diff --git a/frontends/tests/test_tuiapp_v2_stream_layout.py b/frontends/tests/test_tuiapp_v2_stream_layout.py new file mode 100644 index 000000000..42bdba1a1 --- /dev/null +++ b/frontends/tests/test_tuiapp_v2_stream_layout.py @@ -0,0 +1,167 @@ +"""Streaming repaint must not re-arrange the transcript on every token. + +`Static.update()` defaults to `layout=True`, so the 20Hz streaming paint used to +mark the whole screen layout-dirty and make Textual re-arrange every message on +the next frame (5-15ms per chunk on a 30-turn session, ~430ms on long ones). + +`_update_text()` only asks for a layout pass when the rendered height changes. +These tests pin both halves of that contract: + * same-line growth must not request a layout (the perf fix), + * content that grows new lines must still grow the widget (no clipping). +""" +import asyncio +import os +import sys +import time +from pathlib import Path +from types import SimpleNamespace + +import pytest + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) +FE = ROOT / "frontends" +if str(FE) not in sys.path: + sys.path.insert(0, str(FE)) + + + +def _repo_module_names() -> set: + """Top-level module names that really exist on disk in this checkout.""" + names = set() + for base in (ROOT, FE): + try: + for entry in os.listdir(base): + if entry.endswith(".py"): + names.add(entry[:-3]) + except OSError: + pass + return names + + +def _purge_stub_modules() -> None: + """Drop bare-namespace stubs that sibling tests leave in ``sys.modules``. + + Several tests stub repo modules (``agentmain``, ``agent_loop``, ``llmcore``) + for isolation; a leftover stub has ``__file__ is None`` and makes the real + import fail with "cannot import name ... (unknown location)". Only names + that correspond to an actual ``.py`` in this checkout are considered, so + builtins such as ``sys`` (which legitimately has no ``__file__``) are safe. + """ + if sys.modules.get("sys") is not sys: # some tests swap this one out + sys.modules["sys"] = sys + for name in _repo_module_names(): + module = sys.modules.get(name) + if module is not None and getattr(module, "__file__", None) is None: + sys.modules.pop(name, None) + + +def _import_tui(): + """Import the TUI module with the import chain cleaned up first.""" + global T + _purge_stub_modules() + try: + import tuiapp_v2 + return tuiapp_v2 + except ImportError: + # A stubbed dependency deeper in the chain (imported by a real module) + # only surfaces as ImportError on the first try; purge and retry once. + for name in ("tuiapp_v2", "chatapp_common", "agentmain", "agent_loop", "llmcore"): + sys.modules.pop(name, None) + _purge_stub_modules() + import tuiapp_v2 + return tuiapp_v2 + +T = None + + +class _StubAgent: + """Enough of an agent for the app to mount a message without a network.""" + + def __init__(self): + self.log_path = "" + self.inc_out = True + self.task_dir = "" + self.extra_sys_prompts = [] + self._rw_state = {} + self.history = [] + self.name = "probe" + self.model_name = "stub" + self.last_tokens = (0, 0) + self.token_usage = {} + + +def _patch_layout_counter(app): + counts = {"n": 0, "t": 0.0} + screen_cls = type(app.screen) + original = screen_cls._refresh_layout + + def counting(screen, *args, **kwargs): + start = time.perf_counter() + try: + return original(screen, *args, **kwargs) + finally: + counts["n"] += 1 + counts["t"] += time.perf_counter() - start + + screen_cls._refresh_layout = counting + return counts, lambda: setattr(screen_cls, "_refresh_layout", original) + + +async def _scenario(): + app = T.GenericAgentTUI() + app.make_agent = lambda sess: setattr(sess, "agent", _StubAgent()) + result = {} + async with app.run_test(size=(120, 40)) as pilot: + counts, restore = _patch_layout_counter(app) + try: + app.add_session("probe") + sess = app.current + m = T.ChatMessage(role="assistant", content="", done=False) + sess.messages.append(m) + app._mount_message(app.query_one("#messages"), m) + + # 1) growth inside one line: no layout requests, height stays 1. + counts["n"] = 0 + for i in range(20): + m.content = "x" * 10 + "y" * (i * 3) + app._stream_update_assistant(m) + await pilot.pause(0.01) + widget = m._segment_widgets[-1] + result["inline_layouts"] = counts["n"] + result["inline_height"] = widget.size.height + + # 2) new lines: layout must be requested and the widget must grow. + counts["n"] = 0 + for i in range(1, 9): + m.content = "\n".join("line %02d" % j for j in range(i + 1)) + app._stream_update_assistant(m) + await pilot.pause(0.05) + result["line_layouts"] = counts["n"] + result["line_height"] = widget.size.height + last = widget.render_line(widget.size.height - 1) + result["last_line"] = "".join(seg.text for seg in last).strip() + finally: + restore() + return result + + +def test_streaming_repaint_is_height_aware(): + global T + T = _import_tui() + r = asyncio.run(_scenario()) + + # A 20-chunk same-line stream must not re-arrange the screen per chunk. + assert r["inline_layouts"] <= 4, ( + "same-line streaming requested %d layouts (expected <=4)" % r["inline_layouts"]) + assert r["inline_height"] == 1, ( + "single-line content occupies %d rows" % r["inline_height"]) + + # Growing to 9 lines must be visible, not clipped. + assert r["line_height"] == 9, ( + "9-line content rendered in %d rows" % r["line_height"]) + assert "line 08" in r["last_line"], ( + "last line clipped, got %r" % r["last_line"]) + assert r["line_layouts"] >= 6, ( + "line growth requested only %d layouts" % r["line_layouts"]) diff --git a/frontends/tuiapp_v2.py b/frontends/tuiapp_v2.py index 3e6e1f7cc..501e2c72b 100644 --- a/frontends/tuiapp_v2.py +++ b/frontends/tuiapp_v2.py @@ -93,6 +93,14 @@ def _hint_terminal_capabilities() -> None: _hint_terminal_capabilities() +# Streaming paint coalescing window (seconds). Every token chunk used to be +# painted on a 50ms timer; each paint re-arranged the whole transcript because +# `Static.update()` defaults to `layout=True`. The layout cost is now avoided +# (`_update_text`), and 100ms halves the remaining repaint traffic without a +# visible difference in typing feel. Override: GA_TUI_PAINT_MS. +STREAM_PAINT_INTERVAL = max(0.02, float(os.environ.get("GA_TUI_PAINT_MS", "100")) / 1000.0) + + # Strip terminal control sequences from subprocess stdout but keep SGR color codes, # otherwise Text.from_ansi loses color downstream. _ANSI_CONTROL_RE = re.compile( @@ -6986,7 +6994,8 @@ def _update_assistant(self, agent_id, text, *, task_id=None, done=True, # Keep data current for stop/copy/session switching; coalesce only paint. self._pending_stream_renders[(agent_id, task_id)] = found if self._stream_render_timer is None: - self._stream_render_timer = self.set_timer(0.05, self._flush_stream_renders) + self._stream_render_timer = self.set_timer( + STREAM_PAINT_INTERVAL, self._flush_stream_renders) return self._pending_stream_renders.pop((agent_id, task_id), None) self._render_assistant_update(found) @@ -7354,8 +7363,74 @@ def _refresh_bottombar(self): except Exception: pass - def _refresh_sidebar(self): + def _sidebar_visible_sig(self): + """Everything `render_sidebar` actually draws, cheaply. + + `render_sidebar` needs no more than the session id, name, status and the + Q/S preview lines. The previews are read from the LLM-side history and + therefore only change at turn boundaries (a new prompt is appended, then + the assistant reply); while tokens stream the history is untouched. So + this signature is stable during a stream and the 20x/s refresh calls from + the paint batches collapse into a single tuple comparison. + + Deriving Q/S walks (and regexes) the history, so memoise it per session + keyed on the history list identity + length + last message: all three + only change when a message is appended, which is the only way these + previews can change in practice. + """ + cache = getattr(self, "_sidebar_preview_cache", None) + if cache is None: + cache = self._sidebar_preview_cache = {} + rows = [] + seen = set() + for sid, s in self.sessions.items(): + seen.add(sid) + try: + hist = s.agent.llmclient.backend.history + except Exception: + hist = None + # Length alone would go stale when trim_messages_history drops + # messages in place and the list later grows back to the same size. + tail = hist[-1] if hist else None + hit = cache.get(sid) + if (hist is None or hit is None or hit[0] is not hist + or hit[1] != len(hist) or hit[2] is not tail): + q = _sidebar_last_user(s) + sm = _sidebar_last_summary(s) + cache[sid] = (hist, len(hist) if hist is not None else -1, tail, q, sm) + else: + _, _, _, q, sm = hit + rows.append((sid, s.name, s.status, q, sm)) + for sid in [k for k in cache if k not in seen]: + cache.pop(sid, None) + return tuple(rows) + + def _refresh_sidebar(self, force: bool = False) -> None: + """Repaint the session sidebar, but only when what it draws changed. + + The streaming path calls this on every 50ms paint batch. Rebuilding the + whole table (and re-deriving the Q/S previews from the history) 20x/s is + pure waste, because during a stream nothing the sidebar shows changes. + Comparing `_sidebar_visible_sig()` costs a tuple compare and skips the + repaint entirely in that case. + + It stays edge-triggered rather than throttled: the instant something + really changes — a task finishing (running->idle), a new prompt, a fresh + summary — the signature flips and the paint happens on that very frame, + with no timer in between. + + Callers that know the view must be rebuilt regardless (switch/rename/ + rewind/theme) pass force=True. + """ + if not self.is_mounted: return + if not force and self._sidebar_visible_sig() == getattr( + self, "_sidebar_painted_sig", None): + return + self._paint_sidebar() + + def _paint_sidebar(self) -> None: if not self.is_mounted: return + self._sidebar_painted_sig = self._sidebar_visible_sig() self.query_one("#sidebar", Static).update(render_sidebar(self.sessions, self.current_id)) self._scroll_active_session_into_view() @@ -7814,7 +7889,7 @@ def _mark_stopping(self, sess) -> None: if m.role == "assistant" and not m.done: self._capture_stop_summary(m) if m._spinner_widget is not None: - try: m._spinner_widget.update(self._stopping_annotation(m)) + try: self._update_text(m._spinner_widget, self._stopping_annotation(m)) except Exception: pass def _has_streaming(self) -> bool: @@ -7841,7 +7916,7 @@ def _spinner_tick(self) -> None: if m.role == "assistant" and not m.done and m._spinner_widget is not None: if m._stream_started_at is None: self._mark_stream_start(m) - try: m._spinner_widget.update(self._spinner_annotation(m)) + try: self._update_text(m._spinner_widget, self._spinner_annotation(m)) except Exception: pass if not self._has_streaming(): self._ensure_spinner() @@ -8010,7 +8085,7 @@ def _sync_spinner_widget(self, container, m: ChatMessage, anchor) -> None: else: container.mount(w, after=anchor) m._spinner_widget = w else: - try: m._spinner_widget.update(self._done_annotation(m)) + try: self._update_text(m._spinner_widget, self._done_annotation(m)) except Exception: pass return if m._spinner_widget is None: @@ -8023,6 +8098,42 @@ def _sync_spinner_widget(self, container, m: ChatMessage, anchor) -> None: container.mount(w, after=anchor) m._spinner_widget = w + @staticmethod + def _rendered_height(widget, rendered, width: int): + """Height `rendered` would occupy in `widget` at `width`, or None if unknown.""" + try: + from textual.visual import visualize + visual = visualize(widget, rendered, + markup=getattr(widget, "_render_markup", True)) + return visual.get_height(widget.styles, width) + except Exception: + return None + + def _update_text(self, widget, rendered, *, width: int | None = None) -> None: + """`Static.update()` that only asks for a layout pass when the rendered + height actually changes. + + Why: `Static.update()` defaults to `layout=True`, which marks the whole + screen layout-dirty. Textual then re-arranges the entire transcript on + the next frame — measured at 5-15ms for a 30-turn session and ~430ms on + long ones. Streaming calls this 20x/s, so the TUI burned ~25% of the + main thread just recomputing positions for text that grew by three + characters on the same line. + + `refresh(repaint=True)` (what `update()` does) already invalidates the + cached content height, so a skipped layout pass can never keep a stale + height: the very next real layout re-measures from the new visual. + """ + if widget is None: + return + if width is None: + width = getattr(widget.size, "width", 0) or self._messages_width() + new_h = self._rendered_height(widget, rendered, width) + old_h = getattr(widget, "_ga_last_height", None) + widget._ga_last_height = new_h + widget.update(rendered, layout=(old_h is None or new_h is None + or new_h != old_h)) + def _stream_update_assistant(self, m: ChatMessage) -> None: """Cheap path for per-chunk streaming: if the fold topology is unchanged, only the last text segment got new content, so render and update that one widget. @@ -8047,9 +8158,9 @@ def _stream_update_assistant(self, m: ChatMessage) -> None: rendered = self._render_md(last_text, width) if isinstance(rendered, _MdRender): last_widget._ga_render = rendered - last_widget.update(rendered.text) + self._update_text(last_widget, rendered.text, width=width) else: - last_widget.update(rendered) + self._update_text(last_widget, rendered, width=width) else: last_widget._ga_render = None # Normalise CRLF → LF before from_ansi. On Windows child stdout @@ -8061,15 +8172,13 @@ def _stream_update_assistant(self, m: ChatMessage) -> None: # Markdown to fold on completion. Lone `\r` (no `\n`) is kept so # progress-bar overwrites still work. display = last_text.replace("\r\n", "\n") - last_widget.update(Text.from_ansi(display, style=C_FG)) - try: - self.query_one("#messages", VerticalScroll).refresh() - except Exception: - pass + self._update_text(last_widget, + Text.from_ansi(display, style=C_FG), + width=width) if m.done and m._spinner_widget is not None: # Convert the live spinner into the post-turn ⠿ card in place. self._capture_done_summary(m) - try: m._spinner_widget.update(self._done_annotation(m)) + try: self._update_text(m._spinner_widget, self._done_annotation(m)) except Exception: pass return self._remount_assistant_message(m)