agentenv-framework-protocol 0.1.477__tar.gz → 0.1.479__tar.gz

{agentenv_framework_protocol-0.1.477 → agentenv_framework_protocol-0.1.479}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.477
+Version: 0.1.479
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs
@@ -761,7 +761,9 @@ driver booted with a control token is probed with it: `--token`, by default
 
 At `full` the probe writes the Fixture Desk, a Tk window (`conformance/fixture.py`), into
 `~/.agentenv-probe` with `data/add` and starts it with `computer-exec`. It aims at the boxes the
-window's widgets report, reads back what reached them, and then removes the fixture. When the
+window's widgets report, reads back what reached them, and then removes the fixture. On X11 the
+window is maximized and kept above other windows, raising itself again when one covers it, so a
+window an app keeps on top doesn't take the clicks aimed at it; elsewhere it is full screen. When the
 fixture can't be staged, the `full` checks are unverified rather than failed.
 
 On a driver whose card says `screen: "page"`, the desk is an HTML page with the same widgets at the

{agentenv_framework_protocol-0.1.477 → agentenv_framework_protocol-0.1.479}/README.md

@@ -696,7 +696,9 @@ driver booted with a control token is probed with it: `--token`, by default
 
 At `full` the probe writes the Fixture Desk, a Tk window (`conformance/fixture.py`), into
 `~/.agentenv-probe` with `data/add` and starts it with `computer-exec`. It aims at the boxes the
-window's widgets report, reads back what reached them, and then removes the fixture. When the
+window's widgets report, reads back what reached them, and then removes the fixture. On X11 the
+window is maximized and kept above other windows, raising itself again when one covers it, so a
+window an app keeps on top doesn't take the clicks aimed at it; elsewhere it is full screen. When the
 fixture can't be staged, the `full` checks are unverified rather than failed.
 
 On a driver whose card says `screen: "page"`, the desk is an HTML page with the same widgets at the

{agentenv_framework_protocol-0.1.477 → agentenv_framework_protocol-0.1.479}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.477"
+version = "0.1.479"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"

{agentenv_framework_protocol-0.1.477 → agentenv_framework_protocol-0.1.479}/src/agentenv_protocol/computer/app_data.py

@@ -18,6 +18,7 @@ from typing import TYPE_CHECKING, Any, Optional
 from ..agent_env_environment import OP_ADD_DATA, OP_GET_DATA, OP_RESET_DATA
 from ..transfers import WriteNamespaceGrant
 from ..types import METHOD_ADD, METHOD_RESET, FilePart, uploaded_object_path
+from .app_runtime import paused_app
 from .dataplane import data_files, file_parts, part_bytes
 
 if TYPE_CHECKING:
@@ -131,7 +132,7 @@ class AppDataPlane:
         if not self.paths:
             return None
         return {OP_ADD_DATA: functools.partial(add, paths=self.paths),
-                OP_GET_DATA: functools.partial(get, self.paths, self.runtime.paused),
+                OP_GET_DATA: functools.partial(get, self.paths),
                 OP_RESET_DATA: functools.partial(reset, self.paths)}[op]
 
     async def _within(self, op: str, served: Callable, args: tuple, answer: asyncio.Future) -> Any:
@@ -177,13 +178,12 @@ async def add(parts: list, paths: list[str]) -> None:
     await in_thread(write_within, Path.home(), files, paths)
 
 
-async def get(paths: list[str], paused: Callable[[], contextlib.AbstractContextManager],
-              write_namespace: Optional[WriteNamespaceGrant]) -> list:
-    """A part for each file under ``paths``, copied with the app ``paused``, so they are of one moment, and sent from
-    the copy once it runs again."""
+async def get(paths: list[str], write_namespace: Optional[WriteNamespaceGrant]) -> list:
+    """A part for each file under ``paths``, copied with the app this server launched paused (``paused_app``), so they
+    are of one moment, and sent from the copy once it runs again; an app's own data/get hook calls it so too."""
     INITIAL.parent.mkdir(parents=True, exist_ok=True)
     with tempfile.TemporaryDirectory(dir=INITIAL.parent) as staging:
-        with paused():
+        with paused_app():
             await in_thread(_stage, Path.home(), paths, Path(staging))
         return await file_parts(Path(staging), paths, write_namespace)
 

{agentenv_framework_protocol-0.1.477 → agentenv_framework_protocol-0.1.479}/src/agentenv_protocol/computer/app_runtime.py

@@ -139,10 +139,8 @@ class AppRuntime:
         return _running() is not None
 
     def paused(self) -> contextlib.AbstractContextManager:
-        """The app this server launched last, every process of it, paused while the block runs, so a copy of its files
-        taken meanwhile is of one moment."""
-        pid = _running()
-        return session.paused(pid) if pid is not None else contextlib.nullcontext()
+        """The app this server launched last paused while the block runs (``paused_app``)."""
+        return paused_app()
 
     def exited(self) -> bool:
         """Log that the app this server launched last ended on its own, with its exit code or the signal that ended
@@ -242,6 +240,13 @@ def _running() -> Optional[int]:
     return pid if pid is not None and session.alive(pid) else None
 
 
+def paused_app() -> contextlib.AbstractContextManager:
+    """The app this server launched last, every process of it, paused while the block runs, so a copy of its files
+    taken meanwhile is of one moment; nothing when it isn't running."""
+    pid = _running()
+    return session.paused(pid) if pid is not None else contextlib.nullcontext()
+
+
 async def _bounded(name: str, check: Awaitable[Optional[str]]) -> Optional[str]:
     """What ``check`` finds wrong, within ``CHECK_TIMEOUT_S``; a check that runs past it or raises says so."""
     try:

{agentenv_framework_protocol-0.1.477 → agentenv_framework_protocol-0.1.479}/src/agentenv_protocol/computer/conformance/fixture.py

@@ -2,13 +2,15 @@
 Desk, whose widgets' screen boxes are written to <state-dir>/layout.json and every effect that reaches it, with
 whatever lands in <state-dir>/inbox.txt, to <state-dir>/state.json, so the probe can aim at it and read back what
 arrived. It records the same effects under X11, macOS's Aqua and Windows, whose Tk names keys, binds select-all and
-reports the wheel differently. Run as ``python3 fixture.py <state-dir>``; it needs a 1280x800 screen or larger."""
+reports the wheel differently. On X11 it stays above an app's windows (``keep_on_top``); elsewhere it's full screen.
+Run as ``python3 fixture.py <state-dir>``; it needs a 1280x800 screen or larger."""
 from __future__ import annotations
 
 import ctypes
 import json
 import os
 import sys
+import time
 import tkinter as tk
 from pathlib import Path
 
@@ -29,6 +31,8 @@ NOTCH_DELTA = 120
 Y_BITS = 16
 #: The pixels of a scrolled line, macOS's for a scroll posted in lines.
 LINE_PX = 10
+#: The least time between two of the fixture's raises over other windows, so it can't fight one that raises itself.
+LIFT_GAP_S = 0.5
 
 
 def main(state_dir: Path) -> None:
@@ -37,7 +41,10 @@ def main(state_dir: Path) -> None:
     root.title("Fixture Desk")
     width, height = root.winfo_screenwidth(), root.winfo_screenheight()
     root.geometry(f"{width}x{height}+0+0")
-    root.attributes("-fullscreen", True)
+    if root.tk.call("tk", "windowingsystem") == "x11":
+        keep_on_top(root)
+    else:
+        root.attributes("-fullscreen", True)
     root.configure(bg="#f0f0f0")
     state: dict = {"name": "", "notes": "", "keys": [], "saved_count": 0, "subscribed": False, "selected": None,
                    "scroll_top": 0.0, "cells": {}, "right_clicks": 0, "double_clicks": 0, "drags": [],
@@ -227,6 +234,38 @@ def main(state_dir: Path) -> None:
     root.mainloop()
 
 
+def keep_on_top(root: tk.Tk) -> None:
+    """Keep the fixture over the windows an app opens, which would take the probe's clicks: maximized and above other
+    windows rather than full screen, since xfwm4 keeps a window an app puts above over a full-screen one, and raised
+    again, giving the focus back to the widget that last had it, whenever another window covers some of it, at most once
+    each LIFT_GAP_S."""
+    root.attributes("-zoomed", True)
+    root.attributes("-topmost", True)
+    seen: dict = {"state": "VisibilityUnobscured", "lifted": 0.0, "pending": None}
+
+    def lift() -> None:
+        seen["pending"] = None
+        if seen["state"] == "VisibilityUnobscured":
+            return
+        seen["lifted"] = time.monotonic()
+        # Taking the layer above again restacks it on top, which a raise request alone doesn't get from xfwm4.
+        root.attributes("-topmost", False)
+        root.attributes("-topmost", True)
+        root.lift()
+        # The widget that last had the focus gets it back, so keys the probe types into a text box still reach it.
+        (root.focus_lastfor() or root).focus_force()
+
+    def visibility(event: tk.Event) -> None:
+        if event.widget is not root:
+            return
+        seen["state"] = event.state
+        if event.state != "VisibilityUnobscured" and seen["pending"] is None:
+            wait = max(0.0, seen["lifted"] + LIFT_GAP_S - time.monotonic())
+            seen["pending"] = root.after(round(wait * 1000), lift)
+
+    root.bind("<Visibility>", visibility, add="+")
+
+
 def wheel_steps(delta: int) -> int:
     """The wheel steps a <MouseWheel> event's ``delta`` holds, up positive: whole notches of 120 where Tk scales them
     so (Windows, and Tk 9 everywhere), else one a unit (Aqua's Tk 8.6)."""

{agentenv_framework_protocol-0.1.477 → agentenv_framework_protocol-0.1.479}/tests/test_computer_app_data.py

@@ -138,6 +138,19 @@ async def test_an_app_with_only_paths_loads_exports_and_resets_them_as_installed
     assert reset == {"Mail/inbox.txt": b"installed"}
 
 
+@pytest.mark.asyncio
+async def test_get_takes_paths_and_a_write_namespace_and_pauses_the_running_app_as_exported_apps_call_it(home,
+                                                                                                        desktop):
+    (home / "Mail").mkdir()
+    (home / "Mail/inbox.txt").write_text("kept")
+    await PathsMail()._computer_app.launch_app()
+
+    parts = await app_data.get(["Mail"], None)
+
+    assert [await part_bytes(part) for part in parts] == [b"kept"]
+    assert desktop == [("launch", 4242), ("pause", 4242), ("continue", 4242)]
+
+
 @pytest.mark.asyncio
 async def test_a_file_under_none_of_its_paths_or_through_a_link_out_of_them_is_refused_and_nothing_is_written(home):
     (home / "Documents").mkdir()

{agentenv_framework_protocol-0.1.477 → agentenv_framework_protocol-0.1.479}/tests/test_computer_conformance.py

@@ -323,6 +323,77 @@ def test_the_fixture_counts_a_scroll_tk_9_reports_in_pixels_by_the_lines_it_move
     assert _fixture(monkeypatch).touchpad_steps(delta) == steps
 
 
+class _Root:
+    """A Tk root stood in for: the attributes set on it in order, its bindings, the calls made to it, and what
+    ``after`` was given to run, with its delay."""
+
+    def __init__(self):
+        self.set, self.calls, self.bound, self.timers = [], [], {}, []
+        self.last = self
+
+    def focus_lastfor(self):
+        return self.last
+
+    def attributes(self, name, value):
+        self.set.append((name, value))
+
+    def bind(self, sequence, handler, add=None):
+        self.bound[sequence] = handler
+
+    def after(self, ms, callback):
+        self.timers.append((ms, callback))
+        return f"after#{len(self.timers)}"
+
+    def lift(self):
+        self.calls.append("lift")
+
+    def focus_force(self):
+        self.calls.append("focus_force")
+
+
+def test_the_fixture_on_x11_stays_maximized_above_other_windows_and_takes_the_top_back_once_one_covers_it(monkeypatch):
+    """A window an app keeps above, as Typora's licence dialog is for its first seconds, otherwise takes the clicks the
+    probe aims at the fixture."""
+    fixture = _fixture(monkeypatch)
+    now = [100.0]
+    monkeypatch.setattr(fixture.time, "monotonic", lambda: now[0])
+    root = _Root()
+    fixture.keep_on_top(root)
+    seen = root.bound["<Visibility>"]
+
+    seen(SimpleNamespace(widget="a child", state="VisibilityFullyObscured"))
+    for_child = list(root.timers)
+    seen(SimpleNamespace(widget=root, state="VisibilityPartiallyObscured"))
+    seen(SimpleNamespace(widget=root, state="VisibilityPartiallyObscured"))
+    (first, lift), = root.timers
+    lift()
+    lifted = (root.set[2:], list(root.calls))
+    now[0] += 0.1
+    seen(SimpleNamespace(widget=root, state="VisibilityFullyObscured"))
+    second, again = root.timers[1]
+    seen(SimpleNamespace(widget=root, state="VisibilityUnobscured"))
+    again()
+
+    assert root.set[:2] == [("-zoomed", True), ("-topmost", True)] and for_child == []
+    assert first == 0 and lifted == ([("-topmost", False), ("-topmost", True)], ["lift", "focus_force"])
+    assert second == round((fixture.LIFT_GAP_S - 0.1) * 1000) and root.calls == ["lift", "focus_force"]
+
+
+def test_the_fixture_gives_the_focus_back_to_the_text_box_that_had_it_when_it_takes_the_top_back(monkeypatch):
+    """A window an app opens during a typing check would otherwise leave the probe's keys with the fixture's root."""
+    fixture = _fixture(monkeypatch)
+    monkeypatch.setattr(fixture.time, "monotonic", lambda: 100.0)
+    root, name = _Root(), _Root()
+    root.last = name
+    fixture.keep_on_top(root)
+
+    root.bound["<Visibility>"](SimpleNamespace(widget=root, state="VisibilityPartiallyObscured"))
+    (_, lift), = root.timers
+    lift()
+
+    assert root.calls == ["lift"] and name.calls == ["focus_force"]
+
+
 def _fixture(monkeypatch):
     """The fixture module, which runs in the computer, read with Tk stood in for, as this Python may have none."""
     monkeypatch.setitem(sys.modules, "tkinter", ModuleType("tkinter"))