smartcli-toolkit 0.1.6__tar.gz → 0.1.8__tar.gz

{smartcli_toolkit-0.1.6 → smartcli_toolkit-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.6
+Version: 0.1.8
 Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
 Author: dwgx
 License-Expression: MIT
@@ -195,7 +195,7 @@ backend, and dependency versions — run it and paste the output when filing a b
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 28 effects
+python -m fx list                          # list all 30 effects
 python -m fx play donut --seconds 5        # play one effect (bounded)
 python -m fx gallery                       # one frame of each effect
 python -m fx show --seq "donut:fire:3,plasma::3"
@@ -251,9 +251,9 @@ suite, see **[`README-USAGE.md`](README-USAGE.md)**.
 ## Features
 
 **`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
-`@register` decorator + auto-discovery. **28 effects** (donut, solarsystem, fire, plasma,
+`@register` decorator + auto-discovery. **30 effects** (donut, solarsystem, fire, plasma,
 rain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
-gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt) across **8 themes** (mono, fire,
+gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt, spectrum_bars, cbonsai) across **8 themes** (mono, fire,
 ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
 producers; `play` is bounded by default and always restores the terminal.
 
@@ -285,7 +285,7 @@ cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
 ```text
 SmartCLI/
   smartcli_core/           shared PTY + pyte engine (importable package)
-  skills/cmd-art/          fx effect package and CLI (28 effects, 8 themes)
+  skills/cmd-art/          fx effect package and CLI (30 effects, 8 themes)
   skills/drive-tui/        TUI pattern library and PTY driver CLI (8 recipes)
   skills/tui-ui/           terminal UI layout engine and widgets (17 widgets)
   tools/screenshot/        pyte -> PNG smoke-test harness

{smartcli_toolkit-0.1.6 → smartcli_toolkit-0.1.8}/README.md

@@ -149,7 +149,7 @@ backend, and dependency versions — run it and paste the output when filing a b
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 28 effects
+python -m fx list                          # list all 30 effects
 python -m fx play donut --seconds 5        # play one effect (bounded)
 python -m fx gallery                       # one frame of each effect
 python -m fx show --seq "donut:fire:3,plasma::3"
@@ -205,9 +205,9 @@ suite, see **[`README-USAGE.md`](README-USAGE.md)**.
 ## Features
 
 **`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
-`@register` decorator + auto-discovery. **28 effects** (donut, solarsystem, fire, plasma,
+`@register` decorator + auto-discovery. **30 effects** (donut, solarsystem, fire, plasma,
 rain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
-gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt) across **8 themes** (mono, fire,
+gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt, spectrum_bars, cbonsai) across **8 themes** (mono, fire,
 ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
 producers; `play` is bounded by default and always restores the terminal.
 
@@ -239,7 +239,7 @@ cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
 ```text
 SmartCLI/
   smartcli_core/           shared PTY + pyte engine (importable package)
-  skills/cmd-art/          fx effect package and CLI (28 effects, 8 themes)
+  skills/cmd-art/          fx effect package and CLI (30 effects, 8 themes)
   skills/drive-tui/        TUI pattern library and PTY driver CLI (8 recipes)
   skills/tui-ui/           terminal UI layout engine and widgets (17 widgets)
   tools/screenshot/        pyte -> PNG smoke-test harness

{smartcli_toolkit-0.1.6 → smartcli_toolkit-0.1.8}/pyproject.toml

@@ -30,7 +30,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "smartcli-toolkit"
-version = "0.1.6"
+version = "0.1.8"
 description = "Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core)."
 readme = "README.md"
 license = "MIT"

{smartcli_toolkit-0.1.6 → smartcli_toolkit-0.1.8}/smartcli_core/__init__.py

@@ -27,7 +27,7 @@ from .pty_backend import (
     WinptyBackend,
     get_default_backend,
 )
-from .readiness import wait_for_regex, wait_ready, wait_until_stable
+from .readiness import wait_any, wait_for_regex, wait_ready, wait_until_stable
 from .screen_model import CellAttrs, ScreenModel, safe_screen_display
 from .session import KEY_MAP, PtySession
 from .snapshot import Snapshot, Span, build_snapshot
@@ -50,9 +50,10 @@ __all__ = [
     "wait_until_stable",
     "wait_for_regex",
     "wait_ready",
+    "wait_any",
     # session
     "PtySession",
     "KEY_MAP",
 ]
 
-__version__ = "0.1.6"
+__version__ = "0.1.8"

{smartcli_toolkit-0.1.6 → smartcli_toolkit-0.1.8}/smartcli_core/readiness.py

@@ -21,7 +21,7 @@ from __future__ import annotations
 
 import re
 import time
-from typing import Callable, Optional, Tuple
+from typing import Callable, Optional, Sequence, Tuple
 
 # Callable aliases (documentation only)
 ReadFn = Callable[[], bytes]      # pump: read+feed one batch, return bytes read
@@ -155,6 +155,67 @@ def wait_for_regex(
         time.sleep(poll)
 
 
+def wait_any(
+    read_fn: ReadFn,
+    get_text_fn: TextFn,
+    get_snapshot_fn: Callable[[], object],
+    patterns: Sequence[str],
+    timeout_ms: int = 10000,
+    poll_ms: int = 30,
+    min_wait_ms: int = 0,
+    flags: int = 0,
+) -> Tuple[int, object]:
+    """Pump reads until ANY of ``patterns`` matches the screen, or timeout.
+
+    The pexpect ``expect([...])`` analogue: race several possible outcomes
+    (prompt vs error vs EOF banner) and report WHICH one appeared first. Patterns
+    are scanned **in list order** each poll, so when two would match on the same
+    poll the earliest in the list wins (deterministic, documented) — order the
+    list most-specific-first if that matters.
+
+    Args:
+        read_fn: called each poll to read+feed a batch.
+        get_text_fn: returns the current screen text searched by the regexes.
+        get_snapshot_fn: builds the :class:`Snapshot` returned to the caller.
+        patterns: regexes searched against the whole screen text, in priority order.
+        timeout_ms: hard ceiling.
+        poll_ms: sleep between polls when idle.
+        min_wait_ms: ignore matches before this much time has elapsed (guards
+            against matching a stale prior prompt right after sending input).
+        flags: extra ``re`` flags (``re.I`` etc.) applied to every pattern.
+
+    Returns:
+        ``(index, snapshot)`` — ``index`` is the 0-based position in ``patterns``
+        of the pattern that matched, or ``-1`` on timeout. An empty ``patterns``
+        list can never match, so it returns ``(-1, snapshot)`` immediately (one
+        pump, no spin to the deadline). The snapshot is always the current screen
+        so the caller can act on the last state either way.
+    """
+    rxs = [re.compile(p, flags) for p in patterns]
+    if not rxs:
+        # Nothing to match — pump once (so the snapshot is fresh) and report the
+        # timeout sentinel now instead of spinning the whole timeout window.
+        read_fn()
+        return -1, get_snapshot_fn()
+    poll = poll_ms / 1000.0
+    min_wait = min_wait_ms / 1000.0
+    start = time.monotonic()
+    deadline = start + (timeout_ms / 1000.0)
+
+    while True:
+        now = time.monotonic()
+        read_fn()
+        elapsed = now - start
+        if elapsed >= min_wait:
+            text = get_text_fn()
+            for i, rx in enumerate(rxs):
+                if rx.search(text):
+                    return i, get_snapshot_fn()
+        if now >= deadline:
+            return -1, get_snapshot_fn()
+        time.sleep(poll)
+
+
 def wait_ready(
     read_fn: ReadFn,
     get_screen_hash_fn: HashFn,

{smartcli_toolkit-0.1.6 → smartcli_toolkit-0.1.8}/smartcli_core/session.py

@@ -24,7 +24,7 @@ import time
 from typing import List, Optional, Tuple, Union, Sequence
 
 from .pty_backend import PtyBackend, get_default_backend
-from .readiness import wait_for_regex, wait_ready, wait_until_stable
+from .readiness import wait_any, wait_for_regex, wait_ready, wait_until_stable
 from .screen_model import ScreenModel
 from .snapshot import Snapshot, build_snapshot
 
@@ -297,6 +297,33 @@ class PtySession:
         )
         return matched, snap  # type: ignore[return-value]
 
+    def wait_any(
+        self,
+        patterns: Sequence[str],
+        timeout_ms: int = 10000,
+        poll_ms: int = 30,
+        min_wait_ms: int = 0,
+        flags: int = 0,
+    ) -> Tuple[int, Snapshot]:
+        """Wait for ANY of ``patterns`` (pexpect ``expect([...])`` style).
+
+        Returns ``(index, snapshot)`` where ``index`` is the 0-based position of
+        the pattern that matched (earliest in the list wins a same-poll tie), or
+        ``-1`` on timeout. The snapshot is always the current screen. See
+        :func:`readiness.wait_any`.
+        """
+        index, snap = wait_any(
+            read_fn=self.pump,
+            get_text_fn=self.model.text,
+            get_snapshot_fn=self.snapshot,
+            patterns=patterns,
+            timeout_ms=timeout_ms,
+            poll_ms=poll_ms,
+            min_wait_ms=min_wait_ms,
+            flags=flags,
+        )
+        return index, snap  # type: ignore[return-value]
+
     def wait_change(
         self,
         baseline_hash: Optional[str] = None,

{smartcli_toolkit-0.1.6 → smartcli_toolkit-0.1.8}/smartcli_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smartcli-toolkit
-Version: 0.1.6
+Version: 0.1.8
 Summary: Pluggable-PTY + pyte screen model + semantic snapshot / readiness core for driving interactive terminal programs (SmartCLI shared core).
 Author: dwgx
 License-Expression: MIT
@@ -195,7 +195,7 @@ backend, and dependency versions — run it and paste the output when filing a b
 
 ```bash
 cd skills/cmd-art
-python -m fx list                          # list all 28 effects
+python -m fx list                          # list all 30 effects
 python -m fx play donut --seconds 5        # play one effect (bounded)
 python -m fx gallery                       # one frame of each effect
 python -m fx show --seq "donut:fire:3,plasma::3"
@@ -251,9 +251,9 @@ suite, see **[`README-USAGE.md`](README-USAGE.md)**.
 ## Features
 
 **`cmd-art`** (`skills/cmd-art`) — a "living-template" effect engine: an `Effect` ABC +
-`@register` decorator + auto-discovery. **28 effects** (donut, solarsystem, fire, plasma,
+`@register` decorator + auto-discovery. **30 effects** (donut, solarsystem, fire, plasma,
 rain, starfield, tunnel, text3d, cube, sphere, boids, life, fireworks, sparkle, decrypt,
-gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt) across **8 themes** (mono, fire,
+gradient_text, banner_scroll, image2ascii, typewriter, julia, mandelbrot, perlin, flames, water, nebula, text_flyin, text_converge, text_decrypt, spectrum_bars, cbonsai) across **8 themes** (mono, fire,
 ocean, synthwave, viridis, pastel, matrix-green, rainbow). Effects are pure frame
 producers; `play` is bounded by default and always restores the terminal.
 
@@ -285,7 +285,7 @@ cross-links. See [`knowledge/INDEX.md`](knowledge/INDEX.md).
 ```text
 SmartCLI/
   smartcli_core/           shared PTY + pyte engine (importable package)
-  skills/cmd-art/          fx effect package and CLI (28 effects, 8 themes)
+  skills/cmd-art/          fx effect package and CLI (30 effects, 8 themes)
   skills/drive-tui/        TUI pattern library and PTY driver CLI (8 recipes)
   skills/tui-ui/           terminal UI layout engine and widgets (17 widgets)
   tools/screenshot/        pyte -> PNG smoke-test harness

{smartcli_toolkit-0.1.6 → smartcli_toolkit-0.1.8}/smartcli_toolkit.egg-info/SOURCES.txt

@@ -21,5 +21,8 @@ tests/test_doc_counts.py
 tests/test_fx_contract.py
 tests/test_golden_frames.py
 tests/test_readiness.py
+tests/test_sixel.py
+tests/test_tbench_adapter.py
 tests/test_vendor_sync.py
+tests/test_wait_any.py
 tests/test_wait_change.py

smartcli_toolkit-0.1.8/tests/test_sixel.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""test_sixel.py — Sixel encoder regression (deterministic, pure-memory).
+
+Locks the wire format against the VT330/340 spec's known-good facts:
+  * DCS introducer ESC P 0;1;0 q, ST terminator ESC \\, raster attrs "1;1;W;H,
+  * char = 0x3F + mask, bit0 = TOP pixel (verified via the canonical DEC "HI" math),
+  * color registers #Pc;2;R;G;B with R/G/B in 0..100 PERCENT (not 0..255),
+  * `$` between colors in a band (never trailing), `-` between bands (bands-1 of them),
+  * a round-trip: decode the emitted stream back to a pixel grid and compare.
+
+No terminal, no process — the bytes are checked structurally + by decode.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ROOT / "skills" / "tui-ui"))
+
+from ui.sixel import (encode_sixel, _quantize_index, _index_to_pct,  # noqa: E402
+                      raster_to_sixel)
+
+failures = 0
+
+
+def check(cond, label, detail=""):
+    global failures
+    if not cond:
+        failures += 1
+    print(f"{'PASS' if cond else 'FAIL'}  {label}" + (f"  -- {detail}" if detail else ""))
+
+
+RED = (255, 0, 0)
+BLUE = (0, 0, 255)
+WHITE = (255, 255, 255)
+
+
+def test_red_blue_fixture():
+    """Spec worked example: 2px x 6px, col0 red, col1 blue. One band, two colors."""
+    px = [[RED, BLUE] for _ in range(6)]
+    s = encode_sixel(px)
+    check(s.startswith("\x1bP0;1;0q"), "starts with DCS ESC P 0;1;0 q", repr(s[:9]))
+    check(s.endswith("\x1b\\"), "ends with ST ESC backslash")
+    check('"1;1;2;6' in s, "raster attrs 1:1 aspect + WxH = 2x6")
+    ri, bi = _quantize_index(RED), _quantize_index(BLUE)
+    check(_index_to_pct(ri) == (100, 0, 0), "red register defined as 100;0;0 percent",
+          str(_index_to_pct(ri)))
+    check(_index_to_pct(bi) == (0, 0, 100), "blue register defined as 0;0;100 percent",
+          str(_index_to_pct(bi)))
+    # red column0 = all 6 rows lit = mask 63 = '~'; its column1 empty = '?'
+    check(f"#{ri}~?" in s, "red pass: col0 all-six '~', col1 none '?'",
+          f"want #{ri}~?")
+    check("$" in s, "a graphics-CR '$' separates the two colors in the band")
+    check(f"#{bi}?~" in s, "blue pass: col0 '?', col1 all-six '~'", f"want #{bi}?~")
+    check(s.count("-") == 0, "single band -> no graphics-NL '-'", f"count={s.count('-')}")
+
+
+def test_bit_math_matches_dec_hi_example():
+    """The canonical DEC 'HI' example proves char=0x3F+mask, bit0=top:
+       '~'=0x7E->63 (all six), '@'=0x40->1 (top only), '}'=0x7D->62 (top off)."""
+    check(chr(0x3F + 0b111111) == "~", "mask 63 (all six) encodes to '~'")
+    check(chr(0x3F + 0b000001) == "@", "mask 1 (top pixel only) encodes to '@'")
+    check(chr(0x3F + 0b111110) == "}", "mask 62 (top off, rest on) encodes to '}'")
+    check(chr(0x3F + 0) == "?", "mask 0 (no pixels) encodes to '?'")
+    # a single top-lit pixel in a 1x1 image must emit '@' for its color.
+    s = encode_sixel([[RED]])
+    ri = _quantize_index(RED)
+    check(f"#{ri}@" in s, "1x1 top pixel -> sixel char '@' (bit0=top)")
+
+
+def test_percent_scaling_not_255():
+    """Colors must be 0..100 percent, never 0..255 (the classic gotcha)."""
+    for c in (RED, BLUE, WHITE, (128, 64, 200)):
+        r, g, b = _index_to_pct(_quantize_index(c))
+        check(0 <= r <= 100 and 0 <= g <= 100 and 0 <= b <= 100,
+              f"{c} -> percent in 0..100", f"got {(r, g, b)}")
+
+
+def test_band_advance_count():
+    """A 2-wide x 13-tall image spans ceil(13/6)=3 bands -> exactly 2 '-'."""
+    px = [[WHITE, WHITE] for _ in range(13)]
+    s = encode_sixel(px)
+    check(s.count("-") == 2, "13 rows -> 3 bands -> 2 graphics-NL", f"count={s.count('-')}")
+    check(not s.rstrip("\x1b\\").endswith("-"), "no trailing '-' before ST")
+
+
+def _decode_sixel(s: str):
+    """Minimal decoder for our own output: returns {(x,y): register} for lit px.
+    Enough to prove the encoder is self-consistent (round-trip)."""
+    body = s
+    assert body.startswith("\x1bP")
+    body = body[2:]
+    # strip params up to the 'q'
+    body = body[body.index("q") + 1:]
+    body = body[:body.rindex("\x1b\\")]
+    lit = {}
+    band = 0
+    x = 0
+    cur = None
+    i = 0
+    n = len(body)
+    while i < n:
+        ch = body[i]
+        if ch == '"':                       # raster attrs: skip to next control
+            j = i + 1
+            while j < n and body[j] not in "#$-":
+                j += 1
+            i = j
+            continue
+        if ch == '#':                       # color: #Pc or #Pc;2;r;g;b
+            j = i + 1
+            num = ""
+            while j < n and body[j].isdigit():
+                num += body[j]; j += 1
+            if j < n and body[j] == ';':    # definition — skip the ;2;r;g;b
+                while j < n and body[j] not in "#$-?~" and not (0x3F <= ord(body[j]) <= 0x7E and body[j] not in ";0123456789"):
+                    j += 1
+                # after a definition the register is also selected
+            cur = int(num)
+            x = 0
+            i = j
+            continue
+        if ch == '$':                       # CR: same band, back to x=0
+            x = 0; i += 1; continue
+        if ch == '-':                       # NL: next band
+            band += 1; x = 0; i += 1; continue
+        if ch == '!':                       # RLE: !Pn<char>
+            j = i + 1; num = ""
+            while j < n and body[j].isdigit():
+                num += body[j]; j += 1
+            rep = int(num); sc = body[j]
+            mask = ord(sc) - 0x3F
+            for _ in range(rep):
+                for dy in range(6):
+                    if mask & (1 << dy):
+                        lit[(x, band * 6 + dy)] = cur
+                x += 1
+            i = j + 1
+            continue
+        if 0x3F <= ord(ch) <= 0x7E:         # a data char
+            mask = ord(ch) - 0x3F
+            for dy in range(6):
+                if mask & (1 << dy):
+                    lit[(x, band * 6 + dy)] = cur
+            x += 1
+            i += 1
+            continue
+        i += 1
+    return lit
+
+
+def test_round_trip():
+    """Encode a known pattern, decode our own stream, confirm lit pixels match."""
+    # 3x6 checkerboard of red/blue
+    px = [[RED if (x + y) % 2 == 0 else BLUE for x in range(3)] for y in range(6)]
+    s = encode_sixel(px)
+    lit = _decode_sixel(s)
+    ri, bi = _quantize_index(RED), _quantize_index(BLUE)
+    good = True
+    for y in range(6):
+        for x in range(3):
+            want = ri if (x + y) % 2 == 0 else bi
+            if lit.get((x, y)) != want:
+                good = False
+    check(good, "round-trip: decoded pixels match the source checkerboard",
+          f"{len(lit)} lit px")
+
+
+def test_transparent_pixels_skipped():
+    """None pixels must not be painted (P2=1 transparent)."""
+    px = [[RED, None], [None, RED]]  # 2x2, diagonal
+    s = encode_sixel(px)
+    lit = _decode_sixel(s)
+    ri = _quantize_index(RED)
+    check(lit.get((0, 0)) == ri and lit.get((1, 1)) == ri, "lit diagonal present")
+    check((1, 0) not in lit and (0, 1) not in lit, "None pixels stay transparent")
+
+
+def test_raster_adapter():
+    """raster_to_sixel forwards a SubcellRaster's .px buffer."""
+    from ui.raster import SubcellRaster
+    r = SubcellRaster(2, 2, "quad")   # pw=4, ph=4
+    r.px[0][0] = RED
+    s = raster_to_sixel(r)
+    check(s.startswith("\x1bP") and s.endswith("\x1b\\"), "raster adapter emits a DCS")
+    check('"1;1;4;4' in s, "raster adapter uses the pixel-buffer dims (4x4)")
+
+
+def test_empty_image():
+    s = encode_sixel([])
+    check(s == "\x1bP0;1;0q\x1b\\", "empty image -> bare DCS+ST wrapper", repr(s))
+
+
+def main():
+    for fn in (test_red_blue_fixture, test_bit_math_matches_dec_hi_example,
+               test_percent_scaling_not_255, test_band_advance_count,
+               test_round_trip, test_transparent_pixels_skipped,
+               test_raster_adapter, test_empty_image):
+        fn()
+    print("-" * 60)
+    if failures:
+        print(f"test_sixel FAIL -- {failures} check(s) failed")
+        return 1
+    print("test_sixel PASS -- sixel wire format locked to spec")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

smartcli_toolkit-0.1.8/tests/test_tbench_adapter.py

@@ -0,0 +1,217 @@
+#!/usr/bin/env python3
+"""test_tbench_adapter.py — smartcli_tbench driver + loop (deterministic, no Docker).
+
+Proves the Terminal-Bench adapter's LOGIC on any box (incl. Windows) without
+Docker, terminal-bench, or an LLM:
+  * TmuxSessionDriver.wait_for / wait_any / wait_change / wait_stable fire correctly
+    over a scripted FakeTmuxSession (fake clock + no-op sleep — instant, deterministic),
+  * run_agent_loop executes perceive→decide→act→wait→confirm, terminates on the
+    decider's done signal, and respects the step budget,
+  * send_keys / send_line reach the session.
+
+The LLM-backed SmartCliAgent itself needs terminal-bench (CI/Linux); this locks
+everything below that seam.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from smartcli_tbench.driver import TmuxSessionDriver  # noqa: E402
+from smartcli_tbench.loop import AgentStep, run_agent_loop  # noqa: E402
+
+failures = 0
+
+
+def check(cond, label, detail=""):
+    global failures
+    if not cond:
+        failures += 1
+    print(f"{'PASS' if cond else 'FAIL'}  {label}" + (f"  -- {detail}" if detail else ""))
+
+
+class FakeClock:
+    """Monotonic clock that only advances when the driver sleeps, so wait loops
+    hit their deadline deterministically without real time passing."""
+
+    def __init__(self):
+        self.t = 0.0
+
+    def now(self):
+        return self.t
+
+    def sleep(self, s):
+        self.t += s
+
+
+class FakeTmuxSession:
+    """Scripts capture_pane() outputs: each poll returns the next screen; the last
+    screen repeats forever. Records sent keys. With ``cycle=True`` the script loops
+    (to model a screen that alternates forever and truly never settles)."""
+
+    def __init__(self, screens, cycle=False):
+        self._screens = list(screens)
+        self._i = 0
+        self._cycle = cycle
+        self.sent = []
+
+    def capture_pane(self, capture_entire=False):
+        if self._cycle:
+            s = self._screens[self._i % len(self._screens)]
+        else:
+            s = self._screens[min(self._i, len(self._screens) - 1)]
+        self._i += 1
+        return s
+
+    def send_keys(self, keys, block=False, max_timeout_sec=180.0, **kw):
+        self.sent.append(list(keys))
+
+
+def _driver(screens):
+    clk = FakeClock()
+    sess = FakeTmuxSession(screens)
+    return TmuxSessionDriver(sess, poll_ms=100, clock=clk.now, sleep=clk.sleep), sess, clk
+
+
+def test_wait_for_matches():
+    d, _, _ = _driver(["booting...", "booting...", "$ ready"])
+    ok, screen = d.wait_for(r"\$ ready", timeout_sec=5)
+    check(ok is True, "wait_for finds the marker once it appears")
+    check("ready" in screen, "wait_for returns the matching screen")
+
+
+def test_wait_for_timeout():
+    d, _, _ = _driver(["nope", "nope", "nope"])
+    ok, _ = d.wait_for(r"never", timeout_sec=1)
+    check(ok is False, "wait_for times out when the marker never appears")
+
+
+def test_wait_any_index_and_tie():
+    d, _, _ = _driver(["...", "ERROR: boom"])
+    idx, _ = d.wait_any([r">>> ", r"ERROR"], timeout_sec=5)
+    check(idx == 1, "wait_any returns the index of the matching pattern", f"idx={idx}")
+    # same-poll tie -> earliest in list wins
+    d2, _, _ = _driver(["ERROR: boom"])
+    idx2, _ = d2.wait_any([r"ERROR", r"boom"], timeout_sec=5)
+    check(idx2 == 0, "wait_any tie: earliest-in-list wins", f"idx={idx2}")
+    # empty list short-circuits
+    d3, _, _ = _driver(["anything"])
+    idx3, _ = d3.wait_any([], timeout_sec=5)
+    check(idx3 == -1, "wait_any empty patterns -> -1", f"idx={idx3}")
+
+
+def test_wait_change():
+    d, _, _ = _driver(["same", "same", "DIFFERENT"])
+    changed, screen = d.wait_change(timeout_sec=5)
+    check(changed is True, "wait_change detects the screen changing from baseline")
+    check("DIFFERENT" in screen, "wait_change returns the changed screen")
+
+    d2, _, _ = _driver(["frozen", "frozen", "frozen"])
+    changed2, _ = d2.wait_change(timeout_sec=1)
+    check(changed2 is False, "wait_change times out when nothing changes")
+
+
+def test_wait_stable():
+    # changes for two polls, then holds -> becomes stable (min_wait_sec=0 to isolate
+    # the dwell logic from the stale-screen floor, which is tested separately below).
+    d, _, _ = _driver(["a", "b", "c", "c", "c"])
+    ok = d.wait_stable(quiet_polls=2, timeout_sec=5, min_wait_sec=0)
+    check(ok is True, "wait_stable settles once the screen stops changing")
+
+
+def test_wait_stable_never_settles():
+    # A screen that alternates FOREVER (cycle=True) must never satisfy the dwell
+    # counter -> can only exit via timeout. Uses a truly non-clamping fake so this
+    # is a real never-settle, not a clamp-then-freeze artifact.
+    clk = FakeClock()
+    sess = FakeTmuxSession(["A", "B"], cycle=True)
+    d = TmuxSessionDriver(sess, poll_ms=100, clock=clk.now, sleep=clk.sleep)
+    ok = d.wait_stable(quiet_polls=2, timeout_sec=1, min_wait_sec=0)
+    check(ok is False, "wait_stable never settles on an alternating screen -> timeout")
+
+
+def test_wait_stable_min_wait_guards_stale_screen():
+    # The stale-screen race (finding 1): the screen is ALREADY static from poll 0
+    # (the shell echoed the command instantly) but real output is still pending.
+    # With min_wait_sec, wait_stable must NOT declare stable before the floor, even
+    # though the dwell counter is satisfied immediately.
+    clk = FakeClock()
+    sess = FakeTmuxSession(["prompt$ cmd"], cycle=True)  # static from the very start
+    d = TmuxSessionDriver(sess, poll_ms=100, clock=clk.now, sleep=clk.sleep)
+    t0 = clk.now()
+    ok = d.wait_stable(quiet_polls=2, timeout_sec=5, min_wait_sec=0.5)
+    elapsed = clk.now() - t0
+    check(ok is True, "wait_stable eventually settles on a static screen")
+    check(elapsed >= 0.5, "min_wait_sec floor delays settle past the stale-screen race",
+          f"elapsed={elapsed:.2f}s")
+    # And without the floor it would settle almost immediately (proves the guard bites):
+    clk2 = FakeClock()
+    d2 = TmuxSessionDriver(FakeTmuxSession(["prompt$ cmd"], cycle=True),
+                           poll_ms=100, clock=clk2.now, sleep=clk2.sleep)
+    d2.wait_stable(quiet_polls=2, timeout_sec=5, min_wait_sec=0)
+    check(clk2.now() < 0.5, "without the floor, settle is immediate (guard is what delays)",
+          f"elapsed={clk2.now():.2f}s")
+
+
+def test_send_helpers():
+    d, sess, _ = _driver(["scr"])
+    d.send_keys(["Down", "Enter"])
+    d.send_line("echo hi")
+    check(sess.sent[0] == ["Down", "Enter"], "send_keys forwards key tokens")
+    check(sess.sent[1] == ["echo hi", "Enter"], "send_line appends Enter")
+
+
+def test_loop_runs_to_done():
+    # Decider: step 0 types a command, step 1 declares done.
+    d, sess, _ = _driver(["prompt$ ", "prompt$ output", "prompt$ output"])
+
+    def decide(instruction, screen, history):
+        if len(history) == 0:
+            return AgentStep(line="run the thing", wait_for=None)
+        return AgentStep(done=True)
+
+    res = run_agent_loop("do it", d, decide, max_steps=10)
+    check(res.done is True, "loop ends when the decider signals done")
+    check(res.steps_taken == 1, "one action taken before done", f"steps={res.steps_taken}")
+    check(sess.sent and sess.sent[0] == ["run the thing", "Enter"],
+          "loop actually sent the decided line")
+
+
+def test_loop_respects_step_budget():
+    d, _, _ = _driver(["x"])
+    # Decider never says done -> must stop at max_steps.
+    def decide(instruction, screen, history):
+        return AgentStep(keys=["a"])
+    res = run_agent_loop("loop forever", d, decide, max_steps=5)
+    check(res.done is False, "loop stops at the step budget when never done")
+    check(res.steps_taken == 5, "exactly max_steps actions taken", f"steps={res.steps_taken}")
+
+
+def test_agent_module_imports_without_tb():
+    # Importing the agent module must NOT require terminal-bench; SmartCliAgent is
+    # None here (TB absent), which is the documented non-TB-host behavior.
+    import smartcli_tbench.agent as ag
+    check(hasattr(ag, "SmartCliAgent"), "agent module imports without terminal-bench")
+    check(ag.SmartCliAgent is None, "SmartCliAgent is None on a non-TB host (expected)")
+
+
+def main():
+    for fn in (test_wait_for_matches, test_wait_for_timeout, test_wait_any_index_and_tie,
+               test_wait_change, test_wait_stable, test_wait_stable_never_settles,
+               test_wait_stable_min_wait_guards_stale_screen, test_send_helpers,
+               test_loop_runs_to_done, test_loop_respects_step_budget,
+               test_agent_module_imports_without_tb):
+        fn()
+    print("-" * 60)
+    if failures:
+        print(f"test_tbench_adapter FAIL -- {failures} check(s) failed")
+        return 1
+    print("test_tbench_adapter PASS -- driver + loop logic locked (no Docker/LLM)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

smartcli_toolkit-0.1.8/tests/test_wait_any.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""test_wait_any.py — PtySession.wait_any regression (deterministic).
+
+wait_any is the pexpect expect([...]) analogue: race several regexes and report
+WHICH matched first. This locks:
+  * the pattern that appears wins and its LIST INDEX is returned,
+  * a later-listed pattern wins when only it appears,
+  * earliest-in-list wins a same-poll tie (documented ordering),
+  * timeout with none matched returns (-1, latest snapshot),
+  * min_wait_ms ignores a stale prior match until the guard elapses.
+
+Pure/in-memory: a fake backend feeds bytes on demand. No PTY, no process.
+"""
+from __future__ import annotations
+
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+from smartcli_core import PtySession  # noqa: E402
+from smartcli_core.pty_backend import PtyBackend  # noqa: E402
+
+failures = 0
+
+
+def check(cond, label, detail=""):
+    global failures
+    if not cond:
+        failures += 1
+    print(f"{'PASS' if cond else 'FAIL'}  {label}" + (f"  -- {detail}" if detail else ""))
+
+
+class FakeBackend(PtyBackend):
+    """Feeds queued byte chunks one-per-read; optionally delays the first chunk."""
+
+    def __init__(self):
+        self._q = []
+        self._alive = True
+
+    def queue(self, data):
+        self._q.append(data)
+
+    def spawn(self, cmd, cols, rows):
+        pass
+
+    def read_nonblocking(self, timeout=0.0):
+        return self._q.pop(0) if self._q else b""
+
+    def write(self, data):
+        pass
+
+    def resize(self, cols, rows):
+        pass
+
+    def is_alive(self):
+        return self._alive
+
+    def terminate(self):
+        self._alive = False
+
+
+def test_first_pattern_matches():
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    be.queue(b">>> ")
+    idx, snap = sess.wait_any([r">>> ", r"Traceback"], timeout_ms=2000)
+    check(idx == 0, "the prompt pattern matches -> index 0", f"idx={idx}")
+    check(">>>" in snap.to_text(), "returned snapshot shows the matched screen")
+
+
+def test_later_pattern_matches():
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    be.queue(b"Traceback (most recent call last)")
+    idx, _ = sess.wait_any([r">>> ", r"Traceback"], timeout_ms=2000)
+    check(idx == 1, "only the error pattern is present -> index 1", f"idx={idx}")
+
+
+def test_earliest_in_list_wins_tie():
+    # One screen that matches BOTH patterns; the earlier list entry must win.
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    be.queue(b"ERROR: boom")
+    idx, _ = sess.wait_any([r"ERROR", r"boom"], timeout_ms=2000)
+    check(idx == 0, "same-poll tie: earliest-in-list pattern wins", f"idx={idx}")
+    # And the reverse order proves it's list-order, not text-position.
+    be2 = FakeBackend()
+    sess2 = PtySession(cols=40, rows=10, backend=be2)
+    be2.queue(b"ERROR: boom")
+    idx2, _ = sess2.wait_any([r"boom", r"ERROR"], timeout_ms=2000)
+    check(idx2 == 0, "reversed list -> the now-first pattern ('boom') wins", f"idx={idx2}")
+
+
+def test_empty_patterns_short_circuits():
+    # An empty list can never match: return (-1, snapshot) immediately instead of
+    # spinning the whole timeout window (adversarial-review polish).
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    t0 = time.monotonic()
+    idx, snap = sess.wait_any([], timeout_ms=3000)
+    elapsed_ms = (time.monotonic() - t0) * 1000
+    check(idx == -1, "empty patterns -> index -1", f"idx={idx}")
+    check(snap is not None, "empty patterns still returns a snapshot")
+    check(elapsed_ms < 500, "empty patterns returns immediately, not after timeout",
+          f"elapsed={elapsed_ms:.0f}ms")
+
+
+def test_timeout_returns_minus_one():
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    # nothing queued -> screen stays blank -> no pattern ever matches
+    idx, snap = sess.wait_any([r"never", r"appears"], timeout_ms=250)
+    check(idx == -1, "no pattern within the window -> index -1 (timeout)", f"idx={idx}")
+    check(snap is not None, "timeout still returns the latest snapshot")
+
+
+def test_min_wait_ignores_stale_match():
+    # The target text is already on screen at call time; min_wait_ms must make
+    # wait_any ignore it until the guard elapses, then it still returns the match.
+    be = FakeBackend()
+    sess = PtySession(cols=40, rows=10, backend=be)
+    be.queue(b"$ ")
+    sess.pump()  # paint "$ " BEFORE the wait, so it's a stale prior match
+    t0 = time.monotonic()
+    idx, _ = sess.wait_any([r"\$ "], timeout_ms=2000, min_wait_ms=150)
+    elapsed_ms = (time.monotonic() - t0) * 1000
+    check(idx == 0, "stale match is still returned after the guard", f"idx={idx}")
+    check(elapsed_ms >= 140, "min_wait_ms delayed the match past the guard",
+          f"elapsed={elapsed_ms:.0f}ms")
+
+
+def main():
+    for fn in (test_first_pattern_matches, test_later_pattern_matches,
+               test_earliest_in_list_wins_tie, test_empty_patterns_short_circuits,
+               test_timeout_returns_minus_one, test_min_wait_ignores_stale_match):
+        fn()
+    print("-" * 60)
+    if failures:
+        print(f"test_wait_any FAIL -- {failures} check(s) failed")
+        return 1
+    print("test_wait_any PASS -- all wait_any paths locked")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())