aru-code 0.44.0__tar.gz → 0.45.0__tar.gz

{aru_code-0.44.0/aru_code.egg-info → aru_code-0.45.0}/PKG-INFO

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

aru_code-0.45.0/aru/__init__.py

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

{aru_code-0.44.0 → aru_code-0.45.0}/aru/tui/app.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 
 import asyncio
 import sys
+import time
 from typing import Any
 
 from textual.app import App, ComposeResult
@@ -256,12 +257,24 @@ class AruApp(App):
         "skills", "agents", "commands", "mcp", "yolo",
     }
 
-    # Layer 10 — interval (seconds) between belt-and-suspenders re-emits of
-    # the mouse-tracking enable sequences. 8s is the worst-case time-to-recover
-    # if a leaked DEC private-mode escape disables the wheel mid-turn; the
-    # cost is ~24 bytes per tick (four idempotent SGR sequences). See
-    # ``on_mount`` and ``_reenable_mouse_tracking`` for context.
-    _MOUSE_REENABLE_INTERVAL: float = 8.0
+    # Layer 10 / 12 — interval (seconds) between belt-and-suspenders re-emits
+    # of the mouse-tracking enable sequences. Was 8s pre-Layer-12; user
+    # report on 2026-04-25 against ``final-fantasy-9/.aru/sessions/b33dfb99``
+    # was that the wheel never came back even after the turn ended in YOLO,
+    # and 8s was visibly long enough that the user gave up before the next
+    # tick. 3s is short enough that a corrupted state self-heals before the
+    # next mouse interaction, and the cost is still ~64 bytes per tick (the
+    # Layer 12 off-then-on shake — see ``_reenable_mouse_tracking``).
+    _MOUSE_REENABLE_INTERVAL: float = 3.0
+
+    # Layer 12 — minimum interval (seconds) between keypress-triggered
+    # mouse-tracking re-arms. Each keystroke is an opportunity to recover
+    # — if the user is typing it might be precisely BECAUSE the wheel just
+    # stopped working — but we don't want a fast typist to turn every
+    # keystroke into four extra terminal writes. 500 ms is below human
+    # noticeable retry latency yet caps the keystroke→write amplification
+    # at ~2 Hz worst case.
+    _KEYPRESS_REARM_DEBOUNCE: float = 0.5
 
     def __init__(
         self,
@@ -288,6 +301,12 @@ class AruApp(App):
         # cleared) by on_input_submitted.
         self._pending_paste: str | None = None
         self._pending_paste_lines: int = 0
+        # Layer 12 — last time we re-emitted the mouse-tracking enable
+        # sequences via the keypress path. Used to debounce per-keystroke
+        # re-arming so a fast typist doesn't spam the terminal with re-
+        # enables. Initialised to negative infinity so the first keystroke
+        # always rearms.
+        self._last_mouse_reenable_at: float = float("-inf")
 
     # ── Composition ──────────────────────────────────────────────────
 
@@ -549,7 +568,14 @@ class AruApp(App):
         suggestion and fires ``Input.Submitted``, which produced the
         "three Enters to run /help" glitch. Tab is the only key that
         accepts the highlighted suggestion.
+
+        Layer 12 — every keystroke is also a recovery opportunity. The
+        Layer 10 periodic tick still runs every ``_MOUSE_REENABLE_INTERVAL``
+        but a typing user wants the wheel back NOW, not in three seconds.
+        Debounced via ``_KEYPRESS_REARM_DEBOUNCE`` so a fast typist
+        doesn't amplify each keystroke into four extra terminal writes.
         """
+        self._maybe_rearm_mouse_on_keypress()
         try:
             completer = self.query_one(SlashCompleter)
         except Exception:
@@ -1097,34 +1123,112 @@ class AruApp(App):
             # without waiting for the periodic Layer 10 tick.
             self._reenable_mouse_tracking()
 
+    # Layer 12 — DEC private-mode sequences for mouse tracking. Defined
+    # at class scope so both the off-then-on shake below and any future
+    # caller (Click handler, focus event) can reuse the exact same set
+    # without drift.
+    _MOUSE_DISABLE_SEQS: tuple[str, ...] = (
+        "\x1b[?1000l",
+        "\x1b[?1003l",
+        "\x1b[?1015l",
+        "\x1b[?1006l",
+    )
+    _MOUSE_ENABLE_SEQS: tuple[str, ...] = (
+        "\x1b[?1000h",
+        "\x1b[?1003h",
+        "\x1b[?1015h",
+        "\x1b[?1006h",
+    )
+
     def _reenable_mouse_tracking(self) -> None:
-        """Re-emit Textual's mouse-tracking enable sequences (idempotent).
-
-        Calls the active driver's ``_enable_mouse_support`` which writes
-        four short SGR sequences (``?1000h`` / ``?1003h`` / ``?1015h`` /
-        ``?1006h``). They re-arm X10 mouse reporting at the terminal level
-        so a leaked ``\\x1b[?1000l`` (or any other DEC private-mode escape
-        that disabled wheel input) is recovered from automatically.
-        Idempotent — sending an enable when tracking is already on is a
-        documented no-op on every emulator.
-        Called from two sites:
+        """Re-arm mouse tracking via an off-then-on shake (Layer 12).
+
+        Pre-Layer-12 this method delegated to the driver's
+        ``_enable_mouse_support`` which writes four short SGR sequences
+        (``?1000h`` / ``?1003h`` / ``?1015h`` / ``?1006h``). That worked
+        when the terminal forwarded the writes verbatim, but the user
+        report on 2026-04-25 against
+        ``final-fantasy-9/.aru/sessions/b33dfb99`` was the wheel never
+        coming back even though Layer 9 (turn-boundary call) and Layer 10
+        (8s tick) both ran. Two failure modes the old code couldn't
+        recover from:
+
+        1. **ConPTY enable cache.** Windows ConPTY tracks DEC private-mode
+           state on its side and may treat ``?1000h`` as a no-op when its
+           cache says "already enabled" — even when the underlying
+           terminal lost the state. Sending ``?1000l`` first forces the
+           cache through a state transition so the subsequent ``?1000h``
+           is propagated.
+        2. **Driver-side gate.** ``WindowsDriver._enable_mouse_support``
+           opens with ``if not self._mouse: return`` (textual 8.2.4,
+           windows_driver.py:55). If a future Textual flips the gate
+           during shutdown / pause / alt-screen toggle, our recovery
+           silently no-ops. Going through ``driver.write`` bypasses the
+           gate and writes the bytes regardless.
+
+        Implementation: emit all four ``...l`` (off) sequences, then all
+        four ``...h`` (on) sequences, then flush. Eight short writes
+        (~64 bytes) bufferised into one terminal emit by ``WriterThread``.
+        Idempotent on a healthy terminal — the off→on cycle leaves the
+        final state identical to a single ``?1000h``, just with a
+        microscopic gap during the transition (no observable wheel-event
+        loss in practice).
+
+        Called from three sites:
         * ``_run_turn`` finally-clause (Layer 9) — eager recovery at every
           turn boundary so the first post-turn scroll always works.
         * ``_self_heal_terminal_state`` periodic tick (Layer 10) — recovers
-          mid-turn corruption (e.g. a leaked escape in panel content)
-          within ``_MOUSE_REENABLE_INTERVAL`` instead of leaving the wheel
-          dead until the (potentially long) turn finishes.
+          mid-turn corruption within ``_MOUSE_REENABLE_INTERVAL``.
+        * ``on_key`` keypress trigger (Layer 12) — recovers the moment the
+          user touches the keyboard, since a keystroke is a strong signal
+          they noticed the wheel is dead.
+
         Wrapped in ``try/except`` because the driver may be ``None`` in
-        headless / test mode and the private method's exact name could
-        shift in a future Textual; better to no-op silently than crash.
+        headless / test mode; we'd rather no-op silently than crash.
         """
         try:
             driver = self._driver
-            if driver is not None:
-                driver._enable_mouse_support()
+            if driver is None:
+                return
+            for seq in self._MOUSE_DISABLE_SEQS:
+                try:
+                    driver.write(seq)
+                except Exception:
+                    pass
+            for seq in self._MOUSE_ENABLE_SEQS:
+                try:
+                    driver.write(seq)
+                except Exception:
+                    pass
+            try:
+                driver.flush()
+            except Exception:
+                pass
         except Exception:
             pass
 
+    def _maybe_rearm_mouse_on_keypress(self) -> None:
+        """Layer 12 — re-arm mouse tracking on each keystroke (debounced).
+
+        Trigger fires from ``on_key`` so any user keypress is treated as a
+        recovery opportunity. A typing user is the strongest signal we
+        have that the wheel just stopped working — they reached for the
+        keyboard because the mouse stopped responding, or they're about
+        to scroll back with PgUp and want it ready. Either way, paying
+        ~64 bytes per keypress (capped at 2 Hz by ``_KEYPRESS_REARM_DEBOUNCE``)
+        is a trivial cost for sub-second recovery latency.
+
+        The debounce intentionally uses ``time.monotonic`` rather than the
+        Textual scheduler so it survives across the async ``on_key``
+        boundary without an extra task. ``-inf`` initial value guarantees
+        the first keystroke always rearms.
+        """
+        now = time.monotonic()
+        if now - self._last_mouse_reenable_at < self._KEYPRESS_REARM_DEBOUNCE:
+            return
+        self._last_mouse_reenable_at = now
+        self._reenable_mouse_tracking()
+
     def _self_heal_terminal_state(self) -> None:
         """Periodic recovery of mouse tracking and input focus (Layers 10 + 11).
 

{aru_code-0.44.0 → aru_code-0.45.0}/aru/tui/widgets/chat.py

@@ -345,6 +345,84 @@ virtualisation experiments) would close some of these by structure,
 but at the cost of every other property the chat currently has
 (selection, copy, mid-stream insertion of arbitrary Rich panels, plan
 mounts). Layered defences are cheap and additive; the rewrite is not.
+
+----
+
+Post-mortem — "self-heal didn't recover the wheel" (2026-04-25,
+``fix/scroll-analysis2``)
+---------------------------------------------------------------------
+**Symptom:** wheel-dead reproduced again post-Layer-11, this time
+against ``final-fantasy-9/.aru/sessions/b33dfb99``. After a YOLO turn
+finished, mouse wheel stopped working on every scrollable surface
+simultaneously — the canonical Layer 7/9/10 fingerprint. User report:
+*"não vi nenhum self healing seu funcionar até agora"* — Layers 9
+(turn-boundary call) and 10 (8 s periodic tick) ran, the four
+``?1000h``/``?1003h``/``?1015h``/``?1006h`` enables were emitted, and
+yet the wheel never came back.
+
+A byte scan of the persisted session turned up zero ``\\x1b`` bytes —
+same shape as the Layer 9 incident. The leak is from a non-persisted
+path (transient tool output, panel content, ConPTY-side state drift)
+and we accept we won't trace its emitter. The real question Layer 12
+answers is: **why didn't the recovery sequences work even when they
+fired?**
+
+**Two root causes the previous re-enable couldn't address:**
+
+1. **ConPTY enable-cache.** Windows ConPTY tracks DEC private-mode
+   state on its side. When its cache says ``?1000`` is already ``h``
+   it can suppress the write to the underlying terminal — even when
+   the terminal itself lost the state. Sending ``?1000h`` while the
+   cache thinks it's already on is therefore a no-op against a real
+   leak. Our Layer-9/10 emit was exactly this no-op.
+
+2. **Driver-side enable gate.** ``WindowsDriver._enable_mouse_support``
+   in textual 8.2.4 (``windows_driver.py:55``) opens with
+   ``if not self._mouse: return``. ``_mouse`` is True by default and
+   shouldn't flip in normal use, but our recovery path was a single
+   ``driver._enable_mouse_support()`` call — if any future Textual
+   refactor decides to flip the gate during pause / alt-screen toggle
+   / shutdown, every layer 9 + 10 call silently no-ops and we'd never
+   see the failure.
+
+**Layer 12 — three coordinated changes** (in ``aru/tui/app.py``):
+
+a. **Off-then-on shake instead of enable-only.**
+   ``_reenable_mouse_tracking`` now emits the four ``?...l`` (off)
+   sequences first, then the four ``?...h`` (on) sequences, then
+   flushes. The forced state transition defeats ConPTY's enable-cache —
+   the cache sees ``l→h`` and propagates the write regardless of what
+   it thinks the prior state was. Eight short writes (~64 bytes)
+   bufferised into one terminal emit by Textual's ``WriterThread``.
+   Idempotent: a healthy terminal lands in the same final state as
+   the old enable-only path, with a microscopic transition gap that
+   doesn't drop wheel events in practice.
+
+b. **Bypass the driver's enable gate.** Recovery now calls
+   ``driver.write(...)`` for each sequence directly instead of
+   ``driver._enable_mouse_support()``. The four ``...l`` and four
+   ``...h`` strings are kept as class-level tuples
+   (``_MOUSE_DISABLE_SEQS`` / ``_MOUSE_ENABLE_SEQS``) so any future
+   call site (Click handler, focus event) reuses the exact same set
+   without drift, and the path is robust against Textual API changes.
+
+c. **Keypress trigger + tighter periodic tick.**
+   ``_MOUSE_REENABLE_INTERVAL`` drops from 8 s to 3 s so worst-case
+   self-heal latency is sub-poll-cycle. ``on_key`` calls
+   ``_maybe_rearm_mouse_on_keypress`` which fires
+   ``_reenable_mouse_tracking`` on every keystroke debounced to 2 Hz
+   (``_KEYPRESS_REARM_DEBOUNCE = 0.5 s``). A typing user is the
+   strongest signal we have that they noticed the wheel just stopped
+   responding — recovery now happens on the very next keystroke, not
+   on the next tick.
+
+Layer 12 differs from Layer 10 in the failure-mode it covers, not in
+its shape. Layer 10 said "the bug will keep finding new emitters; let's
+recover on a clock". Layer 12 says "even when we recover on the clock,
+the recovery sequence itself can be ineffective; let's make the
+recovery actually do something". The two stack: tick still runs,
+keypress trigger gives it sub-second latency, off-on shake makes the
+sequence the tick emits actually take effect.
 """
 
 from __future__ import annotations

{aru_code-0.44.0 → aru_code-0.45.0/aru_code.egg-info}/PKG-INFO

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

{aru_code-0.44.0 → aru_code-0.45.0}/aru_code.egg-info/SOURCES.txt

@@ -166,6 +166,7 @@ tests/test_tui_completer.py
 tests/test_tui_completer_dynamic.py
 tests/test_tui_copy.py
 tests/test_tui_input_behaviour.py
+tests/test_tui_layer12_recovery.py
 tests/test_tui_mention_expand.py
 tests/test_tui_modals.py
 tests/test_tui_mode_cycle.py

{aru_code-0.44.0 → aru_code-0.45.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aru-code"
-version = "0.44.0"
+version = "0.45.0"
 description = "A Claude Code clone built with Agno agents"
 readme = "README.md"
 license = "MIT"

aru_code-0.45.0/tests/test_tui_layer12_recovery.py

@@ -0,0 +1,120 @@
+"""Layer 12 — mouse-tracking recovery: off-then-on shake + keypress trigger.
+
+Background: ``aru/tui/widgets/chat.py`` post-mortem under "self-heal didn't
+recover the wheel" (2026-04-25). Layers 9/10 emitted only the four ``?...h``
+enable sequences; if ConPTY's enable-cache or the driver's gate suppressed
+the write, no recovery happened. Layer 12 emits a forced ``?...l → ?...h``
+state transition via ``driver.write`` and adds a per-keypress trigger so the
+user gets sub-second recovery instead of waiting for the periodic tick.
+
+These tests pin down the observable contracts:
+* the eight DEC private-mode sequences are emitted in disable→enable order;
+* the keypress trigger calls into ``_reenable_mouse_tracking`` debounced by
+  ``_KEYPRESS_REARM_DEBOUNCE``.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+pytest.importorskip("textual")
+
+
+class _RecordingDriver:
+    """Driver stub that records every ``write`` call."""
+
+    def __init__(self) -> None:
+        self.writes: list[str] = []
+        self.flushes: int = 0
+
+    def write(self, data: str) -> None:
+        self.writes.append(data)
+
+    def flush(self) -> None:
+        self.flushes += 1
+
+
+@pytest.mark.asyncio
+async def test_reenable_mouse_tracking_emits_off_then_on_shake():
+    """Layer 12: ``?...l`` (4) is emitted *before* ``?...h`` (4), then flush.
+
+    The off→on shake forces ConPTY's enable-cache through a state
+    transition, defeating the case where its cache claims ``?1000`` is
+    already ``h`` and suppresses the propagated write. Order matters —
+    if the on sequences came first the cache could no-op them.
+    """
+    from aru.tui.app import AruApp
+
+    app = AruApp()
+    rec = _RecordingDriver()
+    # ``_driver`` is a private slot of ``App`` — assigning directly
+    # short-circuits the application-mode startup that would normally
+    # set it. The recovery method only reads ``self._driver``.
+    app._driver = rec
+
+    app._reenable_mouse_tracking()
+
+    expected_off = [
+        "\x1b[?1000l",
+        "\x1b[?1003l",
+        "\x1b[?1015l",
+        "\x1b[?1006l",
+    ]
+    expected_on = [
+        "\x1b[?1000h",
+        "\x1b[?1003h",
+        "\x1b[?1015h",
+        "\x1b[?1006h",
+    ]
+    assert rec.writes == expected_off + expected_on
+    # One flush at the end — the ``WriterThread`` bufferises everything
+    # before that into a single terminal emit.
+    assert rec.flushes == 1
+
+
+@pytest.mark.asyncio
+async def test_reenable_mouse_tracking_no_driver_is_noop():
+    """If the driver is ``None`` (headless / pre-mount) the call is a quiet no-op."""
+    from aru.tui.app import AruApp
+
+    app = AruApp()
+    app._driver = None
+    # Must not raise.
+    app._reenable_mouse_tracking()
+
+
+@pytest.mark.asyncio
+async def test_keypress_rearm_is_debounced(monkeypatch):
+    """Layer 12 keypress trigger respects ``_KEYPRESS_REARM_DEBOUNCE``.
+
+    Two keystrokes within the debounce window should produce exactly one
+    ``_reenable_mouse_tracking`` invocation; a third keystroke after the
+    window elapses should produce a second.
+    """
+    from aru.tui import app as app_mod
+    from aru.tui.app import AruApp
+
+    app = AruApp()
+    rec = _RecordingDriver()
+    app._driver = rec
+
+    fake_now = [100.0]
+
+    def fake_monotonic() -> float:
+        return fake_now[0]
+
+    monkeypatch.setattr(app_mod.time, "monotonic", fake_monotonic)
+
+    # 1st keystroke at t=100 — fires.
+    app._maybe_rearm_mouse_on_keypress()
+    # 2nd keystroke 100 ms later — within 500 ms debounce → suppressed.
+    fake_now[0] += 0.1
+    app._maybe_rearm_mouse_on_keypress()
+    # 3rd keystroke 600 ms after 1st (i.e. 500 ms after debounce window
+    # opened) — fires.
+    fake_now[0] += 0.5
+    app._maybe_rearm_mouse_on_keypress()
+
+    # Each fired call emits 8 sequences (4 off + 4 on). Two fires = 16.
+    assert len(rec.writes) == 16
+    assert rec.flushes == 2

aru_code-0.44.0/aru/__init__.py

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