Publish tests/ from marimo

tests/conftest.py

@@ -0,0 +1,22 @@
+"""Shared test helpers.
+
+The OCR guard used to live inline in two files, written two slightly different
+ways - and on a machine with no OCR engine one of them never fired at all. It is
+one function now, and `test_ocr_guard.py` proves it actually skips.
+"""
+
+import pytest
+
+
+def require_ocr() -> None:
+    """Skip the calling test unless a real OCR engine is installed.
+
+    Deliberately asks for the **ocr** detector, not the ``auto`` one: ``auto`` is
+    available even with nothing installed, because it falls back to the numbered
+    grid, so guarding on it silently *never* skips.
+    """
+    from tiny_computer_agent.perception import detector_available
+
+    available, detail = detector_available("ocr")
+    if not available:
+        pytest.skip(f"no OCR engine installed: {detail}")

tests/test_accessibility.py

@@ -0,0 +1,278 @@
+"""The accessibility-tree detector: exact elements, and honest failures.
+
+Nothing here needs a desktop. The tree is injected through `TreeReader`, so the
+filtering, the geometry and the coordinate contract are all tested for real; the
+one test that drives actual AT-SPI is opt-in, like the live-desktop tests.
+"""
+
+import os
+
+import pytest
+from PIL import Image
+
+from tiny_computer_agent import (
+    INTERACTIVE_ROLES, TEXT_ROLES, AccessibleNode, AtspiDetector, AtspiReader,
+    AutoDetector, Element, IndexedScreen, Observation, detector_available,
+    make_detector,
+)
+from tiny_computer_agent.accessibility import accessibility_available
+from tiny_computer_agent.perception import DetectorUnavailable
+
+
+class FakeReader:
+    """A tree, exactly as AT-SPI would report it."""
+
+    name = "fake"
+
+    def __init__(self, nodes):
+        self.nodes = tuple(nodes)
+        self.reads = 0
+
+    def read(self):
+        self.reads += 1
+        return self.nodes
+
+
+FRAME = Image.new("RGB", (1000, 700), (20, 22, 28))     # a frame, for grid fallback
+
+
+def node(role, name, x=100, y=100, width=100, height=36, depth=2):
+    return AccessibleNode(role, name, x, y, width, height, depth)
+
+
+TREE = [
+    node("application", "gtk_dialog.py", 0, 0, 0, 0, 0),
+    node("frame", "Accessible desktop", 160, 160, 460, 220, 1),
+    node("panel", "", 174, 174, 432, 192, 2),
+    node("button", "Files", 174, 201, 100, 36),
+    node("button", "Terminal", 282, 201, 100, 36),
+    node("button", "Save", 390, 201, 100, 36),
+    node("button", "Cancel", 498, 201, 100, 36),
+    node("label", "Choose an action", 174, 245, 424, 19),
+    node("label", "last action: (none)", 174, 174, 424, 19),
+]
+
+
+# -- what the tree gives us --------------------------------------------------
+
+def test_the_tree_yields_labelled_widgets_with_real_coordinates():
+    elements = AtspiDetector(reader=FakeReader(TREE)).detect()
+    assert [(e.label, e.kind) for e in elements] == [
+        ("Files", "button"), ("Terminal", "button"), ("Save", "button"), ("Cancel", "button"),
+    ]
+    save = next(e for e in elements if e.label == "Save")
+    assert (save.x, save.y, save.width, save.height) == (390, 201, 100, 36)
+    assert save.center == (440, 219)
+
+
+def test_window_furniture_is_not_offered_as_a_choice():
+    """A frame and a panel have names too; giving them to a model is a trap."""
+    roles = {e.kind for e in AtspiDetector(reader=FakeReader(TREE)).detect()}
+    assert "frame" not in roles and "panel" not in roles and "application" not in roles
+    assert roles <= INTERACTIVE_ROLES
+
+
+def test_labels_can_be_read_without_being_clickable():
+    plain = AtspiDetector(reader=FakeReader(TREE))
+    with_text = AtspiDetector(reader=FakeReader(TREE), include_text=True)
+    assert not any(e.kind == "label" for e in plain.detect())
+    assert [e.label for e in with_text.detect() if e.kind == "label"] == [
+        "Choose an action", "last action: (none)"]
+    assert "Choose an action" in with_text.text()
+
+
+def test_labels_are_filtered_by_length_and_size():
+    tree = [node("button", "x"), node("button", "a" * 80), node("button", "Sneaky", 5, 5, 2, 2)]
+
+    strict = AtspiDetector(reader=FakeReader(tree), min_label_chars=2)
+    assert [e.label for e in strict.detect()] == []      # too short, too long, too small
+
+    loose = AtspiDetector(reader=FakeReader(tree), min_label_chars=1,
+                          max_label_chars=6, min_size=1)
+    assert [e.label for e in loose.detect()] == ["x", "Sneaky"]   # 80 chars still too long
+
+
+def test_off_screen_and_duplicate_nodes_are_dropped():
+    tree = [node("button", "Save"), node("button", "Save"),
+            node("button", "Ghost", -400, -400)]
+    assert [e.label for e in AtspiDetector(reader=FakeReader(tree)).detect()] == ["Save"]
+
+
+def test_the_detector_ignores_the_image_it_is_handed():
+    reader = FakeReader(TREE)
+    detector = AtspiDetector(reader=reader)
+    detector.detect(None)
+    detector.detect(object())                 # any object at all
+    assert reader.reads == 2
+
+
+# -- the coordinate contract -------------------------------------------------
+
+class ScaledSource:
+    """A source whose frames are downscaled: every element needs re-mapping."""
+
+    def __init__(self):
+        self.origin = (0, 0)
+        self.frame_scale = 2.0
+
+    def capture(self):
+        return Observation(index=0, frame=FRAME)
+
+    def map_to_screen(self, element):
+        return Element(label=element.label, kind=element.kind, x=element.x * 2,
+                       y=element.y * 2, width=element.width * 2, height=element.height * 2)
+
+
+def test_screen_coordinates_are_not_double_mapped_by_a_downscaled_capture():
+    """AT-SPI already speaks screen pixels; a downscale must not scale them again."""
+    detector = AtspiDetector(reader=FakeReader([node("button", "Save", 390, 201, 100, 36)]))
+    observation = IndexedScreen(ScaledSource(), detector).capture()
+    save = observation.elements[0]
+    assert (save.x, save.y) == (390, 201), "the accessibility tree was scaled twice"
+
+
+def test_a_frame_relative_detector_is_still_mapped():
+    """The opt-out is per-detector: a grid in a downscaled frame must be mapped."""
+    from tiny_computer_agent import GridDetector
+    observation = IndexedScreen(ScaledSource(), GridDetector(rows=1, cols=2)).capture()
+    assert [e.x for e in observation.elements] == [0, 1000]   # 500 * frame_scale of 2
+
+
+# -- honest failures --------------------------------------------------------
+
+def test_a_reader_that_cannot_reach_the_bus_raises_rather_than_lying():
+    class Broken:
+        name = "broken"
+
+        def read(self):
+            raise DetectorUnavailable("no a11y bus")
+
+    with pytest.raises(DetectorUnavailable):
+        AtspiDetector(reader=Broken()).detect()
+
+
+def test_ui_automation_is_reported_as_not_implemented():
+    ok, detail = accessibility_available("uia")
+    assert ok is False and "not implemented" in detail
+    assert accessibility_available("telepathy")[0] is False
+
+
+def test_the_reader_itself_works_without_a_desktop_at_all():
+    """AT-SPI is present here, so reading an empty desktop returns no nodes."""
+    available, detail = accessibility_available("atspi")
+    if not available:
+        pytest.skip(f"no AT-SPI here: {detail}")
+    assert isinstance(AtspiReader().read(), tuple)
+
+
+# -- the fallback chain ------------------------------------------------------
+
+def test_best_uses_the_tree_when_it_has_content():
+    chains = []
+
+    class RecordingAccessibility:
+        name = "a11y"
+
+        def detect(self, image=None):
+            chains.append("accessibility")
+            return (Element("Save", kind="button", x=390, y=201, width=100, height=36),)
+
+    class RecordingOcr:
+        name = "ocr"
+
+        def detect(self, image):
+            chains.append("ocr")
+            return (Element("Guessed"),)
+
+    detector = AutoDetector(ocr=RecordingOcr(), accessibility=RecordingAccessibility())
+    assert [e.label for e in detector.detect(None)] == ["Save"]
+    assert chains == ["accessibility"]
+
+
+def test_best_falls_through_to_ocr_then_the_grid():
+    from tiny_computer_agent import GridDetector
+
+    class EmptyTree:
+        name = "a11y"
+
+        def detect(self, image=None):
+            return ()
+
+    class BrokenOcr:
+        name = "ocr"
+
+        def detect(self, image):
+            raise DetectorUnavailable("no engine")
+
+    with_ocr = AutoDetector(ocr=type("Ocr", (), {
+        "detect": lambda self, image: (Element("From OCR"),)})(), accessibility=EmptyTree())
+    assert [e.label for e in with_ocr.detect(FRAME)] == ["From OCR"]
+
+    without_ocr = AutoDetector(ocr=BrokenOcr(), grid=GridDetector(rows=1, cols=2),
+                               accessibility=EmptyTree())
+    assert [e.label for e in without_ocr.detect(FRAME)] == ["cell 1", "cell 2"]
+
+
+def test_the_auto_detector_still_defaults_to_ocr_then_grid():
+    """The new chain is opt-in: `auto` behaviour must not change."""
+    assert AutoDetector().accessibility is None
+
+
+def test_the_new_detector_names_are_reachable():
+    assert type(make_detector("atspi")).__name__ == "AtspiDetector"
+    assert type(make_detector("best")).__name__ == "AutoDetector"
+    ok, detail = detector_available("atspi")
+    assert isinstance(ok, bool) and detail
+    assert TEXT_ROLES and "label" in TEXT_ROLES
+
+
+# -- the one test that drives real AT-SPI ------------------------------------
+
+OPT_IN = os.environ.get("TINY_COMPUTER_AGENT_LIVE_TEST") == "1"
+
+
+@pytest.mark.skipif(not OPT_IN, reason="starts a real GTK window under a session bus")
+def test_atspi_reads_a_real_gtk_button_at_the_right_pixels(tmp_path):
+    import pathlib
+    import subprocess
+    import sys
+    import time
+
+    if not accessibility_available("atspi")[0]:
+        pytest.skip("no AT-SPI on this machine")
+    if not shutil_which("dbus-daemon"):
+        pytest.skip("no dbus-daemon")
+
+    address = subprocess.run(["dbus-daemon", "--session", "--fork", "--print-address=1"],
+                             capture_output=True, text=True).stdout.strip()
+    os.environ["DBUS_SESSION_BUS_ADDRESS"] = address
+    os.environ.setdefault("DISPLAY", ":99")
+    os.environ["NO_AT_BRIDGE"] = "0"
+
+    ready = pathlib.Path(tmp_path) / "gtk.ready"
+    app = subprocess.Popen(
+        [sys.executable, "showcase_scenes/gtk_dialog.py", str(tmp_path / "marker"), str(ready)])
+    try:
+        deadline = time.time() + 25
+        while time.time() < deadline and not ready.exists():
+            if app.poll() is not None:
+                pytest.fail("the GTK window exited early")
+            time.sleep(0.25)
+        assert ready.exists(), "the GTK window never mapped"
+        time.sleep(3)
+
+        elements = AtspiDetector(reader=AtspiReader()).detect()
+        labels = [e.label for e in elements]
+        assert "Save" in labels, f"the tree had no Save button: {labels}"
+        save = next(e for e in elements if e.label == "Save")
+        # the window is at +160+160 and the buttons are 100x36, laid out left to right
+        assert 160 < save.x < 160 + 460 and 160 < save.y < 160 + 220, save
+        assert (save.width, save.height) == (100, 36)
+    finally:
+        app.terminate()
+        app.wait(timeout=10)
+
+
+def shutil_which(name):
+    import shutil
+    return shutil.which(name)

tests/test_cli.py

@@ -51,13 +51,9 @@ def test_live_is_refused_without_a_display(capsys, monkeypatch):
 
 def test_screenshot_replay_needs_no_display(capsys):
     """The whole pipeline - OCR index, menu, action - on a still image."""
-    from tiny_computer_agent.perception import detector_available
+    from conftest import require_ocr
 
-    # detector_available() defaults to "auto", which is True whenever the grid
-    # fallback exists - so it never skips. Ask for the OCR engine specifically:
-    # the pipeline below needs it to find the button.
-    if not detector_available("ocr")[0]:
-        pytest.skip("no OCR engine installed")
+    require_ocr()          # one tested guard, shared with the perception tests
     assert cli.main(["--image", "example", "--brain", "planner"]) == 0
     out = capsys.readouterr().out
     assert "screenshot replay" in out

tests/test_decoding.py

@@ -0,0 +1,277 @@
+"""Constrained decoding: make an echo impossible instead of merely detected."""
+
+import pytest
+
+from tiny_computer_agent import (
+    Action, BrainError, DecisionMenu, Element, GoalUnreachable, ModelBrain, Observation,
+)
+from tiny_computer_agent.decoding import (
+    MenuMask, brevity_ladder, choice_token_ids, digit_token_ids, majority_choice, read_choice,
+)
+
+FRAME = Observation(elements=(
+    Element("Files", x=10, y=6, width=60, height=20),
+    Element("Save", x=200, y=270, width=90, height=30),
+    Element("Cancel", x=400, y=270, width=90, height=30),
+), text="Untitled document - unsaved changes")
+
+
+class FakeTokenizer:
+    """A tokenizer where each digit is one token (bare and space-prefixed)."""
+
+    def __init__(self, expressible=True):
+        self.expressible = expressible
+        self.table = {}
+        if expressible:
+            for digit in range(10):
+                self.table[str(digit)] = 100 + digit
+                self.table[" " + str(digit)] = 200 + digit
+            for index, word in enumerate(("yes", "Yes", "no", "No")):
+                self.table[word] = 300 + index
+                self.table[" " + word] = 320 + index
+
+    def encode(self, text, add_special_tokens=False):
+        if text in self.table:
+            return [self.table[text]]
+        return [999, 999]                      # never a single token
+
+
+# -- token ids ---------------------------------------------------------------
+
+def test_digit_ids_cover_every_digit_exactly_once():
+    ids = digit_token_ids(FakeTokenizer())
+    assert len(ids) == 20                      # 0-9, bare and space-prefixed
+    assert set(range(100, 110)) <= set(ids)
+
+
+def test_choice_ids_cover_only_the_legal_answers():
+    assert sorted(choice_token_ids(FakeTokenizer(), 3)) ==         sorted([100, 101, 102, 103, 200, 201, 202, 203])
+    assert sorted(choice_token_ids(FakeTokenizer(), 2, allow_done=False)) ==         sorted([101, 102, 201, 202])
+
+
+def test_a_tokenizer_that_cannot_spell_a_number_yields_no_ids():
+    assert digit_token_ids(FakeTokenizer(expressible=False)) == []
+    assert choice_token_ids(FakeTokenizer(expressible=False), 5) == []
+
+
+# -- the mask ----------------------------------------------------------------
+
+def test_the_mask_forbids_everything_that_is_not_a_menu_number():
+    torch = pytest.importorskip("torch")
+    scores = torch.zeros(1, 8)
+    masked = MenuMask([1, 3])(None, scores)
+    assert masked[0, 1].item() == 0 and masked[0, 3].item() == 0
+    for blocked in (0, 2, 4, 5, 6, 7):
+        assert masked[0, blocked].item() == float("-inf")
+    assert MenuMask([1, 3]).allowed_ids == (1, 3)
+
+
+def test_the_mask_keeps_the_end_of_sequence_reachable_after_one_token():
+    torch = pytest.importorskip("torch")
+    process = MenuMask([1], eos_token_id=7)
+    first = process(None, torch.zeros(1, 8))
+    assert first[0, 7].item() == float("-inf"), "stopping immediately is not an answer"
+    assert first[0, 1].item() == 0
+    second = process(None, torch.zeros(1, 8))
+    assert second[0, 7].item() == 0            # ...but it can stop after answering
+    assert second[0, 2].item() == float("-inf")
+
+
+def test_the_mask_can_be_told_not_to_force_a_token():
+    torch = pytest.importorskip("torch")
+    process = MenuMask([1], eos_token_id=7, force_first=False)
+    assert process(None, torch.zeros(1, 8))[0, 7].item() == 0
+
+
+# -- reading an answer -------------------------------------------------------
+
+def test_read_choice_reads_only_the_digits():
+    assert read_choice("3", 12) == 3
+    assert read_choice(" 3 ", 12) == 3
+    assert read_choice("3.", 12) == 3
+    assert read_choice("12", 12) == 12
+    assert read_choice("0", 12) == 0           # 0 is "already done"
+    assert read_choice("I would click item 2", 12) == 2
+
+
+def test_read_choice_refuses_what_is_not_exactly_one_answer():
+    assert read_choice("", 12) is None
+    assert read_choice("no idea", 12) is None
+    assert read_choice("13", 12) is None        # outside the menu
+    assert read_choice("2 or 3", 12) is None    # 23: ambiguous, so refused
+    assert read_choice("0", 12, allow_done=False) is None
+
+
+# -- the ladder and the vote -------------------------------------------------
+
+def test_the_brevity_ladder_grows_then_stops():
+    assert brevity_ladder(3) == (0, 1, 2)
+    assert brevity_ladder(1) == (0,)
+    assert brevity_ladder(0) == (0,)
+
+
+def test_majority_choice_ignores_failures_and_breaks_ties_by_first_seen():
+    assert majority_choice([1, 1, 2]) == 1
+    assert majority_choice([None, 3, None]) == 3
+    assert majority_choice([2, 1]) == 2          # a tie goes to the first seen
+    assert majority_choice([]) is None
+    assert majority_choice([None, None]) is None
+
+
+# -- the brain, in constrained mode ------------------------------------------
+
+class Scripted(ModelBrain):
+    """A backend whose replies are scripted, so the ladder can be tested."""
+
+    name = "scripted"
+    supports_constrained = True
+
+    def __init__(self, replies, tokenizer=None, **kwargs):
+        super().__init__("fake/model", **kwargs)
+        self._replies = list(replies)
+        self._tokenizer = tokenizer or FakeTokenizer()
+        self.prompts = []
+
+    def _tokenizer_for_choice(self):
+        return self._tokenizer
+
+    def _generate_constrained(self, prompt, observation, allowed_ids, max_new_tokens, *, sample=False):
+        self.prompts.append(prompt)
+        assert allowed_ids, "the mask must be non-empty"
+        return self._replies.pop(0)
+
+    def _generate(self, prompt, observation):
+        self.prompts.append(prompt)
+        return self._replies.pop(0)
+
+
+def test_choice_mode_turns_a_number_into_a_click():
+    brain = Scripted(["2"], decision_mode="choice")
+    action = brain.decide("save the document", FRAME)
+    assert action.kind == "click" and action.label == "Save"
+    assert "constrained choice 2" in action.reason
+    assert brain.last_choice == 2
+
+
+def test_choice_mode_reads_zero_as_already_done():
+    action = Scripted(["0"], decision_mode="choice").decide("save", FRAME)
+    assert action.kind == "done"
+
+
+def test_the_echoed_prompt_is_not_usable_even_if_the_model_returns_it():
+    """The old failure mode, fed straight in: it cannot be mistaken for an answer."""
+    brain = Scripted(["2"], decision_mode="choice")
+    echo = brain.build_prompt("save", DecisionMenu(FRAME), FRAME, brevity=0)
+    assert read_choice(echo, 12) is None, "an echoed menu must not parse as a choice"
+    # the prompt contains the menu numbers, spaced apart: 1, 2, 3 -> "123"
+    assert read_choice(brain.build_prompt("save", DecisionMenu(FRAME), FRAME), 3) is None
+
+
+def test_a_useless_reply_shortens_the_prompt_and_tries_again():
+    brain = Scripted(["", "3"], decision_mode="choice", retries=3)
+    action = brain.decide("discard the change", FRAME)
+    assert action.label == "Cancel"
+    assert len(brain.prompts) == 2
+    assert len(brain.prompts[1]) < len(brain.prompts[0]), "the retry must be shorter"
+
+
+def test_the_prompt_shrinks_all_the_way_when_nothing_works():
+    brain = Scripted([""] * 5, decision_mode="choice", retries=3)
+    with pytest.raises(BrainError, match="not a menu number"):
+        brain.decide("save", FRAME)
+    lengths = [len(prompt) for prompt in brain.prompts]
+    assert lengths[0] > lengths[-1] and len(lengths) == 3
+    assert "Text on screen" not in brain.prompts[-1]
+
+
+def test_votes_take_a_majority_over_samples():
+    brain = Scripted(["2", "3", "2"], decision_mode="choice", votes=3)
+    action = brain.decide("save", FRAME)
+    assert action.label == "Save"                       # 2 wins over 3
+    assert len(brain.prompts) == 3                      # only one ladder rung used
+
+
+def test_a_tokenizer_that_cannot_spell_numbers_is_refused_clearly():
+    brain = Scripted(["1"], tokenizer=FakeTokenizer(expressible=False), decision_mode="choice")
+    with pytest.raises(BrainError, match="cannot express a menu number"):
+        brain.decide("save", FRAME)
+
+
+def test_an_empty_screen_is_a_hard_stop_in_choice_mode():
+    brain = Scripted(["1"], decision_mode="choice")
+    with pytest.raises(GoalUnreachable):
+        brain.decide("save", Observation(elements=()))
+
+
+class ScanBackend(ModelBrain):
+    """Answers yes only for the labels it was told to like."""
+
+    name = "scan-backend"
+    supports_constrained = True
+
+    def __init__(self, likes, tokenizer=None, **kwargs):
+        super().__init__("fake/model", **kwargs)
+        self.likes = set(likes)
+        self.tokenizer = tokenizer or FakeTokenizer()
+        self.prompts = []
+
+    def _tokenizer_for_choice(self):
+        return self.tokenizer
+
+    def _generate_constrained(self, prompt, observation, allowed_ids, max_new_tokens, *, sample=False):
+        self.prompts.append(prompt)
+        label = prompt.split("Candidate item: ", 1)[1].splitlines()[0]
+        return "yes" if label in self.likes else "no"
+
+
+def test_scanning_asks_one_question_per_item_and_takes_the_first_yes():
+    brain = ScanBackend(["Save"], decision_mode="scan")
+    action = brain.decide("click 'Save' to save the document", FRAME)
+    assert action.kind == "click" and action.label == "Save"
+    assert "said yes to 'Save'" in action.reason
+    assert len(brain.prompts) == 2                 # Files, Save - then it stopped
+    assert all("yes or no" in prompt for prompt in brain.prompts)
+    assert all("Candidate item:" in prompt for prompt in brain.prompts)
+
+
+def test_scanning_refuses_when_every_item_is_rejected():
+    brain = ScanBackend([], decision_mode="scan")
+    with pytest.raises(BrainError, match="said no to all"):
+        brain.decide("save", FRAME)
+    assert len(brain.prompts) == 3                 # every item was asked about
+
+
+def test_scanning_refuses_a_reply_that_is_neither_yes_nor_no():
+    class Mute(ScanBackend):
+        def _generate_constrained(self, prompt, observation, allowed_ids, max_new_tokens, *, sample=False):
+            return "maybe"
+
+    with pytest.raises(BrainError, match="neither yes nor no|masked reply"):
+        Mute(["Save"], decision_mode="scan").decide("save", FRAME)
+
+
+def test_read_verdict_reads_what_the_mask_allows():
+    from tiny_computer_agent.decoding import pair_token_ids, read_verdict
+    assert read_verdict("yes") == "yes"
+    assert read_verdict(" Yes ") == "yes"
+    assert read_verdict("no") == "no"
+    assert read_verdict("No.") == "no"
+    assert read_verdict("perhaps") is None
+    assert read_verdict("") is None
+    yes_ids, no_ids = pair_token_ids(FakeTokenizer())
+    assert yes_ids and no_ids and not (set(yes_ids) & set(no_ids))
+
+
+def test_json_mode_is_untouched():
+    """The default must not change: the existing lenient parsing still applies."""
+    brain = Scripted(['{"kind": "click", "index": 2}'])
+    assert brain.decision_mode == "json"
+    assert brain.decide("save", FRAME).label == "Save"
+
+
+def test_choice_mode_is_only_entered_when_the_backend_supports_it():
+    class Plain(Scripted):
+        supports_constrained = False
+
+    brain = Plain(['{"kind": "click", "index": 2}'], decision_mode="choice")
+    assert brain.decide("save", FRAME).label == "Save"     # fell back to JSON parsing

tests/test_ocr_guard.py

@@ -0,0 +1,46 @@
+"""The OCR guard must actually skip when there is no engine.
+
+This is a regression test for a real bug: the guard in `test_cli.py` asked
+`detector_available()`, whose default `auto` is `True` even with nothing
+installed - because the grid fallback always exists. So on a machine with no OCR
+engine the test *failed* instead of skipping, and the failure looked like a
+harness defect. The guard now asks for `ocr` specifically, and here is the proof.
+"""
+
+import pytest
+
+from conftest import require_ocr
+
+import tiny_computer_agent.perception as perception
+
+
+def test_the_guard_skips_when_no_engine_is_installed(monkeypatch):
+    monkeypatch.setattr(perception, "detector_available",
+                        lambda name="auto": (False, "simulated: no engine"))
+    with pytest.raises(pytest.skip.Exception):
+        require_ocr()
+
+
+def test_the_guard_passes_when_an_engine_is_installed(monkeypatch):
+    monkeypatch.setattr(perception, "detector_available",
+                        lambda name="auto": (True, "simulated: engine present"))
+    require_ocr()          # must not raise
+
+
+def test_the_guard_asks_for_ocr_and_not_auto(monkeypatch):
+    """`auto` is available with nothing installed, so it would never skip."""
+    asked = []
+
+    def record(name="auto"):
+        asked.append(name)
+        return True, "recorded"
+
+    monkeypatch.setattr(perception, "detector_available", record)
+    require_ocr()
+    assert asked == ["ocr"]
+
+
+def test_auto_is_available_without_any_engine():
+    """The reason the old guard never fired, pinned down as a test."""
+    available, detail = perception.detector_available("auto")
+    assert available is True, "auto must stay usable with no OCR engine"

tests/test_perception.py

@@ -94,7 +94,7 @@ def test_the_synthetic_desktop_looks_like_the_intended_screen():
     assert image.size == (720, 460)
 
 
-@pytest.mark.skipif(not detector_available("ocr")[0], reason="no OCR engine installed")
+@pytest.mark.skipif(not detector_available("ocr")[0], reason="no OCR engine installed")  # conftest.require_ocr is the in-test form
 def test_real_ocr_reads_a_real_screenshot():
     """The whole point: pixels in, labelled elements with usable coordinates out."""
     elements = OcrDetector().detect(fake_desktop())
@@ -108,7 +108,7 @@ def test_real_ocr_reads_a_real_screenshot():
     assert 260 <= save.center[1] <= 310
 
 
-@pytest.mark.skipif(not detector_available("ocr")[0], reason="no OCR engine installed")
+@pytest.mark.skipif(not detector_available("ocr")[0], reason="no OCR engine installed")  # conftest.require_ocr is the in-test form
 def test_ocr_index_plugs_straight_into_a_click():
     """Label -> pixel resolution on coordinates the detector actually produced."""
     from tiny_computer_agent import Action, resolve_point

tests/test_stepwise.py

@@ -0,0 +1,190 @@
+"""The stepwise API: a console needs to run the loop one turn at a time.
+
+`run()` is the batch form. A live console needs the opposite - the caller owns the
+loop, so a button press advances exactly one step and a pause switch stops between
+them. Both are the same rules; these tests pin that down, including an
+equivalence check so the two forms cannot drift apart.
+"""
+
+import pytest
+
+from tiny_computer_agent import (
+    AgentLoop, Element, FakeScreen, MockBrain, PlannerBrain, Policy,
+)
+
+
+def script():
+    return MockBrain([
+        {"kind": "wait", "seconds": 0.1},
+        {"kind": "click", "label": "Save"},
+        {"kind": "key", "keys": "ctrl+s"},
+        {"kind": "done", "reason": "saved"},
+    ])
+
+
+def screen():
+    return FakeScreen([
+        (Element("Files", x=10, y=6, width=60, height=20),),
+        (Element("Save", x=320, y=120, width=80, height=24),),
+    ])
+
+
+def shape(episode):
+    """Everything about an episode that a user could notice."""
+    return (
+        episode.stop_reason,
+        episode.success,
+        [
+            (s.index,
+             s.action.describe() if s.action else None,
+             s.error,
+             s.result.summary() if s.result else None)
+            for s in episode.steps
+        ],
+    )
+
+
+# -- stepping ---------------------------------------------------------------
+
+def test_begin_reads_the_screen_once_and_step_once_advances_one_turn():
+    screen_ = screen()
+    loop = AgentLoop(screen=screen_, brain=script()).begin("save")
+    assert screen_.captures == 1                    # one read, before the first decision
+    assert loop.finished is False
+    assert loop.episode.steps == []
+
+    first = loop.step_once()
+    assert first.index == 0 and first.action.kind == "wait"
+    assert len(loop.episode.steps) == 1
+    assert loop.finished is False                   # three turns still to go
+
+    loop.step_once()
+    assert [s.action.kind for s in loop.episode.steps] == ["wait", "click"]
+
+
+def test_stepping_past_the_end_returns_none_instead_of_raising():
+    loop = AgentLoop(screen=screen(), brain=script()).begin("save")
+    while loop.step_once() is not None:
+        pass
+    assert loop.finished is True
+    assert loop.episode.success is True
+    assert loop.step_once() is None
+    assert loop.step_once() is None
+
+
+def test_step_once_before_begin_does_nothing():
+    loop = AgentLoop(screen=screen(), brain=script())
+    assert loop.step_once() is None
+    assert loop.episode is None
+
+
+def test_the_budget_is_enforced_one_step_at_a_time():
+    loop = AgentLoop(
+        screen=screen(),
+        brain=MockBrain([{"kind": "wait", "seconds": 0.2 + i} for i in range(10)]),
+        policy=Policy(step_budget=3),
+    ).begin("save")
+    taken = 0
+    while loop.step_once() is not None:
+        taken += 1
+    assert taken == 3
+    assert "budget of 3" in loop.episode.stop_reason
+
+
+# -- pause and resume -------------------------------------------------------
+
+def test_pause_stops_between_steps_and_leaves_the_episode_open():
+    loop = AgentLoop(screen=screen(), brain=script()).begin("save")
+    loop.step_once()
+    loop.pause()
+    episode = loop.run()                       # returns immediately
+    assert len(episode.steps) == 1
+    assert loop.finished is False              # not finished, only paused
+    assert loop.paused is True
+
+
+def test_resume_continues_the_same_episode_to_the_same_end():
+    loop = AgentLoop(screen=screen(), brain=script()).begin("save")
+    loop.step_once()
+    loop.pause()
+    loop.run()
+    loop.resume()
+    episode = loop.run()
+    assert episode.success is True
+    assert [s.action.kind for s in episode.steps] == ["wait", "click", "key", "done"]
+    assert loop.paused is False
+
+
+def test_a_paused_run_is_equivalent_to_an_uninterrupted_one():
+    straight = AgentLoop(screen=screen(), brain=script()).run("save")
+
+    interrupted = AgentLoop(screen=screen(), brain=script()).begin("save")
+    interrupted.step_once()
+    interrupted.pause()
+    interrupted.run()
+    interrupted.resume()
+    interrupted.run()
+
+    assert shape(interrupted.episode) == shape(straight)
+
+
+# -- the two forms cannot drift apart ---------------------------------------
+
+def test_run_is_exactly_begin_plus_step_once_in_a_loop():
+    batch = AgentLoop(screen=screen(), brain=PlannerBrain()).run("click 'Save'")
+
+    stepwise = AgentLoop(screen=screen(), brain=PlannerBrain()).begin("click 'Save'")
+    while stepwise.step_once() is not None:
+        pass
+
+    assert shape(stepwise.episode) == shape(batch)
+
+
+def test_verify_still_owns_success_when_stepping():
+    texts = ["Unsaved changes", "before", "Saved"]
+
+    class TextScreen:
+        def __init__(self):
+            self.n = 0
+
+        def capture(self):
+            from tiny_computer_agent import Observation
+            text = texts[min(self.n, len(texts) - 1)]
+            self.n += 1
+            return Observation(index=self.n - 1, elements=(Element("Save"),), text=text)
+
+    loop = AgentLoop(
+        screen=TextScreen(),
+        brain=MockBrain([{"kind": "wait", "seconds": 0.1}] * 4),
+        verify=lambda observation: "saved" in observation.text.lower(),
+    ).begin("save")
+    while loop.step_once() is not None:
+        pass
+    assert loop.episode.success is True
+    assert loop.episode.stop_reason == "verified after 2 action(s)"
+
+
+def test_a_kill_switch_stops_a_stepwise_run_before_the_first_action(tmp_path):
+    marker = tmp_path / "STOP"
+    marker.write_text("stop")
+    loop = AgentLoop(
+        screen=screen(),
+        brain=MockBrain([{"kind": "click", "label": "Save"}]),
+        policy=Policy(kill_switch_path=str(marker)),
+    ).begin("save")
+    assert loop.step_once() is None
+    assert loop.episode.steps == []
+    assert loop.episode.stop_reason == "kill switch engaged"
+    assert loop.finished is True
+
+
+def test_a_dead_screen_finishes_the_episode_at_begin():
+    class Blind:
+        def capture(self):
+            raise RuntimeError("X connection failed")
+
+    loop = AgentLoop(screen=Blind(), brain=script()).begin("anything")
+    assert loop.finished is True
+    assert loop.episode.steps == []
+    assert loop.episode.stop_reason.startswith("capture failed: RuntimeError")
+    assert loop.step_once() is None