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)