aru-code 0.52.0__tar.gz → 0.53.0__tar.gz

{aru_code-0.52.0/aru_code.egg-info → aru_code-0.53.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aru-code
-Version: 0.52.0
+Version: 0.53.0
 Summary: A Claude Code clone built with Agno agents
 Author-email: Estevao <estevaofon@gmail.com>
 License-Expression: MIT

aru_code-0.53.0/aru/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.53.0"

aru_code-0.53.0/aru/_debug/__init__.py

@@ -0,0 +1,6 @@
+"""Debug instrumentation package — gated by env vars, zero cost when off.
+
+See ``loop_tracer.py`` for the Ctrl+C / loop-saturation tracer
+(``ARU_DEBUG_LOOP=1``). New tracers go here as siblings; each owns its
+own env var and log file under ``~/.aru/``.
+"""

aru_code-0.53.0/aru/_debug/analyze_trace.py

@@ -0,0 +1,328 @@
+"""Analyze ``~/.aru/loop-trace.log`` and answer the decision tree from
+``docs/aru/2026-04-30-ctrlc-streaming-plan.md`` Fase 3.
+
+Usage::
+
+    python -m aru._debug.analyze_trace [path]
+
+Default path: ``~/.aru/loop-trace.log``. Pass an explicit path to
+analyse a different file (e.g. one shipped from another machine).
+
+The analyser is intentionally simple — `awk`-style line parsing,
+bucketed counters, and a fixed set of questions. Any pattern more
+complex than what this script captures should be added as a new
+section here, not a separate ad-hoc script.
+
+Output sections:
+
+  STATISTICS  — summary of every event kind that appeared, with
+                count and (where relevant) max duration.
+  HOTSPOTS    — top-10 ``loop_blocked`` entries sorted by gap.
+  CTRL_C      — for each Ctrl+C key press detected at
+                ``driver.process_message``, the latency to
+                ``app._post_message`` and ``action_ctrl_c``.
+  VERDICT     — direct readout of the decision tree (P1/P2/P3 or
+                continue-investigating).
+
+Designed to be idempotent and zero-side-effect — never writes back to
+the log.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from collections import defaultdict
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Event:
+    ts_ms: int
+    thread: str
+    name: str
+    detail: str
+
+    @classmethod
+    def parse(cls, line: str) -> "Event | None":
+        if line.startswith("#") or not line.strip():
+            return None
+        parts = line.rstrip("\n").split(",", 3)
+        if len(parts) < 3:
+            return None
+        try:
+            ts = int(parts[0])
+        except ValueError:
+            return None
+        thread = parts[1]
+        name = parts[2]
+        detail = parts[3] if len(parts) > 3 else ""
+        return cls(ts_ms=ts, thread=thread, name=name, detail=detail)
+
+
+def _parse_kv(detail: str) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for tok in detail.split():
+        if "=" in tok:
+            k, _, v = tok.partition("=")
+            out[k] = v
+    return out
+
+
+def _detail_int(detail: str, key: str) -> int | None:
+    kv = _parse_kv(detail)
+    if key not in kv:
+        return None
+    try:
+        return int(float(kv[key]))
+    except ValueError:
+        return None
+
+
+@dataclass
+class Stats:
+    counts: dict[str, int] = field(default_factory=lambda: defaultdict(int))
+    max_gap_ms_loop: int = 0
+    loop_blocked_top: list[Event] = field(default_factory=list)
+    finalize_render_max_ms: int = 0
+    finalize_render_calls: int = 0
+    finalize_render_total_ms: int = 0
+    stream_bursts: list[Event] = field(default_factory=list)
+    ctrl_c_press: list[Event] = field(default_factory=list)
+    post_messages_ctrl_c: list[Event] = field(default_factory=list)
+    action_ctrl_c: list[Event] = field(default_factory=list)
+
+
+def _is_ctrl_c(detail: str) -> bool:
+    kv = _parse_kv(detail)
+    return kv.get("key") == "ctrl+c"
+
+
+def collect(events: list[Event]) -> Stats:
+    s = Stats()
+    for e in events:
+        s.counts[e.name] += 1
+        if e.name == "loop_blocked":
+            gap = _detail_int(e.detail, "gap_ms") or 0
+            s.max_gap_ms_loop = max(s.max_gap_ms_loop, gap)
+            s.loop_blocked_top.append(e)
+        elif e.name == "loop_tick":
+            gap = _detail_int(e.detail, "gap_ms") or 0
+            s.max_gap_ms_loop = max(s.max_gap_ms_loop, gap)
+        elif e.name == "finalize_render":
+            dt = _detail_int(e.detail, "dt_ms") or 0
+            s.finalize_render_calls += 1
+            s.finalize_render_total_ms += dt
+            s.finalize_render_max_ms = max(s.finalize_render_max_ms, dt)
+        elif e.name == "stream.event_burst":
+            s.stream_bursts.append(e)
+        elif e.name == "driver.process_message":
+            if _is_ctrl_c(e.detail):
+                s.ctrl_c_press.append(e)
+        elif e.name == "app._post_message":
+            if _is_ctrl_c(e.detail):
+                s.post_messages_ctrl_c.append(e)
+        elif e.name == "action_ctrl_c":
+            s.action_ctrl_c.append(e)
+
+    s.loop_blocked_top.sort(
+        key=lambda e: _detail_int(e.detail, "gap_ms") or 0, reverse=True
+    )
+    s.loop_blocked_top = s.loop_blocked_top[:10]
+    return s
+
+
+def _correlate_ctrl_c(s: Stats) -> list[dict]:
+    """Match each ``driver.process_message ctrl+c`` to the next
+    ``app._post_message ctrl+c`` and ``action_ctrl_c`` after it.
+
+    Returns one dict per press with latencies in ms.
+    """
+    out: list[dict] = []
+    for press in s.ctrl_c_press:
+        next_post = next(
+            (p for p in s.post_messages_ctrl_c if p.ts_ms >= press.ts_ms),
+            None,
+        )
+        next_action = next(
+            (a for a in s.action_ctrl_c if a.ts_ms >= press.ts_ms),
+            None,
+        )
+        out.append(
+            {
+                "press_ms": press.ts_ms,
+                "thread_seen": press.thread,
+                "post_lag_ms": (
+                    next_post.ts_ms - press.ts_ms if next_post else None
+                ),
+                "action_lag_ms": (
+                    next_action.ts_ms - press.ts_ms if next_action else None
+                ),
+            }
+        )
+    return out
+
+
+def _verdict(s: Stats, presses: list[dict]) -> list[str]:
+    out: list[str] = []
+    if not presses:
+        out.append("No Ctrl+C key events recorded.")
+        out.append("-> Either the user did not press Ctrl+C during this trace,")
+        out.append("  or the Textual input thread (P1) is wedged before")
+        out.append("  ``Driver.process_message`` is reached. If the user did")
+        out.append("  press Ctrl+C: P1 — investigate EventMonitor / ConIn read.")
+        return out
+
+    for i, p in enumerate(presses, 1):
+        out.append(f"Press #{i} at ts={p['press_ms']}ms (thread={p['thread_seen']}):")
+        post = p["post_lag_ms"]
+        action = p["action_lag_ms"]
+
+        if post is None:
+            out.append(
+                "  P2/P3 — driver saw the key, but ``app._post_message`` "
+                "never fired."
+            )
+            out.append(
+                "  -> loop saturated for the rest of the trace. Look at "
+                "loop_blocked HOTSPOTS at this timestamp."
+            )
+            continue
+
+        out.append(f"  press -> app._post_message: {post}ms")
+        if post > 500:
+            out.append(
+                "  P2 — loop took >500ms to drain the posted callback. "
+                "Saturation is the dominant cause."
+            )
+        elif post > 50:
+            out.append(
+                "  Borderline — pump latency >50ms; check loop_blocked "
+                "near this timestamp."
+            )
+        else:
+            out.append("  pump latency healthy.")
+
+        if action is None:
+            out.append(
+                "  P3 — pump received but action_ctrl_c never dispatched. "
+                "Check Screen.dispatch."
+            )
+            continue
+        out.append(f"  press -> action_ctrl_c:    {action}ms")
+        if action > 500:
+            out.append(
+                "  P3 — pump dispatch is the bottleneck (likely behind a "
+                "queue of expensive events)."
+            )
+        elif action - (post or 0) > 100:
+            out.append(
+                "  Pump->action handoff is slow; suspect heavy event "
+                "ahead of Key in the queue."
+            )
+
+    return out
+
+
+def _suggest_fix(s: Stats) -> list[str]:
+    out: list[str] = []
+    if s.finalize_render_max_ms > 200:
+        out.append(
+            f"finalize_render max {s.finalize_render_max_ms}ms across "
+            f"{s.finalize_render_calls} calls "
+            f"(total {s.finalize_render_total_ms}ms)."
+        )
+        out.append(
+            "-> C3 candidate: move finalize_render off-thread "
+            "(asyncio.to_thread). One-file change in chat.py."
+        )
+
+    fast_bursts = [
+        b
+        for b in s.stream_bursts
+        if (_detail_int(b.detail, "dt_ms") or 999) < 5
+    ]
+    if fast_bursts:
+        out.append(
+            f"{len(fast_bursts)} stream bursts of 16 events in <5ms — "
+            f"hot-loop without yield."
+        )
+        out.append(
+            "-> C1 candidate: ``await asyncio.sleep(0)`` every N events "
+            "in streaming.py. One-line change."
+        )
+
+    if not out:
+        out.append(
+            "No obvious culprit in C1/C3. New round of instrumentation "
+            "needed (Compositor render hooks, paint cost)."
+        )
+    return out
+
+
+def main(argv: list[str]) -> int:
+    # Windows cp1252 stdout chokes on em-dashes / arrows in our prose
+    # — switch to UTF-8 so the analyser can run anywhere without
+    # truncating the report.
+    try:
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")  # type: ignore[attr-defined]
+    except Exception:
+        pass
+    path = argv[1] if len(argv) > 1 else os.path.expanduser("~/.aru/loop-trace.log")
+    if not os.path.exists(path):
+        print(f"trace file not found: {path}", file=sys.stderr)
+        return 2
+    with open(path, encoding="utf-8") as fh:
+        events = []
+        for line in fh:
+            ev = Event.parse(line)
+            if ev is not None:
+                events.append(ev)
+
+    if not events:
+        print("trace file has no events", file=sys.stderr)
+        return 2
+
+    s = collect(events)
+    presses = _correlate_ctrl_c(s)
+
+    print("=" * 72)
+    print(f"Trace: {path}")
+    print(f"Events: {len(events)}  ({events[0].ts_ms}ms -> {events[-1].ts_ms}ms)")
+    print("=" * 72)
+
+    print("\n--- STATISTICS ---")
+    for name in sorted(s.counts):
+        print(f"  {name:<32} {s.counts[name]}")
+    print(f"  max loop gap:                  {s.max_gap_ms_loop}ms")
+    print(
+        f"  finalize_render: max={s.finalize_render_max_ms}ms  "
+        f"total={s.finalize_render_total_ms}ms  "
+        f"calls={s.finalize_render_calls}"
+    )
+
+    print("\n--- HOTSPOTS (top 10 loop_blocked) ---")
+    for e in s.loop_blocked_top:
+        print(f"  ts={e.ts_ms:>8}ms  thread={e.thread:<20}  {e.detail}")
+
+    print("\n--- CTRL_C ---")
+    for p in presses:
+        print(
+            f"  ts={p['press_ms']:>8}ms  "
+            f"post_lag={p['post_lag_ms']}ms  "
+            f"action_lag={p['action_lag_ms']}ms"
+        )
+
+    print("\n--- VERDICT ---")
+    for line in _verdict(s, presses):
+        print(f"  {line}")
+
+    print("\n--- SUGGESTED FIX ---")
+    for line in _suggest_fix(s):
+        print(f"  {line}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

aru_code-0.53.0/aru/_debug/loop_tracer.py

@@ -0,0 +1,329 @@
+"""Loop-saturation tracer for Ctrl+C-during-streaming investigation.
+
+Activate with ``ARU_DEBUG_LOOP=1``. When off, every entry point is a
+single ``if not _ENABLED: return`` so production cost is one branch.
+
+Output: ``~/.aru/loop-trace.log`` — append-only CSV with one event per
+line, columns ``timestamp_ms,thread,event,detail``. Suitable for
+``awk`` / pandas / spreadsheet import without parsing.
+
+Six instrumentation points (see ``docs/aru/2026-04-30-ctrlc-streaming-plan.md``
+Fase 1):
+
+  A. ``loop_tick`` / ``loop_blocked`` — heartbeat scheduled on the
+     main asyncio loop at 20 Hz. Gap > 200 ms yields a ``loop_blocked``
+     entry — direct evidence the loop was unable to drain a callback
+     for that long, regardless of why.
+
+  B. ``driver.process_message`` — every message the Textual input
+     thread parses, before it's posted to the App pump. Confirms the
+     input thread is alive and saw the keystroke. Logged from the
+     ``textual-input`` thread.
+
+  C. ``app._post_message`` — every message the App pump dequeues.
+     Confirms the ``run_coroutine_threadsafe`` callback that B
+     scheduled actually drained on the loop. Logged from the loop
+     thread.
+
+  D. ``action_ctrl_c`` — entry of the App's Ctrl+C handler. Confirms
+     binding dispatch reached our action.
+
+  E. ``stream.event_burst`` — sampled every N events inside the
+     ``async for event in agent.arun(...)`` loop. Detects rajadas of
+     events arriving without a yield between them.
+
+  F. ``finalize_render`` — duration of the synchronous full-buffer
+     markdown re-parse on the loop thread.
+
+Also exposed: ``trace(event, detail)`` so ad-hoc probes can be added
+during diagnosis without recompiling.
+"""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from typing import Any
+
+# ── Activation gate ──────────────────────────────────────────────────
+
+_ENABLED: bool = bool(os.environ.get("ARU_DEBUG_LOOP"))
+
+
+def is_enabled() -> bool:
+    return _ENABLED
+
+
+# ── File handle (lazy, line-buffered) ────────────────────────────────
+
+_TRACE_PATH: str = os.path.expanduser("~/.aru/loop-trace.log")
+_LOCK = threading.Lock()
+_FILE: Any = None
+_T0: float = time.monotonic()
+
+
+def _now_ms() -> int:
+    return int((time.monotonic() - _T0) * 1000)
+
+
+def trace(event: str, detail: str = "") -> None:
+    """Append one event to the trace log. No-op when disabled.
+
+    Format: ``ts_ms,thread,event,detail\\n``. Detail is allowed to
+    contain commas — analysis tools should split on the first three
+    commas only.
+    """
+    if not _ENABLED:
+        return
+    try:
+        ts_ms = _now_ms()
+        thread = threading.current_thread().name
+        line = f"{ts_ms},{thread},{event},{detail}\n"
+        with _LOCK:
+            global _FILE
+            if _FILE is None:
+                os.makedirs(os.path.dirname(_TRACE_PATH), exist_ok=True)
+                # Line-buffered so a hard kill still leaves a usable
+                # trace on disk. ``buffering=1`` is line-buffered for
+                # text mode in Python.
+                _FILE = open(_TRACE_PATH, "a", encoding="utf-8", buffering=1)
+                _FILE.write(
+                    f"# === session start === pid={os.getpid()} "
+                    f"t0_monotonic={_T0:.3f}\n"
+                )
+            _FILE.write(line)
+    except Exception:
+        # Never let the tracer crash the app.
+        pass
+
+
+# ── (B/C) Textual monkey-patches ─────────────────────────────────────
+
+_patches_installed = False
+
+
+def install_textual_patches() -> None:
+    """Patch ``Driver.process_message`` and ``App._post_message``.
+
+    Idempotent — only patches once per process. Patches the *class*,
+    so it covers all driver/app instances created later. Safe to call
+    multiple times.
+
+    The patched functions log to the tracer then delegate to the
+    original. They never raise — a buggy tracer must not break the
+    app.
+    """
+    global _patches_installed
+    if not _ENABLED or _patches_installed:
+        return
+    try:
+        from textual.driver import Driver
+        from textual.app import App
+    except Exception:
+        return
+
+    try:
+        _orig_pm = Driver.process_message
+
+        def _patched_pm(self, message):
+            try:
+                trace(
+                    "driver.process_message",
+                    f"type={type(message).__name__} "
+                    f"key={getattr(message, 'key', '-')}",
+                )
+            except Exception:
+                pass
+            return _orig_pm(self, message)
+
+        Driver.process_message = _patched_pm
+    except Exception:
+        pass
+
+    try:
+        _orig_post = App._post_message
+
+        async def _patched_post(self, message):
+            try:
+                trace(
+                    "app._post_message",
+                    f"type={type(message).__name__} "
+                    f"key={getattr(message, 'key', '-')}",
+                )
+            except Exception:
+                pass
+            return await _orig_post(self, message)
+
+        App._post_message = _patched_post
+    except Exception:
+        pass
+
+    # WriterThread.stop instrumentation — investigates the Ctrl+Q
+    # "summary appears but terminal does not release" symptom. ``stop()``
+    # internally does ``put(None) + join()``; if the queue has thousands
+    # of pending writes, ``join()`` blocks until ConPTY drains them all,
+    # which is exactly the wedge shape the user reports.
+    try:
+        from textual.drivers._writer_thread import WriterThread
+        _orig_stop = WriterThread.stop
+
+        def _patched_stop(self):
+            qsize = self._queue.qsize() if hasattr(self._queue, "qsize") else -1
+            trace("writer_thread.stop", f"begin qsize={qsize}")
+            try:
+                return _orig_stop(self)
+            finally:
+                trace("writer_thread.stop", "end")
+
+        WriterThread.stop = _patched_stop
+    except Exception:
+        pass
+
+    # Sniff every WriterThread.write call for escapes that change the
+    # terminal's mode (alt-screen, mouse, bracketed paste, etc.). The
+    # "TUI invadida pelo terminal" symptom is consistent with one of
+    # these escapes leaking from a non-Textual source while mouse
+    # tracking remains enabled. Logging the *issuer* lets us pin which
+    # site sent ``\x1b[?1049l`` (leave alt-screen) at runtime.
+    #
+    # The sniff is pattern-based — only a handful of escapes are
+    # logged, so noise is bounded even at high write rates.
+    try:
+        import re as _re
+        _MODE_RE = _re.compile(
+            r"\x1b\[\?(1049|1000|1003|1006|1015|1004|2004|25)([hl])"
+        )
+        _orig_write = WriterThread.write
+
+        def _patched_write(self, text):
+            try:
+                if isinstance(text, str):
+                    for m in _MODE_RE.finditer(text):
+                        trace(
+                            "term_mode_escape",
+                            f"mode={m.group(1)} action={m.group(2)} "
+                            f"sample={text[max(0, m.start()-8):m.end()+8]!r}",
+                        )
+            except Exception:
+                pass
+            return _orig_write(self, text)
+
+        WriterThread.write = _patched_write
+    except Exception:
+        pass
+
+    _patches_installed = True
+
+
+# ── (A) Heartbeat ────────────────────────────────────────────────────
+
+_heartbeat_state: dict[str, Any] = {"last": 0.0, "running": False}
+
+
+def start_heartbeat(loop) -> None:
+    """Begin a 20 Hz heartbeat on *loop*.
+
+    Each tick measures the wall-clock gap since the previous tick. A
+    healthy loop ticks every ~50 ms (the call_later interval); a
+    saturated loop ticks late, and the gap measures exactly how long
+    the loop was unable to run a callback.
+
+    Gap > 200 ms emits ``loop_blocked``; otherwise ``loop_tick``. The
+    heartbeat keeps itself alive via recursive ``call_later`` and
+    stops when ``stop_heartbeat`` flips the running flag.
+    """
+    if not _ENABLED:
+        return
+    _heartbeat_state["last"] = time.monotonic()
+    _heartbeat_state["running"] = True
+
+    def _tick() -> None:
+        if not _heartbeat_state["running"]:
+            return
+        now = time.monotonic()
+        gap_ms = (now - _heartbeat_state["last"]) * 1000
+        _heartbeat_state["last"] = now
+        if gap_ms > 200:
+            trace("loop_blocked", f"gap_ms={gap_ms:.0f}")
+        else:
+            trace("loop_tick", f"gap_ms={gap_ms:.0f}")
+        try:
+            loop.call_later(0.05, _tick)
+        except Exception:
+            _heartbeat_state["running"] = False
+
+    try:
+        loop.call_later(0.05, _tick)
+    except Exception:
+        _heartbeat_state["running"] = False
+
+
+def stop_heartbeat() -> None:
+    _heartbeat_state["running"] = False
+
+
+# ── (E) Stream hot-loop sampler ──────────────────────────────────────
+
+class StreamSampler:
+    """Sampler used inside ``streaming.run_stream``'s ``async for``.
+
+    Counts events and emits ``stream.event_burst`` every ``every`` ticks
+    with the wall-clock duration since the previous emission. A burst
+    of 16 events in <5 ms means the loop processed 16 events back-to-back
+    with no IO yield — direct evidence of hot-loop saturation.
+
+    Used as a context-light counter (one int + one float per call); the
+    log emission is gated by ``every`` so the trace stays readable.
+    """
+
+    __slots__ = ("_n", "_t0", "_every")
+
+    def __init__(self, every: int = 16) -> None:
+        self._n = 0
+        self._t0 = time.monotonic()
+        self._every = every
+
+    def tick(self, event_kind: str = "") -> None:
+        if not _ENABLED:
+            return
+        self._n += 1
+        if self._n % self._every == 0:
+            now = time.monotonic()
+            dt_ms = (now - self._t0) * 1000
+            trace(
+                "stream.event_burst",
+                f"n={self._n} dt_ms={dt_ms:.0f} kind={event_kind}",
+            )
+            self._t0 = now
+
+
+# ── (F) finalize_render timer (helper) ───────────────────────────────
+
+class TimedSection:
+    """Context manager that logs the duration of a sync block.
+
+    Used in ``finalize_render`` and any other place we suspect of
+    blocking the loop synchronously. Emits ``<event> dt_ms=...`` on
+    exit even if the block raised, so the duration is recorded for
+    both success and failure paths.
+    """
+
+    __slots__ = ("_event", "_detail", "_t0")
+
+    def __init__(self, event: str, detail: str = "") -> None:
+        self._event = event
+        self._detail = detail
+        self._t0 = 0.0
+
+    def __enter__(self) -> "TimedSection":
+        if _ENABLED:
+            self._t0 = time.monotonic()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if not _ENABLED:
+            return
+        dt_ms = (time.monotonic() - self._t0) * 1000
+        suffix = f" exc={exc_type.__name__}" if exc_type is not None else ""
+        trace(self._event, f"{self._detail} dt_ms={dt_ms:.0f}{suffix}")

{aru_code-0.52.0 → aru_code-0.53.0}/aru/streaming.py

@@ -199,11 +199,20 @@ async def run_stream(
     doom_loop_detector = DoomLoopDetector()
     import time as _time
 
+    # Loop-saturation tracer hook (off unless ``ARU_DEBUG_LOOP=1``).
+    # Counts events as they're processed and emits ``stream.event_burst``
+    # periodically so we can detect rajadas with no IO yield in between
+    # — the suspected hot-loop pattern that strands Ctrl+C during
+    # streaming. See ``docs/aru/2026-04-30-ctrlc-streaming-plan.md``.
+    from aru._debug.loop_tracer import StreamSampler as _StreamSampler
+    _stream_sampler = _StreamSampler(every=16)
+
     while True:
         reset_last_stop_reason()
         _stall_counter = 0
 
         async for event in agent.arun(current_input, **arun_kwargs):
+            _stream_sampler.tick(type(event).__name__)
             if isinstance(event, RunOutput):
                 run_output = event
                 state.run_output = event