codex-agent-framework 0.1.55__tar.gz → 0.1.56__tar.gz

{codex_agent_framework-0.1.55 → codex_agent_framework-0.1.56}/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 This project loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning where practical.
 
+## [0.1.56] - 2026-05-17
+### Changed
+- Replace the TUI chat surface with a widget-based timeline inspired by Textual chat patterns so live assistant output updates an active message widget instead of mutating a monolithic transcript buffer.
+- Add compact TUI event streams that truncate verbose tool/slash result payloads for live UI subscribers while preserving full replay/API data outside compact mode.
+- Add persistent TUI stream diagnostics in `~/.codex-agent/tui-stream-debug.jsonl` and lightweight perf snapshots in `~/.codex-agent/tui-perf.json` to capture intermittent live-stream stalls after the fact.
+- Preserve the previous sparse terminal look with role headers, compact tool/info/error rows, a right-aligned step marker, and sticky-only autoscroll.
+
+### Tests
+- Validate the TUI/server/client changes with targeted chat/client/server coverage and the full offline CI suite (570 passed).
+
 ## [0.1.55] - 2026-05-17
 ### Fixed
 - Decouple SSE event-stream consumption from local client/TUI event handling so slow or blocked UI work no longer stalls event intake during long-running or heavy tool activity.

{codex_agent_framework-0.1.55/codex_agent_framework.egg-info → codex_agent_framework-0.1.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.55
+Version: 0.1.56
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT

{codex_agent_framework-0.1.55 → codex_agent_framework-0.1.56}/codex_agent/client.py

@@ -14,11 +14,12 @@ from .utils import snake_case_type
 class AgentClient:
     """Small HTTP/SSE client for a codex-agent server."""
 
-    def __init__(self, base_url="http://127.0.0.1:8765", timeout=10, event_read_timeout=15.0, event_stale_after=5.0):
+    def __init__(self, base_url="http://127.0.0.1:8765", timeout=10, event_read_timeout=15.0, event_stale_after=5.0, compact_events=False):
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
         self.event_read_timeout = event_read_timeout
         self.event_stale_after = event_stale_after
+        self.compact_events = compact_events
         self.client_pid = os.getpid()
         self._event_handlers = {}
         self._event_thread = None
@@ -36,6 +37,16 @@ class AgentClient:
         self.health_interval = 1.0
         self.health_failure_threshold = 3
         self._health_failures = 0
+        self.stream_debug = None
+
+    def debug_stream(self, stage, event=None, **fields):
+        logger = getattr(self, "stream_debug", None)
+        if logger is None:
+            return None
+        try:
+            return logger.record(stage, event, **fields)
+        except Exception:
+            return None
 
     def on(self, event_type, handler=None):
         if handler is None:
@@ -73,9 +84,13 @@ class AgentClient:
             seen.add(handler)
             handlers.append(handler)
         for handler in handlers:
+            handler_name = getattr(handler, "__name__", handler.__class__.__name__)
+            self.debug_stream("handler_begin", event, handler=handler_name)
             try:
                 handler(event)
+                self.debug_stream("handler_done", event, handler=handler_name)
             except Exception as exc:
+                self.debug_stream("handler_error", event, handler=handler_name, error=str(exc))
                 if event_type != "client_event_error":
                     self.emit_local({"type": "client_event_error", "error": str(exc), "event": event_type})
         return event
@@ -89,7 +104,9 @@ class AgentClient:
 
     def _enqueue_local(self, event):
         self._start_dispatch_thread()
-        self._local_event_queue.put(modict(event))
+        event = modict(event)
+        self.debug_stream("queue_put", event, queue_size=self._local_event_queue.qsize())
+        self._local_event_queue.put(event)
         return event
 
     def _dispatch_loop(self):
@@ -102,7 +119,13 @@ class AgentClient:
                 continue
             if event is None:
                 break
-            self.emit_local(event)
+            self.debug_stream("dispatch_begin", event, queue_size=self._local_event_queue.qsize())
+            try:
+                self.emit_local(event)
+                self.debug_stream("dispatch_done", event, queue_size=self._local_event_queue.qsize())
+            except Exception as exc:
+                self.debug_stream("dispatch_error", event, error=str(exc), queue_size=self._local_event_queue.qsize())
+                raise
 
     def start_events(self):
         if self._event_thread and self._event_thread.is_alive():
@@ -226,11 +249,14 @@ class AgentClient:
                     self._set_server_connected()
                     stream_ended = True
                     try:
-                        for event in self.iter_sse(response.iter_lines(chunk_size=1, decode_unicode=True)):
+                        # Keep SSE latency low for interactive streams without
+                        # falling back to the old byte-by-byte reader.
+                        for event in self.iter_sse(response.iter_lines(chunk_size=16, decode_unicode=True)):
                             if self._event_stop.is_set():
                                 stream_ended = False
                                 break
                             self._record_event_stream_activity()
+                            self.debug_stream("sse_received", event)
                             self.remember_event_sequence(event)
                             self._enqueue_local(event)
                     finally:
@@ -324,6 +350,8 @@ class AgentClient:
             self._last_event_sequence = sequence
     def events_url(self):
         params = {"client_pid": int(self.client_pid)}
+        if self.compact_events:
+            params["compact"] = 1
         if self._last_event_sequence is not None:
             params["after_sequence"] = int(self._last_event_sequence)
         return self.url(f"/events?{urlencode(params)}")
@@ -437,6 +465,8 @@ class AgentClient:
     def replay_events(self, before_sequence=None, session_id=None):
         path = "/events/replay"
         params = {}
+        if self.compact_events:
+            params["compact"] = 1
         if before_sequence is not None:
             params["before_sequence"] = int(before_sequence)
         if session_id:

{codex_agent_framework-0.1.55 → codex_agent_framework-0.1.56}/codex_agent/server/app.py

@@ -1,5 +1,7 @@
 import json
 
+from modict import modict
+
 from ..agent import Agent
 from ..version import __version__
 from ..agent_runtime import InProcessAgentRuntime, ProcessAgentRuntime
@@ -61,6 +63,22 @@ def create_app(agent: Agent | None = None, start_agent=False, process_agent=Fals
     def jsonable(value):
         return json.loads(json.dumps(value, ensure_ascii=False, default=str))
 
+    def compact_event_payload(payload, *, max_content_chars=2_000):
+        payload = modict(jsonable(payload))
+        event_type = payload.get("type")
+        if event_type in {"tool_call_done_event", "slash_command_done_event"}:
+            content_key = "content" if "content" in payload else "result" if "result" in payload else None
+            if content_key is not None:
+                content = "" if payload.get(content_key) is None else str(payload.get(content_key))
+                if len(content) > max_content_chars:
+                    payload[f"{content_key}_truncated"] = True
+                    payload[f"{content_key}_full_length"] = len(content)
+                    payload[content_key] = content[:max_content_chars] + "\n… truncated for compact event stream …"
+        return payload
+
+    def event_payload(payload, compact=False):
+        return compact_event_payload(payload) if compact else payload
+
     def busy_guard(call):
         try:
             return call()
@@ -162,7 +180,7 @@ def create_app(agent: Agent | None = None, start_agent=False, process_agent=Fals
         return jsonable(service.interrupt(request.reason))
 
     @app.get("/events")
-    def events(limit: int | None = None, after_sequence: int | None = None, client_pid: int | None = None):
+    def events(limit: int | None = None, after_sequence: int | None = None, client_pid: int | None = None, compact: bool = False):
         try:
             subscription = service.subscribe(after_sequence=after_sequence, client_pid=client_pid)
         except RuntimeError as exc:
@@ -171,6 +189,7 @@ def create_app(agent: Agent | None = None, start_agent=False, process_agent=Fals
         def stream():
             count = 0
             for payload in subscription:
+                payload = event_payload(payload, compact=compact)
                 lines = []
                 if payload.get("id"):
                     lines.append(f"id: {payload.id}")
@@ -183,8 +202,12 @@ def create_app(agent: Agent | None = None, start_agent=False, process_agent=Fals
         return StreamingResponse(stream(), media_type="text/event-stream")
 
     @app.get("/events/replay")
-    def replay_events(before_sequence: int | None = None, session_id: str | None = None):
-        return jsonable(service.replay_events(before_sequence=before_sequence, session_id=session_id))
+    def replay_events(before_sequence: int | None = None, session_id: str | None = None, compact: bool = False):
+        replay = service.replay_events(before_sequence=before_sequence, session_id=session_id)
+        if compact:
+            replay = modict(replay)
+            replay.events = [compact_event_payload(event) for event in replay.get("events") or []]
+        return jsonable(replay)
 
     return app
 

{codex_agent_framework-0.1.55 → codex_agent_framework-0.1.56}/codex_agent/tui/app.py

@@ -6,9 +6,10 @@ from textual.events import Resize
 from textual.widgets import Footer, Static, TextArea
 
 from .lifecycle import clear_tui, install_tui_cleanup_handlers
-from .log import SelectableRichLog
+from .perf import TuiPerfMonitor
+from .stream_debug import TuiStreamDebugLog
 from .style import CHAT_CSS
-from .transcript import TranscriptRenderer
+from .widgets import ConversationTimeline
 
 
 def composer_height(text):
@@ -33,20 +34,13 @@ class AgentTextualApp(App):
         super().__init__(**kwargs)
         self.chat = chat
         self.mouse_mode_hint = mouse_mode_hint
-        self.transcript_renderer = None
         self._live_delta_flush_scheduled = False
+        self.perf = TuiPerfMonitor()
+        self.stream_debug = TuiStreamDebugLog()
 
     def compose(self) -> ComposeResult:
         with Vertical(id="main"):
-            yield SelectableRichLog(
-                id="conversation",
-                wrap=True,
-                highlight=False,
-                markup=True,
-                on_scroll_top=self.load_older_transcript,
-                on_resize=lambda: self.handle_terminal_resize(log_resized=True),
-                right_padding=6,
-            )
+            yield ConversationTimeline(id="conversation")
             yield Static("", id="status")
             yield TextArea(
                 "",
@@ -59,29 +53,26 @@ class AgentTextualApp(App):
 
     def on_mount(self):
         self.chat.app = self
-        self.transcript_renderer = TranscriptRenderer(self.chat, self)
+        self.chat.client.stream_debug = self.stream_debug
+        self.stream_debug.record("tui_mount")
         install_tui_cleanup_handlers()
         self.chat.attach()
         self.chat.client.start_events()
         self.refresh_status()
         self.resize_input()
         self.query_one("#input", TextArea).focus()
+        self.set_interval(1.0, self.write_perf_snapshot)
         self.write_info(f"Codex Agent client ready - {self.mouse_mode_hint}")
 
     def on_resize(self, event: Resize):
         self.handle_terminal_resize()
 
     def handle_terminal_resize(self, *, log_resized=False):
-        if getattr(self, "transcript_renderer", None) is None:
-            return
-        log = self.query_one("#conversation", SelectableRichLog)
-        if not log_resized:
-            log.invalidate_layout()
-        self.render_transcript(keep_scroll=True)
         self.resize_input()
         self.refresh_status()
 
     def on_unmount(self):
+        self.stream_debug.record("tui_unmount")
         clear_tui(pid=os.getpid())
 
     def action_quit(self):
@@ -113,7 +104,7 @@ class AgentTextualApp(App):
 
     def action_clear(self):
         self.chat.transcript.clear()
-        self.query_one("#conversation", SelectableRichLog).clear()
+        self.conversation.clear_messages()
         self.write_info("screen cleared - session history preserved")
         self.refresh_status()
 
@@ -150,77 +141,113 @@ class AgentTextualApp(App):
         finally:
             self.call_from_thread(self.refresh_status)
 
+    @property
+    def conversation(self):
+        return self.query_one("#conversation", ConversationTimeline)
+
     def render_transcript(self, *, keep_scroll=False):
-        self.transcript_renderer.render(keep_scroll=keep_scroll)
+        # The widget timeline is updated incrementally. This method remains as a
+        # compatibility shim for older call sites during the migration.
+        return None
 
     def begin_transcript_batch(self):
-        self.transcript_renderer.begin_batch()
+        return None
 
     def end_transcript_batch(self):
-        self.transcript_renderer.end_batch()
+        return None
 
     def load_older_transcript(self):
-        self.transcript_renderer.load_older()
+        return None
 
     def write_user(self, prompt):
         self.chat.transcript.append_user(prompt, self.chat.username())
-        self.render_transcript()
+        self.conversation.add_user(prompt, title=self.chat.username())
 
     def ensure_agent_role(self, name=None):
-        if self.chat.transcript.ensure_agent(name or self.chat.agent_name()):
-            self.render_transcript()
+        self.chat.transcript.ensure_agent(name or self.chat.agent_name())
+        return self.conversation.ensure_active_assistant(title=name or self.chat.agent_name())
 
     def write_agent_start(self, name):
         self.chat.begin_turn_rendering()
 
     def start_agent_step(self):
         self.chat.transcript.begin_step()
-        self.render_transcript()
 
     def write_agent_delta(self, delta):
+        self.stream_debug.record("ui_render_delta_begin", delta_len=len(str(delta or "")))
+        self.perf.count("write_agent_delta")
+        self.perf.count("write_agent_delta_chars", len(str(delta or "")))
+        with self.perf.timed("write_agent_delta"):
+            self.ensure_agent_role()
+            self.chat.transcript.apply_agent_delta(delta)
+            self.chat.transcript.step_had_content = True
+            self.conversation.append_assistant_delta(delta, title=self.chat.agent_name())
+        self.stream_debug.record("ui_render_delta_done", delta_len=len(str(delta or "")), live_chars=len(self.conversation._active_assistant_text))
+
+    def write_agent_message(self, content):
         self.ensure_agent_role()
-        previous_text = self.chat.transcript.agent_buffer
-        self.chat.transcript.apply_agent_delta(delta)
-        self.chat.transcript.step_had_content = True
-        if not self.transcript_renderer.update_last_agent(delta, previous_text):
-            self.render_transcript()
+        self.chat.transcript.agent_buffer = str(content or "")
+        if self.chat.transcript.entries and self.chat.transcript.entries[-1].kind == "agent":
+            self.chat.transcript.entries[-1].text = self.chat.transcript.agent_buffer
+        self.conversation.add_assistant_message(content, title=self.chat.agent_name())
 
     def schedule_agent_delta_flush(self):
+        self.perf.count("schedule_agent_delta_flush")
         if self._live_delta_flush_scheduled:
             return
         self._live_delta_flush_scheduled = True
         self.set_timer(self.chat.live_delta.interval, self.flush_agent_delta)
 
     def flush_agent_delta(self):
-        self._live_delta_flush_scheduled = False
-        delta = self.chat.live_delta.pop()
-        if delta:
-            self.write_agent_delta(delta)
+        self.perf.count("flush_agent_delta")
+        with self.perf.timed("flush_agent_delta"):
+            self._live_delta_flush_scheduled = False
+            delta = self.chat.live_delta.pop()
+            if delta:
+                self.write_agent_delta(delta)
 
     def write_tool(self, name, call_id=None, status=None):
         self.flush_agent_delta()
-        self.ensure_agent_role()
+        self.conversation.commit_active_assistant_preview()
         self.chat.transcript.append_tool(name, call_id=call_id, status=status)
-        self.render_transcript()
+        self.conversation.add_tool(name, call_id=call_id, status=status)
 
     def write_slash_command(self, name, args="", status=None):
         self.flush_agent_delta()
-        self.ensure_agent_role()
+        self.conversation.commit_active_assistant_preview()
         self.chat.transcript.append_slash_command(name, args=args, status=status)
-        self.render_transcript()
+        self.conversation.add_slash_command(name, args=args, status=status)
 
     def end_agent_step(self):
         self.flush_agent_delta()
+        self.conversation.commit_active_assistant_preview()
         self.chat.transcript.end_step()
-        self.render_transcript()
+        self.conversation.add_step_separator()
 
     def write_info(self, text):
         self.chat.transcript.append_info(text)
-        self.render_transcript()
+        self.conversation.add_info(text)
 
     def write_error(self, text):
         self.chat.transcript.append_error(text)
-        self.render_transcript()
+        self.conversation.add_error(text)
 
     def refresh_status(self):
-        self.query_one("#status", Static).update(self.chat.status_renderable())
+        self.perf.count("refresh_status")
+        with self.perf.timed("refresh_status"):
+            self.query_one("#status", Static).update(self.chat.status_renderable())
+
+    def write_perf_snapshot(self):
+        client = self.chat.client
+        queue_obj = getattr(client, "_local_event_queue", None)
+        extra = {
+            "entries": len(self.chat.transcript.entries),
+            "live_buffer_chars": len(self.conversation._active_assistant_text),
+            "pending_live_delta_chars": len(self.chat.live_delta.text),
+            "last_event_sequence": getattr(client, "_last_event_sequence", None),
+            "event_queue_size": queue_obj.qsize() if queue_obj is not None else None,
+            "event_stream_connected": getattr(client, "_event_stream_connected", None),
+            "live_delta_flush_scheduled": self._live_delta_flush_scheduled,
+        }
+        self.perf.write_snapshot(extra=extra)
+        self.stream_debug.record("tui_heartbeat", **extra)

{codex_agent_framework-0.1.55 → codex_agent_framework-0.1.56}/codex_agent/tui/chat.py

@@ -47,7 +47,7 @@ class Chat:
     """Textual-based chat UI client for a codex-agent server."""
 
     def __init__(self, client=None, base_url="http://127.0.0.1:8765"):
-        self.client = client or AgentClient(base_url=base_url)
+        self.client = client or AgentClient(base_url=base_url, compact_events=True)
         self.app = None
         self.view = TuiAppBridge(self)
         self.deduper = DisplayDeduper()
@@ -233,6 +233,9 @@ class Chat:
         message = event.get("message") or {}
         if message.get("type") == "user_message":
             self.view.write_user(str(message.get("content") or ""))
+        elif message.get("type") == "assistant_message":
+            self._flush_live_delta()
+            self.view.write_agent_message(str(message.get("content") or ""))
         self.view.refresh_status()
 
     def _on_assistant_turn_start(self, event):

codex_agent_framework-0.1.56/codex_agent/tui/perf.py

@@ -0,0 +1,73 @@
+import json
+import os
+import time
+from contextlib import contextmanager
+from pathlib import Path
+
+
+class TuiPerfMonitor:
+    """Tiny in-process profiler for diagnosing TUI stream stalls.
+
+    The monitor keeps only counters and cumulative timings in memory, then writes
+    an atomic JSON snapshot. It is intentionally small enough to leave enabled
+    during local debugging without needing ptrace/py-spy access.
+    """
+
+    def __init__(self, path=None):
+        self.path = Path(path or os.path.expanduser("~/.codex-agent/tui-perf.json"))
+        self.started_at = time.monotonic()
+        self.reset_window()
+
+    def reset_window(self):
+        self.window_started_at = time.monotonic()
+        self.counts = {}
+        self.timings = {}
+        self.last = {}
+
+    def count(self, name, value=1):
+        self.counts[name] = self.counts.get(name, 0) + value
+
+    def set_last(self, name, value):
+        self.last[name] = value
+
+    @contextmanager
+    def timed(self, name):
+        start = time.perf_counter()
+        try:
+            yield
+        finally:
+            elapsed = time.perf_counter() - start
+            total, count, max_elapsed = self.timings.get(name, (0.0, 0, 0.0))
+            self.timings[name] = (total + elapsed, count + 1, max(max_elapsed, elapsed))
+
+    def snapshot(self, extra=None):
+        now = time.monotonic()
+        window_seconds = max(1e-9, now - self.window_started_at)
+        timings = {}
+        for name, (total, count, max_elapsed) in self.timings.items():
+            timings[name] = {
+                "count": count,
+                "total_ms": round(total * 1000, 3),
+                "avg_ms": round((total / count) * 1000, 3) if count else 0.0,
+                "max_ms": round(max_elapsed * 1000, 3),
+            }
+        return {
+            "pid": os.getpid(),
+            "uptime_seconds": round(now - self.started_at, 3),
+            "window_seconds": round(window_seconds, 3),
+            "rates_per_second": {key: round(value / window_seconds, 3) for key, value in self.counts.items()},
+            "counts": dict(self.counts),
+            "timings": timings,
+            "last": dict(self.last),
+            "extra": dict(extra or {}),
+        }
+
+    def write_snapshot(self, extra=None, *, reset=True):
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = self.snapshot(extra=extra)
+        tmp_path = self.path.with_suffix(self.path.suffix + ".tmp")
+        tmp_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
+        tmp_path.replace(self.path)
+        if reset:
+            self.reset_window()
+        return payload

{codex_agent_framework-0.1.55 → codex_agent_framework-0.1.56}/codex_agent/tui/state.py

@@ -1,5 +1,13 @@
 class LiveDeltaBuffer:
-    def __init__(self, interval=1 / 60):
+    """Coalesce live text deltas before touching the Textual render loop.
+
+    Human-readable terminal text does not benefit from display-refresh-rate
+    updates, and high-frequency flushes can overwhelm Textual during bursty
+    model streams. Twenty frames per second keeps the UI feeling live while
+    leaving enough breathing room for input, health checks, and repaint work.
+    """
+
+    def __init__(self, interval=1 / 20):
         self.interval = interval
         self.text = ""
         self.flush_requested = False
@@ -59,8 +67,29 @@ class TuiAppBridge:
             return None
         if self.app is None:
             return None
+        perf = getattr(self.app, "perf", None)
+        if perf is not None:
+            perf.count("bridge_call_from_thread")
+            perf.count(f"bridge_call_from_thread.{method}")
+        stream_debug = getattr(self.app, "stream_debug", None)
+        if stream_debug is not None:
+            stream_debug.record("bridge_schedule", method=method, args_count=len(args))
         callback = getattr(self.app, method)
-        return self.app.call_from_thread(callback, *args)
+
+        def traced_callback(*callback_args):
+            if stream_debug is not None:
+                stream_debug.record("ui_callback_begin", method=method, args_count=len(callback_args))
+            try:
+                result = callback(*callback_args)
+                if stream_debug is not None:
+                    stream_debug.record("ui_callback_done", method=method, args_count=len(callback_args))
+                return result
+            except Exception as exc:
+                if stream_debug is not None:
+                    stream_debug.record("ui_callback_error", method=method, error=str(exc), args_count=len(callback_args))
+                raise
+
+        return self.app.call_from_thread(traced_callback, *args)
 
     def refresh_status(self):
         return self.call("refresh_status", skip_during_replay=True)
@@ -92,6 +121,9 @@ class TuiAppBridge:
     def write_agent_delta(self, delta):
         return self.call("write_agent_delta", delta)
 
+    def write_agent_message(self, content):
+        return self.call("write_agent_message", content)
+
     def write_tool(self, name, call_id=None, status=None):
         return self.call("write_tool", name, call_id, status)
 

codex_agent_framework-0.1.56/codex_agent/tui/stream_debug.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+from pathlib import Path
+
+
+class TuiStreamDebugLog:
+    """Append-only black-box log for intermittent TUI stream stalls.
+
+    The file is intentionally outside the Textual render path and is flushed on
+    every record. When the UI stops updating but the process stays alive, the
+    last records should reveal whether events stopped at SSE receive, queue,
+    dispatch, bridge scheduling, or actual widget rendering.
+    """
+
+    def __init__(self, path=None, *, max_bytes=5_000_000):
+        self.path = Path(path or os.path.expanduser("~/.codex-agent/tui-stream-debug.jsonl"))
+        self.max_bytes = int(max_bytes or 0)
+        self._lock = threading.Lock()
+        self._started_at = time.monotonic()
+
+    def record(self, stage, event=None, **fields):
+        payload = {
+            "ts": round(time.time(), 6),
+            "monotonic": round(time.monotonic(), 6),
+            "uptime": round(time.monotonic() - self._started_at, 6),
+            "pid": os.getpid(),
+            "thread": threading.current_thread().name,
+            "stage": str(stage),
+        }
+        payload.update(self.event_fields(event))
+        payload.update(fields)
+        line = json.dumps(payload, ensure_ascii=False, default=str, sort_keys=True)
+        with self._lock:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self._trim_if_needed()
+            with self.path.open("a", encoding="utf-8") as handle:
+                handle.write(line + "\n")
+                handle.flush()
+        return payload
+
+    def event_fields(self, event):
+        if not isinstance(event, dict):
+            return {}
+        payload = {
+            "event_type": event.get("type"),
+            "event_id": event.get("id"),
+            "sequence": event.get("sequence"),
+        }
+        if "delta" in event:
+            payload["delta_len"] = len(str(event.get("delta") or ""))
+        if "content" in event:
+            payload["content_len"] = len(str(event.get("content") or ""))
+            payload["content_truncated"] = bool(event.get("content_truncated"))
+            payload["content_full_length"] = event.get("content_full_length")
+        message = event.get("message")
+        if isinstance(message, dict):
+            payload["message_type"] = message.get("type")
+            payload["message_content_len"] = len(str(message.get("content") or ""))
+        tool_call = event.get("tool_call")
+        if isinstance(tool_call, dict):
+            payload["tool_name"] = tool_call.get("name")
+            payload["tool_call_id"] = tool_call.get("call_id")
+        if "error" in event:
+            payload["error"] = str(event.get("error") or "")[:500]
+        return payload
+
+    def _trim_if_needed(self):
+        if self.max_bytes <= 0 or not self.path.exists():
+            return
+        try:
+            if self.path.stat().st_size <= self.max_bytes:
+                return
+            data = self.path.read_bytes()[-self.max_bytes // 2:]
+            first_newline = data.find(b"\n")
+            if first_newline >= 0:
+                data = data[first_newline + 1:]
+            self.path.write_bytes(data)
+        except Exception:
+            # Debug logging must never break the TUI.
+            return